1.0 Inter-Application Communication
    1.1 Remote Procedure Call (RPC)
    1.2 Dynamic Data Exchange (DDE)
        1.2.1 DDE Conversations
        1.2.2 Items
        1.2.3 Requesting Information from a DDEServer
    1.3 SQL Connect
    1.4 AppleEvents
    1.5 Dynamic Link Libraries (DLL)
    1.6 Shared Libraries (Macintosh)

2.0 Encrypting and Embedding Avenue Scripts
    2.1 Embed & Unembed Scripts
        2.1.1 Why Embed an Avenue Script?
        2.1.2 Unembed a Script
    2.2 Encrypting
        2.2.1 Why encrypt a script?

3.0 Dialog Designer
    3.1 What is the Dialog Designer?
    3.2 What Does the Dialog Designer Provide?
    3.3 What can you do with the Dialog Designer?
    3.4 How Does it Work?
    3.5 Working with dialogs
        3.5.1 Add a Dialog to an ArcView Project
        3.5.2 Dialog Editor Pull Down Menu
        3.5.3 What Controls are Available?
        3.5.4 Controls Pull Down Menu
    3.6 Control Properties
    3.7 Avenue Requests with Dialogs
    3.8 Applications of the Dialog Designer
        3.8.1 A Simple Dialog
        3.8.2 Access a Dialog from the ArcView Interface
        3.8.3 Naming Conventions
        3.8.4 Making Controls Work Together
    3.9 Updating Controls with Broadcaster-Listener Relationship
    3.10 Add Controls Directly to Documents
    3.11 Delivering Customizations
        3.11.1 Dialogs in an Extension
        3.11.2 Dialogs within a Project
        3.11.3 Dialogs in a Personal Work Environment
        3.11.4 Dialogs in a System Default Environment

4.0 ArcView Extensions
    4.1 Create Extensions
        4.1.1 Naming Conventions
        4.1.2 Extension Builder Sampler Extension
    4.2 Avenue and Customized Extensions
        4.2.1 Extension Objects
        4.2.2 Making Extensions with Dialogs
        4.2.3 Other Considerations

5.0 Other Goodies
    5.1 System Level Commands
    5.2 Calling Scripts From Other Scripts
        5.2.1 Run
        5.2.2 DelayedRun
        5.2.3 DoIt
    5.3 Return versus Exit
        5.3.1 Return
        5.3.2 Exit
    5.4 Recursion

1.0 Inter-Application Communication

Inter-application communication (IAC) refers to the ability to have two or more applications communicate. IAC depends upon platform-specific protocols. Applications which 'understand' these protocols can make requests of other applications, or send information back and forth. With IAC, a collection of independent applications can interact to form an integrated application environment.

In many situations, ArcView provides only a piece of a larger solution strategy. Other applications or programs you've written in a programming environment may provide key components to your application. How do you make ArcView work with these other applications?  ArcView offers several different methods of interacting with other applications. On all platforms, you can use Remote Procedure Call (RPC) to establish Client/Server relationships with other applications. On Windows, you can use Dynamic Data Exchange (DDE) for Client/Server relationships, or calls to external Dynamic Link Libraries (DLL).  This same functionality is also available on UNIX and Macintosh with shared libraries. If you are working on the Macintosh, you can use AppleEvents and AppleScript to interact with other applications. The most appropriate method will depend on the tasks that you need to perform and the level at which you need to integrate the applications.

PC

• Remote Procedure Calls (RPC)
• Dynamic Data Exchange (DDE)
• Calls to Dynamic Link Libraries (DLLs)

• Remote Procedure Calls (RPC)

• AppleEvents
• AppleScript

Remote Procedure Call (RPC) provides a standard protocol for implementing Client/Server relationships between applications.  One application establishes itself as a server and the other application becomes a client by connecting to the server.  A client requests services from servers. The server performs requests and sends a response to the client. The Client/Server relationship allows you to share functionality among multiple processes and to distribute functionality across multiple machines.

There are several forms of RPC, but both ArcView and ARC/INFO use the Open Network Computing (ONC) standard. (DCE is another common variety). ArcView and ARC/INFO interact via RPC with any other applications supporting ONC/RPC. Both ArcView and ARC/INFO can be clients, servers or both.

ArcView supports RPC with the RPCClient and RPCServer classes.  You make the ArcView application an RPCServer by issuing the RPCServer.Start request. Clients make requests to the ArcView RPCServer in the form of Avenue statements. You can create clients to other RPCServers with ArcView’s RPCClient class. RPCClient.Make creates a client object establishing a connection to another application that is a server. With RPCClient.Execute you request services from the server.

If you are on Windows or Macintosh, make sure a portmap is running before you start the RPCServer in ArcView.  Portmap is an executable that comes with Arcview.  Servers register with portmap and clients locate the appropriate server through portmap.  If portmap is not running, then clients cannot access servers.

Through these classes, you can connect ArcView to any other application that supports RPC with the ONC/RPC protocols.  For example, you might choose to connect your ArcView application to ARC/INFO so that an ArcView client could request processing from an ARC/INFO server.  Through RPC, an ArcView client can request ARC/INFO to create topology, perform sophisticated analysis, generate coverages, create advanced maps, etc. The RPC connection allows the two applications to communicate status and results.

To use ArcView as a server run the following script (the server is started on a machine named "sherpa").

' start the RPCServer
RPCServer.Start( 0x40000001, 1 )

Here is an Avenue script to stop the ArcView RPCServer.

' stop the RPCServer
RPCServer.Stop

Here is an Avenue script to create an ArcView RPCClient and issue a service request to the server.

