Copyright: Copyright (c) 1990-1998 ESRI, Inc.


Error message displayed when a topic is not found
Topic not available

Sorry, the topic you chose to display is not available in ArcView's help system.

To see ArcView's Help Contents, Index, and Find tabs, please click the Help Topics button.


Bring to Front

 Brings a selected control to the front of other controls.

To make a control fully visible that is partially visible behind another control, first select the control with the Pointer tool [image] and then click the Bring to Front button. If the control is completely behind another, select the visible control and choose Send to Back from the Controls menu.


Button tool

 Use a button to begin, end, or interrupt a process. Buttons are typically represented by an icon that indicates what it does. If you need to display text, use a label button instead.


Check Box tool

 Use a check box to provide a true/false or yes/no option on your dialog. When selected, the check box will appear checked.


Combo Box tool

 Use a combo box to provide a list of choices on your dialog when there is a minimum of space. The list of available choices drops down allowing you to select a choice.

The number of rows that drop down from the combo box is determined by the size of the bounding rectangle you make when you add the combo box to the dialog.


Compile

 Compiles the dialog in the active window.

Once you compile a dialog you can run it. If a dialog is the active window, clicking Run or F5 executes the current dialog. Run-time errors may still occur, in which case, ArcView generates appropriate error messages.


Control Fasteners

Displays a dialog that allows you to specify how the controls on your dialog are attached, or fastened, to it. The control fasteners govern what happens to a control when you resize your dialog. For example, if you enlarge your dialog, you might want a list box contained on the dialog to enlarge as well. The settings are only in effect when you run your dialog, not while you're designing it in the dialog editor.


Control Fasteners (Dialog box)

The Control Fasteners dialog allows you to specify how the controls on your dialog are attached, or fastened, to it. The control fasteners govern what happens to a control when you resize the window that contains your dialog.

Suppose you've placed a list box on your dialog. If you enlarge your dialog, the list box will, by default, not change size. However, you might want your list box to get larger as well. That way, you'll be able to see more of the information it contains. To do this, you set control fasteners for the list box as described in the first example below.

The following examples illustrate some common settings. These settings are only in effect when you run the dialog and not while you're designing it in a dialog editor.

 If you want a list box to enlarge as you enlarge your dialog, you would maintain the distance from the left and right sides of the dialog, and maintain the distance from the top and bottom of the dialog.

 If you want a button to stay the same size but always be positioned at the bottom of your dialog, you would maintain the width and height of the button, and also maintain the distance from the bottom of the dialog.

 If you want a control not to move or change its size, you would maintain its distance from the left and top of the dialog, and also keep the same height and width.

If you don't want someone to be able to resize your dialog at all, set the dialog's Resizable property to False on the Control Properties dialog.


Control Panel tool

 Use a control panel to organize related controls. For example, you might use a control panel to subdivide different options your dialog can perform.


Control Properties

Displays the properties for the selected control, or of the dialog itself. Once displayed, you can review and edit the properties of any control on the dialog by selecting the desired control from the drop-down list.

To get online help about the individual properties of a control, press F1 on the Properties dialog box.

You can also double-click on a control to view and edit its properties.


Control Properties (Dialog box)

Use the Control Properties dialog to change the properties of the individual controls on your dialog, or of the dialog itself.

Choose the control you want property descriptions of.

Button	List Box

Check Box	Radio Button

Combo Box	Slider

Control Panel	Text Box

The Dialog	Text Label

Icon Box	Text Line

Label Button	Tool

When adding controls to a view or layout, you'll see an additional option that allows you to specify how the control will react when you pan or zoom the map.

  Related topics


Control Tools (Dialog box)

Use the Control Tools dialog to add controls to a dialog, view, or layout. These are the same tools that are available on the tool bar of the dialog editor.

Simply select the control you want to add, then move the mouse over a dialog, view or layout.

Note	Due to a limitation in ArcView, you can’t add radio buttons and check boxes to a view.


Copy

 Copies the selected controls to the system clipboard.

Use Paste to paste the selection you copy.


Cut

 Cuts the selected controls and places them on the system clipboard.


Delete

Deletes the currently selected controls on the dialog. The controls removed with Delete are not placed into the clipboard. The existing contents of the clipboard, if any, are preserved.


Dialog Editor Properties (Dialog box)

Displays the properties of the dialog you are currently working on.

Name    The name of the dialog.

Creator    The name of the person who created the dialog.

Creation date    The date and time the dialog was created. This is recorded automatically and can't be edited.

Comments    Type any comments you want to store to document the dialog.


Dialog Properties

Lets you review and change the properties of the dialog you are currently working on such as the name of the dialog and comments describing what it does.


Dialog Size

Allows you to set the height and width of the dialog.


Icon Box tool

 Use an icon box to display an icon on your dialog. Create icons from one of the following file types:

 Windows Bitmap (.bmp)

 Gif (.gif)

 Tiff (.tif)

 X-Bitmap (.xbm).

 SunRaster (.rs)

 MacPaint (.mcp)

 Nexpert Object Image (.nbi)

 An Open Interface icon resource


Label Button tool

 Use a label button to begin, end, or interrupt a process. Label buttons contain a text label that indicates what the label button does. If you need to display an icon, use a button instead.


List Box tool

 Use a list box to present a list of choices to select from. A list box can contain many rows and columns and can be defined from a list object or a VTab.


Load Text File

 Loads a dialog and its associated scripts from a text file into a dialog editor. The text file must be an ODB (object data base) file created with the Write Text File button. By default, these files have a .ded extension.


Load Text File (Dialog box)

Loads a dialog and its associated scripts from a text file created with the Write Text File utility. Once you specify the text file to load, you can review the scripts associated with the dialog and decide whether or not to load them into the current project.


Next Control (Dialog box)

This dialog allows you to specify the control that will receive keyboard focus when the tab key is pressed. You might set this property when, for example, you have several text line controls on your dialog and want your user to be able to use the tab key to move between them in a specific order.

You can set the next control to one of the following controls: a text line, text box, list box, combo box, or slider.


Paste

 Pastes controls that have been copied or cut onto the clipboard.


Pointer tool

 Use this tool to select, move, and resize controls.

When you select a control, selection handles appear around it, at the extent (bounding box) of the control.

To select a particular control

 Choose the Pointer tool and click on the control with the mouse.

To select a number of controls

 Choose the Pointer tool and drag a box over them with the mouse. All the controls falling completely inside the box will be selected

To select additional controls

 Follow the instructions above but hold down SHIFT while you make your selection with the mouse. The additional controls will be selected.

To unselect all the selected controls

 Click anywhere on the dialog where there is not a control.

To select all controls at once

 Choose Select All from the Edit menu.

To access the properties of a control

 Double-click on a control to access its properties, or select the control and choose Properties from the Controls menu.

To move a control

 Choose the Pointer tool, click on the control and then drag it. You can also select the control and choose Size and Position from the Controls menu. This allows you to enter an exact position on the dialog for the control.

To move a number of controls

 When a number of controls are selected you can move them all at once by dragging any one of them. When one is moved, all the others will move as well.

To resize a control

 Choose the Pointer tool, click on the control and then drag one of its handles. Dragging a corner handle lets you preserve the aspect ratio of the control. Dragging a side handle lets you resize either vertically or horizontally.


Radio Button tool

 Use a radio button to present a set of mutually exclusive options. You group a set of radio buttons by drawing them inside a control panel. Selecting one radio button deselects the other radio buttons on the same panel.


Run

 Runs the compiled dialog.

Before you can run a dialog, you must first compile it.


Save Detached

Detaches the project from the Dialog Designer. This option creates a new project that contains all your dialogs but without the dialog editors and is not dependent upon the Dialog Designer extension.

To detach a project from the Dialog Designer

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.

Note  Once you’ve detached a project, keep the source project if you anticipate a need to edit the dialogs in the future. You can’t interactively edit the dialogs in the detached project.


Select All

 Selects all the controls on the dialog.

To select individual controls, use the Pointer tool.


Send to Back

 Puts a selected control behind other controls.

To put a control behind other controls, select it with the Pointer tool [image] and then click the Send to Back button.


Show Control Tools
Show/Hide Control Tools

Displays or removes the Control Tools dialog. Use this dialog to add controls to your dialog editor, view, or layout.


Size and Align

Sizes and aligns the selected controls in the dialog you are working on. You can align controls to the left, right, top, bottom or middle of the area in which the controls are located. Additionally, you can make controls the same size with equal spacing. Control height and width is specified in inches.


Slider tool

 Use a slider to set a value from a discrete range of continuous values.


Text Box tool

 Use a text box when you need to display or edit multiple lines of text. If you only need a single line, use the text line tool instead.


Text Label tool

 Use a text label to annotate your dialog. There is no user interaction with a text label; it simply displays static text.


Text Line tool

 Use a text line when you want to provide a single line for text input. If you need more than one line, use a text box instead.


Tool tool

 Use a tool when you need to interact with a document. A tool generally stays depressed when clicked, but usually nothing happens until you click somewhere in the active document. For instance, you'd use a tool if you wanted a user to specify an area on the display to zoom in to.


Write Text File

 Writes the current dialog and its associated scripts to a text file. Use this utility when, for example, you want to manage your dialogs in a source code version control system.


Write Text File (Dialog box)

Writes a dialog and its associated scripts to a text file. You might use this utility to transfer dialogs between project or to create a file that you can store in a source code version control system.

To write the text file, specify a File Name, and optionally a Dialog Name, a Creator, and Comments. Any changes you make to Dialog Name, Creator, and Comments will be written to the text file and to the current dialog you're editing. The scripts associated with the dialog are listed at the right of the dialog box. Check the box next to the script name to write it out to the text file.

This utility creates an ArcView ODB (object data base) file that contains the dialog and script objects.


Accessing dialogs

There are several different ways to access dialogs in a script. The way you choose will depend upon what you need to accomplish.

If you need to access a dialog editor document, you search for the document in the project much like you search for a view, script, or layout document.

av.GetProject.FindDoc("Dialog1")

This statement will return the DialogEditor object named Dialog1. Once you have the DialogEditor document you might then open or close it, access the controls on it, or compile it. If you want to find all the Dialog Editor documents in the current project, you could do this:

theDialogGUI = av.FindGUI("DialogEditor")

listOfDialogEditors = av.GetProject.GetDocsWithGUI(theDialogGUI)

for each d in listOfDialogEditors

  d.GetDialog.Open

end

While you typically create and edit dialogs through the DialogEditor document, you display, or run, Dialog objects. Use this request to find a dialog in the current project or any loaded extensions:

av.FindDialog("Dialog1")

If you want to restrict your search to dialogs within the current project, do this:

av.GetProject.FindDialog("Dialog1")

Given a Dialog object, you run it by sending it the Open request.


Adding controls to a dialog

Controls are the interface components you place on your dialog. You can add controls interactively by selecting the one you want on the tool bar and placing it on your dialog, or you can add them programmatically through scripts.

How do you want to add a control to your dialog?

Interactively with the mouse

With a script


Adding controls to views and layouts

In addition to placing controls on dialogs, you can also place them on views and layouts. This allows you to merge the controls that manipulate the map with the map itself, providing a more intuitive and interactive experience for a map user. For example, you might place buttons directly on top of a view to allow a user to change the view in some way.

How do you want to add a control to your view or layout?

Interactively with the mouse

With a script


Attaching a dialog to ArcView's interface

Once you've built a dialog, you'll want to make it available through ArcView's interface. You display a dialog by calling it from a script attached to a control on ArcView's menu, button or tool bar. For example, you can add a new button to the interface through the Customize Dialog and attach the following Click script to it:

av.FindDialog("My Dialog").Open

This request searches for the dialog in the current project, then in any loaded extensions. Alternatively, if you only want to search the current project, do this:

av.GetProject.FindDialog("My Dialog").Open


Canunload script for an extension with dialogs

The Canunload script checks to see if your extension can be unloaded.

 Check whether the dialog library, avdlog.dll, can be unloaded.

 You can use the extension's dependencies list to reference avdlog.dll when you check to see if it can be unloaded. For example, if avdlog.dll is the first item in the dependencies list of the extension in your Make script, use self.GetDependencies.Get(0) to reference that library, where the self object is the extension object.

 Here is a sample Canunload script:

' MyDialogExt.CanUnload

return (System.CanUnloadLibrary(self.GetDependencies.Get(0)))


Checking for errors

What should you do if your dialog doesn't work? Here are some things to look for.

If you see an error message display, it usually means that there's an error in one of your scripts. The script with an error should open and indicate the line with the problem. Correct the problem and recompile the script.

If you don't get an error message, yet your dialog still doesn't work as expected, you probably have some logic error. The first thing to do is check the control properties. Make sure scripts are attached to the correct properties, and that they reference the correct script. Check your scripts to make sure they're doing what you expect. It's often useful to use the MsgBox class to examine variables. Unfortunately, you can't use the script debugging tools to step through scripts attached to dialog events.


Compiling and running a dialog

To display your dialog you first need to compile it.

How do you want to compile and run your dialog?

Interactively through the interface

With a script


Creating a multipanel dialog
Creating a multi-paneled dialog

Suppose you have a task that requires a series of steps to complete. To make it easier for an end user to complete the task, you want to lead them through the process with a dialog. You could create a dialog for each step and display them sequentially, or instead you could create a single dialog with a different panel for each step.

To build a multi-paneled dialog such as this, you need to lay out each panel side-by-side in the dialog editor, placing the controls required for a step on the appropriate panel. When you run your dialog, you can use the Open script to align all the panels, making the first one visible and hiding the rest.

Here's an example of a two-paneled dialog.

1	Create a dialog and add a control panel to it defined as follows:

Control	Property	Setting

Control panel	Name	cpa_PanelOne

Label	aControlPanel1

Update	Panels.cpa_PanelOne.Update

2	Copy and paste the control panel, creating a new one of the same size. Place the two control panels side by side with this second one outside of the dialog frame. Define its properties as follows:

Control	Property	Setting

Control panel	Name	cpa_PanelTwo

Label	aControlPanel2

Update	Panels.cpa_PanelTwo.Update

3	Add a label button to each control panel, placing a 'Next' button on the first panel and a 'Back' button on the second panel. Define each button as follows:

Control	Property	Setting

Label button	Name	lbt_Next

Click	Panels.lbt.Click

Label	Next

Label button	Name	lbt_Back

Click	Panels.lbt.Click

Label	Back

4	Set the dialog's Open script to the following:

'Open script

Next = self.FindByName("lbt_Next")

Back = self.FindByName("lbt_Back")

aPanel = self.FindByName("cpa_PanelOne")

aPanel2 = self.FindByName("cpa_PanelTwo")

'Set Listeners. This section defines the order of control panel display

Next.SetListeners({aPanel, aPanel2})

Back.SetListeners({aPanel, aPanel2})

'Align panels, making the second invisible

aPanel.MoveTo(10,10)

aPanel2.MoveTo(10,10)

aPanel.SetVisible(true)

This script establishes the relationship between the label buttons and the control panels, defining the next panel to appear when you press a label button. Notice that the Open script is also where you align the control panels. You can easily extend this logic in this script to handle more control panels.

5	Write the following scripts.

'Panels.cpa_PanelOne.Update - Shows/hides control panels depending

'upon broadcaster

self.SetVisible(self.GetBroadcaster.GetName = "lbt_Back")

'Panels.cpa_PanelTwo.Update - Shows/hides control panels depending

'upon broadcaster

self.SetVisible(self.GetBroadcaster.GetName = "lbt_Next")

'Panels.lbt.Click - displays next panel

self.BroadcastUpdate

The main purpose of these scripts is to show a particular control panel while hiding the other.


Creating dialogs

