ArcUser Online

Develop Better Applications
with Dialog Designer

By Thad Tilton, Esri Instructor

Dialogs are nothing more than windows that contain controls. Anyone who has used ArcView GIS is familiar with dialogs. The ArcView Buffer Wizard, the Legend Editor, and the Identify Results dialogs are but a few examples of dialogs you have probably used. All of these dialogs make ArcView GIS easier to use by grouping related controls within a single, intuitive window.

Many custom Avenue applications require input from the user. All too often, simple message or input boxes are used for this purpose. However, by using the ArcView GIS Dialog Designer extension an Avenue developer can implement the same professional-looking dialogs used by standard ArcView GIS.

This tutorial will walk you through the process of producing a simple dialog. The dialog lets the user add a new record for a city to a table of cities using an intuitive interface that specifies field values. To simplify data entry, the dialog uses controls such as check boxes and combo boxes. A printer-friendly version of this page is available.

Start a New Project

1. Open a new ArcView GIS project.
2. In the project window, click on the Table icon, click on the Add button, and navigate to the location of the sample data that comes with ArcView GIS. Go to the Mexico subdirectory under Esridata and add a table of Mexican cities (cities.dbf) to the project.
3. Instead of working with the original table, copy this table. Make cities.dbf active and choose File > Export from the menu to make a copy of the table. Export this file in dBASE format and name it mexcities.dbf. Click the Add button and navigate to the location of mexcities.dbf to add it to the project.
4. Highlight cities.dbf in the project window and choose Project > Delete cities.dbf from the menu to remove cities.dbf from the project.
5. Choose File > Extensions, check the box next to Dialog Designer extension, and press OK to load the Dialog Designer extension. The Dialog Designer extension should now be added to your project. If you scroll to the bottom of the project window, you should see a new document type listed there-Dialogs.
6. Choose File > Save Project and save the project with the name ddlesson.

Create a New Dialog

Even a simple application will have numerous dialog boxes, scripts, and controls. If you do not use some method for managing all these items, keeping track of them during the development and any subsequent revisions of the application can be difficult. Consequently, it is a good idea to adopt a naming convention for these items that ensures that dialog or script names do not conflict with names already used by ArcView GIS or extensions. Giving scripts descriptive names and using standardized prefixes for control names will make them easy to locate and reference.

Change the name of the dialog box by changing the Title property.

For dialog names, use the name of the application as a prefix followed by the dialog name (e.g., if the dialog in this exercise was part of an application called City Update, it would be named CityUpdate.AddCity). For scripts, use the name of the dialog, followed by the control name and the property to which the script is attached (e.g., AddCity.AddRecord.Click). Name controls using the standardized prefixes such as lbt for label button and cbx for check box. A complete list of these prefixes is available in the online help for Dialog Designer or in the user manual Using the ArcView Dialog Designer.

1. Double-click the Dialogs icon in the project window. A new Dialog Editor window and new dialog box should appear. The default names for the window and box are Dialog1 and Title, respectively. Notice that when the Dialog Editor document is active, the interface changes and a new row of buttons appears. These tools are used to design and modify dialogs.
2. Choose Controls > Properties to view the property sheet for Dialog1. Property sheets are used to set the properties for each control added to the dialog box as well as properties for the dialog box itself.
3. Since this dialog box will be used to add a new record to a table of Mexican cities, change the name of the Dialog window from Dialog1 to AddCity by choosing Dialog Editor > Properties from the menu and changing the name.
4. Change the name of the dialog box itself by right-clicking on the title bar to bring up the properties sheet. Scroll down in the property sheet to the Title property and double-click on it. In the text box that appears, type "Add a new City record" as the new title.

Add Controls to the Dialog

1. Choose Window > Show Control Tools. This will bring up the floating toolbox of available dialog controls. To learn what each tool does, hover your mouse over a control and read the tool tip description.
2. From the toolbox, click on the Label Button control. The cursor changes to a crosshair. Move over to the dialog box and use the crosshair to draw a button on the AddCity dialog.
3. Double-click the new Label Button to view its properties in the property sheet. Change its name from aLabelButton1 to lblAddRecord and its Label to "Add Record." Resize and position the control in the lower right portion of the dialog.
4. Add, position, and set the properties for the other required controls listed in Figure 1. When adding the combo box, make sure you drag out an area for the box to drop down so that more than one of the combo box items will be visible. The combo box can overlap the text line control below it.

Figure 1: Properties for the Dialog Controls

Compile and Run the Dialog

Before attaching scripts the controls, compile the dialog to check the location of the controls.

The Dialog Editor interface contains the same Compile and Run buttons that are on the Script Editor interface. Dialogs, like Avenue scripts, must be compiled before they can be executed. Any change made in the Dialog Editor, such as adding, resizing, or changing control properties, requires that the dialog be recompiled. Once a dialog is compiled, you may test it by clicking the Run button. While this is useful for checking the layout of dialog controls, it is not generally useful for testing the dialog's code.

1. Compile the dialog by clicking the Compile button with the check mark icon or by choosing Dialog Editor > Compile from the menu.
2. Run the dialog by clicking the Run button, choosing Dialog Editor > Run menu, or hitting the F5 key.
3. Interact with the dialog controls-check the check box, pull down the combo box, type in the text lines. The controls already have the familiar behavior you expect, but no Avenue code has been written to make them work.
4. Hit the "X" in the upper right corner of the dialog to close it.

Write Scripts for the Dialog and Its Controls

After designing the dialog and placing the controls, the next step is to write Avenue scripts for performing tasks when the controls are activated. Many of the properties listed in the Dialog Editor property sheet can be set with a script. Just as you associate an Avenue script with the Click property on a button in a view GUI, you can assign scripts to certain properties of a dialog and its controls such as Open, Close, Activate, Click, and Select. The next step is to write a script that will execute when the dialog is opened and assign this script to the dialog's Open property.