' create an RPCClient
aClient = RPCClient.Make( "sherpa", 0x40000001, 1 )
' check the connection
if ( aClient.HasError ) then
   msgbox.Error( aClient.GetErrorMsg, "" )  'report error
   exit
end
' check the timeout and reset if too short
if ( aClient.GetTimeout < 15 ) then
   aClient.SetTimeout( 15 )
end
' request service from server
result = aClient.Execute( 1, "av.GetActiveDoc", String )
if ( aClient.HasError ) then       'check status of service request
   msgbox.Error( aClient.GetErrorMsg, "" )
end
MsgBox.Info( "The active document is"++result, "Got it!" )
' Close the client connection
aClient.Close

1.2 Dynamic Data Exchange (DDE)

Dynamic Data Exchange (DDE) is the IAC protocol most frequently supported in Windows.  ArcView supports DDE only on Windows.  For example, through DDE, you can share data between PC ArcView and Microsoft Access.

The DDEServer object is used when ArcView will act as a server to other applications (e.g., a database or spreadsheet).  The DDEClient object is used to allow ArcView to act as a client of another application.

Unlike RPC, there is no portmap program needed to manage server-client communications.

1.2.1 DDE Conversations

When two applications interact via DDE it is referred to as a conversation.  In a similar fashion to RPC, one application acts as the server and the other as the client.  A conversation is identified by two pieces of information; the application name of the server and the topic name.

A DDE conversation is defined by two components: the application name and the topic, or subject, of the conversation. Every application that can be a DDE server has a unique application name, which is usually the name of the executable program without the file extension (e.g., ArcView, Excel or Access). The topic defines the subject of the conversation, and is typically a name that is defined by the source application. Most applications recognize a document name as a topic for a conversation and many also support a general topic named "system." The combination of application name and topic uniquely defines a conversation and remains constant throughout the duration of the conversation.

ArcView has only one topic; system.  To establish a conversation with Excel there are many different topics to choose from including a topic named "System" and topics for each spreadsheet.  To establish a conversation with a Visual Basic form, the form provides its own application and topic names.