There are several different ways you can create a new dialog. Typically you'll use ArcView's interface to do so but you can also create dialogs through Avenue scripts, for example, when you want to create a template dialog or when your application requires you to create a dialog "on-the-fly."

How do you want to create a new dialog?

Through the interface

With a script


Deleting controls on a dialog

Delete a control when you no longer want it to be part of your dialog.

How do you want to delete a control?

Interactively using the mouse

With a script


Deleting controls on views and layouts

Delete a control on your view or layout when you no longer need it.

How do you want to delete a control?

Interactively using the mouse

With a script


Dialog Designer Avenue class hierarchy

Obj

    Window

        Dialog

        PropWin

    Doc

        Layout

            DialogEditor

    Graphic

        GraphicControl

    Control

        ControlSet

            ControlPanel

        Tool

        Button

        LabelButton

        CheckBox

        ComboBox

        IconBox

        ListBox

        RadioButton

        Slider

        TextBox

        TextLabel

        TextLine


Dialog naming conventions

When developing an application, the number of dialogs, controls on dialogs, and scripts associated with dialogs gets quite large. Keeping track of all these components can be difficult if you don't establish some method for managing them. One convention to set in place early is a naming convention that will make it easy to find and reference these components.

What do you want to name?

Controls on a dialog

Scripts associated with a dialog

The dialog itself


Distributing your application

Depending upon your application, there are several different ways to distribute your custom dialogs. If you’ll be using your dialogs with different projects or you plan to distribute them to others either within or outside your organization, you could create an ArcView extension. If you’ve designed your dialogs for a specific project, you could store and deliver them in that ArcView project. If the functionality in your dialogs is something that only you’ll use, you could create a personal working environment. If everyone in your organizations needs your dialogs for their work, you could create a system default environment.

How do you want to distribute your application?

In an extension

In a project

With a personal working environment

With a system default environment


Drawing lines boxes and circles
Drawing lines, boxes, and circles on dialogs

The Dialog Designer does not currently support drawing graphic elements, such as lines, boxes, and circles, on dialogs.


Events controls respond to
Events that controls respond to

Each control on the dialog can respond to certain kinds of interactions, or events, and run scripts. Here's a list of events that controls respond to and how they are triggered. Use the Related Topics button at the bottom of this topic for more information on these events. (Note: don't use the Exit request in any event scripts attached to a dialog; use Return instead.)

Label Buttons, Buttons and Tools

 Apply (Tool only) - triggered by clicking the mouse on a document.

 Click - triggered by clicking on the control.

 Update - programmatically triggered by some change on the dialog.

Text Line and Text Box

 Apply (Text Line only) - triggered by pressing the RETURN key.

 Changed - triggered by any change in the text in the control.

 Click - triggered by clicking on the control.

 Empty - triggered when the control is cleared or first typed into.

 FocusLost (Text Line only) - triggered by pressing TAB key or moving the mouse from the text line.

 Update - programmatically triggered by some change on the dialog.

List Box and Combo Box

 Apply (List Box only) - triggered by double-clicking a cell.

 RangeApply (List Box only) - trigger by double-clicking a specific cell or group of cells. Use the SetRangeApply request to set the script to run.

 RangeSelect (List Box only) - triggered by selecting a particular cell or group of cells. Use the SetRangeSelect request to set the script to run.

 Select - triggered by selecting or deselecting a cell.

 Update - programmatically triggered by some change on the dialog.

Check box and Radio Button

 Click - triggered by clicking on the control.

 Update - programmatically triggered by some change on the dialog.

Slider

 Click - triggered by clicking on the control.

 Drag - triggered by dragging the slider handle.

 Update - programmatically triggered by some change on the dialog.

Text Label, Icon Box and Control Panel

 Update - programmatically triggered by some change on the dialog.

  Related topics


Events the dialog responds to

The dialog itself can respond by running a script when certain events occur . Here's a list of events that a dialogs responds to and how they are triggered. Use the Related Topics button at the bottom of this topic for more information on these events. (Note: don't use the Exit request in any event scripts attached to a dialog; use Return instead.)

 Activate - triggered when the dialog becomes active.

 Close - triggered when the dialog closes.

 DocActivate - triggered whenever a document becomes active.

 Open - triggered when the dialog opens.

 Resize - triggered whenever the dialog window is resized.

 ServerActivated - triggered when the dialog's server document activates.

 ServerClosed - triggered when the dialog's server document closes.

 ServerDeactivated - triggered when the dialog's server document deactivates.

 ServerDefinitionChanged - triggered when the definition changes in the dialog's server VTab.

 ServerOpened - triggered when the dialog's server document opens.

 ServerRecordsAdded - triggered when records are added to the dialog's server VTab or Table document.

 ServerRecordsDeleted - triggered when records are deleted from the dialog's server VTab.

 ServerSelectionChanged - triggered when the selection changes on the dialog's server VTab.

 Update - programmatically triggered by some change on the dialog.

  Related topics


The self object in event scripts

The self object always refers to the control or dialog the event script is attached to. For instance, in the dialog's Open script, the self object is the dialog; in a button's Click script, the self object is the button. This makes it a easier to write Avenue code in event script. For example, you can disable a control in the control's Update script using the self object instead of writing additional code that finds the particular control object on the dialog.

self.SetEnabled(false)

instead of

av.FindDialog("Dialog1").FindByName("aButton1").SetEnabled(false)


Event scripts

Each control on a dialog can run a script when a particular event happens, such as clicking a button or entering a carriage return on a text line. Through events, you control what your dialog does. Additionally, the dialog itself can respond to certain events that occur in ArcView, such as you open a document or make a document the active document.

What event scripts do you want to learn about?

Control event scripts

Dialog event scripts


Executing an action

The primary reason for building a dialog is to perform an action, or task. When you click a button on ArcView's button bar, it runs the associated script that performs a particular action. The same is true for controls on a dialog--you attach scripts to them to perform an action. The difference is, not every control on the dialog has to perform an action.

When you build a dialog, you determine how the dialog will perform its particular task. For example, you could immediately execute an action upon typing into a text line, or you could wait until a user presses an OK button. Each control on a dialog can run a script when a particular event happens, such as clicking a button or entering a carriage return on a text line.

What do you want to learn about?

Events that controls respond to

Events the dialog responds to

The self object in event scripts


Finding controls on views and layouts

If you want to alter a control through a script, you first need to find it on the view or layout. The controls that you place on top of views and layouts are part of the document's graphic list. This is the same graphic list that references all graphic elements. Thus, to find controls, you search the graphic list. Here's how you can find a control with a specific name:

theDoc = av.GetActiveDoc

theGraphicList = theDoc.GetGraphics

aButton = theGraphicList.FindByName("aButton1")

Given a graphic control, like the button above, you might then want to display the Control Properties dialog and adjust its properties:

aButton.Edit(theGraphicList)

Or you may want to move it:

aButton.Invalidate

aButton.Offset(1@1)

aButton.Invalidate

To find all controls, you can do this:

allControls = theGraphicList.FindAllByClass(GraphicControl)


Functional overview of Dialog Designer classes

Object Model diagram

Loading the Dialog Designer adds several Avenue classes and extends some existing classes.

Dialog

The Dialog class 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. A dialog is a modal or modeless window that contains controls. This window is not clipped to the ArcView main application window. It can be dragged anywhere on the computer screen. You can create dialogs interactively using a Dialog Editor document or by sending the Make request to the Dialog class, then adding controls to it using other requests.

DialogEditor

The Dialog Editor class, a subclass of Layout, lets you interactively create dialogs. Instead of letting you manipulate graphic shapes and frames positioned on a "page", it lets you manipulate graphic controls positioned inside a "dialog". The frame inside the dialog editor window represents the visible portion of the dialog. You can size the frame as needed to fit all your controls.

GraphicControl

A GraphicControl is a kind of graphic that lets you place controls objects on view or layout documents. By using graphic controls in these documents, you can merge the controls that manipulate the map with the map itself, providing a more intuitive and interactive experience for a map user.

PropWin

A PropWin is a modeless window that displays properties for controls embedded within graphic controls. Only one PropWin exists. Reference it using the class request PropWin.The. The PropWin instance is normally displayed when you double click or right-click on a selected graphic control.

Control

The Control class is the abstract class defining ArcView's user interface controls: menu choices, buttons, tools, spaces, and the ControlSets. The Dialog Designer extension adds more controls that can be used in dialogs or as graphic controls on views and layouts.

ControlSet

ControlSet is the abstract class which defines general properties and methods for collections of Controls. To be displayed in the DocGUI, a Control must belong to a control set. Each DocGUI contains 3 ControlSets: a MenuBar, a ButtonBar and a ToolBar. In dialogs, controls can be organized in a control set called a control panel.

ControlPanel

A ControlPanel is a kind of ControlSet that organizes controls in two dimensions inside a Dialog, rather than linearly inside a DocGUI. When you add a control to a control panel, you specify the bounding box for that control (rather than its index relative to other controls).

Tool

A Tool control provides a means of interacting with the document display. A tool supports a special event, the Apply event. The Apply event triggers whenever the user clicks on the active document display. Tools display icons. Tools can be used on the ToolBars of DocGUIs, in dialogs, and or as graphic controls on views and layouts.

Button

A Button control displays an icon and recognizes the Click event. A Click event occurs when the user clicks on a button or when an Avenue script issues the Button Click request. Buttons can be used on the ButtonBars of DocGUIs, in dialogs, or as graphic controls on views and layouts.

LabelButton

A LabelButton control is a button that display text rather than icons. Label Buttons recognize the Click event. Label buttons are found at the top of the project window. They can also be used in dialogs or as graphic controls on views and layouts.

CheckBox

A CheckBox control displays a Boolean value. A true value is represented by a checked box. A false value is represented by an unchecked box.

ComboBox

A ComboBox control provides an interface for selecting an object from a list of related objects. A combo box consists of a set of rows, each of which is associated with a single object of any kind. One row is always presented to the user. This is the selected row. When the user wants to select another row, they click on a part of the combo box in order to drop-down a single-column, scrolling list that shows all rows in the combo box. The contents of a combo box can be defined from a list, dictionary, or VTab.

IconBox

An IconBox control displays an icon. The user cannot interact with an icon box. An icon box is associated with an ArcView Icon object. Refer to that class for a description of the supported image types.

ListBox

A ListBox control provides an interface for examining data organized into multiple rows and columns. Each row and column intersection is called a cell. The object attached to a cell is referred to as a cell value. Zero or more cells can be selected. The contents of a list box can be defined from a list, dictionary, or VTab.

RadioButton

A RadioButton control cooperates with other radio buttons to show the selected choice in a small number of possible choices. Each radio button has a label that names one possible choice. Related radio buttons are placed in a control panel and the control panel automatically makes sure that only one radio button in the group is selected at a time.

Slider

A Slider control displays a selected value in a range of real-values defined over a finite interval. A slider has a vertical or horizontal slot that represents the range of values. Its thumb shows the current value.

TextBox

A TextBox control presents an interface for displaying and/or editing multiple lines of text.

TextLabel

A TextLabel control is a group of words appearing in a dialog that provides information about a part of the dialog. The user does not interact with a text label.

TextLine

A TextLine control is a single line of editable text, optionally including a label.


Dialog Designer (Avenue object model diagram)
Dialog Designer


Initializing controls on views and layouts

Just as a dialog has an Open script, views and layouts also have their own Open script. It's in the Open script that you put the Avenue code to initialize controls on your view or layout. You have to write a script to set the Open script for a view or layout as there is no way to do so through ArcView's interface. Here's a script that sets the Open script for a view:

av.FindDoc("View1").SetOpenScript("MyViewOpenScript")

The Open script can contain Avenue statements to initialize the controls on the view. Every time the you open the view, this script runs.

To set a property for a control on the view, you first find the control by searching for it by name in the view's graphic list.

'Open script attached to a view.

'Self object is the view.

System.RefreshWindows

aTextLine = self.GetGraphics.FindByName("aTextLine1").GetControl

aTextLine.SetText("HI")

aListBox = self.GetGraphics.FindByName("aListBox2").GetControl

aTheme = self.GetThemes.Get(0).GetFTab

theFields = aTheme.GetFields

aListBox.DefineFromVTab(aTheme, theFields, false)

System.RefreshWindows

Notice that you use the GetControl request to get the Control object of the graphic control. Through the Control object, you can manipulate all of the properties of a control.

The Open script is also a place where you might establish broadcaster-listener relationships between controls on your view or layout.

Note	This script executes the System.RefreshWindows request twice; once at the beginning of the script and once at the end. This is a workaround to a known limit. Include it in your scripts when you manipulate the properties of a list box.


Known issues with the Dialog Designer

The horizontal scroll bar on a list box scrolls a column at a time.

Screen resolution can affect icon display.

Default control names may not be unique.

Radio buttons don't have a default choice exposed on the control properties dialog.

Combo box tool tip doesn't appear over the combo box.

The NextControl property doesn't include buttons or check boxes.

Dialogs position incorrectly on the screen on UNIX.

Avoid using the Exit request in scripts associated with a dialog.

Avoid using the Undo menu item to remove a control added to a view or layout.

Pressing F1 over a dialog editor displays the wrong help file.

Can't unload the Dialog Designer extension when the 3D Analyst extension is also loaded.

Modal dialogs always have a title bar.

The listener list for label buttons, push buttons and tools is not persistent.

Populating aCombobox using the large elements of aList is slow.


Dialog Designer Known Issue
The horizontal scroll bar on a list box scrolls a column at a time.

If the text in a particular column of a list box is wider than the list box, the horizontal scroll bars don't reveal more of the text. Instead, the scroll bars will scroll to the next column. Your only option is to make the list box wider to accommodate the length of text you want to display. (SDBsn53460)


Dialog Designer Known Issue
Screen resolution can affect icon display.

The size of an icon box is constant but the amount of an image displayed in that icon will vary depending upon screen resolution. For example, the amount of an image displayed in a 1" by 1" square icon box will be greater on higher resolution displays. (SDBsn51341)


Dialog Designer Known Issue
Default control names may not be unique.

ArcView attempts to generate unique names for controls added to dialogs within a given ArcView session. However, if you open an existing project and start adding controls to dialogs, the names ArcView gives to controls may not be unique. In general, it's better to explicitly name your controls instead of relying on the default naming convention. (SDBsn51916)


Dialog Designer Known Issue
Radio buttons don't have a default choice exposed on the control properties dialog.

To make a particular radio button the default radio button on a dialog, you need to set it in the dialog's open script using aRadioButton.Select. (SDBsn50167)


Dialog Designer Known Issue
Combo box tool tip doesn't appear over the combo box.

A combo box tool tip will appear at the bottom of the pulled down area of the combo box. Thus, they don't appear to be associated with the combo box. There is no workaround for this issue. (SDBsn54472)


Dialog Designer Known Issue
The NextControl property doesn't include buttons or check boxes.

These controls can't accept keyboard focus with NextControl. There is no workaround for this issue. (SDBsn54104)


Dialog Designer Known Issue
Dialogs position incorrectly on the screen on UNIX.

The 0,0 coordinate of the screen is offset slightly from the true upper-left corner of the screen. Thus, when you attempt to position a dialog, it will be offset roughly by the height of the title bar on the dialog window. Adjust the coordinates as necessary to correctly position the dialog.  (SDBsn51326)


Dialog Designer Known Issue
Avoid using the Exit request in scripts associated with a dialog.

Using the Exit request in a script associated with a dialog can cause a dialog to stop working properly. Use Return Nil instead. (SDBsn56230)


Dialog Designer Known Issue
Avoid using the Undo menu item to remove a control from a view or layout.

Undo only removes the graphic representation of the control, not the actual control object. To remove a control from a view or layout, select it then press the Delete key. (SDBsn53300)


