Develop Better Applications
What You'll Need
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.
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.
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.
Figure 1: Properties for the Dialog Controls
|Type of Control||Name for Control||Label Property|
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.
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.
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.
To test your dialog, add a button to the ArcView GIS Table interface that launches the AddCity dialog.
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.
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 JanuaryMarch 2000 issue of ArcUser magazine. This article is available in PDF format from the ArcUser Online Web site (www.esri.com/arcuser/). See the user manual Using the ArcView Dialog Designer for information on creating working environments that use custom dialogs.
Troubleshooting the AddCity Dialog
If you have problems with this tutorial, check these items:
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)
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 ...
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")
vtbCities.SetValue (fldCapital, recNewCity, "N")
Msgbox.Info ("New Record Added", "Add City")