'Establish a DDEClient
DDEClient.Make("Excel", "System)

However, to start ArcView as a DDEServer there is the Start request.  You can change the name of ArcView's DDE server using the DDEServer request StartNamed.  This may be useful if you have more than one ArcView application running on a single system.

From ArcView, you can initiate a conversation with another application using the DDEClient.Make request.  Arguments for the Make request specify the application and the topic. The conversation is successfully initiated if the client has no errors. For example:

myClient = DDEClient.Make( "Excel", "System" )
if (myClient.HasError) then
  MsgBox.Error( myClient.GetErrorMsg, "")
  return nil
end

The DDEServer application must already be running.  In the case above, Excel must already be open and running on the server.

1.2.2 Items

When a client initiates a conversation regarding a particular topic, the server application responds if it recognizes the topic.  The two applications can then exchange data.  An item identifies the piece of data actually being passed during the DDE conversation.

Examples of items:

• In Excel, a spreadsheet cell reference (i.e., R1C1);
• In ArcView, an Avenue request;
• In Visual Basic a form, a text box, picture box, or label.

1.2.3 Requesting Information from a DDEServer

There are three transactions which allow DDE clients to communicate with DDE servers.

• Execute causes the server to execute commands it receives in a string from the client.
• Request returns information on a particular item to the client.
• Poke requests acknowledgement of a data transfer.

Request
Request returns data on an item. Request returns a string representation of that value.

Poke
Passes data to an item.  The item is defined in the server application.

A client connected to the ArcView DDE server makes requests to the server through Avenue scripts. For the execute transaction, the client provides an Avenue script for the server to execute. The Avenue script may be the entire source string or simply a request.

av.run("Script1", "input data")

For typical Request and Poke transactions, the server publishes a list of "items" available to the client for access. For ArcView, there is no way to publish a list of items. Because there are so many values that may be of interest and because the system is extremely dynamic, any attempt to publish a set list of items would be both overwhelming and very constraining. Instead, the DDE client identifies objects to Request and Poke with Avenue scripts. This solution allows the client full access to the ArcView object model and to all values within the application.

The Request transaction requires that the client name an item whose value is returned. For the ArcView server, the item is an Avenue script and the value returned is the return object of that script converted to string. Remember that most Avenue requests return objects including av.run, which returns the object in the RETURN statement or the last object created if there is no RETURN. The script may be very simple such as av.GetProject which returns the project name or very complex.

The POKE transaction is slightly more complicated. The item has two elements, a type (which in the current release MUST BE string) and the name of a script in the server to execute. The data is a string of any length. The data becomes the value of SELF to the script specified in the item. That script then "does something" with the data.

1.3 SQL Connect

The SQL Connect feature (from the pull down menu Project | SQL Connect...') will connect ArcView to a database server, such as Oracle, Sybase or Access, and run an SQL query to retrieve records.  The records you access become a table in your project.  You can then use this table like any other ArcView table.

If the SQL Connect file pull down menu is unavailable on your system you either did not install SQL Connect or you need to install ODBC drivers.  To install SQL Connect run the ArcView install program again, choose the Custom option, and choose ArcView SQL Connectivity.  To install ODBC in Windows go to the Control Panel and double-click the ODBC icon.  Data sources listed will appear in ArcView's SQL Connect dialog.

ArcView stores the definition of the SQL query you used to create the table, not the records themselves. The records themselves are stored in a temporary file while the table is being used.  The file is removed when you delete the table, close the project, or quit ArcView.  When you open a project containing a table representing the results of an SQL query, ArcView will automatically reconnect to the database to obtain the data for your table. Any changes in the database will therefore be reflected in your table, and any views, charts or layouts that use this table's data.  A VTab can be returned from an SQL connection by using the VTab.MakeSQL request.

PC & Macintosh SQL Connections
SQL connections for PCs and Macintoshes are based on Microsoft's ODBC (Open DataBase Connectivity) standard.

UNIX SQL Connections
UNIX SQL connections are performed with ESRI's DATABASE INTEGRATOR technology.
 
 

1.4 AppleEvents

AppleEvents is the protocol found on the Macintosh. IAC is based upon a client/server relationship between applications. The application initiating the request or conversation is the Client, the application which fulfills the request is the Server. ArcView can be a client of many other server applications. ArcView also can be a server to many different client applications. In some cases ArcView may be both a client and a server at the same time.  See the class documentation for RPCServer, RPCClient, DDEServer, DDEClient, AppleEvent and AppleScript for further information.

1.5 Dynamic Link Libraries (DLL)

A library is a compiled collection of procedures (or functions) that you can call from another application. Libraries are used to store procedures that are called frequently, eliminating the need to code the same procedures in every application that uses them. When a library is used it must be linked to an application. There are two kinds of libraries, static libraries and dynamic libraries. How you link a library with another application depends on the kind of library you wish to use.

A dynamic link library (DLL) is an executable module that contains functions that other applications can use in order to perform tasks. DLLs are linked to an application at run time, not at compile time as occurs with static libraries.  DLLs can be purchased from various vendors, or may be included as part of an application. You can also create and compile your own DLLs for specific purposes using C and other language compilers. Functions found in a DLL may be called directly from Avenue. These functions can in turn call other functions that may perform various tasks. Information can be passed back and forth as parameters, or returned as the result of a function call.

DLLs can be used to extend the basic functionality of Avenue, or can be used to integrate one or more applications with ArcView. Application integration through DLLs occurs at a lower-level than IAC communications, and therefore may be more desirable in some cases.

1.6 Shared Libraries (Macintosh)

A Shared library is an executable module that contains functions that other applications can use in order to perform tasks. Shared libraries are linked to an application at run-time, not at compile time as occurs with static libraries.
Shared Libraries can be purchased from various vendors, or may be included as part of an application. You can also create and compile your own Shared Libraries for specific purposes using C and other language compilers. Functions found in a Shared Library may be called directly from Avenue. These functions can in turn call other functions that may perform various tasks. Information can be passed back and forth as parameters, or returned as the result of a function call.

Shared Libraries can be used to extend the basic functionality of Avenue, or can be used to integrate one or more applications with ArcView. Application integration through Shared Libraries occurs at a lower-level than IAC communications, and therefore may be more desirable in some cases.
 

2.0 Encrypting and Embedding Avenue Scripts

When you have finished writing, debugging and testing your script, you may choose to encrypt or embed it.

2.1 Embed & Unembed Scripts

Embedding a script will move the completed script from the Script Editor document (which is part of the project's document list) to the Project's script list. When you embed a script, you add a script object to the project's collection of scripts.  The net result for a user's perspective is that the script editor is gone.  However, the script is not inaccessible, to modify or debug an embedded script, you must restore it to a script editor.  The Script Editor's user interface includes choices in the Script menu to embed and unembed scripts.  Avenue programmers can write their own scripts that embed and unembed custom scripts.

The process of embedding a script utilizes a name dictionary.  A name dictionary is a special type of dictionary.  In a generic dictionary, such as those mentioned in the end of the second Avenue course, the key is any object that identifies any other object (the value). In a Name Dictionary, the key for an object is its name. This constraint allows us to implement this type of dictionary more efficiently than if the key/value relationship were arbitrary.  A name dictionary uses a hash table to locate elements, so ArcView can quickly find embedded scripts.

2.1.1 Why Embed an Avenue Script?

There are several reasons why you should consider moving your completed scripts to the project's script list; that is, "embedding" the script.
 

• Faster access - the hash table used in a name dictionary provides faster access than a binary search (used to locate Script Editor documents).

• Eliminates clutter - if you have a large application, you may have hundreds of scripts. It would be easier for you if you saw only those scripts that you are currently working on in the list of scripts in the project window.

• Less available - an embedded script is less accessible to your end users. While it is still easy for a developer to retrieve and alter, novice users or your end users are less likely to accidentally change the script and perhaps mess up the application.

'This script will:
'1. Get the active document - an SEd
'2. Check to see if it is compiled - if not compiled
'3. Embed the script with the AddScript request
'4. Remove the SEd document from the project
'5. Display a message box that it was done
'
'Check to see if the SEd is compiled
theSEd = av.GetActiveDoc
  if (NOT (theSEd.IsCompiled)) then
    msgbox.error(theSEd.GetName++"is not compiled", "You forgot to compile")
    return nil
  end

'See if script is already on the script list
  if ( av.GetProject.GetScripts.Get(theSEd.GetName ) <> nil) then
    replace = msgbox.yesno( "Do you want to overwrite"++theSEd.GetName+"?",
                                  "Embed Script", TRUE)
      if (replace.Not) then
        return nil
      end
  end

'Embed the script
theScript = theSEd.GetScript
av.GetProject.AddScript( theScript )

'Remove the script editor
av.GetProject.RemoveDoc( theSEd )

'Report success
msgbox.Info(theScript.Getname++"was embedded successfully", "SUCCESS")
 
 

2.1.2 Unembed a Script

To modify or debug an embedded script, you must retrieve it from the embedded scripts and restore it to a script editor. This script asks you to pick an embedded script, then creates a new Script Editor document, names it and copies the source string of the embedded script to it. Finally, it removes the embedded script so that the script editor you are debugging executes when you do an av.run.  This script is similar to the system script called Script.Unembed.

'This script will:
'1. Get the embedded scripts affiliated with a project - returns 'aNameDictionary
'2. Use the ReturnKeys request to create a list from 'aNameDictionary
'3. Let the user choose which script to unembed from the list
'4. Use the Remove request to unembed the selected script
'
'Get the script name dictionary
aNameDictionaryOfScripts = av.GetProject.GetScripts
'
'Create a list from the name dictionary
scriptlist = aNameDictionaryOfScripts.ReturnKeys
'
'Sort the script list
scriptlist.sort( true )
'
'Query the user with a message box to select the script to unembed
scriptName = MsgBox.ListAsString( scriptlist, "Select script", "UnEmbed" )
'
'Create an SEd from scriptName and open it
  if (scriptName <> nil) then
  ' get the script
  theScript = aNameDictionaryOfScripts.Get(scriptName)
  newSEd = SEd.Make
  newSEd.SetName( scriptName )
  newSEd.SetSource( theScript.AsString )
  newSEd.GetWin.Open

'Remove it from the embedded script list
aNameDictionaryOfScripts.Remove( scriptName )
end

2.2 Encrypting

2.2.1 Why encrypt a script?

Encrypted scripts (and encrypted projects) allow you to protect your investment in Avenue code by making your source code unreadable.  You can encrypt individual scripts using the Script request AsEncrypted, EncryptedScript, MakeFromScript, or you can encrypt an entire project with the EncryptScripts request.

Be sure to keep a copy of all original Avenue scripts because encrypted scripts cannot be decrypted.

Here is an example of encrypting an individual script. See the script library encscrpt.ave and encprj.ave for more information.

‘This script will both embed and encrypt the script
‘The script will be able to be unembedded by not decrypted
‘
theSEd = av.GetActiveDoc
'Encrypt and Embed the script
theScript = EncryptedScript.MakeFromScript( theSEd.GetScript )
theScript.SetName( theSEd.GetName )
av.GetProject.AddScript( theScript )

'Remove the script editor
av.GetProject.RemoveDoc( theSEd )

If you were to open up the ArcView project in a text editor, you'd see that the script is unreadable.

/3.0
...
(Information removed to save space)
...
...
(EnScript.131
 Name: "encrypt test"
 SourceCode: "sYlg 9%Ex_Aqq*Nfums* -M]~ Fqh`%Dtgjkg#% nfrgkp%qtmq\"g]r]. +\" Iw&%Ehekku`tfd\"<krejjbkZh%Jj]mc\\pr]sl!. -' .  \"bb% sYlg 8C sak+ pm]s -\"fuX[waov 9%KHJHRM*R9P='$folZtp-kgbt ' Gqp ,Ztms\"pa%[ted\"iehc%qnw qu qYsgk-0#sYlg$-& '$-$ >j]u ag^l' . !+  % n^-*fuX[waov'DfkJjqqk*Sgy!-vaas % -orOhjnhs0=kNl- !+  %]s\\ \"^ji "
)

3.0 Dialog Designer

3.1 What is the Dialog Designer?

The ArcView Dialog Designer is an extension to ArcView GIS that provides Avenue developers with a new tool, a dialog, to customize ArcView's interface. A dialog lets you organize a single task or set of related tasks onto a separate window, much like you can organize related tasks under a particular menu item or on the button bar.

Before the Dialog Designer, you couldn't design and build custom dialogs using ArcView. For example, if you needed to ask the user a series of questions each question would have been presented in a separate message box.  The user would answer those questions one at a time and the application could then proceed.  This was cumbersome and slow.  A typical response to this deficiency with Avenue was to turn to other applications that run outside of ArcView, such as Microsoft Visual Basic, to provide needed functionality. While this worked to a degree, getting the external dialog to communicate with ArcView was slow, clumsy and inefficient.

The Dialog Designer is free to all ArcView 3.0a users.  It can be downloaded off of ESRI's web site (www.esri.com).  The Dialog Designer is currently available for PC and UNIX ArcView users.  The Dialog Designer is available for the following operating systems:

• Windows 3.x
• Windows 95
• Windows NT
• Digital UNIX
• Hewlett-Packard
• IBM RS/6000
• SGI
• Sun Solaris

3.2 What Does the Dialog Designer Provide?

The Dialog Designer provides:

• a cross platform development environment that works on the PC, UNIX Workstation, and Macintosh.
• integrated dialogs that don't need to communicate with ArcView through Dynamic Data Exchange (DDE) or Remote Procedure Calls (RPC).
• direct access to and manipulation of ArcView components, such as tables, views, and themes.
• an easier way to distribute an application; everything can be included in an ArcView project or incorporated into an extension.

3.3 What can you do with the Dialog Designer?

With the Dialog Designer you can:

• Create specialized input forms
• Organize related tools in separate dialogs
• Add buttons directly to your view or layout
• Link what's displayed in a dialog directly to your data

3.4 How Does it Work?

To use the Dialog Designer extension, you first load it into ArcView just like any other ArcView extension.

To load the Dialog Designer

• Activate the ArcView Project window
• From the File menu, choose Extensions. This will bring up the Extensions dialog
• Check the box next to Dialog Designer in the Extensions dialog
• Press OK in the Extensions dialog

3.5 Working with dialogs

3.5.1 Add a Dialog to an ArcView Project

Once the Dialog Designer is loaded as an ArcView Extension, a new dialog is created by either double-clicking on the dialog icon in the project window or clicking the new button.

3.5.2 Dialog Editor Pull Down Menu

Dialog Properties

Dialogs have two kinds of properties; properties just like a view, table, theme or layout and properties just like all controls.  This section refers to the former.
 
 

Dialog Size

You can explicitly set the size of any dialog with the 'dialog size' setting under the dialog editor pull down menu.  The units measurements are given in (either inches or centimeters) is in actually units so if a dialog is programmed to be 6 x 6 inches it will appear on the screen that big.

Compile

    Dialogs must be compiled before they can be executed just like Avenue code.  A dialog can be compiled from the 'dialog editor' menu or via tool buttons.

Run

    Once a dialog is compiled it can be run from the pull down menu or the "running man" tool.
 

Write Text File

    The applications you build with the Dialog Designer will commonly contain numerous dialogs and scripts. How you choose to manage these components will depend upon how large an application you're building and how many people are working on it. If you're building a small application, you might choose to save your dialogs in an ArcView project. Alternatively, you could write them out to text files and store them in a version control system.  To write a dialog to a text file select the dialog as the current document and choose 'Write Text File...' from the dialog editor pull down menu.  This can also be done with the 'Write Text File' button.

Load Text File

    Once a dialog has been written out to a file, it can be read into an ArcView project with the 'Load Text File...' option of the dialog editor pull down menu.  This can also be done with the 'Read Text File' button.

3.5.3 What Controls are Available?

The Dialog Designer contains a number of different controls you can include on your dialogs.  If you are a Visual Basic, Delphi, Visual C++ or PowerBuilder programmer you may be used to having many more controls at your disposal.  This is a simple set of primary controls.  If you need others you will have to resort to other methods (i.e., have your application jump out to a Visual Basic program that does everything you need).

When a control has been added to a dialog, you can manually adjust the control's properties, size and alignment, control fasteners, or its location (i.e., bring to front and send to back).

3.5.4 Controls Pull Down Menu

Properties

Every control on a dialog, and the dialog itself, is defined by a set of properties that govern its behavior. For example, you set a property to define the text label of a check box, to set the upper and lower bounds of a slider, and to set the script to run when a user clicks a button. You can change the properties of a control two ways, either through the Control Properties dialog or by using specific Avenue requests. Typically, you'll use Avenue requests to change the state of your dialog while it's running (e.g., disable a control).

Control Properties Dialog Box

The control properties dialog box allows you to interactively change properties while you're editing a dialog.

Double-clicking a control on a dialog will bring up the controls properties.

Changing Control Properties with Avenue Requests

See section 3.6 Control Properties and 3.7 Avenue requests with Dialogs for a detailed description of dialog control properties.

Size and Align

The size and alignment menu choice for dialog controls helps you determine where to locate a control on a dialog and its relationship to other controls.  That is useful when you have more than one control that you'd like to be the same size and properly aligned.
 
 

Control Fasteners

Control fasteners allow you to determine how controls behave if the dialog is resized.  You can set a distance from the top and left of the dialog (or from the right and bottom) and the width and height of the dialog.  There is a default setting too as backup.
 
 

Bring to Front / Send to Back

Controls can be stacked on top of each other just like a graphic element in a layout.  The ‘bring to front’ and ‘send to back’ menu selections allow you to determine how controls are presented on a dialog.

3.6 Control Properties

Each control has a set of properties that dictate the appearance and behavior of that control.  Some properties are shared by more than one control (e.g., click) whereas other properties are special to one kind of control (e.g., auxincrement - for a slider bar).  As mentioned in section 3.5.2, dialogs have properties just like controls in addition to their document properties (like a view, table, layout or theme).
 
 

The Adobe Acrobat documentation that comes with the Dialog Designer has an appendix that describes all the properties for each control and states the avenue requests that deal with each particular property.

3.7 Avenue Requests with Dialogs
 
 

3.8.1 A Simple Dialog

A very simple starter example of a dialog is one with only one button that closes the dialog.  Create a new dialog. Change the title property of the dialog to 'Practice Dialog' and the name property to 'dog'.  Add a button control to the dialog.  Open the properties window for the button by whatever method you see fit.  Three of the eight properties should have something set.  Change the name of the button to 'btn1_Close'.  Change the help property to say 'This button will close the dialog'.  Add 'Bex' the dog as an icon to the button.  Add a textlabel control above the button.  Change the label for the textlabel control to "Close".  Compile the dialog and run it.  It looks fine but when you click on Bex what happens?

Question: What is missing?
Answer: A script tied to an event (i.e., button click event)

That script must be created and attached to the click event of the button.  Create an avenue script called testproject.dog.btn1_Close.click and type one line of Avenue code:

self.GetDialog.Close

3.8.2 Access a Dialog from the ArcView Interface

Let's assume that the dialog you just completed is finished.  You would now like to start that dialog from a button at the project level.  To accomplish that you must create a script that finds and opens the dialog you created and add a button to the ArcView project with the 'Project | Customize' menu.  Create a new script called testproject.dog.start:

theDialog = av.GetProject.FindDialog("dog").Open

Create a button at the project level and put this script as the click event for that button.

3.8.3 Naming Conventions

It is good practice to name all dialogs and controls in a similar fashion.  ESRI recommends beginning all names with the project they are affiliated with followed by the actual name of the dialog or control.  For example:

Myproject.Dialog1
Myproject.btn_Close

ESRI also recommends that you name all scripts descriptively so that from the title you can tell to which project it belongs, to what dialog or control it is tied and to what event it responds to.  For example,

Myproject.Dialog1.btn_Close.click

This script would run when the button named 'btn_Close' is clicked in Dialog1 of Myproject.

3.8.4 Making Controls Work Together

Controls within a dialog need to communicate with each other.  For example, if you have a dialog that is requesting information from the user, once that information is completed the dialog's OK button should be enabled.  How do controls communicate?

Create a new dialog and change its name property to 'ListBuilder'.  Add 2 label buttons, a text line control and a listbox control to the dialog.
 

'ListBuilder.Open script
'This script will
'1. Clear out the current list
'2. Disable the delete button
'
'find the list box called lbx_Current
theListBox = self.FindByName("lbx_Current")
'
'empty the list box
theListBox.Empty
'
'set the column width of the list
theListBox.GoColumn(0)
theListBox.SetColumnWidth(3)
'
'disable the delete button
self.FindByName("lbt_Delete").SetEnabled(false)

Compile that script and run it.  The dialog should be opened with a blank list and a disabled delete button.

Second, create the script that is attached to the done button (ListBuilder.lbt_Done.Click).  This will close the dialog.

'ListBuilder.lbt_Done.Click
'This script will close the dialog
'
self.GetDialog.Close

Compile that script and run the dialog.  You should now be able to close the click on the Done button and close the dialog.

Thirdly, create the script that is attached to the delete button (ListBuilder.lbt_Delete.Click) that will delete elements from the list.

'ListBuilder.lbx_Delete.Click
'This script will remove selected elements from the list
'when the delete button is clicked
'
'get the list from the dialog
theListBox = self.GetDialog.FindByName("lbx_Current")
'
'Delete the selected rows
theListBox.DeleteRows(1)
'
'check to see whether it should disable itself
theListBox.SelectCurrent(false)
  if (theListBox.GetRowCount = 0) then
    self.SetEnabled(false)
  end

Next create the script that will add elements to the list (ListBuilder.txl_add.Apply).

'ListBuilder.txt_Add.Apply
'This script will add what is typed into the text line to the
'list
'
'set an object equal to the current text in the txt_Add
aNewElement = self.GetText
'
'get the list box lbx_Current
theListBox = self.GetDialog.FindByName("lbx_Current")
'
'
theListBox.GoRow(theListBox.GetRowCount)
theListBox.InsertRows(1)
theListBox.SetCurrentValue (aNewElement)
self.SetText(" ")

Now create the script that enables the Delete button (ListBuilder.lbx_Current.Select) when elements are selected in the list.

'ListBuilder.lbx_Current.Select
'Atteched to the list box, this script enables the
'delete button
'
self.GetDialog.FindByName("lbx_Delete").SetEnabled(true)

Finally, add a button to the button bar and attach a script called ListBuilder.Run to its click event.  Rename the dialog to "ListBuilder".

'ListBuilder.Run
'Runs the dialog from the GUI
'
av.GetProject.FindDialog("ListBuilder").Open

3.9 Updating Controls with Broadcaster-Listener Relationship

In the previous exercise the delete button (lbx_Delete) was enabled by the ListBuilder.lbx_Current.Select script when list items were selected.  This is one way to enable and disable controls.  However, as the number of controls increases it becomes increasingly difficult to manage.

Suppose you have two controls on your dialog, a text line and a button.  When you enter text into the text line, you want to enable the button.  To do this, you use the control’s Update property.  The Update script associated with this property allows a control to respond to some change.  The mechanism that triggers the Update script (causing it to run) is an Update event. This is the same event that ArcView sends to controls on the button bar when, for example, you make a theme active.

While controls that are part of the document user interface respond automatically to Update events and run their Update scripts, controls on a dialog do not.  Instead, you programmatically control when an Update event is sent, and to which controls. Why is this different?  Because there is no automatic way for ArcView to know which controls should respond to an Update event.

In order for controls on a dialog to effectively use the Update event, you need to organize them into a broadcaster-listener relationship. In this example, the text line would be a broadcaster, and the button would be a listener.  Whenever you enter text into the text line, it would broadcast an Update event causing the button to run its Update script (that would presumably enable it).  You typically establish broadcaster-listener relationships in a dialog’s Open script.

'Open script
txtLine = self.FindByName("txl_Input")
btn1 = self.FindByName("lbt_OK")
txtLine.SetListeners({btn1})
 

A given broadcaster can have many listeners.  Thus, if other controls on your dialog also need to respond, you can add them to the list.  For example, if you have a few more buttons on your dialog:

txtLine.SetListeners({btn1, btn2, btn3})

The list of listeners is dynamic so you can add or remove controls at any time.

txtLine.AddListener(btn4)

Listeners need not be confined to a particular dialog either. They may be part of other dialogs or on ArcView’s menu, button, and tool bar.  To trigger the Update event, the broadcaster simply broadcasts an Update event. For example, the text line’s Apply script could contain this line:

self.BroadcastUpdate

All listeners will then run their Update scripts.

3.10 Add Controls Directly to Documents

In some circumstances (i.e., simple applications working with static datasets), it may make sense to add controls directly to a view or layout.  If the application is quite complicated this may not be appropriate.

When a view is active, select 'Window | Show Control Tools'.  This will provide a menu interface to all the controls provided with the Dialog Designer.
 
 

Controls can be selected from the menu and placed directly on the document.  The control will be treated as a graphic (use the 'GetGraphics' request in Avenue to select it) and will be managed with the view's object tag control.

3.11 Delivering Customizations

Customized dialogs can be disseminated as extensions, within ArcView projects directly, in a personal working environment or as a system default environment..

3.11.1 Dialogs in an Extension

Extensions are a good way to distribute your application if you will be using your dialogs with different projects or you plan to distribute them to others either within or outside your organization.  Search the ArcView on line help for " dialogs, distributing your application" for details.

3.11.2 Dialogs within a Project

If you’ve designed a dialog for a specific project and this is the only project that you will ever use it in, you can load the Dialog Designer into this project and create the dialog. The project would remain dependent on the Dialog Designer extension. Anyone who can access the Dialog Designer can load the project, and use and edit the dialog.

Suppose you want to distribute a project with dialogs, yet not let anyone see or edit the dialog editor documents. To do this, you can create a new project, based upon your original development project, that contains your dialogs but without the associated dialog editor documents. This new project is not dependent on dialog.avx, but instead on a special extension ($AVEXT/dlogcore.___) that loads only the dialog library into the project.

1. Make sure all the dialogs in your development project are compiled.
2. From the project’s File menu, choose Save Detached.
3. Choose ‘Yes’ to save your current development project. All changes that you’ve made to this project during this session will be saved.
4. Specify a name for the new detached project. Your current development project will be saved to the new project and the dialog editor icon will be         removed from the project window.

3.11.3 Dialogs in a Personal Work Environment

If you need access to your own dialogs every time you start ArcView, you could create a user default project in you working directory.

1. Open a project and load the Dialog Designer.
2. Create your dialogs and make any other changes to the interface you want.
3. From the project’s File menu, choose Save Detached to detach the project from the Dialog Designer.
4. Open your new detached project and choose Make Default from the Customize Dialog box.

If everyone in your organization will be using your dialogs in all their work, you could create a new system default environment. This is an easy way to deliver your dialogs without having to learn how to create an extension.

1. Open a project and load the Dialog Designer.
2. Create your dialogs and make any other changes to the interface you want.
3. From the project’s File menu, choose Save Detached to detach the project from the Dialog Designer.
4. In your new detached project, create and run a new script containing the following line of code:

Prefix this script’s name with a dot (.),  for example, .MyScript. This script creates a system default file in your home directory called asysdef.apr.

Copy this file into ArcView’s etc directory and name it default.apr.
 

4.0 ArcView Extensions

Changes to ArcView’s graphic interface and unique Avenue code can be packaged into an extension.  The benefits of extensions are that all unique work can be distributed within one file.  These files have an "*.avx" extension.

4.1 Create Extensions

ArcView provides an extension to assist you in creating your own extension.  This extension is called the "Extension Builder Sampler".  When loaded, this extension will added 3 template Avenue scripts that will assist you in making the extension and creating an install and uninstall script.  However, you must first create a project that contains the scripts, controls, documents, dialogs and any other objects you want to include in the extension.

4.1.1 Naming Conventions

By convention, save the project that contains all the customized changes that will be come the extension as <ExtName>.apr. (for example, "parcelview.apr").  Any scripts that you want to include in the extension should be named with a prefix that indicates the extension; for example, ParcelView.MyScript1.  This is recommended because scripts in a loaded extension appear in the ScriptManager and it is much easier to find and identify scripts when you follow this naming convention.

4.1.2 Extension Builder Sampler Extension

As mentioned earlier, the Extension Builder Sampler extension adds 3 template Avenue scripts that will assist you in making the extension and creating an install and uninstall script.

Make Script - This script contains the code that makes the extension object, sets its properties and populates it with the objects you wish to share. You run this script to create the extension object.

Install Script - The install script defines how the objects in the extension are installed into the current project when you create or open a project or when you load the extension. This script becomes a property of the extension. This script is optional, but if your extension has any objects besides scripts, you will probably need it.

Uninstall Script - The uninstall script defines how objects in the extension are removed from the project when you close the project or unload the extension. All objects that you add to the project in the Install script must be removed from the project in the Uninstall script. This script becomes a property of the extension. This script is optional, but if your extension has any objects besides scripts, you will probably need it.

To create the extension file, edit the three scripts by following the comments in the scripts.  When you want to make changes to the extension, first update this project file and then rerun the make script.

4.2 Avenue and Customized Extensions

An extension is a kind of object database that can be used to provide new functionality to ArcView without altering existing projects and to permit multiple individuals to contribute without conflict to a single ArcView-based development effort.  Extension objects have about 30 Avenue requests.

4.2.1 Extension Objects

An extension object is an abstract super class that defines a means for ArcView extension products to add properties to existing ArcView classes.  Extension object subclasses (DocumentExtension, LegendExtension, SrcExtension and ThemeExtension) are used to store ArcView extension product's specific environments with Documents, Themes, Legends and Srcs.  The four subclasses are abstract classes.  Each Extension product must define the four subclasses that define its special properties.

You use extension objects when you want to access particular properties included in ArcView extensions.

The Spatial Analyst requires special properties on the View document.  The Spatial Analyst defines a new class subclass of DocumentExtension called AnalysisEnvironment. The AnalysisEnvironment includes the definition of the grid cell size, the extent and the mask.  You can access these properties from the View with the request GetExtension and pass it the class AnalysisEnvironment.  This returns the AnalysisEnvironment object for this View.

analysisEnv = myView.GetExtension( AnalysisEnvironment )
cellsize = 0
analysisEnv.GetCellSize(cellsize)

You can query and manipulate the AnalysisEnvironment object using AnalysisEnvironment requests such as SetMask, SetCellSize, and SetExtent.

Extension products dynamically add special properties to existing classes using extension objects.  Document, Legend, FTab and Theme objects are given new requests from the extension object: GetExtension, SetExtension and RemoveExtension.  These requests are used to access the special properties defined for an extension product.  For example, if your view has a Grid Theme, you can get the AnalysisEnvironment for that view with the GetExtension request.  The argument to GetExtension is the class of the object.  GetExtension returns nil if there is no AnalysisEnvironment object.

The extension class itself provides six events that you can customize (Load, Unload, Install, Uninstall, CanUnload and ProjectSave). You can deliver any objects through an extension. Extension's dependencies on other extensions allow you to build upon other extensions.

There are many design options to consider and many different ways to build extensions.  Here are some examples:

• When an extension unloads, the project should be returned to its original state. The unload script should clean-up the results of the load script. The uninstall script should clean-up the results of the install script.
• Save any project specific information in the project's preferences dictionary.
• If your extension installs objects to project space or if the extension saves information to the project's preferences dictionary, save the extension's version number in the project preferences dictionary. You can use the version number to provide a migration path to the next version of the extension.
• Extension authors should be prudent with the use of global variables. If global variables are required, choose names that are unlikely to conflict with other extensions or projects.
• Extension authors should refrain from using object tags of objects that are not part of the extension.

4.2.2 Making Extensions with Dialogs

There are a few issues you should be aware of when creating an extension that contains one or more dialogs.  The Dialog Designer help suggests the following steps to disseminating dialogs in extensions using Avenue:

1. Open the project containing the customizations
2. Write the script that makes the extension
3. Write the scripts to load and/or install the extension
4. Write the script that determines whether the extension can be unloaded
5. Write the scripts to unload and uninstall the extension
6. Create the extension

4.2.3 Other Considerations

You need to be careful that extraneous information is not written out to an extension file.  For example, if a script in your source project sets an object tag and you test that script, ArcView will create the object tag.  If that object tag is attached to an object that gets incorporated into your extension (e.g., a dialog or menu item), it can cause problems in projects that load your extension.  The same is also true for customized DocGUIs.  If your extension delivers a customized DocGUI, it may contain extraneous information associated with the DocGUI.  All this information needs to be cleaned out prior to creating the extension (see page 31 of the Dialog Designer help manual)

5.0 Other Goodies

5.1 System Level Commands

Any command that you can execute by typing directly at the operating system prompt (e.g., UNIX or DOS prompt) can be used.  For example, you can start Excel and open a worksheet by typing something similar to the following at the DOS prompt:

   c:\excel\excel.exe  c:\data\sheet1.xls

You can perform the same task directly from ArcView by using the following script:

   System.Execute("c:excel\excel.exe  c:\data\sheet1.xls")

System.Execute does not provide true application interaction. It simply sends the string to the operating system for execution. System.Execute can be used effectively in hotlink scripts, to start other applications, and other cases where true inter-application communication is not necessary.

Hotlink to Netscape Script (using a system level command)
theVal = SELF
if (theVal.IsNull) then
    MsgBox.Warning("File "+theVal+" not found.","HTML Hot Link")
       else av.ShowMsg("Loading HTML browser, Please wait...")
       for each n in 1..1000 by 1
       av.SetStatus(n/10)
    end
System.Execute("C:\Program Files\NETSCAPE\NAVIGATOR\PROGRAM\NETSCAPE.EXE" ++ theVal)
      av.ClearMsg
end

5.2 Calling Scripts From Other Scripts

Avenue does not support procedures and functions, but it does allow you to call scripts from other scripts and even pass "arguments." There are three basic methods: av.run, av.DelayedRun and aScript.DoIt.

5.2.1 Run

The application request Run allows you to execute another script from within a script. Run takes two arguments; the first is the name of the script to execute and the second is the argument to this script.

The Run request searches for the named script in the project's embedded scripts and Script Editors, then the user default scripts, then any loaded extensions and finally the system default scripts. If it does not find the script, you get the error message "The script "<NAME>" could not be found" and returns the NIL object.

  results = av.run( "myScript", { "Rebecca", "Mustang", 96 } )

5.2.2 DelayedRun

av.DelayedRun is like av.run except actual execution of the called script occurs after a specified interval. The interval is in seconds. Use av.DelayedRun to implement periodic functionality or a timer. DelayedRun does not return a value.

'This script will:
'1. Open a message box
'2. Rerun the message box with the delayedrun request if
'   the answer is 'no'
'
status = MsgBox.YesNo( "Is this annoying?", "ANNOY", FALSE )
  if (NOT status) then
    av.DelayedRun( "5.2.2 DelayedRun", "", 1)
  end

5.2.3 DoIt

The third method to call a script from another script uses the script request DoIt. DoIt executes the target script and takes a single argument which becomes the argument (or SELF object) to the script on execution. DoIt returns the object specified in the target script's return statement.

DoIt is handy because it allows you to create and run scripts dynamically. For example, you could ask the user for her name and then create and execute a little script to greet her. 'This script will:

'1. Ask the user for their name in a message box
'2. Create another script on the fly and use the
'   results of the earlier message box in the new script
'
'Get the user's name
name = MsgBox.Input( "What is your name?", "Name", "" )
  'if they answered, create a new script and use their name
  if (name <> nil) then
    'create the script
    myScript = Script.Make(msgbox.info("Hello"++name,"GREETINGS").AsString)
    'Check for errors
    if (myScript.HasError.Not) then
      'if no errors then execute
      myScript.DoIt("")
    end
  end

The application startup script also employs this technique. Because the DDEServer class exists only on Windows, the request DDEServer.Start gives compile errors on UNIX and Macintosh platforms. With aScript.DoIt, startup compiles and executes based upon the current system.

5.3 Return versus Exit

5.3.1 Return

The return statement ends the current script and returns control to the calling script. The return statement is used to return control to a calling script and to pass back the result. The value specified in the return statement becomes the result of the calling run or doit request. If there is no particular result to return, return the nil object.

5.3.2 Exit

The exit statement ends execution of all scripts restoring control to the main event loop. Use exit to escape from an unrecoverable error.

Warning: The exit statement should never be used in scripts called from Appl.Initialize, project startup or any event triggered by a popup.

5.4 Recursion

Avenue is not recursive. If you attempt to execute a script recursively, you will get the following error message:  "Script ABCDE is already in the process of being executed."
 

Document's URL: http://www.cla.sc.edu/gis/avshtcrs/avenue3.html.   Page maintained by Paul Braun
 ©Copyrighted 1998 by the Board of Trustees of the University of South Carolina. All Rights Reserved. Last Updated on 6 April 1998 at  10:15 am EST by The College of Liberal Arts of the University of South Carolina.