Dialog Designer Known Issue
Pressing F1 over a dialog editor displays the wrong help file.

To get context sensitive help about the dialog editor, use the help button instead of pressing the F1 key over the dialog editor window. Clicking the Help button will change the cursor to a question mark that you can then click over the dialog editor window to display context sensitive help. (SDBsn50910)


Dialog Designer Known Issue
Can't unload the Dialog Designer extension when the 3D Analyst extension is also loaded.

The 3D Analyst uses the functionality provided by the Dialog Designer. You must unload the 3D Analyst first, then unload the Dialog Designer. (SDBsn55338)


Dialog Designer Known Issue
Modal dialogs always have a title bar.

A modal dialog will always have a title bar, even though you set the HasTitleBar property to false. (SDBsn48741)

Pressing the "X" on a modal dialog’s title bar does not execute the dialog’s close script. (SDBsn60743)


Dialog Designer Known Issue
The listener list for label buttons, push buttons and tools is not persistent.

The listener list for label buttons, push buttons and tools is not persistent when these controls and the dialog that they are attached to are created with a script. (SDBsn69629)


Dialog Designer Known Issue
Populating aCombobox using the large elements of aList is slow.

Populating aCombobox using a list with a large number of elements, such as a list of 25,000 items, is slower in Arcview 3.1 than in Arcview 3.0. (SDBsn67324)


List of available controls

 Button. Use a button to begin, end, or interrupt a process. Buttons are typically represented by an icon that indicates what it does. If you need to display text, use a label button instead.

 Check box. Use a check box to provide a true/false or yes/no option on your dialog. When selected, the check box will appear checked.

 Combo box. Use a combo box to provide a list of choices on your dialog when there is a minimum of space. The list of available choices drops down allowing you to select a choice.

 Control panel. Use a control panel to organize related controls. For example, you might use a control panel to subdivide different options your dialog can perform.

 Icon box. Use an icon box to display an icon on your dialog. Create icons from one of the following file types: Windows Bitmap (.bmp), Gif (.gif), Tiff (.tif), X-Bitmap (.xbm), SunRaster (.rs), MacPaint (.mcp), Nexpert Object Image (.nbi), an Open Interface icon resource.

 Label button. Use a label button to begin, end, or interrupt a process. Label buttons contain a text label that indicates what the label button does. If you need to display an icon, use a button instead.

 List box. Use a list box to present a list of choices to select from. A list box can contain many rows and columns and can be defined from a list object or a VTab.

 Radio button. Use a radio button to present a set of mutually exclusive options. You group a set of radio buttons by drawing them inside a control panel. Selecting one radio button deselects the other radio buttons on the same panel.

 Slider. Use a slider to set a value from a discrete range of continuous values.

 Text box. Use a text box when you need to display or edit multiple lines of text. If you only need a single line, use a text line instead.

 Text label. Use a text label to annotate your dialog. There is no user interaction with a text label; it simply displays static text.

 Text line. Use a text line when you want to provide a single line for text input. If you need more than one line, use a text box instead.

 Tool. Use a tool when you need to interact with a document. A tool generally stays depressed when clicked, but usually nothing happens until you click somewhere in the active document. For instance, you'd use a tool if you wanted a user to specify an area on the display to zoom in to.


Loading the Dialog Designer

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

To load the Dialog Designer

1	Activate the ArcView Project window.

2	From the File menu, choose Extensions. This will bring up the Extensions dialog.

3	Check the box next to Dialog Designer in the Extensions dialog. If you want the Dialog Designer extension to load automatically every time you start ArcView, press the Make Default button after checking the Dialog Designer. The next time you start ArcView the Dialog Designer will automatically load.

4	Press OK in the Extensions dialog.

Once you've loaded the extension, you'll notice a new document in the project window called Dialogs. Double-click it and you'll create a new dialog editor document that's ready to accept the interface components you want on your dialog--for example, buttons, sliders, and check boxes.


Load and Install script for an extension with dialogs
Load and Install scripts for an extension with dialogs

As you create your extension, you need to consider how your customizations will get added to ArcView when a user loads it. When you open the Extensions dialog and check an extension, two scripts run: the Load script and the Install script.

Load script

The Load script executes once when an extension file loads into ArcView. Use this script to specify any one time only initializations such as establishing some environment or initializing global variables. Nothing special needs to be done to load an extension containing dialogs.

Install script

The Install script executes when you first load the extension and every time you open a project or create a new project during that ArcView session. The Install script defines how the extension objects are installed into the current project.

 The Install script doesn't need to install any dialogs or scripts referenced by the extension into the current project. ArcView will automatically search through any loaded extension for the dialogs and scripts.

 Here is a sample Install script:

' MyDialogExt.Install

' Only install user interface components if a project is open

if (av.GetProject = nil) then

  return nil

end

' Retrieve the button from the extension (self) and add it after the first

' button in the View button bar

myButton = Self.Get(1)

viewGUI = av.GetProject.FindGUI("View")

viewGUI.GetButtonBar.Add( myButton, 0 )

viewGUI.SetModified(TRUE)

The Install script adds extension objects to the current project; thus, if there isn't an open project, the script ends. If there is, this Install script adds the button to the View's DocGUI. The Install script retrieves the objects from the extension in the same order that you added them to it. For example, if the button was the second object added to the extension in the Make script, then you would retrieve it using Self.Get(1), where the self object is the extension object.


Make script for an extension with dialogs

The Make script builds the extension. This script retrieves the objects that you want to deliver from the source project and writes those objects out to the extension file (.avx).

 All extensions that contain dialogs must be dependent upon either the ESRI dialog library, avdlog.dll or the Dialog Designer Extension, dialog.avx. If you want the users of your extension to have access to the dialog editor in addition to your dialogs, use $AVEXT/dialog.avx in the dependencies list. If your extension delivers complete dialogs that users will not edit, use $AVBIN/avdlog.dll in the dependencies list.

 You will run this Make script after you have written all the other scripts the extension needs: the Install, CanUnload, Uninstall, and Unload scripts.

 Here is a sample Make script for an extension that delivers one dialog called MyDialog and a button on the View GUI.

' MyDialogExt.Make

' Make the extension object

MyDialogExt = Extension.Make("$USEREXT/MyDialogExt.avx".AsFileName,

   "My Dialog Extension",

   av.FindScript("MyDialogExt.Install"),

   av.FindScript("MyDialogExt.Uninstall"),

   {"$AVBIN/avdlog.dll".AsFileName})

MyDialogExt.SetExtVersion(1)

MyDialogExt.SetAbout("My first dialog extension (v1) ")

MyDialogExt.SetUnloadScript(av.FindScript("MyDialogExt.Unload"))

MyDialogExt.SetCanUnloadScript(av.FindScript("MyDialogExt.CanUnload"))

' Retrieve the MyDialog dialog from the project and add it to the

' extension

MyDialogExt.Add(av.FindDialog("MyDialog"))

' Retrieve the View button that launches the dialog and add it to the

' extension

MyDialogExt.Add( av.FindGUI( "View").GetButtonBar.GetControls.Get(1))

' Retrieve all the scripts for the dialog, make sure they are all complied,

' and then add them to the extension. Assumes that the scripts are prefix by

' "MyDialog"

for each aDoc in av.GetProject.GetDocs

  if (aDoc.Is(SEd)) then

    if (aDoc.GetName.Contains("MyDialog.")) then

      if (aDoc.IsCompiled.Not) then

        aDoc.Compile

      end

      MyDialogExt.Add(av.FindScript(aDoc.GetName))

    end

  end

end

' Write the extension to file

MyDialogExt.Commit

This script first makes the extension object (MyDialogExt) using the Extension.Make request. The parameters for this request are:

Extension's file name	MyDialogExt.avx

Extension name	My Dialog Extension

Install script name	MyDialogExt.Install

Uninstall script name	MyDialogExt.Uninstall

Dependencies list	{"$AVBIN/avdlog.dll".AsFileName}

Then the Make script sets some properties for the extension such as version number, about string, Unload script name, and CanUnload script name. The script then adds the dialog, the button, and the necessary scripts to the extension object, and commits them to the extension file.

Other considerations

If your extension contains dialogs with list boxes or combo boxes, contains objects with object tags, or delivers customized document user interfaces (DocGUIs), then there are a few extra things you need to consider before distributing the extension.

 If you use your extension's source project to test your dialogs, you need to remove any unnecessary object references to prevent those objects from getting written to your extension file. For example, if your dialog sets up a server VTab and also defines a list box or combo box contents from a VTab, then running the dialog will establish the object references. Thus, if you then write the dialog to your extension, these referenced object will get written to the extension as well. Unless you're distributing the VTab with the extension, you should remove the references to it before you write the dialog to the extension. To do this, you can set the server to nil and empty list boxes and combo boxes by adding the following lines of code to your Make Script where you add the dialog.

MyDialog = av.FindDialog("MyDialog")

MyDialog.SetServer(nil)

listBoxes = MyDialog.FindByClass(ListBox)

for each lb in listBoxes

  lb.Empty

end

comboBoxes = MyDialog.FindByClass(ComboBox)

for each cb in comboBoxes

  cb.Empty

end

MyDialogExt.Add(MyDialog)

 You should avoid setting object tags on objects in your source project as they may get written out to the extension. For example, if a script in your source project sets an object tag, and you test the script, ArcView will create the object tag. If that object 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. To avoid this problem, you should remove all object tags from your extension before you distribute it. Add the following lines of code to the end of your extension’s Make script after the Commit statement.

MyDialogExt.Commit

RFileName = FileName.Make("$USEREXT/MyDialogExt.avx")

WFileName = FileName.Make("$USEREXT/MyDialogExt.tmp")