1. Click on the Script icon in the project window to open a new Script Editor document. Choose Script > Properties from the menu and name the new script "AddCity.Open."
2. Type the code shown in Listing 1 into AddCity.Open and compile it.
3. Return to the Dialog Editor by clicking on the Dialog icon in the project window. Double-click the AddCity dialog to bring up its property sheet. Locate the dialog's Open property, then assign AddCity.Open as the Open script.
4. Remember--when you make any change in the Dialog Editor, you must recompile the dialog. Click the Compile button to recompile the AddCity dialog.

At this point, you could again test your dialog by clicking the Run button. In this case, however, ArcView GIS will generate an error because it cannot get a VTab from a Dialog Editor document. The AddCity.Open script assumes that the mexcities.dbf table is the active document. To adequately test this dialog, you must launch it from the Table interface while mexcities.dbf is active.

Create a Button to Launch the Dialog

To test your dialog, add a button to the ArcView GIS Table interface that launches the AddCity dialog.

1. Click on the Script icon in the project window to open a new Script Editor document. Choose Script > Properties from the menu and name the new script "AddCity.LaunchDialog." Type the following line of code in the script window and compile it by clicking the Check Mark button.

Av.FindDialog("AddCity").Open

2. Double-click anywhere on the toolbar that does not already have a button to bring up the Customize dialog box. In this dialog box, choose Table as the type and Button as the category.
3. Double-click on the Click property and scroll through the Script Manager to locate the AddCity.LaunchDialogAdd script. Select it to assign this script a new button to the Table interface.

Test the Dialog's Open Script

1. Open the mexcities.dbf table.
2. Make sure the mexcities.dbf table is active, then click your new button to launch the AddCity dialog. The dialog should open, and the combo box should be filled with all unique values from the table's State_name field.
3. Click on the dialog's State Name combo box. Scroll through the list to verify that all state names are listed.

Code to Create a New City Record

In the AddCity's Open script, you specified the active document (mexcities.dbf in this case) as the dialog's server. When a VTab is set as a server to a dialog, you can dynamically tie the dialog to data in a table. For example, as different records are selected in a table, the dialog can respond by updating the information it displays. When you set the server in the Open script, you used the syntax Dialog.SetServer(aVTab). To reference the server VTab, you will use the syntax vtbServer = Dialog.GetServer.

1. Open a new Script Editor document. Name it "AddCity.lbtAddRecord.Click".
2. Type the code in Listing 2 in this document. This code will add a new city record in the mexcities.dbf table. The values specified in the dialog will be used to populate the new record.
3. Compile the script.
4. Return to the Dialog Editor. Double-click the Add Record button to bring up its properties. Assign the script in Listing 2 (AddCity.AddRecord.Click) to the button's Click property.
5. Recompile the dialog.
With the mexcities.dbf table active, launch the dialog. Add a new record using the dialog. Make sure to provide appropriate values for each field-a string value for the new city's name and a number for the population. Choose a state from the combo box for the new city and check the box to make it the capital. You should get a message box confirming the new record. Close the dialog and check the table to verify that the record was added.

What's Next

Now that you have created this simple dialog, it is easy to see how you can create other dialogs for ArcView GIS applications using the other controls available in Dialog Designer. The dialog created in this tutorial will only be available to the project for which it was created. To distribute custom dialogs, you can create an extension containing custom dialogs or create a personal or systemwide working environment that includes custom dialogs. To learn how to make custom extensions, read "Creating Extensions the Easy Way" by Thad Tilton in the January-March 2000 issue of ArcUser magazine. See the user manual Using the ArcView Dialog Designer for information on creating working environments that use custom dialogs.

LISTING 1: AddCity.Open Script
'This script will run when the dialog is opened

'SELF refers to the dialog
vtbCities = av.GetActiveDoc.GetVTab
fldState = vtbCities.FindField("State_name")
cboStateName = SELF.FindByName("cboState")
cboStateName.DefineUniqueFromVTab(vtbCities, fldState, false, false, true)
SELF.SetServer(vtbCities)

LISTING 2: AddCity.lbtAddRecord.Click
'This code runs when the "Add Record" button is clicked ...
'SELF refers to the button
'-Reference all dialog controls ...
dlgAddCity = SELF.GetDialog
txtName = dlgAddCity.FindByName("txtName")
cboState = dlgAddCity.FindByName("cboState")
txtPopulation = dlgAddCity.FindByName("txtPop")
chkCapital = dlgAddCity.FindByName("chkCapital")

'-Reference the mexcities.dbf VTab and all required fields ... vtbCities = dlgAddCity.GetServer fldCityName = vtbCities.FindField("Name") fldStateName = vtbCities.FindField("State_name") fldPop = vtbCities.FindField("Population") fldCapital = vtbCities.FindField("Capital")

'-Add the new record, populate field values ...
vtbCities.SetEditable(true)
recNewCity = vtbCities.AddRecord
vtbCities.SetValue (fldCityName, recNewCity, txtName.GetText)
vtbCities.SetValue (fldStateName, recNewCity, cboState.GetCurrentValue)
vtbCities.SetValue (fldPop, recNewCity, txtPopulation.GetText.AsNumber)
if (chkCapital.IsSelected = true) then
vtbCities.SetValue (fldCapital, recNewCity, "Y")
else
vtbCities.SetValue (fldCapital, recNewCity, "N")
end
vtbCities.SetEditable(false)
vtbCities.Refresh
Msgbox.Info ("New Record Added", "Add City")