RFile = LineFile.Make(RFileName,#FILE_PERM_READ)

WFile = LineFile.Make(WFileName,#File_PERM_WRITE)

WFile.SetScratch(TRUE)

while (RFile.IsAtEnd.Not)

  buf = RFile.ReadElt

  if (buf.Contains("ObjectTag:").not) then

    WFile.WriteElt(buf)

  end

end

RFile.Close

WFile.Flush

File.Copy(WFilename, RFileName)

WFile.Close

This opens the avx file as a LineFile, creates a temporary file, and writes every line except ObjectTag lines in the avx file to the temporary file. Then the temporary file is copied to the avx file name.

 If your extension delivers a customized DocGUI, it may contain extraneous information associated with the DocGUI. For instance, the Window menu of your DocGUI contains menu options to activate all documents that are currently open in the project. Also, the separator in this menu references an object that contains a list of the open windows. These menu options and the object tag get written to the extension with the DocGUI. This will cause problems in projects that load the extension.

If your customized DocGUI is a View or Layout, you may need to remove a few controls that the Dialog Designer installs into these DocGUIs. These controls are "Show/Hide Control Tools" on the Windows menu and "Design/Run Controls" on the Graphics menu. If your extension will not be dependent upon the Dialog Designer extension (dialog.avx), you should remove these menu options from these GUIs before you add them to your extension.

To remove the object tag and menu controls, add the following line of code to your Make script where you add the View or Layout GUI.

' Get the customized View DocGUI from the project

viewGUI = av.getproject.FindGUI( "View")

viewMenuBar = viewGUI.GetMenuBar

' Find the separator that contains the object tag and set the object tag to

' nil

winUpdate = viewMenuBar.FindByScript("WindowMenuUpdate")

winUpdate.SetObjectTag(nil)

' Delete all the activate window menu options

cSet = winUpdate.GetControlSet

cList = cSet.GetControls

last = cList.Get(cList.Count - 1)

while (last <> winUpdate)

  cSet.Remove(last)

  last = cList.Get(cList.Count- 1)

end

' Find the controls that were added by Dialog Designer and remove them

showControlTools = viewMenuBar.FindByScript("GraphicControl.ShowHideTools")

designControls = viewMenuBar.FindByScript("GraphicControl.DesignRun")

showControlTools.GetControlSet.Remove(showControlTools)

designControls.GetControlset.Remove(designControls)

' Then add your DocGUI to your extension

MyDialogExt.Add(viewGUI)


Making a dialog the single source for input

Suppose your application requires specific input, such as a user name and password, that must be provided before beginning some process or activity. One solution is to make the dialog the focus of input and prevent someone from working with any other part of ArcView (or any other dialogs) while the dialog is displayed. Such a dialog is called a modal dialog.

You make a dialog modal by setting the Modal property through the Control Properties dialog or with the SetModal request on a Dialog object. When you create a modal dialog, you must provide some method for dismissing the dialog (e.g., an OK or Cancel button). However, while designing your dialog, you can dismiss it by pressing the ESCAPE key if you haven't yet implemented a method for dismissing it. When you've finished editing your dialog and are ready to incorporate it into your application, you may want to set the EscapeEnabled property to FALSE so that a user of your dialog can't dismiss it by pressing ESCAPE.


Organizing controls on a control panel

If you want to organize the controls you place on top of views and themes within a control panel, you have to do so through a script as there is no interactive way to associate controls with a control panel. The following script that shows you how. Before you run this script, interactively add a control panel and two radio buttons to a layout.

theDoc = av.GetActiveDoc

aGraphicList = theDoc.GetGraphics

'Find graphic controls on document

aControlPanel = aGraphicList.FindByName("aControlPanel1")

aRadio1 = aGraphicList.FindByName("aRadioButton2")

aRadio2 = aGraphicList.FindByName("aRadioButton3")

'Get bounding box of radio buttons. This is done while the Radio buttons

'are still part of the graphic list; otherwise ReturnBox returns Nil.

x1 = aRadio1.GetControl.ReturnBox.GetWidth

y1 = aRadio1.GetControl.ReturnBox.GetHeight

x2 = aRadio2.GetControl.ReturnBox.GetWidth

y2 = aRadio2.GetControl.ReturnBox.GetHeight

'Activate the controls

aRadio1.SetEditable(false)

aRadio2.SetEditable(false)

'Get control object from graphic control

aRadioControl1 = aRadio1.GetControl

aRadioControl2 = aRadio2.GetControl

'Remove graphic controls from graphic list

aGraphicList.RemoveGraphic(aRadio1)

aGraphicList.RemoveGraphic(aRadio2)

'Add radio button controls to control panel

aControlPanel.GetControl.Add(aRadioControl1, Rect.Make(10@10, x1@y1))

aControlPanel.GetControl.Add(aRadioControl2, Rect.Make(10@30, x2@y2))

The two radio buttons should now be part of the control panel. From Graphics, choose Run Controls to activate the control panel. Once you add controls to a control panel you will no longer be able to edit their properties through the Control Properties dialog. For example, if you want to change the Click script of a button you've just added to a control panel, you have to use the appropriate Avenue request.


Passing arguments to dialogs

When your application requires you to maintain information (objects) external to the dialog but needed by the dialog, you pass the information to the dialog through global variables or object tags. For instance, suppose you've created a dialog that allows you to zoom to the previous extents of your view. You might maintain the coordinates of the previous extents in a list stored either as an object tag on the dialog or in a global variable. To set a global variable, simply precede the variable name with an underscore. To set an object tag on a dialog, use the SetObjectTag request on the Dialog object.

You don't necessarily need to pass arguments to a dialog to initialize controls on the dialog. If a control's initial value can be determined at run time, you simply need to place the appropriate code to do so in the dialog's Open script. Additionally, a dialog maintains control values after it is closed. Thus, if a user of your dialog changes a value, that value will still be set the next time the dialog is displayed, unless you initialize it in the Open script.


Positioning a dialog on the screen

Once you've finished designing and creating your dialog, you need to consider where it should appear on the screen. You can roughly position a dialog while editing it; however, if you want to position the dialog at a specific location, you need to include some Avenue code in the dialog's Open script to do so.

How do you want to position your dialog?

Interactively while editing it

Position the upper-left corner to ArcView's upper-left corner

Position the upper-left corner to ArcView's upper-right corner

Centered over ArcView's window

Move it relative to its current position on the screen


Positioning controls on a dialog

How do you want to position a control?

Move it interactively with the mouse

Move it one pixel at a time

Align it with other controls

Move it an equal distance from other controls

Move it in front of or behind other controls

With a script


Providing online help
Providing on-line help for your dialog

You can create on-line help for your dialogs and integrate it with ArcView's online help system. Assuming you've built your own WinHelp compatible help file (HyperHelp for UNIX or QuickHelp for Macintosh), you can easily access it from your dialog.

How do you want to display help for your dialog?

Display a help topic from a Help button on the dialog

Display a help topic when F1 is pressed over the dialog

Display a tool tip for an individual control

  Related topics


Responding when documents open close or activate
Responding when documents open, close, or activate

A dialog can react when certain events happen in ArcView, such as when a document becomes active. For each event, you can write a script to make your dialog respond appropriately.

What do you want to do?

Respond when the dialog becomes active

Respond when the active document changes

Respond to a change in a particular document

Respond to other types of changes


Running controls on views and layouts

When you've finished editing the controls you've placed on your views and layouts, you need to run them to make them respond when, for example, you click on a button.

How do you want to put your controls in run mode?

Interactively with the mouse

With a script


Saving your work

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.

How do you want to manage your dialogs?

Save them in an ArcView project

Save them in text files


Selecting controls on a dialog

Before you can edit a control, you need to select it. If you want to change its size and position, or adjust its properties, you'll probably use the mouse to select it. However, you can also find controls through scripts and edit them there as well.

How do you want to select controls?

Interactively with the mouse

With a script


Setting a control's initial value

There are a couple of different ways you can set an initial value for controls on a dialog. The way you decide to do so will depend upon how you want the dialog to appear.

How do you want to initialize controls?

Every time the dialog displays

Only the first time the dialog displays


Changing control properties on a view or layout
Setting control properties of controls on a view or layout

You define the behavior of a control on your view or layout through its properties. For example, you set a property to define the icon that appears on a button or the label associated with a text line. You can change these properties either through the Control Properties dialog or through specific Avenue requests.

How do you want to set control properties?

Interactively through the Control Properties dialog

With a script


Setting dialog and control properties

Every control on the 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 you click 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). The Control Properties dialog allows you to interactively change properties while you're editing a dialog.

What do you want to do?

Set properties interactively through the Control Properties dialog

Set properties at run time through a script

Integrate your scripts with the Control Properties dialog

  Related topics


Setting font and color

The Dialog Designer does not currently provide any utilities for setting the text font, text size, or color of a control, or of a dialog itself. However, you can create your own icons that contain text of a particular font and size and display the icon on a button or tool. Additionally, you can use an icon box to display a background image on the dialog.

Note  The default system font used by the Dialog Designer varies across platforms. Thus, if your application containing dialogs supports different hardware platforms or operating systems, you should test your dialogs on those platforms to ensure that the text on them displays as you expect. In some instances, you may need to adjust the size of controls to accommodate a particular platform.


Setting keyboard focus

You can set the keyboard focus to a combo box, list box, slider, text box or text line control on your dialog through the Focus request on these controls. For example, if you want a particular text line to receive the keyboard focus when you first display the dialog, you might include code like this in the dialog's open script.

self.FindByName("aTextLine1").Focus


Sizing controls on a dialog

You set the size of the controls on your dialog to create an effective and well organized display. You can set the size several different ways.

What do you want to do?

Set the size of an individual control with the mouse

Set an explicit height and width for a control

Make two (or more) controls the same size

Manage control size at run time when the dialog size changes

Change control size with a script


Sizing the dialog window

The window, or frame, inside of the dialog editor document represents the visible portion of the dialog that you see when you run it. If you change the size of the frame, the resulting dialog size will also change. You can change the frame size by selecting and dragging any corner of the frame.

Controls positioned outside of the frame won't be visible when you initially display the dialog until you resize the dialog at run time. Thus, all controls on a dialog are part of it, they just may initially be positioned outside of the dialog's visible area.

In addition to interactively dragging the frame, you can manage the dialog size in other ways.

What do you want to do?

Set the size of the dialog explicitly

Prevent a dialog from being resized

Set the dialog size at run time with a script

Manage control size at run time when the dialog size changes


Tabbing through controls

The Dialog Designer provides some control over defining the order in which an end user will interact with the controls on your dialog. Set a control's NextControl property to define the order that controls will receive the keyboard focus when an end user presses the tab key.

This property is used mainly when your dialog has text line controls on it and you want a user to enter text into the text line controls in a specific order, without having to move the mouse to the next line.


To add a control interactively
To add a control interactively with the mouse

1	Select the control you want to add from the tool bar.

2	Move the mouse over the dialog editor, inside the dialog frame.

The dialog frame represents the visible portion of the dialog. You can size the frame as needed to fit all your controls. Controls not within the frame are still part of the dialog, they just won't be seen.

3	Click and drag the mouse to add the control at the size you want. Alternatively, click once to add a control of a default size.

Tip	Not all controls are visible on the tool bar. Some controls are part of drop-down tool menus. For example, click and hold the mouse over the label button tool to reveal other controls. To see a separate palette of the available controls, display the Control Tools menu. From Window, choose Show Control Tools.


To add a control with a script

Here's a script that adds a control to a dialog you're currently editing.

aDialogDoc = av.GetProject.FindDoc("Dialog1")

aGraphicList = aDialogDoc.GetGraphics

aLabelButton = LabelButton.Make

aLabelButton.SetLabel("OK")

aGraphicControl = GraphicControl.Make(aLabelButton, Rect.Make(1@1,1@1))

aGraphicList.AddName(aGraphicControl)

aGraphicControl.SetSelected(true)

System.RefreshWindows

PropWin.The.Update(aGraphicList,aGraphicControl)

aDialogDoc.NeedsCompile

Adding a control to a dialog editor is much like adding any graphic element to a view or layout. In fact, the DialogEditor class is a subclass of the Layout class; thus, the controls you add to your dialog are ordinary graphic elements with a few more properties. Once you create a control, like a label button, you use it to create a graphic control specifying its location and size (in inches) on the dialog. Then, you add the graphic control to the dialog's graphic list. The AddName request assures that the new control has a unique name and the Update request sent to the PropWin shows the newly added control in the Control Properties dialog box. The NeedsCompile request indicates that the dialog must be compiled before it can be run. Alternatively, you could compile the dialog directly with the Compile request.

(Note, to work around a known problem, the System.RefreshWindows request is included in the above script. It is only required when adding a list box to a dialog when the Control Properties dialog is open.)

If you're application requires you to add a control to a running dialog, you can do so like this.

aDialog = av.FindDialog("Dialog1")

aLabelButton = LabelButton.Make

aLabelButton.SetLabel("OK")

aControlPanel = aDialog.GetControlPanel

aControlPanel.Add (aLabelButton, Rect.Make(50@50,100@100))

In this example, you add the control directly to the dialog's control panel, there is no graphic component you need to create like you did above. Also notice that the coordinate of the control's bounding rectangle are specified in pixels, not inches. When you add controls directly to the Dialog object, you'll only see the control in the running dialog and not in the dialog editor document you may be editing. If you compile the associated dialog editor document, the control you added will disappear.


To add a control to a view or layout interactively with the mouse
To add a control to a view or layout with the mouse

1	With a view or layout as the active document, from Window, choose Show Control Tools.

2	Choose the control you want to add.

3	Click and drag the mouse over the view or layout to add the control at the size you want. Alternatively, click once to add a control of a default size.

At this point, you can double-click the control to display its properties or move it around.

Note	Due to a limitation in ArcView, you can’t add radio buttons and check boxes to a view.


To add a control to a view or layout with a script
To add controls to a view or layout with a script

A control placed on a view or layout is a special kind of graphic element, called a graphic control. A graphic control interprets mouse and keyboard events in one of two ways: it can either act like a graphic or like a control. When you first place controls on a view or layout, you want them to act like graphics so that you can position them, size them and set their properties. Once you've finished editing them, you run them to make them respond like controls on a dialog (i.e., pressing a button to run some script).

Here's a script that adds a label button to a view or layout.

theDoc = av.GetActiveDoc

aGraphicList = theDoc.GetGraphics

theDisplay = theDoc.GetDisplay

aControl = LabelButton.Make

'Size control to 20% by 7% of display width

aWidth = theDisplay.ReturnVisExtent.GetWidth

aSize = (aWidth * 0.2)@(aWidth * 0.07)

aRect= Rect.Make(theDisplay.ReturnVisExtent.ReturnCenter, aSize)

aGraphicControl = GraphicControl.Make(aControl, aRect)

aGraphicList.UnselectAll

aGraphicControl.SetSelected(true)

aGraphicList.AddName(aGraphicControl) 'this also sets name of control

aControl.SetLabel("OK")

av.GetProject.SetModified(true)

'Update property window if open

PropWin.The.Update(aGraphicList, aGraphicControl)

At this point, the control still acts like a graphic element. You can select it with the mouse, move it around, change its size, and edit its properties. To activate the control, you run it.

When you add a control to a view or layout, you can also define how the control should respond when the map is panned or zoomed. The control can do one of the following: do nothing, pan with the map, pan and zoom with the map. You can set the desired behavior through the Control Properties dialog or with the SetConstraint request on a GraphicControl:

aGraphicControl.SetConstraint(#GRAPHICCONTROL_CONSTRAINT_NONE)

Note	Due to a limitation in ArcView, you shouldn't add radio buttons and check boxes to a view.


To change control size with a script

To adjust the size of a control on the dialog you're editing, you find the control, then adjust the bounding box of that control as necessary. For example, here's a script that scales a control.

aDialogEditor = av.GetActiveDoc

aGraphicList = aDialogEditor.GetGraphics

aLabelButton = aGraphicList.FindByName("aLabelButton1")

CurrentRect = aLabelButton.GetBounds

aLabelButton.Invalidate

aLabelButton.SetBounds(CurrentRect.Scale(0.5))

aLabelButton.Invalidate

Note that both statements that contain the Invalidate request are required. Conceptually, the first Invalidate erases the control and the second draws it with its new size.

All size changes are based upon the bounding box defined by a rectangle passed to the SetBounds request. Here are some other rectangles you could pass as an argument to the request.

aLabelButton.SetBounds(CurrentRect.ExpandBy(0.25))

This request would enlarge the control by one-quarter inch in each cardinal direction.

aLabelButton.SetBounds(Rect.Make(0@0,1@1))

This request will make the control one inch square and also position it at coordinate 0,0 (the lower-left corner of the dialog editor window).

To change the size of a control on a running dialog (Dialog object), you again find the control and adjust the size as necessary. Changes you make to the dialog at run time are not propagated to the dialog editor document.

aDialog = av.FindDialog("Dialog1")

aControlPanel = aDialog.GetControlPanel

aButton = aControlPanel.FindByName("aButton1")

aButton.Resize(10,10)

Here, the Resize request increases the size of the button by 10 pixels in both the x and y direction. Note that on the dialog, you specify sizes in pixels and the origin is the upper left corner of the dialog. If you want to explicitly size the control, use the ResizeTo request.

aButton.ResizeTo(100,100)


To compile and run a dialog interactively

1	From the dialog editor, press Compile [image].

2	Then, press Run [image].


To compile and run a dialog with a script

When you build with dialogs, you work primarily with two objects in Avenue's class hierarchy: the DialogEditor object and the Dialog object. A DialogEditor is a document, much like a view or layout. (In fact, a DialogEditor is a subclass of the Layout class.) Through the editor, you interactively add, position and set the properties of controls on your dialog. When you want to display the dialog represented in the editor, you compile it. Compiling a DialogEditor synchronizes the associated Dialog object with the DialogEditor object. To compile a DialogEditor, you send it the Compile request.

av.FindDoc("Dialog1").Compile

Once you've compiled your dialog, you'll likely want to display it.

av.FindDialog("Dialog1").Open

Typically, you'll create a script with a line of code in it like this and attach it to a button or menu item in ArcView's interface. Notice that you compile a DialogEditor object, but display the associated Dialog object.

You don't have to create a DialogEditor object to create a Dialog object. For example, your application can create a dialog "on-the-fly," bypassing the DialogEditor object.

aDialog = Dialog.Make (false,true,true,true,true)

aLabelButton = LabelButton.Make

aLabelButton.SetLabel("OK")

aControlPanel = aDialog.GetControlPanel

aControlPanel.Add (aLabelButton, Rect.Make(50@50,100@100))

aDialog.SetName("My Dialog2")

av.GetProject.AddDialog(aDialog)

aDialog.Open

When you create a dialog in this manner, you add controls directly to the Dialog, positioning them on the dialog in pixels, with the upper-left corner as the origin. As there is no DialogEditor object, you don't need to compile. Nor can you edit the dialog interactively.


To create a dialog through the interface

In the project window, double-click the Dialogs icon.

This creates a new dialog editor document that's ready to accept controls, for example, buttons, sliders, and check boxes.

The frame inside the dialog editor window represents the visible portion of the dialog. You can size the frame as needed to fit all your controls. Controls not within the frame are still part of the dialog, they just won't be seen.


To create a dialog with a script

When writing scripts that create dialogs, you need to understand the difference between a Dialog object and a DialogEditor object. The Dialog object represents the visible dialog that you display and interact with. The DialogEditor object is the document that allows you to interactively edit controls (e.g., add, size and position) on your dialog. Compiling a DialogEditor synchronizes the associated Dialog object to the DialogEditor.

Here's a short script that creates a DialogEditor object and adds a label button to it.

aDialogEditor = DialogEditor.Make

aDialogEditor.SetName("My Dialog1")

av.GetProject.AddDoc(aDialogEditor)

aLabelButton = LabelButton.Make

aLabelButton.SetLabel("OK")

aGraphicControl = GraphicControl.Make(aLabelButton, Rect.Make(1@1,1@1))

aDialogEditor.GetGraphics.AddName(aGraphicControl)

aDialogEditor.GetWin.Open

You can interactively add more controls or edit the existing one. When you want to display it, you press the Compile, then Run buttons.

The DialogEditor provides an interactive method for creating and editing dialogs. You can, however, create a Dialog object directly in a script, without using a DialogEditor. Here's a script that shows how. It also creates a dialog with one label button on it.

aDialog = Dialog.Make (false,true,true,true,true)

aLabelButton = LabelButton.Make

aLabelButton.SetLabel("OK")

aControlPanel = aDialog.GetControlPanel

aControlPanel.Add (aLabelButton, Rect.Make(50@50,100@100))

aDialog.SetName("My Dialog2")

av.GetProject.AddDialog(aDialog)

aDialog.Open

The difference between this and the previous script is that this script directly creates the dialog object, without creating a DialogEditor object. You might do this when your application requires you to create a dialog "on-the-fly." One thing to note when creating a dialog like this is that you can't edit it interactively (i.e., you can't load it into a DialogEditor).


To delete a control interactively
To delete a control interactively with the mouse

1	Select the control(s) you want to delete.

2	Press the DELETE key on your keyboard.


To delete a control with a script

To delete a control from a dialog you're editing, you remove it from the graphic list associated with the dialog editor. For example, assuming that the dialog is the active document:

aDialogEditor = av.GetActiveDoc

aGraphicList = aDialogEditor.GetGraphics

aLabelButton = aGraphicList.FindByName("aLabelButton1")

aGraphicList.RemoveGraphic(aLabelButton)

To remove a control from a dialog at run time (the Dialog object) you find it on the dialog's control panel and remove it.

aDialog = av.FindDialog("Dialog1")

theControlPanel = aDialog.GetControlPanel

aControl = aDialog.FindByName("aLabelButton1")

theControlPanel.Remove(aControl)

This script only removes the control from the Dialog object. If the control exists in the DialogEditor object, it will appear on your dialog when you recompile the editor.


To delete controls on a view or layout with a script

To delete a control from a view or layout you're editing, you remove it from the graphic list. For example, assuming that the view or layout is the active document:

aDoc = av.GetActiveDoc

aGraphicList = aDoc.GetGraphics

aLabelButton = aGraphicList.FindByName("aLabelButton1")

aGraphicList.RemoveGraphic(aLabelButton)

To remove all the graphic controls, you could do this:

aDoc = av.GetActiveDoc

aGraphicList = aDoc.GetGraphics

theGraphicControls = aGraphicList.FindAllByClass(GraphicControl)

for each gc in theGraphicControls

  aGraphicList.RemoveGraphic(gc)

end


To delete a control on a view or layout with the mouse
To delete a control on a view or layout interactively with the mouse

1	Make sure the controls are in design mode. If not, from Graphics, choose Design Controls.

2	Select the control(s) you want to delete.

3	Press the DELETE key on your keyboard.


To display and edit records in a VTab

With a dialog, you can create a graphical interface to display and edit tabular data. For example, your dialog could display an individual record, allow a user to modify it, then commit the change to the data.

To create your dialog, you use ArcView's existing classes and requests that manipulate tabular data to write scripts that you associate with the controls on your dialog. Here's an example of a dialog that displays the value of a given field in a dBASE file and allows you to edit it. You can follow the steps below to create the dialog, substituting your own dBASE file for the one specified here.

1	Create a dialog and add 3 label buttons and a text line to it. Set the properties as shown below

Control	Property	Setting

Label Button	Name	lbt_Next

Click	MyEditor.lbt_Next.Click

Label	Next

Update	MyEditor.lbt_Next.Update

Label Button	Name	lbt_Prev

Click	MyEditor.lbt_Prev.Click

Label	Previous

Update	MyEditor.lbt_Prev.Update

Label Button	Name	lbt_Commit

Click	MyEditor.lbt_Commit.Click

Label	Commit

Text Line	Name	txl_Record

Label	Current Record

Update	MyEditor.txl_Record.Update

Dialog	Open	MyEditor.Open

Close	MyEditor.Close

2	Write the following scripts:

'MyEditor.Open - initializes the dialog. Substitute the name of

'your Table document which should be based on a dBASE or Info file.

aTable = av.GetProject.FindDoc("Customers.dbf")

aVTab = aTable.GetVTab

aVTab.SetEditable(true)

NameField = aVTab.FindField("Name")

theBitmap = aVTab.GetDefBitmap

'Get controls on dialog

aTxl_Record = self.FindByName("txl_Record")

aLbt_Next = self.FindByName("lbt_Next")

aLbt_Prev = self.FindByName("lbt_Prev")

aLbt_Commit = self.FindByName("lbt_Commit")

'Get first record and populate text line control

recno = theBitmap.GetNextSet(-1)

aName = aVTab.ReturnValue(NameField,recno)

aTxl_Record.SetText(aName)

'disable previous button; enable Next button

aLbt_Prev.SetEnabled(false)

aLbt_Next.SetEnabled(true)

'Set some object tags for quick access later

self.SetObjectTag(aVTab)

aTxl_Record.SetObjectTag(NameField)

aLbt_Next.SetObjectTag(recno)

aLbt_Commit.SetObjectTag(aTable)

'Set Listeners

aLbt_Prev.SetListeners({aTxl_Record,aLbt_Next,aLbt_Prev})

aLbt_Next.SetListeners({aTxl_Record,aLbt_Prev,aLbt_Next})

'MyEditor.Close - Stops editing the VTab

self.GetObjectTag.SetEditable(false)

'MyEditor.lbt_Next.Click - moves to the next record in the VTab

'storing the record number as an object tag.

recno = self.GetObjectTag

aVtab = self.GetDialog.GetObjectTag

nextRecno = (aVTab.GetDefBitmap.GetNextSet(recno))

if (nextRecno <> -1) then

  self.SetObjectTag(nextRecno)

end

self.BroadcastUpdate

'MyEditor.lbt_Next.Update - enables and disables the next button

'by checking if the current record number = last record number

aVTab = self.GetDialog.GetObjectTag

recno = self.GetObjectTag

aBitmap = aVTab.GetDefBitmap

self.SetEnabled(not (recno = aBitmap.GetPrevSet(aBitmap.GetSize)))

'MyEditor.lbt_Prev.Click - moves to the previous record in the VTab

'storing the record number as an object tag.

aLbt_Next = self.GetDialog.FindByName("lbt_Next")

recno = aLbt_Next.GetObjectTag

aVtab = self.GetDialog.GetObjectTag

nextRecno = (aVTab.GetDefBitmap.GetPrevSet(recno))

if (nextRecno <> -1) then

  aLbt_Next.SetObjectTag(nextRecno)

end

self.BroadcastUpdate

'MyEditor.lbt_Prev.Update - enables and disables the Previous button

'by checking if the current record number = the first record number.

aVTab = self.GetDialog.GetObjectTag

recno = self.GetDialog.FindByName("lbt_Next").GetObjectTag

aBitmap = aVTab.GetDefBitmap

self.SetEnabled(not (recno = aBitmap.GetNextSet(-1)))

'MyEditor.lbt_Commit.Click - Commits the edited value in the text line

'to the VTab

aVTab = self.GetDialog.GetObjectTag

aTxl_Record = self.GetDialog.FindByName("txl_Record")

NameField = aTxl_Record.GetObjectTag

recno = self.GetDialog.FindByName("lbt_Next").GetObjectTag

aVTab.SetValue(NameField, recno, aTxl_Record.GetText)

self.GetObjectTag.GetWin.Invalidate 'redraw table document

'MyEditor.txl_Record.Update - updates the field value displayed.

aVtab = self.GetDialog.GetObjectTag

NameField = self.GetObjectTag

recno = self.GetDialog.FindByName("lbt_Next").GetObjectTag

self.SetText(aVTab.ReturnValue(NameField,recno))

3	Compile and run the dialog. Make sure you've added a table to your project as referenced in your scripts.

This example illustrates how you might go about creating your own dialog to edit your tabular data. Depending upon the data in your tables, you might put different control to manipulate it. You might further enhance your dialog to prevent an end user from doing something they shouldn't (e.g., validating any input supplied). For more information on editing tabular data, search the on-line help for the VTab class.


To display a tool tip for an individual control

1	Double-click the control you want to provide a tool tip for.

2	In the Control Properties dialog, set the Help property.

The Help property is a string that has two components: a help message that appears in ArcView's status bar and a tool tip that appears directly over the control under the Windows 95 and NT operating systems. The syntax for the help string is:

tool tip//status bar help

Typically the tool tip is one or two words that describe the control whereas the status bar help string is a longer description of the control.

If you just want a tool tip, enter the string as:

tool tip//

If you just want the status bar help string, enter the string without "//".


To display a help topic from a button on the dialog
To display a help topic from a Help button on the dialog

1	Add a label button to the dialog.

2	Display the Control Properties dialog by double-clicking the label button.

3	Set the Label property to 'Help' or something appropriate.

4	Set the Click property to a script containing a line of code like this:

av.Help.ShowTopic("some_help_topic@somehelpfile.hlp")

The argument to the ShowTopic request is a string representing the name of the help topic, given as its topic ID (# footnote in the source help file), followed by @, then the name of the help file containing the topic.

ArcView will search for the help file in the Help directory of ArcView's install directory. While you can optionally specify a pathname to the help file, the best method for integrating your help file with ArcView's help system is to place it in ArcView's Help directory. Then you can link your help file to ArcView's contents file (arcview.cnt).


To display a help topic when F1 is pressed over the dialog

1	Double-click the dialog to display the Control Properties dialog.

2	Set the HelpTopic property to:

<aTopicName>@<aHelpFileName>

for example mytopic@myhelp.hlp. ArcView will search for the help file in the Help directory of ArcView's install directory. While you can optionally specify a pathname to the help file, the best method for integrating your help file with ArcView's help system is to place it in ArcView's Help directory. Then you can link your help file to ArcView's contents file (arcview.cnt).


To distribute your application 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.

1	Create a project that contains the dialogs and other changes to the interface you want to deliver. This project is referred to as the extension’s source project. To ensure that your dialog and script names don't conflict with dialogs and scripts in ArcView or any extensions (either developed by ESRI or other third party developers), you should prefix your dialog and script names with a unique identifier. For example, you might use the name of the application you're creating as the prefix,
<application name>.<dialog name>
<application name>.<script name>

2	Open the source project.

3	Write the script that makes the extension. Make script

4	Write the scripts to load and install the extension. Load and Install scripts

5	Write the script that determines whether the extension can be unloaded. Canunload script

6	Write the scripts to unload and uninstall the extension. Uninstall and Unload scripts

7	Run the Make script to create the extension.

8	Save the source project and close it.

9	Open a new project and load your extension. Test your dialogs. If there are any problems, go back into the source project and fix then and run the Make script again.

10	Deliver the extension to others. Answer the following question to determine what files you'll need to distribute with your extension file (.avx).

Do the people who will use your extension have the Dialog Designer installed on their computer?

If the answer is Yes, then you just need to distribute your extension file.

If the answer is No, then you'll need to distribute a few extra files with your extension as outlined in the table below.

Windows 95 and NT	UNIX

bin32 directory	bin directory
avdlog.dll	avdlog.dll

lib32 directory	lib directory
 avdlog.dat	avdlog.dat

The files listed above are installed by the Dialog Designer into the ArcView install directory. You can copy these files from your installation and install them onto the computer of someone who needs to run your extension. These files are platform specific. Thus, you will have to install the Dialog Designer on a UNIX system to get the appropriate files for that system.


To distribute your application in 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.

To create a project without dialog editors

Suppose that 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.

Note  Once you’ve detached a project, keep the development project if you anticipate a need to edit the dialogs in the future. You can’t interactively edit the dialogs in the detached project.


To distribute your application with a personal working 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	In your new detached project, create and run a new script containing the following line of code:

av.Getproject.MakeUserDefault

ArcView creates a file in your home directory called default.apr. Now whenever you start ArcView, all your customizations, including your dialogs, will be available.


To distribute your application with a system default environment

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:

av.GetProject.MakeSysDefault("$HOME/asysdef.apr".AsFileName, False)

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.

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

Now whenever anyone starts ArcView, all your customizations, including your dialogs, will be available.


To initialize controls every time the dialog displays

The default value you specify for a control at design time through the Control Properties dialog will only initialize the control the first time the dialog displays. Thus, if you change the value at run time, that value is maintained and displayed when the dialog is subsequently displayed. This is because the dialog maintains its state until you recompile it.

To initialize a control every time you display the dialog, you need to do so programmatically through a script. Typically, you initialize controls in the dialog's Open script. An Open script may contain statements like this:

'The self object in an Open script is the dialog object

aTextLine = self.FindByName("aTextLine1")

aTextLine.SetText("")  'clear out any previous value

aListBox = self.FindByName("aListBox2")

aListBox.DefineFromList( { {"one","two","three"}, {1,2,3} } )

aCheckBox = self.FindByName("aCheckBox3")

aCheckBox.SetSelected(true)

aRadioButton = self.FindByName("aRadioButton4")

aRadioButton.Select

aSlider = self.FindByName("aSlider5")

aSlider.SetValue(10)

Because the Open script runs each time the dialog displays, the controls initialize to the values specified in this script.


To initialize controls the first time a dialog displays

You can set an initial value for some controls through the Control Properties dialog. For example, you can specify whether or not a check box will be checked when the dialog is first opened. Once you display the dialog, any change in value you make to a control is maintained even after you close the dialog, until such time that you recompile it. Thus, you don't need to do any programming if you want your controls to initialize only once when you first display a dialog.


Integrating scripts with the control properties dialog
To integrate scripts with the Control Properties dialog

If you plan on editing the controls on your dialog editor through scripts. you might also want to display the Control Properties dialog or update its contents.

For example, to display the Control Properties dialog:

aDialogEditor = av.GetActiveDoc

PropWin.The.OpenOnDialogEditor(aDialogEditor)

Assuming the active document is a DialogEditor object, the above will open the Control Properties dialog and populate it with the properties of the controls on the dialog.

Here's how you can select a control on the dialog and show its properties:

aDialogEditor = av.FindDoc("dialog1")

theGraphicList = aDialogEditor.GetGraphics

aButton = theGraphicList.FindByName("aButton1")

theGraphicList.UnselectAll

aButton.Select

PropWin.The.Update(theGraphicList, aButton)

This script will work with controls on a dialog or controls on views and layouts. Optionally, you could replace the last line of the script with this line:

PropWin.The.SetSelectedControl(aButton)

If you only want to display the properties for a control but not alter the selected set, you can do this:

aDialogEditor = av.FindDoc("dialog1")

theGraphicList = aDialogEditor.GetGraphics

aButton = theGraphicList.FindByName("aButton1")

aButton.Edit(theGraphicList)

This example will also display the properties of controls on views and layouts.


To keep dialog in sync with changes to a table or VTab
To keep a dialog in sync with changes to a table or VTab

Your dialog can respond to certain changes to a table or VTab. These include:

 changing the selection on the VTab (ServerSelectionChanged)

 changing the definition of the VTab (ServerDefinitionChanged)

 adding a record to the VTab or table document (ServerRecordsAdded)

 deleting a record from the VTab or table document (ServerRecordsDeleted)

The dialog responds to the change by running a script attached to the appropriate dialog property shown in parenthesis above. In addition to setting the property, you need to establish the relationship between the dialog and the particular table document or VTab. To do this, you use the SetServer request on the Dialog class. The script you actually put this request in depends upon what you’re trying to accomplish. For example, you might put this request in a dialog’s Open script when you only need to set the server once for a dialog. For example:

'Server set in Open script

self.SetServer(av.GetProject.FindDoc("Table1"))

If you need to change the server, for example as the active document changes, you might put this request in the DocActivate script.


To make two controls the same size
To make two or more controls the same size

1	Select the controls you want to make the same size.

2	From Controls, choose Size and Align.

3	In the dialog that appears, check the Same Height and Same Width options.

4	Enter in the height and width in inches and click OK


To manage control size when the dialog size changes

When you create a dialog, you can control whether or not someone who uses your dialog can increase or decrease the size of the window that contains it (by setting the dialog's Resizable property). For each control on the dialog, you can also specify how that control should react to the change in size.

For example, suppose you've placed a list box on your dialog. As you enlarge the dialog, you want the list box to enlarge as well to show more of the data it contains. To do this, you need to set Control Fasteners for the control. Control Fasteners allows you to specify how the controls on your dialog are attached, or fastened, to it.

To set Control Fasteners

1	Select the controls you want to set Control Fasteners for. You can set Control Fasteners for controls individually or in groups.

2	From Controls, choose Control Fasteners.

3	In the dialog that appears, choose the appropriate options that define how you want the control to respond.

Here are some common settings.

 If you want a list box to enlarge as you enlarge your dialog, you would maintain the distance from the left and right sides of the dialog, and maintain the distance from the top and bottom of the dialog.

 If you want a button to stay the same size but always be positioned at the bottom of your dialog, you would maintain the width and height of the button, and also maintain the distance from the bottom of the dialog.

 If you want a control not to move or change its size, you would maintain its distance from the left and top of the dialog, and also keep the same height and width.


To name controls on a dialog

If you use a standard naming convention for your controls, they'll be easy to reference in your scripts. One way to do this is to give each control a prefix that identifies its type, followed by some descriptive name, such as its visible label. For instance, an OK button on your dialog would be named 'lbt_OK'. Control names on a particular dialog should be unique. However, you can use the same control name for controls on different dialogs.

Here's a table of suggested prefixes

Prefix	Control Type	Prefix	Control Type

lbt	Label button	cbx	Combo box

btn	Button	chk	Check box

tol	Tool	rad	Radio button

txl	Text line	sld	Slider

tbx	Text box	ibx	Icon box

txt	Static Text	cpa	Control Panel

lbx	List box


To name scripts associated with a dialog

It's a good idea to give your scripts descriptive names so that you can easily reference them. Here's a naming convention that will keep the scripts associated with a dialog listed together in the project window and allow you to quickly find the one you want to edit.

Use the name of your dialog, followed by the control name and property name the script is attached to.

<dialog name>.<control name>.<property name>

For example, the name of the script attached to the Click property of a button named Done would be 'MyDialog.lbt_Done.Click'. (Note, it's also a good idea to name your dialog using a unique prefix, such as the name of the application or name of your organization.)

By following this naming convention you can avoid naming conflicts with other dialogs or system script names. Additionally, avoid beginning your script names with the word 'Dialog', as many system scripts associated with the Dialog Designer begin with this word. This will prevent you from inadvertently overriding a system script.


To name the dialog itself

To ensure that your dialog names don't conflict with dialogs in ArcView or any extensions (either developed by ESRI or other third party developers), we recommend that you prefix your dialog names with a unique identifier. For example, you might use the name of the application you're creating as the prefix,

<application name>.<dialog name>

or some other prefix, such as the name of your organization.


To move a control an equal distance from other controls

1	Select the controls you want to distribute evenly.

2	From Controls, choose Size and Align.

3	Check the Equal Spacing option for Horizontal or Vertical alignment, or both.

4	Enter in an appropriate distance, in inches.


To move a control interactively with the mouse

1	Select the control you want to move.

2	Click and drag it to the new location.


To move a control in front of or behind other controls

1	Select the control.

2	From Controls, choose Bring to Front or Send to Back.


To move a control one pixel

1	Select the control you want to move.

2	Use the arrow keys on the keyboard to move the control one pixel horizontally or vertically.


To position a control with a script

To change the position of a control on the dialog you're editing, you can write a script like this:

aDialogEditor = av.GetProject.FindDoc("Dialog1")

aGraphicList = aDialogEditor.GetGraphics

aLabelButton = aGraphicList.FindByName("aLabelButton1")

CurrentRect = aLabelButton.GetBounds

aLabelButton.Invalidate

aLabelButton.SetBounds(Rect.Make(0@0,1@1))

aLabelButton.Invalidate

This script positions the control at coordinates 0,0 (the lower-left corner of the dialog editor window). The SetBounds request additionally sets the size of the control. If you only want to change the position, you can substitute either of these two statements.

aLabelButton.Offset(1@1)

or

aLabelButton.PixelOffset(100@100)

These statements move the control a specified number of inches or pixels relative to the control's current position.

To position a control on a dialog that's currently running (on the Dialog object) you can write a script like this:

aDialog = av.FindDialog("Dialog1")

aControlPanel = aDialog.GetControlPanel

aLabelButton = aControlPanel.FindByName("aLabelButton1")

aLabelButton.Move(10, 20)

This script moves the control 10 pixels in the x direction and 20 pixels in the y direction. On the Dialog object, the origin is the upper-left corner. If you want to move the control to an explicit x,y location, use the MoveTo request. Changes you make to the dialog while it's running are not propagated to the dialog editor document.


To align a control with other controls

1	Select all the controls you want to align.

2	From Controls, choose Size and Align.

3	Use the alignment buttons to align the top, bottom, left or right sides of the controls.


To center the dialog over ArcView's window

Place the following code fragment into the dialog's Open script.

AVUpperLeft = av.ReturnOrigin

AVCenter = avUpperLeft + (av.ReturnExtent / (2@2))

aDialog =  av.FindDialog("Dialog1")

halfDialogWidthHeight = aDialog.ReturnExtent.ReturnSize / (2@2)

MovePoint = AVCenter - halfDialogWidthHeight

aDialog.MoveTo(MovePoint.GetX, MovePoint.GetY)


To position a dialog interactively while editing it

To position a dialog while editing it, simply move the dialog frame. The upper-left corner of the document window corresponds to the upper-left corner of the screen. The distance between the upper-left corner of the document window and the upper-left corner of the dialog frame will equal the distance between the upper-left corner of the screen and the upper-left corner of the displayed dialog.


To position the dialog's upper-left corner to ArcView's upper left corner
To position the dialog's upper-left corner to ArcView's upper-left corner

Place the following code fragment into the dialog's Open script.

AVUpperLeft = av.ReturnOrigin

aDialog =  av.FindDialog("Dialog1")

aDialog.MoveTo(AVUpperLeft.GetX, AVUpperLeft.GetY)


To move a dialog relative to its current position

To move a dialog relative to its current position, include this line of code in your script:

aDialog.Move(100,50)

This will move the dialog 100 pixels left and 50 pixels down from the dialog's current position.


To position the dialog's upper-left corner to ArcView's upper-right corner
To position the dialog's upper-left corner to ArcView's upper-right

Place the following code fragment into the dialog's Open script.

AVUpperLeft = av.ReturnOrigin

AVWidth = av.ReturnExtent.GetX

aDialog =  av.FindDialog("Dialog1")

aDialog.MoveTo((AVUpperLeft.GetX + AVWidth), AVUpperLeft.GetY)


To prevent a dialog from being resized

1	Display the Control Properties for the dialog.

2	Locate the Resizable property and set its value to False.


To respond to a change in a particular document

Suppose you've created a dialog that provides extra information about an individual view document. You want the dialog to appear when the view is opened and disappear when closed. To do this, you need to link the dialog directly to the view so that it can respond to changes, such as closing the view. This involves establishing a client-server relationship between the dialog and the document, where the dialog is the client to the server document.

A dialog can respond to a limited number of server events and run a script attached to the appropriate dialog property when that event occurs. These server events are:

 ServerActivated - the associated document has been activated.

 ServerDeactivated - the associated document has been deactivated.

 ServerOpened - the associated document has been opened.

 ServerClosed - the associated document has been closed.

 ServerSelectionChanged - the selection on the VTab has changed.

 ServerDefinitionChanged - the definition of the VTab has changed.

 ServerRecordsAdded - a record is added to the VTab or table document.

 ServerRecordsDeleted - a record is deleted from the VTab or table document.

To set up a server, you use the SetServer request on a Dialog. The script you actually put this request in depends upon what you’re trying to accomplish. For example, you might put this request in a dialog’s Open script when you only need to set the server once for a dialog. For example:

'Server set in Open script

self.SetServer(av.GetProject.FindDoc("View1"))

If interacting with the dialog requires you to change the server, this request may instead be part of a script attached to a control on the dialog.

Once you've established a server, the dialog will respond to the above server events. For example, if you want your dialog to close when the view closes, you'd attach a script to the ServerClosed property that contains this code:

self.Close

where the self object is the dialog.


To respond to other types of changes

Your dialog can respond to almost anything that can happen during a session. However, not every event that can happen in ArcView has a dialog property you can set. Sometimes you'll need to do a bit of programming to make your dialog respond accordingly.

For example, you can attach an Update script to a document’s button bar (ControlSet) and directly call the Update scripts of the controls in your dialog. The button bar’s Update script will run as a result of an Update event sent by ArcView, just as the individual controls on the button bar automatically run their Update scripts. The Update scripts of each control on your dialog would then determine what sort of change occurred and respond accordingly.

Here's how you can attach an Update script to a View's button bar:

'attach an update script to the View button bar

aButtonBar = av.GetProject.FindGui("View").GetButtonBar

aButtonBar.SetUpdate("anUpdateScript")

The Update script would contain this code to call the Update script of a dialog control:

theDialog = av.FindDialog("Dialog1")

aLButton  = aDialog.FindByName("aLabelButton1")

if (theDialog.IsOpen) then

  'run update only when dialog is displayed

  aLButton.Update

end

The Update script for the button could then do whatever it needs to do to respond to the Update event. Alternatively, you could run the Update script for the dialog itself, which could then run the update scripts of controls on it.


To respond when the active document changes

Suppose you create a dialog that contains tools that work with views and layouts. As long as a view or layout is the active document, the tools on your dialog should be available. However, when a script becomes active, you want to disable the controls on the dialog as they don't apply to the script. You need your dialog to respond to changes in the active document. To do this, you set the dialog's DocActivate property.

The DocActivate property executes its associated script whenever the active document changes. Thus, you might write a script like this to disable controls on a dialog:

'Dim control when active doc is not view or layout

'the self object is the dialog

theDoc = self.GetActiveDoc

enabled = theDoc.Is(View) or theDoc.Is(Layout)

self.GetControlPanel.SetEnabled(enabled)

The DocActivate script is also where you might include code to update individual controls on your dialog. For example, suppose your dialog lists the active themes in a view. As different views become active, you want to update the list of themes to reflect those in the current view.

theDoc = self.GetActiveDoc

aListBox = self.FindByName("aListBox1")

If (theDoc.Is(View) and theDoc.GetThemes.IsEmpty.Not) then

  theThemes = theDoc.GetThemes

  aListBox.DefineFromList(theThemes)

else

  aListBox.DefineFromList({})

end

Note	Use the GetActiveDoc request on the Dialog object instead of the application object, av, in your DocActivate scripts, or any scripts called from a DocActivate script.


To respond when the dialog becomes active

If you need to run a script whenever the dialog becomes active, you set the dialog's Activate property to the particular script you want to run. In the script, you perform whatever actions is necessary. You can set the Activate property either from the Control Properties dialog or with the SetActivate request on a Dialog.


To run controls on a view or layout interactively

From Graphics, choose Run Controls.

If you want to edit your controls again,

From Graphics, choose Design Controls.


To put controls on a view or layout in run mode with a script

If you've added a control to a view or layout with a script, you might want to append this code to immediately run it.

aGraphicControl.SetEditable(false)

This will put a single control in run mode. To put all controls on a view or layout in run mode, you can do this:

theDoc = av.GetActiveDoc

for each gc in theDoc.GetGraphics

  if (gc.Is(GraphicControl)) then

    gc.SetEditable(false)

  end

end

When you programmatically set the editable state of graphic controls on a view or layout, you might also want to change the Design/Run Controls menu item under the Graphics menu so that it accurately reflects the current state of the controls. See the system script named GraphicControl.DesignRun to see how to do this.


To save dialogs in a project

To save your dialogs in a project, you just save the project. The next time you open it, the Dialog Designer extension will load automatically. Saving dialogs in a project is an effective way to manage an application if only a few developers are working on it, and they don't need to access it simultaneously. For larger applications, you'd be better off saving your dialogs to text files.


To save dialogs in text files

The Dialog Designer provides tools that allow you to read and write dialogs, and their associated scripts, to text files. You can use this feature to transfer dialogs between ArcView projects and to edit dialogs stored in a version control system.

To write a dialog to a text file

1	Make the dialog the active document.

2	From the Dialog Editor menu, choose Write text file.

When you write the text file, you can choose whether or not to write out the scripts associated with the dialog

To read a dialog from a text file

1	Open a dialog.

2	From the Dialog Editor menu, choose Read text file.


To select a control interactively
To select a control interactively with the mouse

To select a single control

Move the mouse over the control and click once with the mouse.

To select several controls at once

Click and drag the mouse and enclose the controls you want to select within the rectangle.

To add to the selection

Hold down the SHIFT key and click or click and drag the mouse.


To select a control with a script

There are several different ways you can find and select controls on a dialog. How you write your scripts depends upon what you need to do. For example, if you want to make a control appear selected on the dialog editor (i.e., selection handles showing), you could write a script like this:

aDialogDoc = av.GetProject.FindDoc("Dialog1")

aGraphicList = aDialogDoc.GetGraphics

aGraphicControl = aGraphicList.FindByName("aLabelButton1")

aGraphicControl.Select

After running this script, the label button will appear selected in the dialog editor. To remove a control from the selected set of controls, use the Unselect request.

If you simply want to find a control on a dialog to change it in some way, for instance, change a property, you search through the graphic list as shown in the script above. Once you have the GraphicControl, you can get its Control object through which you modify the properties of the control. For example, you could set the label of the label button:

aGraphicControl.GetControl.SetLabel("OK")

At run time, you select controls from the Dialog object directly (the previous script changed a property at design time in the DialogEditor object). For instance, an Open script commonly contains Avenue code to initialize controls on the dialog. In an Open script, you search the Dialog object directly for a particular control. For example

'Sample Open script to initialize a control.

'The self object in an Open script is the Dialog object.

aListBoxControl = self.FindByName("aListBox1")

aListBoxControl.DefineFromList({1,2,3,4,5})

In scripts not associated with a particular dialog, you can find a Dialog object by searching the application.

av.FindDialog("Dialog1").FindByName("aListBox1")


To select records in a VTab

In ArcView, the Query Builder allows you to select records in a Table document (VTab) based upon attribute values. Through the Query Builder, you build an expression to find records in the table that meet your criteria. The Query Builder provides a generic interface for selecting records based upon their attribute values. However, you might want to create your own interface that caters to your specific needs.

Here's an example that shows you how you could create a dialog to select features in a VTab. This dialog contains a list box and a text line. Text entered into the text line acts as a wildcard to select records from the VTab to display in the list box.

Follow the steps below to create the dialog, substituting your own VTab for the one specified here.

1	Create a dialog and add a list box and a text line to it. Set the properties as shown below.

Control	Property	Setting

List box	Name	lbx_Records

Update	Query.lbx_Records.Update

Text Line	Name	txl_Wildcard

Label	Search String

Changed	Query.txl_WildCard.Changed

Dialog	Name	Query

Open	Query.Open

2	Write the following scripts:

'Query.Open - Initializes the dialog

aLbx = self.FindByName("lbx_Records")

aTxl = self.FindByName("txl_Wildcard")

'Initialize List box display

'Substitute your table document and field name here

aVTab = av.GetProject.FindDoc("Customers.dbf").GetVTab

aField = aVTab.FindField("Name")

aLbx.DefineFromVTab(aVTab, {aField}, false)

'Initialize Text line

aTxl.SetText("")

'Set Listeners

aTxl.SetListeners({aLbx})

'Query.txl_Wildcard.Changed - runs when text line changes

self.BroadcastUpdate

'Query.lbx_Records.Update - Updates list box based upon wildcard

aVTab = self.GetVTab

aBitmap = aVTab.GetSelection

aField = self.GetFields

aFldAlias = aField.Get(0).GetAlias

aWildcard = (self.GetDialog.FindByName("txl_Wildcard").GetText + "*").Quote

'Query VTab based on wildcard

aVTab.Query("["+ aFldAlias +"] = " + aWildCard, aBitmap, #VTAB_SELTYPE_NEW)

aVTab.UpdateSelection

'redefine list box based on new selection

self.DefineFromVTab(aVTab, aField, true)

3	Compile and run the dialog. Make sure you've added a table to your project as referenced in the script, Query.Open.

This example illustrates how you might go about creating your own dialog to query records in a table based upon attribute values. If your goal is to simply move quickly to a particular record in a list box, you can do so by typing a character while the list box has the keyboard focus. The list box will scroll to the first record that begins with that character.


To set control properties of controls on views or layouts with a script

The controls you place on views and layouts are special types of graphics called graphic controls (GraphicControl class). Each graphic control has an associated Control object through which you set the properties of the control, such as its Click script. Here's a script that finds a label button on a view and sets its Click script.

theView = av.GetProject.FindDoc("View1")

theGraphicList = theView.GetGraphics

aGraphicControl = theGraphicList.FindbyName("aLabelButton1")

aControl = aGraphicControl.GetControl

aControl.SetClick("MyScript")

Once you have the Control object, you can set any property of the control with the appropriate request.


To set dialog size at run time
To set the dialog size at run time

To adjust the size of the dialog without changing its position, you can include this code in a script, substituting the name of your dialog:

av.FindDialog("Dialog1").Resize(200,100)

This code sets the dialog width to 200 pixels and the height to 100 pixels. Alternatively, you can size and position the dialog in one step with this code:

av.FindDialog("Dialog1").SetExtent(Rect.Make(50@50, 300@400))

The SetExtent request defines the size and location of a dialog on the screen based on the dimensions of a rectangle. The units of the rectangle are in pixels, relative to the upper-left corner of the screen. The resulting dialog has a width of 300 pixels and a height of 400 pixels, positioned 50 pixels from the top and right sides of the screen.


To explicitly set the dialog size

1	From the Dialog Editor menu, choose Size.

2	Enter the new height and width for the dialog and click OK.


To set an explicit height and width for a control

1	Select the control.

2	From Controls, choose Size and Align.

3	Check the Same Height and Same Width options.

4	Enter in the height and width in inches and click OK


To set properties at run time
To set properties at run time with a script

Each property you see on the Control Properties dialog has corresponding Avenue request that allow you to manipulate it through a script. You use these requests to change the state of the of the control while the dialog is running. For example, you might enable or disable controls based upon the state of other controls on the dialog.

The names of the Avenue request that manipulate control properties typically begin with words like Set, Get, Is, and Has, followed by the name of the property--for example, SetDocActivate, GetLabel, IsEnabled, and HasHorizontalScroll. You can find these requests by searching the on-line help index for the particular control name, such as 'ListBox'.

To manipulate a control, you send the request directly to the control object. For scripts that are attached to control properties (such as the Click property of a button), you can quickly reference the control object with Self. For example, if you want to disable a button by pressing it, you could attach this script to the button's Click property.

Self.SetEnabled(false)

Of course, you'd have to write another script to enable the button. To do that, you need to find the control object on the dialog.

aDialog = av.FindDialog("Dialog1")

aButton = aDialog.FindByName("aButton1")

aButton.SetEnabled(true)

For any control on a dialog, you can get the dialog object that contains it with the GetDialog request. With a dialog object, you can find any other control on it. For example, if you want to enable the disabled button by pressing another button on your dialog, you could use this script as the second button's Click script:

Self.GetDialog.FindByName("aButton1").SetEnabled(false)


How to set control properties
Setting properties through the Control Properties dialog

To change the value of a property

Double-click on it. For properties that consists of only two choices, such as True and False, double-clicking will toggle between the two values. For other properties that, for example, require a string (e.g., help string) or a project component (e.g., a script), you'll be prompted for the appropriate setting.

To clear the value of a property

Click on the property and press DELETE or BACKSPACE. You cannot clear the value of an Icon or Cursor property.

To undo your last change

Press <Control Z> on UNIX and Windows or <Command Z> on Macintosh. Undo restores the state of the last change you made.


To set the size of a control interactively
To set the size of a control interactively with the mouse

1	Select the control.

2	Position the mouse over one of the selection handles.

3	Click and drag the mouse and resize as necessary.


Uninstall and Unload scripts for an extension with dialogs

To unload your extension, you must remove any objects from the current project that the extension installed. Unloading an extension executes two scripts: the Uninstall script and the Unload script.

Uninstall script

Use the Uninstall script to remove extension objects from the project.

 All objects that you add to the project in the Install script must be removed from the project in the Uninstall script.

 If any dialogs or any other objects get created while someone uses the extension, then the Uninstall script must remove these objects as well.

 Here is a sample Uninstall script:

' MyDialogExt.UnInstall

if (av.GetProject = nil) then

  return nil

end

if (av.GetProject.IsClosing) then

  return nil

end

' Remove the button from the button bar

theButtonBar = av.GetProject.FindGUI("View").GetButtonBar

theButtonBar.Remove(Self.Get(1))

This script removes the new button from the View button bar that was added by the Install script of this sample extension. You can use the extension (self) to directly reference the objects to remove from the current project.

Unload script

Use the Unload script to perform any final clean up your extension requires.

 Any extension containing dialogs must have the Dialog.DetachFromExtension request in its Unload script. This request allows the extension to unload properly.

 Here is a sample Unload script:

' MyDialogExt.Unload

Dialog.DetachFromExtension(self)


Updating controls based on changes to other controls

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. Specifically, you want one control to respond to a change in another. 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--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.


Updating controls on views and layouts

If you want the controls on your view or layout to respond to changes in that document, you need to write scripts to update the controls based upon the events that occur. For example, suppose you want to disable a button if there are no themes in the view. You could attach an Update script to the view document, which in turn could call the Update script of the button. To attach an Update script to a document, you need to write a script like this and run it once:

'Script to set an Update script for a document

av.GetProject.FindDoc("View1").SetUpdateScript("anUpdateScript")

The view's Update script would contain an Avenue statement to call the Update script of the button.

'View's update script

self.GetGraphics.FindByName("aButton1").GetControl.Update

The view's Update script runs whenever an Update event occurs, thus, executing the button's Update script. The button's Update script could then verify that the view contains themes and enable or disable itself accordingly.

'Button Update script. This script searches for the

'view document in the current project, but you could just

'as easily store it as an object tag.

theView = av.getproject.finddoc("view1")

self.SetEnabled(theView.GetThemes.IsEmpty.Not)

You could easily enhance these script to update other controls on the view or to check for other types of events.

Instead of attaching an Update script to a particular view document, you can alternatively attach it to the view's button bar.

aButtonBar = av.GetProject.FindGui("View").GetButtonBar

aButtonBar.SetUpdate("anUpdateScript")

With this approach, the Update script runs no matter what view document is active.


What is a dialog?

A dialog is another user interface tool you can use to build applications in ArcView. A dialog is a container for a set of controls--such as a button, a slider, and a check box--arranged in an intuitive manner. 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.

A dialog editor is the document you see in the project window. The dialog editor is analogous to a script editor. It's a place where you put the controls you want on your dialog and arrange them while you're building it. Inside this document is the dialog frame. The frame represents the visible portion of the dialog. You can size the frame as needed to fit all your controls. Controls not within the frame are still part of the dialog, they just won't be seen.


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. 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

The Dialog Designer only allows you to supplement ArcView's interface with dialogs that perform a specialized task. The Dialog Designer does not allow you to replace ArcView's main window, for example, and run your application completely from a dialog.

Why should you use the Dialog Designer?

Before the Dialog Designer, you couldn't design and build custom dialogs using ArcView. Thus, you may have turned to other applications that run outside of ArcView, such as Microsoft Visual Basic, to provide the functionality you needed. While this works to a degree, getting the external dialog to communicate with ArcView is clumsy and inefficient. 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, for example, 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.


Working with tabular data

While the Dialog Designer controls are not designed specifically for working with tabular data, you can use them to create dialogs that display and edit data. For example, you might create a dialog that allows a user to step through the individual records of a table and edit them. On the dialog, you might use a check box to display field values that can be either true or false, or use radio buttons for fields that only have a small number of possible values.

What do you want to do?

Select records in a VTab

Display and edit records in a VTab

Keep the dialog in sync with changes to a table or VTab


Activate Property

The name of a script attached to the dialog's activate event. This script is executed when the dialog becomes the active dialog (for example, when the mouse enters the window of a modeless dialog).

  Related topics


AlwaysOnTop Property

Controls whether or not the dialog will stay on top of the ArcView application window. When TRUE, the dialog will always stay on top of ArcView's application window. Setting this property will not keep the dialog on top of the windows of other applications running on your system.

This property is not supported on the Macintosh and some UNIX workstations.

  Related topics


Apply Property

Specifies the name of the script to execute when an Apply event occurs. A tool, text line, and list box control each have different implementations of the Apply event.

Tool

An Apply event on a tool is triggered by clicking the mouse on a document, such as a view.

Text line

An Apply event on a text line occurs when you press the RETURN key while the text line has the keyboard focus and the dialog doesn't have a default button set. This event is not triggered when the text line loses focus, such as when you press the TAB key or use the mouse to move to another control; use the FocusLost property for this. While you can use the Apply script to validate the text entered into the text line, it may be better to place the validation on the button that executes the dialog, such as an OK button.

List box

An Apply event on a list box occurs when the user double-clicks a cell. Double-clicking the cell runs the Select script (Select property) first, then the script specified with the Apply property. The Apply event typically performs some action on the selection. For example, double-clicking a cell might delete its contents.

With a list box, you can also run scripts when the user:

 clicks a cell; set the Select property or use the SetSelect request.

 selects a specific cell or group of cells; use the SetRangeSelect request.

 double-clicks a specific cell or group of cells; use the SetRangeApply request.

  Related topics


AuxIncrement Property

Adds tick marks along either the top or left side of the slider, depending upon the slider orientation. The default value for this property is zero, or no tick marks. The value you specify represents the distance between the tick marks in the units of the slider and should be appropriate for the range of the slider. For example, a value of 1 on a slider with a range from 0 to 10 would create a tick mark every one unit along the slider. However, a value of 1 is not appropriate where the range of the slider is from 0 to 1000.

This property has no effect on the slider's current value and is only used to enhance the display of the slider.

Some operating systems don't support tick marks on sliders.

  Related topics


Changed Property

Specifies the name of the script to execute when you change the text in the text line or text box. This script runs after every keystroke. This event is not triggered when text is cut from or pasted into the text line.

  Related topics


Click Property

Specifies the name of the script to execute when you click on a button, check box, label button, radio button, slider, text box, text line, or tool.

  Related topics


Closeable Property

Indicates whether the dialog can be closed from the standard window controls on the dialog's frame. Note: different operating systems implement different window frame controls. Thus, even though this property is set to FALSE, the dialog may still be closeable under some operating systems.

  Related topics


Close Property

The name of the script to execute when the dialog is closed.

  Related topics


Cursor Property

Identifies the cursor associated with a tool. Double-click the Cursor property to display the Cursor Manager, a dialog box that contains a list of available cursors. The cursor you select appears when you use the tool on the active document.


DefaultButton Property

Identifies a label button inside a dialog that will have its click script executed when the user presses RETURN. The default button only works when a text line, slider, list box, or combo box control currently has the keyboard focus in the running dialog. Thus, if a checkbox currently has the focus in the dialog, it will be checked or unchecked when the user presses RETURN. Similarly, if another label button has the keyboard focus, its click script will execute, not the default label button's click script.

If, at run time, the default button is disabled, its click script will not execute.

Setting a default button will override the Apply property on a text line.

Use this property, for instance, on dialogs that contain a series of text line controls where the user enters several pieces of information, all of which are validated by pressing RETURN to execute the click script of an OK button.

  Related topics


Disabled Property

Enables or disables the control. You disable a control when it's inappropriate to use it. Typically you'll enable or disable a control through the control's Update script. The Update script determines whether or not the control should be enabled based on the state of other controls on the dialog or on the state of ArcView. For example, you might include a line of code like this:

self.SetEnabled(some condition)

The self object in a control's Update script is the control itself.

Disabling a control panel will disable all the controls on that panel. The dialog itself is a control panel, thus to disable all the controls on a dialog, you could do this:

aDialog.GetControlPanel.SetEnabled(false)

  Related topics


DocActivate Property

The name of a script to execute whenever an ArcView document is activated. This lets the dialog know about any document that becomes active. For example, if you want to disable the controls on a modeless dialog when the active document is not a view or layout, include this code in your DocActivate script:

'Dim control when active doc is not view or layout

theDoc = self.GetActiveDoc

enabled = theDoc.Is(View) or theDoc.Is(Layout)

'the self object is the dialog

self.GetControlPanel.SetEnabled(enabled)

ArcView sends a DocActivate event to all open dialogs that have a DocActivate property set whenever a document becomes active.

The DocActivate script is also where you might include code to update individual controls on your dialog. For example, suppose your dialog lists the active themes in a view. As different views become active, you'd want to update the list of themes to reflect those in the current view.

theDoc = self.GetActiveDoc

aListBox = self.FindByName("aListBox1")

If (theDoc.Is(View) and theDoc.GetThemes.IsEmpty.Not) then

  theThemes = theDoc.GetThemes

  aListBox.DefineFromList(theThemes)

else

  aListBox.DefineFromList({})

end

If, for some reason, the DocActivate script contains an error (e.g., syntax error), the dialog will no longer respond to the DocActivate event (and thus, the DocActivate script will not execute). After correcting the problem with the script, you must reset the DocActivate property on the Control Properties dialog or use the ResetDocActivate request on the Dialog class.

Note	When finding the active document in a DocActivate script or any script called from it, use the GetActiveDoc request on the Dialog object (the self object in the examples above), not the application object, av.

  Related topics


Drag Property

The name of the script that will execute repeatedly while you drag the slider handle.

  Related topics


Empty Property

Specifies the name of the script to execute whenever you enter text into an empty text line or text box, or when you clear out all of the text in a text line or text box.

  Related topics


EscapeEnabled Property

Allows you to dismiss a dialog by pressing the ESCAPE key. Pressing ESCAPE sends the Close request to the dialog. This property is a design time property that prevents you from creating a modal dialog that can't be dismissed for some reason. When you've finished editing your dialog and are ready to incorporate it into your application, you may want to set this property to FALSE so that a user of your dialog can't dismiss it by pressing ESCAPE.

  Related topics


FieldNamesVisible Property

Specifies whether or not field names will appear as the first row in the list box when the list box is defined from a VTab. If a field has an alias, it will be displayed.

  Related topics


FocusLost Property

Specifies the name of the script to execute when the text line loses focus. This occurs when you press the TAB key or use the mouse to move to another control.

  Related topics


HasTitleBar Property

Determines whether or not the dialog frame will have a title bar. To set the text that appears in a title bar, use the Title property.

  Related topics


HelpTopic Property

Specifies the name of the help topic to display as context sensitive help for the dialog when the F1 key is pressed over the dialog. This property is only functional on the dialog itself. In order to maintain compatibility with ArcView version 3.0a, this property also appears on the Control Properties dialog for buttons and tools. However, it is not functional with buttons and tools on dialogs.

The value of this property is the name of the help topic, given as its topic ID (# footnote in the source help file), followed by @, then the name of the help file containing the topic. Use the following syntax:

<aTopicName>@<aHelpFileName>

for example mytopic@myhelp.hlp. ArcView will search for the help file in the Help directory of ArcView's install directory. While you can optionally specify a pathname to the help file, the best method for integrating your help file with ArcView's help system is to place it in ArcView's Help directory. Then you can link your help file to ArcView's contents file (arcview.cnt).

For information on building your own help file, search the online help index for 'help files'.

  Related topics


Help Property

Specifies the help string for the control when you move the mouse over it. This help string has two components: a string that appears in ArcView's status bar and a tool tip that appears directly over the control under the Windows 95 and NT operating systems. The syntax for the help string is:

tool tip//status bar help

Typically the tool tip is one or two words that describe the control whereas the status bar help string is a longer description of the control.

If you just want a tool tip, enter the string as:

tool tip//

If you just want the status bar help string, enter the string without "//".

Tool tips do not appear over control panels or over any control placed on top of a view or layout.

  Related topics


HiddenText Property

When set to True, this property replaces any characters typed into the text line with an asterisk (*). For example, set this property when you want the text line to accept a password. The default value is False.

  Related topics


HorizontalScroll Property

Adds a horizontal scroll bar to a list box or text box.

If a text box does not have a horizontal scroll bar and the text is longer than the width of the text box, the text will wrap. With a horizontal scroll bar, the text will wrap when the new line character (NL) is encountered in the text string displayed in the text box.

If a list box does not have a horizontal scroll bar, its columns will be stretched or compressed to fit the width of the list box. To avoid this behavior set a column width for each column explicitly, or add a horizontal scroll bar.

  Related topics


Horizontal Property

Orients the slider either horizontally or vertically. When True, the slider will be oriented horizontally. This is the default.

  Related topics


Icon Property

Specifies the name of the icon associated with a button, a tool, or an icon box.

To set an icon, double-click the Icon property to display the Icon Manager, a dialog box that contains a list of available icons. From this dialog, you can load your own icon. Valid file formats for an icon include: Windows bitmaps, TIFF, GIF, Sun Rasterfiles, X bitmap, and MacPaint files. For information on loading your own icons into the Icon Manager, search the on-line Help index for 'loading an icon'.

The icon you specify will be centered over the control. If the icon is larger than the control, it will get clipped by the control; ArcView does not scale icons. Screen resolution may also impact the visible display of the icon.

  Related topics


Invisible Property

Determines if the control is visible on the dialog. Use this property to hide or show controls on the dialog. This property can also be set in a script with the SetVisible request.

Making a control panel invisible will also hide all the controls on that panel. The dialog itself is a control panel, thus to hide all the controls on a dialog, you could do this:

aDialog.GetControlPanel.SetVisible(false)

  Related topics


LabelSize Property

Specifies the width in pixels the label associated with a text line will occupy. When set to zero (the default value), the length of the label determines the amount of space required for the label.

Typically, you'll set this property to when you want to align the type-in area of several text line controls, making the type-in area the same width. For example, add two text line controls and set the LabelSize for both to 100. This will make the width of both labels equivalent, regardless of the length of the actual text string. Common settings for this property will range from 25 to 500 pixels, depending upon the size of your dialog. The label will be truncated if the width you specify is not sufficient enough to display the entire text of the label.

  Related topics


Label Property

The visible text string that annotates the control. For example, on a label button, this is the text on the button; on a check box, this is the text next to the check box.

If you don't want a label on your control, highlight the property in the Control Properties dialog and press the delete key.

If you want a multi-line text label, here's a tip. Double-click the Label property to display the dialog that allows you to enter a text string. Select all the text and press the DELETE or BACKSPACE, then immediately press the RETURN key. You can now use the arrow keys on the keyboard to enter text on two lines. If you need more than two lines of text for your label, use the keyboard shortcut to copy and paste the RETURN character to get the number of lines you need. Then, use the arrow keys to enter in text. Another way to create a multi-line label is with Avenue code. For example, you could include this in a dialog's Open script:

l = self.FindByName("aTextLabel1")

l.SetLabel("First line"+NL+"Second line"+NL+"Third line")

The effect a multi-line label has on a control will vary.

  Related topics


Lower Property

Specifies the lower bound of the slider's range. The default value is zero.

After adjusting the slider's range, make sure the ValueIncrement property is set appropriately for the range. An inappropriate ValueIncrement can prevent the slider handle from moving.

  Related topics


MainIncrement Property

Adds tick marks along either the bottom or right side of the slider, depending upon the slider orientation. The value you specify represents the distance between the tick marks in the units of the slider and should be appropriate for the range of the slider. For example, the default value of 2 on a slider with a range from 0 to 10 would create a tick mark every two units along the slider. However, a value of 2 is not appropriate where the range of the slider is from 0 to 1000. Set the property to zero to remove the tick marks.

This property has no effect on the slider's current value and is only used to enhance the display of the slider.

Some operating systems don't support tick marks on sliders.

  Related topics


Modal Property

Makes the dialog the focus of input and prevents the user from working with any other part of ArcView (or any other dialogs) while the modal dialog is displayed. Typically, you use a modal dialog to solicit required information from a user before beginning some process or activity. In order to continue, the user must explicitly dismiss the dialog. Thus, your dialog must provide a method for dismissing itself, such as an OK or Cancel button with the appropriate Avenue code behind it.

While designing your dialog, you can dismiss it by pressing the ESCAPE key if you haven't yet implemented a method for dismissing it. When you've finished editing your dialog and are ready to incorporate it into your application, you may want to set the EscapeEnabled property to FALSE so that a user of your dialog can't dismiss it by pressing ESCAPE.

  Related topics


NextControl Property

Specifies the control that will receive keyboard focus when the tab key is pressed. You might set this property when, for example, you have several text line controls on your dialog and want your user to be able to use the tab key to move between them in a specific order.

You can set the NextControl to one of the following controls: a text line, text box, list box, combo box, or slider. Setting the NextControl of a control to itself stops the tab key from moving when that control is encountered.

  Related topics


Open Property

Specifies the name of the script to execute when the dialog is opened.

This script will typically establish starting values for controls, broadcaster-listener relationships between controls to handle Update events, and a client-server relationship between a dialog and a document. For example:

aTextLine = self.FindByName("aTextLine1")

'initialize a control

aTextLine.SetText("")

'set up listeners for update events

aButton1 = self.FindByName("aLabelButton1")

aButton2 = self.FindByName("aLabelButton2")

aButton3 = self.FindByName("aLabelButton3")

aTextLine.SetListeners({aButton1, aButton2, aButton3})

'set up a server document

self.SetServer(av.GetProject.FindDoc("view1"))

The self object of the Open script is the dialog.

  Related topics


ReadOnly Property

Creates a read-only slider, text box, or text line control that can't be modified by dialog interaction. The default value of this property is false. Set the value to true to create a read-only control. The information displayed by the control can still be modified in your scripts using the appropriate Avenue requests.

  Related topics


Resizable Property

Controls whether a dialog can be resized once displayed. If you want to prevent a user from changing the size of your dialog, set this property to False. You might consider making a dialog resizable when, for example, you have a list box on the dialog and want to show more of the list when the dialog is enlarged. In addition to making the dialog resizable, you'll also need to specify how the list box should respond when the dialog is enlarged. You do this through the Control Fasteners dialog, available on the Control menu of the dialog editor.

  Related topics


Selected Property

Sets the initial state of the checkbox when you first display the dialog. Once you change the selected state of the check box, it will retain that state when you display the dialog again. If you want the check box to initialize to a particular selected state each time you display the dialog, you'll need to add a line of code such as this to the dialog's Open script:

self.FindByName("aCheckBox1").SetSelected(true)

  Related topics


SelectionStyle Property

Defines how you can make selections from the list box. You can define the list box so that you can select:

 a single cell

 a single row

 a single column

 a single range of cells

 multiple ranges of cells

Making a selection in the list box will clear any previous selection, except with the multiple range option. With this option, holding down the SHIFT key will add to the selection.

You can run scripts in response to selections made in the list box. To run a script when the user:

 selects any cell, set the Select property or use the SetSelect request

 double-clicks a cell, set the Apply property or use the SetApply request

 selects a specific cell or group of cells, use the SetRangeSelect request.

 double-clicks a specific cell or group of cells, use the SetRangeApply request

  Related topics


Select Property

Specifies the name of the script to execute when a user interactively selects a row in a combo box or when a user interactively selects or deselects cell in a list box. Select scripts typically inform other controls, or other parts of ArcView, that the selection has changed. For example, making a selection might cause a button to activate.

This script does not run when you programmatically select a row through another script associated with the dialog.

With a list box, you can also run scripts when the user:

 double-clicks a cell; set the Apply property or use the SetApply request.

 selects a specific cell or group of cells; use the SetRangeSelect request.

 double-clicks a specific cell or group of cells; use the SetRangeApply request.

  Related topics


ServerActivated Property

The name of the script to execute when the dialog's server document becomes active. For example, suppose you wanted to enable the controls on the dialog when its server document became active. You could include this code in the ServerActivated script:

self.GetControlPanel.SetEnabled(true)

where the self object is the dialog.

This property does not apply when the server is a VTab.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("view1"))

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerActivated script whenever the server document becomes active, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerClosed Property

The name of the script to execute when the dialog's server document window is closed. For example, if you want to close the dialog when the server document is closed. The ServerClosed script would contain:

self.Close

where the self object is the dialog.

This property does not apply when the server is a VTab.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("view1"))

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerClosed script whenever the server document window is closed, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerDeactivated Property

The name of the script to execute when the dialog's server document becomes inactive. For example, suppose you wanted to disable the controls on the dialog when its server document became inactive. You could include this code in the ServerDeactivated script:

self.GetControlPanel.SetEnabled(false)

where the self object is the dialog.

This property does not apply when the server is a VTab.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("view1"))

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerDeactivated script whenever the server document becomes inactive, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerDefinitionChanged Property

The name of the script to execute when the definition of the dialog's server VTab is changed.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("Table1").GetVTab)

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerDefinitionChanged script whenever you change the definition of the server VTab, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerOpened Property

The name of the script to execute when the dialog's server document window is opened. For example, if you want to open the dialog when the server document is opened, you could include this code in the ServerOpened script:

self.Open

where the self object is the dialog.

This property does not apply when the server is a VTab.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("view1"))

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerOpened script whenever the server document window is opened, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerRecordsAdded Property

The name of the script to execute when records are added to the dialog's server VTab or Table document.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("Table1"))

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerRecordsAdded script whenever you add records to the server VTab or Table, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerRecordsDeleted Property

The name of the script to execute when records are deleted from the dialog's server VTab or Table document.

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("table1"))

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerRecordsDeleted script whenever you delete records from the server VTab or Table, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


ServerSelectionChanged Property

The name of the script to execute whenever the selection changes in a dialog's server VTab (or FTab). For instance, this can occur when a user of the dialog:

 Selects a feature using theme selection tools

 Selects a record in a table

 Deletes a data element from a chart

 Performs theme on theme selection

 Interacts with the Query Builder

A dialog can establish a client-server relationship with a particular document or VTab. You typically establish the server document in the dialog's Open or DocActivate scripts using the SetServer request.

self.SetServer(av.GetProject.FindDoc("table1").GetVTab)

If interacting with a control on the dialog can change the server, the SetServer request may instead be part of a script attached that control.

A dialog will continue to run its ServerSelectionChanged script whenever the selection changes in the server VTab, even if the dialog is closed. If you don't want this to happen, your script should contain code to check if the dialog is open:

if (aDialog.IsOpen) then

  (do something)

else

  (do something else)

  Related topics


Size Property

Specifies the length of the string the text line or text box can accept. The default value of zero indicates that the control will accept an unlimited number of characters. Set this property when you need to restrict the number of characters that should be entered into the control.

The SetSize request on a text line and text box control allow you to set this property in your scripts.


StepButtons Property

Adds or removes step buttons from the slider. The default value is False, or no step buttons. When set to True, the slider displays step buttons providing another method for setting the slider value. When you click a step button, the slider will move by the value specified in the ValueIncrement property. If ValueIncrement is zero, the slider will move by the value specified in MainIncrement. If this is also zero, the slider will move 10% of the interval. Step buttons are not available under the UNIX operating system.

  Related topics


Tag Property

Stores any additional text string that's needed for a control. ArcView does not use the Tag property so you can use it without affecting any of the control's other property settings or causing any other side effects. The Tag property can only reference a string; use an ObjectTag to reference other objects.

  Related topics


TextType Property

Defines the types of characters that a text line can accept: alpha-numeric characters, integers, or only real numbers. The first will be left-justified; the latter two will be right-justified.

If you specify a default text string with the Text property, it's a good idea that the string matches the type you specify here.

  Related topics


Text Property

Specifies the text string to display in the text line or text box when the dialog is first displayed. If you change the text string, the dialog will retain the value when subsequently displayed. To initialize the text string each time you display the dialog, you need to add a line of code like this to the dialog's Open script.

self.FindByName("aTextLine1").SetText("Initial value")

ArcView does not check whether the text you supply for this property matches the text type you specify with the TextType property. For example, if you enter a character string here, but define the text line to accept only integers, the character string will display on the dialog, but the end user will need to erase the character string before they can enter an integer.

  Related topics


Title Property

Sets the title for the dialog. If you don't want a title bar at all on your dialog, set the HasTitleBar property to FALSE.

  Related topics


Update Property

Sets the name of the script to execute when an Update event occurs. The Update script typically performs some operation in response to a change in the dialog that triggers an Update event. For example, you might use an Update script to enable an OK button on your dialog once a user provides some input the dialog requires--such as typing some text into a text line control.

With dialogs, you control when to broadcast an Update event and which controls will respond to that event. This is different from how the Update property works with controls on the menu, button, and tool bar. For instance, ArcView broadcasts an Update event whenever a document is activated. The controls on the menu, button, and tool bar respond by running their respective Update scripts. In the case of controls on a dialog, ArcView does not attempt to determine which controls need to respond to the Update event; it's up to you to decide when a control's Update script should be run.

For a given control on your dialog, you specify which other controls should listen to it. When you want to run the Update scripts of the listening controls, you broadcast an Update event. For example, if you have a dialog that contains a text line and a button, and you want to dim the button when the text line is empty, you would make the button a listener of the text line. Typically, you set this broadcaster-listener relationship in the dialog's Open script:

'the self object is the dialog

aTextLine = self.FindByName("aTextLine1")

aButton = self.FindByName("aLabelButton2")

aTextLine.SetListeners({aButton})

If the text line is cleared out, it would broadcast an Update event causing the button's Update script to execute. For example, the text line's Empty property would reference a script that contained this code:

'the self object is the text line control

self.BroadcastUpdate

It would then be the responsibility of the button's Update script to dim the button.

A control 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:

aTextLine.SetListeners({aButton1, aButton2, aButton3})

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

ATextLine.AddListener(aButton4)

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.

  Related topics


Upper Property

Specifies the upper bound of the slider's range. The default value is 10.

After adjusting the slider's range, make sure the ValueIncrement property is set appropriately for the range. An inappropriate ValueIncrement can prevent the slider handle from moving.

  Related topics


ValueIncrement Property

Restricts the values that a slider can take on. The default value is 1. When ValueIncrement is zero, the slider can assume any real number defined within its range. When ValueIncrement is greater than zero, the slider's value will always be in the form

slider lower bound + (i * ValueIncrement)

where i is a positive integer.

For example, suppose you want to restrict a slider's value to an integer. Given a lower bound of 0 and an upper bound of 10, setting ValueIncrement to 1 would allow the slider to assume all integer values between 0 and 10. A ValueIncrement of 2 would restrict values to even numbers. To restrict the slider to odd numbers, you'd have to set the slider's lower bound to 1 and keep ValueIncrement at 2.

  Related topics


Value Property

Sets the initial value for the slider the first time you display the dialog. The default setting for this property is zero. Once you change the slider's value, it will retain that value when you display the dialog again. If you want the slider to initialize to a particular value each time you display the dialog, you'll need to add a line of code such as this to the dialog's Open script:

self.FindByName("aSlider1").SetValue(4)

You can also set the slider's value equal to a percentage of the slider's interval with the SetValuePercentage request:

self.FindByName("aSlider1").SetValuePercentage(50)

  Related topics


VerticalScroll Property

Adds a vertical scroll bar to a list box or text box.

If a text box does not have a vertical scroll bar, you can still scroll the text by dragging the mouse through the text box.

If a list box does not have a vertical scroll bar, the height of its rows will be stretched or compressed to fit the height of the list box. To avoid this behavior set a row height for each row explicitly, or add a vertical scroll bar.

  Related topics


VisibleBorder Property

Determines whether the control panel will have a visible border. When True, the control panel will have a line drawn around its perimeter.

  Related topics