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.


ComboBox

 A ComboBox control provides an interface for selecting an object from a list of related objects. A ComboBox 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 popup a single-column, scrolling list that shows all rows in the combo box.

Before you can do anything to a row (select it, for example), or obtain its associated object, you must make it the "current" row. Only one row can be "current" at a time. A row can also be "selected". This is the row containing the object that is visible to the user. The current row does not have to stay the same as the selected row.

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

Attributes

Listening.When TRUE, the combo box will execute its update event script whenever it receives an update event. When FALSE, it will ignore update events.

VTab.You can define the rows of the combo box from a field in a VTab. This attribute is a reference to that VTab.

Dictionary.You can define the rows of the combo box from the keys in a dictionary. This attribute is a reference to that dictionary. The property references a dictionary that you provide. The combo box does make a copy of it. Thus, you must avoid updating this dictionary directly without sending the DefineFromDictionary request again.

Select.The name of the script that will be executed when the user selects a row in the combo box. This script will not be executed if you programmatically select a row. In that case, you must explicitly tell the combo box to execute its select event script.

Listeners.The list of controls that will have their update scripts executed whenever the request BroadcastUpdate is sent to the combo box.

NextControl.The control that will receive keyboard focus when the tab key is pressed when the combo box has keyboard focus.

Fasteners.A list of enumeration elements from the enumeration ControlFastenerEnum. They describe how the combo box will adjust its size and position when its containing control panel changes its size and position.

RowCount.The number of rows in the combo box.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making ComboBoxes

Make  :  ComboBox

Instance Requests

Defining the contents of ComboBoxes

DefineFromDictionary ( aDictionary )

DefineFromList ( aList )

DefineFromVTab ( aVTab, aField, displaySelectedRecords )

DefineUniqueFromVTab ( aVTab, aField, selectionOnly, caseSensitive, sortAscending )

Empty

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Moving around in a ComboBox

FindByValue ( anIconOrString )

GoFirst  :  Boolean

GoLast  :  Boolean

GoNext  :  Boolean

GoPrevious  :  Boolean

GoRecord ( nthRecord )

GoRow ( aRowOffset )

Using ComboBoxes

DeleteRows ( numRows )

Focus

InsertRows ( numRows )

Select

SelectCurrent

SortAscending ( caseSensitive )

SortDescending ( caseSensitive )

Update

Getting/Setting attributes of ComboBoxes

GetCurrentRecord  :  Number

GetCurrentRow  :  Number

GetCurrentValue  :  Obj

GetDialog  :  Dialog

GetDictionary  :  Dictionary

GetField  :  Field

GetLabel  :  String

GetList  :  List

GetNextControl  :  Control

GetRowCount  :  Number

GetSelect  :  String

GetSelection  :  Obj

GetVTab  :  VTab

HasFastener ( aFastener ) :  Boolean

HasScript ( aScriptName ) :  Boolean

HasSelection  :  Boolean

SetCurrentValue ( anObject )

SetEnabled ( enabled )

SetFastener ( fastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetField ( aField )

SetLabel ( aLabel )

SetNextControl ( aControl )

SetSelect ( aScriptName )

SetVisible ( visible )

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

ControlPanel
Icon
String
Table
VTab


Make (ComboBox)
Make
Example

Create a new ComboBox object.

Syntax

ComboBox.Make

Returns

ComboBox


DefineFromDictionary (ComboBox)
DefineFromDictionary

Associates aDictionary with aComboBox and displays its keys as the values of aComboBox. The request SetCurrentValue updates the key for a particular association in aDictionary.

aComboBox becomes the owner of aDictionary. You should not modify the keys of aDictionary directly without subsequently calling DefineFromDictionary again. You can, however, manipulate the values in any way at any time.

Syntax

aComboBox.DefineFromDictionary (aDictionary)


DefineFromList (ComboBox)
DefineFromList

Populates aComboBox using the contents of aList. aList can contain objects of any kind, except other lists. Each element of aList is displayed on a new row.

When the ComboBox is drawn on the dialog, elements that are symbols or icons are drawn in their rows; elements that are strings are printed in their rows and the width of the row is not adjusted to show the entire string; elements that are other kinds of objects get sent the AsString request, and those strings are then printed in their rows. When the end user selects an element from the Combobox, the actual object is returned, not a string representation of it, as shown in the Combobox.

You can manipulate aList in any way after using it as a parameter in this request. aComboBox maintains separate references to its objects.

For example, the following Avenue code fragment will result in aComboBox with three rows:

  aComboBox.DefineFromList( { 1, "hi", av.FindGUI("View").GetIcon} )

Syntax

aComboBox.DefineFromList (aList)


DefineFromVTab (ComboBox)
DefineFromVTab

 Populates the contents of aComboBox from aVTab. aField is the field from aVTab that should be shown in aComboBox. If displaySelectedRecords is true, then only records that are selected in aVTab will be visible in aComboBox. aComboBox can display a maximum of 32,767 records from aVTab.

Syntax

aComboBox.DefineFromVTab (aVTab, aField, displaySelectedRecords)


DefineUniqueFromVTab (ComboBox)
DefineUniqueFromVTab

 Populates the contents of aComboBox with unique values from aField in aVTab. If selectionOnly is TRUE, then only selected values from aVTab will be examined for uniqueness. If caseSensitive is TRUE, then values from character fields will be considered unique if they differ only in case, otherwise they will be considered identical. If sortAscending is TRUE, then the values will be sorted in ascending order, otherwise they will be sorted in descending order.

Syntax

aComboBox.DefineUniqueFromVTab (aVTab, aField, selectionOnly, caseSensitive, sortAscending)


Empty (ComboBox)
Empty

Removes all rows from aComboBox. If its contents were defined from the keys of a dictionary, then the dictionary is also emptied. If its contents were defined from a VTab, the VTab is not affected. The requests GetDictionary and GetVTab return nil after using this request.

Syntax

aComboBox.Empty


Move (ComboBox)
Move

Move aComboBox dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aComboBox to another control panel. If aComboBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aComboBox to a dialog object. You cannot use this request to move aComboBox in a View, Layout or Dialog Editor document; see the SetBounds request on the GrphicControl class.

Syntax

aComboBox.Move (dx, dy)


MoveTo (ComboBox)
MoveTo

Move aComboBox to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aComboBox to another control panel. If aComboBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aComboBox is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aComboBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aComboBox to a dialog object. You cannot use this request to move aComboBox in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aComboBox.MoveTo (x, y)


Resize (ComboBox)
Resize

Make aComboBox dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aComboBox to a dialog object. You cannot use this request to resize aComboBox in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aComboBox.Resize (dw, dh)


ResizeTo (ComboBox)
ResizeTo

Makes aComboBox w pixels wide and h pixels tall. The position of its upper left hand corner of the bounding box is not changed.

You can only use this request after adding aComboBox to a dialog object. You cannot use this request to resize aComboBox in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aComboBox.ResizeTo (w, h)


ReturnBox (ComboBox)
ReturnBox

Returns a copy of the bounding box for aComboBox. The box's coordinates are in the coordinate system of aComboBox's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aComboBox is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aComboBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aComboBox.ReturnBox

Returns

Rect


FindByValue (ComboBox)
FindByValue

Each row in aComboBox is examined to see if its value is anIcon, or if it contains a string that exactly matches the characters in aString. If such a row is found, it becomes the current row. Otherwise, the current row is not changed. The search is not case sensitive. If aComboBox has several rows with the same value that qualify the search, the first one it finds becomes the current row. Use SelectCurrent request to make the current row visible to the user.

You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.FindByValue (anIconOrString)


GoFirst (ComboBox)
GoFirst

Makes the first row the current row. The request returns TRUE if aComboBox is not empty, FALSE if it is empty. Use the SelectCurrent request to show the current row. This request can only be used after aComboBox has been added to a dialog.

Syntax

aComboBox.GoFirst

Returns

Boolean


GoLast (ComboBox)
GoLast

Makes the last row the current row. Returns TRUE if aComboBox is not empty, FALSE if it is. Use the SelectCurrent request to show the current row. This request can only be used after aComboBox has been added to a dialog.

Syntax

aComboBox.GoLast

Returns

Boolean


GoNext (ComboBox)
GoNext

Makes the next row the current row. The request returns TRUE if this operation doesn't move the current row beyond the end of aComboBox, FALSE if it does. Use the SelectCurrent request to show the current row. This request can only be used after aComboBox has been added to a dialog.

Syntax

aComboBox.GoNext

Returns

Boolean


GoPrevious (ComboBox)
GoPrevious

Makes the previous row the current row. The request returns TRUE if this operation doesn't move the current row beyond the beginning of aComboBox, FALSE if it does. Use the SelectCurrent request to show the current row. This request can only be used after aComboBox has been added to a dialog.

Syntax

aComboBox.GoPrevious

Returns

Boolean


GoRecord (ComboBox)
GoRecord

Makes the current row the one containing the object obtained from the nthRecord of the vtab associated with aComboBox. AComboBox must have been defined using DefineFromVTab. Otherwise, it returns nil. Use the SelectCurrent request to show the current row. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GoRecord (nthRecord)


GoRow (ComboBox)
GoRow

Makes the current row the one that is aRowOffset rows from the top of aComboBox. Use the SelectCurrent request to show the current row. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GoRow (aRowOffset)


DeleteRows (ComboBox)
DeleteRows

Deletes the current row, and numRows-1 rows following that row. If less than numRows-1 rows follow, then they will be deleted, and the total number of deleted rows will be less than numRows. Deleting rows from aComboBox defined from a dictionary removes from the dictionary those associations whose keys were displayed in the rows. Deleting rows from aComboBox defined from a VTab doesn't affect its associated VTab in any way.

You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.DeleteRows (numRows)


Focus (ComboBox)
Focus

Assigns keyboard focus to aComboBox. This request has no effect between the time aComboBox is loaded from a project and the time its containing dialog or document is made visible.

Syntax

aComboBox.Focus


InsertRows (ComboBox)
InsertRows

Inserts numRows rows into aComboBox. These rows are inserted before the current row. You cannot add rows to aComboBox when its contents are defined from a VTab or a dictionary. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.InsertRows (numRows)


Select (ComboBox)
Select

Executes aComboBox's select script.

Syntax

aComboBox.Select


SelectCurrent (ComboBox)
SelectCurrent

Selects and shows the current row. No event scripts are executed. Send the Select request to aComboBox if you want its select event script to be executed with the new selection.

Syntax

aComboBox.SelectCurrent


SortAscending (ComboBox)
SortAscending

Sorts aComboBox in ascending order. If caseSensitive is TRUE, differences in the case of string will influence the sorting order. Icons are sorted by name. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.SortAscending (caseSensitive)


SortDescending (ComboBox)
SortDescending

Sorts aComboBox in descending order. If caseSensitive is TRUE, differences in the case of string will influence the sorting order. Icons are sorted by name. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.SortDescending (caseSensitive)


Update (ComboBox)
Update

Executes aComboBox's update script if aComboBox is listening to updates.

Syntax

aComboBox.Update


GetCurrentRecord (ComboBox)
GetCurrentRecord

Get the VTab record number of the current row of aComboBox. This request returns nil if if the contents of aComboBox were not defined using DefineFromVTab. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GetCurrentRecord

Returns

Number


GetCurrentRow (ComboBox)
GetCurrentRow

Gets the offset of the current row from the top of aComboBox. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GetCurrentRow

Returns

Number


GetCurrentValue (ComboBox)
GetCurrentValue

Gets the object associated with the current row. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GetCurrentValue

Returns

Obj


GetDialog (ComboBox)
GetDialog

Gets the dialog that contains aComboBox. You may only use this request after adding aComboBox to a dialog.

Syntax

aComboBox.GetDialog

Returns

Dialog


GetDictionary (ComboBox)
GetDictionary

Gets the dictionary used to define the contents of aComboBox. This request returns NIL if DefineFromDictionary was not used to define the current contents of aComboBox.

Syntax

aComboBox.GetDictionary

Returns

Dictionary


GetField (ComboBox)
GetField

Gets the field from which aComboBox's values were obtained. The return value will be nil if aComboBox's contents are not defined from a VTab.

Syntax

aComboBox.GetField

Returns

Field


GetLabel (ComboBox)
GetLabel

Gets the label for aComboBox. This request will always return whatever was last passed to the SetLabel request, even if SetLabel didn't produce a visible change (see SetLabel).

Syntax

aComboBox.GetLabel

Returns

String


GetList (ComboBox)
GetList

Gets a list containing the objects that are in aComboBox. You can manipulate this list without affecting the ordering of the objects in aComboBox. This request return nil when aComboBox is defined from a VTab or a dictionary.

Syntax

aComboBox.GetList

Returns

List


GetNextControl (ComboBox)
GetNextControl

Gets the control which will receive keyboard focus when the user presses the TAB key when aComboBox has focus.

Syntax

aComboBox.GetNextControl

Returns

Control


GetRowCount (ComboBox)
GetRowCount

Gets the current number of rows in aComboBox. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GetRowCount

Returns

Number


GetSelect (ComboBox)
GetSelect

Gets the name of the Select script used by aComboBox.

Syntax

aComboBox.GetSelect

Returns

String


GetSelection (ComboBox)
GetSelection

Gets the object associated with the row that is currently visible in aComboBox. This may be different than the current row if GoFirst, GoNext, etc. were used after the selection was made. If there is no selection, nil is returned.

Syntax

aComboBox.GetSelection

Returns

Obj


GetVTab (ComboBox)
GetVTab

Returns the VTab currently associated with aComboBox, or nil if aComboBox is not obtaining its values from any vtab. You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.GetVTab

Returns

VTab


HasFastener (ComboBox)
HasFastener

Returns TRUE if aComboBox currently has aFastener defined for it.

Syntax

aComboBox.HasFastener (aFastener)

Returns

Boolean


HasScript (ComboBox)
HasScript

Returns TRUE if aComboBox is associated with an event script name aScriptName.

Syntax

aComboBox.HasScript (aScriptName)

Returns

Boolean


HasSelection (ComboBox)
HasSelection

Returns true if an element of aComboBox is displayed. This might not be the case after deleting rows from aComboBox, for example.

Syntax

aComboBox.HasSelection

Returns

Boolean


SetCurrentValue (ComboBox)
SetCurrentValue

Associate anObject with the current row. The object is represented in one of three ways:

  - If anObject is an icon, the icon is drawn
  - If anObject is a string, it is printed in the row
  - If anObject is some other kind of object, it is sent the AsString
     request when it needs to be drawn, and that string is then printed
     in the row.

This request does not affect any associated VTab in any way. You are responsible for posting such changes back to the VTab. The requests GetCurrentRecord and GetField can aid in doing this.

You may only use this request after adding aComboBox to a control panel.

Syntax

aComboBox.SetCurrentValue (anObject)


SetEnabled (ComboBox)
SetEnabled

When enabled is TRUE, the user can interactively change the selected element. When enabled is FALSE, that element cannot be changed interactively.

Syntax

aComboBox.SetEnabled (enabled)


SetFastener (ComboBox)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aComboBox.SetFastener (fastener, onOrOff)

Returns

Boolean


SetFasteners (ComboBox)
SetFasteners

Defines resizing and repositioning fasteners for aComboBox. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aComboBox's fasteners are not altered.

Syntax

aComboBox.SetFasteners (aListOfFasteners)

Returns

Boolean


SetField (ComboBox)
SetField

Changes the field from which aComboBox obtains its values. aField must be part of the same VTab that was originally used to define aComboBox's values.

Syntax

aComboBox.SetField (aField)


SetLabel (ComboBox)
SetLabel

Changes the label of aComboBox. This request will not have a visible effect when aComboBox is already in a dialog. You will need to remove aComboBox from the dialog, then re-add it, for the change to take place.

Syntax

aComboBox.SetLabel (aLabel)


SetNextControl (ComboBox)
SetNextControl

Sets the control which will receive keyboard focus when the user presses the TAB key while aComboBox has the keyboard focus.

Syntax

aComboBox.SetNextControl (aControl)


SetSelect (ComboBox)
SetSelect

Sets the Select script for aComboBox.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aComboBox.SetSelect (aScriptName)


SetVisible (ComboBox)
SetVisible

When visible is TRUE, aComboBox will be made visible, otherwise it will be made invisible.

Syntax

aComboBox.SetVisible (visible)


AddListener (ComboBox)
AddListener

Adds aControl as a listener of aComboBox. If aControl is already a listener, it is not added again. You do not need to use the ChangedListeners request after using this request.

Syntax

aComboBox.AddListener (aControl)


BroadcastUpdate (ComboBox)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aComboBox.

Syntax

aComboBox.BroadcastUpdate


ChangedListeners (ComboBox)
ChangedListeners

Informs aComboBox that you have modified its list of listeners. Send this request after manipulating the list obtained from the GetListeners request. You do not need to send this request after using the SetListeners, AddListener, or RemoveListener requests.

Syntax

aComboBox.ChangedListeners


GetBroadcaster (ComboBox)
GetBroadcaster

Returns the control that is sending an update event to aComboBox. Do not store the result of this request over multiple executions of aComboBox's update script. This request will return nil if the update event was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aComboBox.GetBroadcaster

Returns

Obj


GetListeners (ComboBox)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aComboBox. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aComboBox.

Syntax

aComboBox.GetListeners

Returns

List


IsListening (ComboBox)
IsListening

Returns TRUE if aComboBox will execute its update script in response to an update event.

Syntax

aComboBox.IsListening

Returns

Boolean


RemoveListener (ComboBox)
RemoveListener

Removes aControls from aComboBox's list of listeners. Nothing happens if aControl is not in that list. You do not need to send the ChangedListeners request after using this request.

Syntax

aComboBox.RemoveListener (aControl)


SetListeners (ComboBox)
SetListeners
Example

Sets the listeners that will be sent the update event when aComboBox is sent the BroadcastUpdate request. The input list, but not its elements, is cloned by this request. You do not need to use the ChangedListeners request after using this request.

Syntax

aComboBox.SetListeners (aListOfListeners)


StartListening (ComboBox)
StartListening

aComboBox will respond to any future update events by executing its update script.

Syntax

aComboBox.StartListening


StopListening (ComboBox)
StopListening

aComboBox will not execute its update script in response to an update event.

Syntax

aComboBox.StopListening


CheckBox

 A check box is a control that displays a boolean value. A true value is represented by a selected check box. A false value is represented by an unselected check box.

Attributes

Selected.TRUE when the check box is selected, FALSE otherwise.

Click.The name of the script that executes whenever a user clicks on the check box.

Label.The text that appears next to the check box square.

Listeners.The list of controls that will have their update scripts executed whenever the request BroadcastUpdate is sent to the check box.

Listening.When TRUE, the check box will respond to an update event by executing its update event script, otherwise it will ignore the update event.

Box.The bounding box of the check box. It is expressed in the pixel coordinate system, which has coordinates in screen pixels and an origin at the upper left hand corner of the control panel or dialog containing the check box.

Fasteners.A list of enumeration elements from the enumeration ControlFastenerEnum. They describe how the check box will adjust its size and position when its containing control panel changes its size and position.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making CheckBoxes

Make  :  CheckBox

Instance Requests

Using CheckBoxes

Click

Update

Getting/Setting attributes of CheckBoxes

GetClick  :  String

GetDialog  :  Dialog

GetLabel  :  String

HasFastener ( aFastener ) :  Boolean

HasScript ( aScriptName ) :  Boolean

IsSelected  :  Boolean

SetClick ( aScriptName )

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetLabel ( aLabel )

SetSelected ( selected )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

ControlPanel


Make (CheckBox)
Make
Example

Creates a CheckBox object.

Syntax

CheckBox.Make

Returns

CheckBox


Click (CheckBox)
Click

 Executes aCheckBox's Click event script. This request does not select aCheckBox.

Syntax

aCheckBox.Click


Update (CheckBox)
Update

Executes aCheckBox's update script if aCheckBox is listening to updates.

Syntax

aCheckBox.Update


GetClick (CheckBox)
GetClick

 Returns the name of the event script that is executed when a user clicks on aCheckBox to select or unselect it.

Syntax

aCheckBox.GetClick

Returns

String


GetDialog (CheckBox)
GetDialog

Gets the dialog containing a checkbox. You may only use this request after adding aCheckBox to a dialog.

Syntax

aCheckBox.GetDialog

Returns

Dialog


GetLabel (CheckBox)
GetLabel

 Gets the label used by aCheckBox.

Syntax

aCheckBox.GetLabel

Returns

String


HasFastener (CheckBox)
HasFastener

Returns TRUE if aCheckBox currently has aFastener defined for it.

Syntax

aCheckBox.HasFastener (aFastener)

Returns

Boolean


HasScript (CheckBox)
HasScript

Returns TRUE when aCheckBox is associated with a script named aScriptName.

Syntax

aCheckBox.HasScript (aScriptName)

Returns

Boolean


IsSelected (CheckBox)
IsSelected

Returns TRUE when aCheckBox is selected. Otherwise it returns FALSE.

Syntax

aCheckBox.IsSelected

Returns

Boolean


SetClick (CheckBox)
SetClick

 Assigns the script named aScriptName to be executed when a user clicks on aCheckBox to select or unselect it.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aCheckBox.SetClick (aScriptName)


SetFastener (CheckBox)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aCheckBox.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (CheckBox)
SetFasteners

Defines positioning and resizing fasteners for aCheckBox. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aCheckBox's fasteners are not altered.

Syntax

aCheckBox.SetFasteners (aListOfFasteners)

Returns

Boolean


SetLabel (CheckBox)
SetLabel

 Sets aLabel to be the label drawn next to aCheckBox.

Syntax

aCheckBox.SetLabel (aLabel)


SetSelected (CheckBox)
SetSelected

If selected is TRUE, aCheckBox will be put into its selected state, otherwise it will be unselected. Sending this request does not execute aCheckBox's click script.

Note There is no equivalent of this request to select a RadioButton. use aRadioButton.Select instead.

Syntax

aCheckBox.SetSelected (selected)


Move (CheckBox)
Move

Move aCheckBox dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aCheckBox to another control panel. If aCheckBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding Check Box to a dialog object. You can't use this request to move a check box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aCheckBox.Move (dx, dy)


MoveTo (CheckBox)
MoveTo

Move aCheckBox to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aCheckBox to another control panel. If aCheckBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aCheckBox is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aCheckBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding Check Box to a dialog object. You can't use this request to move a check box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aCheckBox.MoveTo (x, y)


Resize (CheckBox)
Resize

Make aCheckBox dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding Check Box to a dialog object. You can't use this request to resize a check box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aCheckBox.Resize (dw, dh)


ResizeTo (CheckBox)
ResizeTo

Makes aCheckBox w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding Check Box to a dialog object. You can't use this request to resize a check box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aCheckBox.ResizeTo (w, h)


ReturnBox (CheckBox)
ReturnBox

Returns a copy of the bounding box of aCheckBox. The box's coordinates are in the coordinate system of aCheckBox's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aCheckBox is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aCheckBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aCheckBox.ReturnBox

Returns

Rect


AddListener (CheckBox)
AddListener

Adds aControl to aCheckBox's list of listeners. aControl will be sent an update when the BroadcastUpdate request is sent to aCheckBox. You do not need to use the ChangedListeners request after this request.

Syntax

aCheckBox.AddListener (aControl)


BroadcastUpdate (CheckBox)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aCheckBox.

Syntax

aCheckBox.BroadcastUpdate


ChangedListeners (CheckBox)
ChangedListeners

Notifies aCheckBox that its list of listeners has been changed. You need to use this request after modifying the list obtained from the request GetListeners. You do not need to use this request after using SetListeners, AddListener or RemoveListener.

Syntax

aCheckBox.ChangedListeners


GetBroadcaster (CheckBox)
GetBroadcaster

Returns the control that is sending an update event to aCheckBox. Do not store the result of this request over multiple executions of aCheckBox's update script. This request will return nil if the update event aCheckBox is responding to was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aCheckBox.GetBroadcaster

Returns

Obj


GetListeners (CheckBox)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aCheckBox. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the ChangedListeners request to aCheckBox.

Syntax

aCheckBox.GetListeners

Returns

List


IsListening (CheckBox)
IsListening

Returns TRUE if aCheckBox will execute its update script in response to an update event.

Syntax

aCheckBox.IsListening

Returns

Boolean


RemoveListener (CheckBox)
RemoveListener

Removes aControl from aCheckBox's list of listeners. aControl will no longer receive update events when aCheckBox is sent the BroadcastUpdate request. You do not need to use the ChangedListeners request after this request.

Syntax

aCheckBox.RemoveListener (aControl)


SetListeners (CheckBox)
SetListeners
Example

Sets the listeners that will be sent the update event when aCheckBox is sent the BroadcastUpdate request. You are free to modify aListOfListeners after using it with this request. You do not need to use the ChangedListeners request after using this request.

Syntax

aCheckBox.SetListeners (aListOfListeners)


StartListening (CheckBox)
StartListening

aCheckBox will respond to any future update events by executing its update script.

Syntax

aCheckBox.StartListening


StopListening (CheckBox)
StopListening

aCheckBox will not execute its update script in response to an update event.

Syntax

aCheckBox.StopListening


Dialog

 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 dialog objects in two ways. You can either send the Make request to the Dialog class, then add controls to it using other requests, or you can interactively create dialogs and controls using a Dialog Editor document. In either case, the resulting dialog and its controls can be manipulated in almost any way at any time.

You customize the behavior of a dialog and its controls the same as you customize arcview. You identify events of a dialog and its controls that you are interested in responding to, and then attach scripts to those events.

Dialogs and Extensions

One way to distribute your dialogs to other users is to package them into an ArcView Extension. Creating an extension that contains dialogs is mostly like creating any other kind of extension but there are two important differences.

- Your extension probably shouldn't contain the dialog editor document or the dialog editor DocGUI. These dialog development components are probably of no use to those who want to use your dialogs. To avoid distributing these along with your dialogs, you need to make your extension dependant on $AVBIN/avdlog.dll, rather than $AVEXT/dialog.avx.

- You need to create an Unload script for your dialog extension. Any extension that has dialogs needs to define an Unload script that contains at least this line:

     Dialog.DetachFromExtension(self)

This request lets your extension unload itself properly when it contains dialogs. In addition, if your extension creates dialogs and adds them to a project, you are responsible for either making sure that the user can't unload your extension (by defining a CanUnload script for the extension and having it return FALSE), or for making sure that those dialogs are removed from the project and made eligble for garbage collection during execution of the extension's Unload script.

Working with modal dialogs

A modal dialog prevents the user from working with any other dialog (or any other part of ArcView) while it is displayed. It is typically used to solicit information from a user which is required before some processing activity can continue. In order to continue, the user must explicitly dismiss the dialog by doing something to a control in the content area of the dialog. For example, ArcView's MsgBox class implements a number of different modal dialogs. The user dimisses these dialogs by pressing a lable button, usually labelled "OK" or "Cancel". You can create your own modal dialogs either through Avenue scripts, or interactively by using a dialog editor document.

In either case, you will probably display your modal dialog repeatedly while developing it. What happens if you display a modal dialog, but you haven't included a control that knows how to dismiss the dialog? In this case, you can press the ESCAPE key to dismiss the dialog. This key sends the Close request to the dialog. Before distributing your dialog, you will probably want to disable this behavior, because it would permit a user to dismiss the dialog before providing the information requested by the dialog (which is, presumably, why you're making it modal).

The dialog's EscapeEnabled property controls this behavior. By default, its value is TRUE. This means that, by default, you can press the ESCAPE key to dismiss the dialog at any time. You can change this property either through an Avenue request, or interactively through a dialog editor's property window. If you set this property to FALSE, you MUST provide a control inside the dialog that can dismiss the dialog. The user will have to forcibly terminate the ArcView process otherwise.

Using the Update event with controls in a dialog

ArcView normally sends the update event to controls at particular times. For example, when a document is activated, all controls in its associated DocGUI are sent the update event.

The update event is also used by controls and dialogs when they need to alert other controls to changes. In this case though, ArcView doesn't attempt to figure out when, or to whom, the event should be sent. You, as the avenue programmer, are responsible for managing update events. You do this by arranging controls in a listener-broadcaster relationship with each other, and then broadcasting an update event when you think it is appropriate.

You are already familiar with listener-broadcaster relationships in ArcView. For example, when a selection is made in a view document, any associated tables and charts also update their selections. In this case, the view document is the broadcaster and the other documents are the listeners. The purpose of a listener- broadcaster relationship is to allow multiple objects to respond to changes in a single object, without that single object having to know explicitly who is paying attention to it. This relationship will be an effective way to manage complex flows of information that occur inside and between dialogs.

You can arrange controls in a listener-broadcaster relationship with each other. Here is an example. Say you have a dialog box that contains a scrolling list box, an "OK" button, and a single line text entry control (a textline control). When the user changes the selection in the list box, the textline should update its contents to show that selection, and the OK button should highlight itself if that selection is "ok" in some sense. In this case, the list box plays the part of the broadcaster, and the other two controls are the listeners.

You need to do three things to make this relationship work: tell the list box about its listeners, send the BroadcastUpdate event to the list box whenever its listeners need to know about a change to the list box, and attach scripts to the update events of those controls. You set up the relationship, typically, when the dialog box is first displayed on the screen. You can use the "open" event script of a dialog to do this. In that script, you must locate the list box, locate the other controls, then add them to the list box's list of listeners.

Later, you need to send the BroadcastUpdate event to the list box whenever a selection is made in it. You can attach a script to it's Select event to do this. That script should send the BroadcastUpdate event to the list box.

In response, the update event scripts of the listening controls will be executed. In each such script, you can send to the control the request GetBroadcaster in order to find out who is telling the control to update itself. In this case, the broadcaster is the list box.

Making dialogs work with documents and VTabs

A dialog box can provide extra information to the user about the contents of an ArcView document or Virtual Table (VTab). It can also provide the user with new ways of manipulating that content. In order for these objects to work well together, it is important that a dialog can find out about changes that occur to them. We will call documents and VTabs "servers" of information and events to dialogs. This relationship is similar to the broadcaster-listener relationship described above, but it has a key difference: you do not have to attach scripts to these servers in order for dialogs to find out about changes to them. This makes it easy to effectively introduce dialogs into projects and other kinds of applications without knowing a lot about how those applications are structured.

Here is an example. Let's say that you want to create a modeless dialog that shows information about the selected features for the active theme in a view. You also want the dialog to disable itself (not go away, but become inactive), when a view is not the active document. You need to do three things to make this happen: Attach a script to the dialog's DocActivate event. This event is sent to a dialog whenever a document is activated. If that document is a view, you could then find the first active theme, and set its FTab (VTab) as the server for the dialog with the SetServer request. Finally, you attach a script to the dialog's ServerSelectionChanged event. This event informs the dialog whenever the selection changes in the server. If the user changes the selection in the theme, the dialog will be notified of it. In response you can send the Update request to the dialog, which could send an update event to all controls within the dialog that might be interested in knowing about the new selection.

Attributes

EscapeEnabled.- By default, you can dismiss a modal dialog by pressing the ESCAPE key. This causes the Close request to be sent to the dialog. This prevents you from getting into the situation where you are testing a modal dialog, but for some reason, can't dismiss it. You should set this property to FALSE before distributing the dialog for use.

ModalResult.- A modal dialog typically returns some value to the caller of the dialog. The ModalResult property contains this return value. It can be set by event scripts attached to controls inside the dialog. This allows those controls to communicate results to the caller of the dialog.

Open.- The name of a script that will be executed when the dialog is opened.

Close.- The name of a script that will be executed when an open dialog is closed.

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

Update.- The name of a script attached to the dialog's Update event. ArcView never sends the update event to a dialog. You trigger execution of this script by sending the Update request to a dialog from some other Avenue script.

DefaultButton.- This property identifies a label button inside a dialog that will have its click script executed when the user presses RETURN while a TextLine, Slider, ListBox or ComboBox has the keyboard focus.

Title.- The text that appears in the title bar of the dialog.

Server.- A Dialog can be associated with a particular document or VTab. This latter object is a server. Servers broadcast events that may be of interest to the dialog. For example, if a user changes the selection in a view document, the dialog may want to know about it. Here is a list of the events that can be broadcast by a server.

    ServerSelectionChanged - The selection in the VTab has been changed.
    ServerDefinitionChanged - The definition of the VTab has been changed.
    ServerRecordsAdded - A record has been added to the VTab or Table document.
    ServerRecordsDeleted - A record has been deleted from the VTab or table document.
    ServerOpened - The associated document has been opened
    ServerClosed - The associated document has been closed
    ServerActivated - The associated document has been activated
    ServerDeactivated - The associated document has been deactivated

DocActivate.The name of a script that will be executed whenever an arcview document is activated. This lets this dialog know about any document that is becoming active. For example, a floating tool palette may want to disable itself if the active document is not a view or layout. ArcView send a DocActivate event to all open dialogs that have a non-empty DocActivate property whenever a document becomes active.

HelpTopic.This property identifies the online help topics displayed by the help tool when it is used on this dialog.

Inherits From

Window

Enumerations

ControlFastenerEnum

Required Extension

     Dialog Designer

Class Requests

Making and Managing Dialogs

DetachFromExtension ( anExtension )

Make ( modal, resizable, hasTitleBar, closeable, alwaysOnTop ) :  Dialog

MakeSized ( resizable, hasTitleBar, closeable, alwaysOnTop, initialSize ) :  Dialog

Instance Requests

Using Dialogs

Close

Open  :  Obj

Managing Dialog Controls

FindByClass ( aClass ) :  List

FindByName ( aControlName ) :  Control

FindByScript ( aScriptName ) :  Control

GetControlPanel  :  ControlPanel

Dialog Events

GetActivate  :  String

GetActiveDoc  :  Doc

GetClose  :  String

GetDocActivate  :  String

GetOpen  :  String

GetServer  :  Obj

GetServerActivated  :  String

GetServerClosed  :  String

GetServerDeactivated  :  String

GetServerDefinitionChanged  :  String

GetServerOpened  :  String

GetServerRecordsAdded  :  String

GetServerRecordsDeleted  :  String

GetServerSelectionChanged  :  String

GetUpdate  :  String

ResetDocActivate

SetActivate ( aScriptName )

SetClose ( aScriptName )

SetDocActivate ( aScriptName )

SetOpen ( aScriptName )

SetServer ( aDocumentOrVTab )

SetServerActivated ( aScriptName )

SetServerClosed ( aScriptName )

SetServerDeactivated ( aScriptName )

SetServerDefinitionChanged ( aScriptName )

SetServerOpened ( aScriptName )

SetServerRecordsAdded ( aScriptName )

SetServerRecordsDeleted ( aScriptName )

SetServerSelectionChanged ( aScriptName )

SetUpdate ( anUpdateScriptName )

Update

Getting/Setting Dialog Attributes

GetDefaultButton  :  LabelButton

GetHelpTopic  :  String

GetModalResult  :  Obj

GetObjectTag  :  Obj

GetTitle  :  String

HasTitleBar  :  Boolean

IsAlwaysOnTop  :  Boolean

IsCloseable  :  Boolean

IsEscapeEnabled  :  Boolean

IsModal  :  Boolean

IsOpen  :  Boolean

IsResizable  :  Boolean

Move ( dx, dy )

MoveTo ( x, y )

Resize ( width, height )

ReturnExtent  :  Rect

ReturnInnerExtent  :  Point

SetAlwaysOnTop ( onTop )

SetCloseable ( aBoolean )

SetDefaultButton ( aLabelButton )

SetEscapeEnabled ( payAttentionToEscapeKey )

SetExtent ( aRectangle )

SetHelpTopic ( aHelpTopicString )

SetInnerExtent ( width, height )

SetModal ( modal )

SetModalResult ( anObject )

SetName ( aName )

SetObjectTag ( anyObject )

SetResizable ( resizable )

SetSlamDunkModalOpen ( slamDunkOpen )

SetTitle ( aTitle )

UseTitleBar ( aBoolean )

Generic object management

Clone  :  Dialog

__________

See also

Control
Document


DetachFromExtension (Dialog)
DetachFromExtension

Allows anExtension to unload when its list of roots contains references to dialogs. Send this request in the unload script of anExtension if it contains dialogs. The unload script executes when you unload the extension from ArcView.

Syntax

Dialog.DetachFromExtension (anExtension)


Make (Dialog)
Make
Example

 Creates a new empty Dialog. The default size and position of the dialog varies depending upon the operating system you are running. Roughly, the dialog is 200 pixels high by 300 pixels wide, positioned 50 pixels down and right of the upper-left corner of the screen. Use the request MakeSized to create a dialog with the user specified (non-default) initial size and position.

The parameters to this request control various attributes of the dialog.

    modal - when true, the dialog will be modal.
    resizable - when true, the dialog will have either resize handles
       or a resize box.
    hasTitleBar - when true, there will be room at the top of the dialog
       for a title. Without a title bar, the dialog cannot be moved
       interactively.
    closeable - when true, the user will be able to close the dialog via
       an icon in the titlebar (if the latter exists).
    alwaysOnTop - when true, the dialog will always be visible above
       ArcView's document window. Other windows may obscure it. This
       kind of dialog is also referred to as a "floating" dialog.

You can change these parameters at run time with the appropriate requests, however, doing so is expensive as ArcView must recreate the dialog.

On some platforms, some combinations of parameters have no affect. For example, a modal dialog cannot also be closeable. In a modal dialog, you must explicitly include some control that knows how to close the dialog. You can, however, use the ESCAPE key to close a modal dialog that doesn't have such a control. This lets you test a modal dialog before you've implemented the control that closes it. Before shipping a modal dialog as part of an ArcView-based application, you should disable the ESCAPE key by setting the dialog's EscapeEnabled property to FALSE.

If you create a dialog with this request in a script, you need to make sure the dialog object is referenced by some other object (e.g., a global variable) or added to the project like this:

av.GetProject.AddDialog(aDialog)

If you don't, the dialog will get garbage collected.

Syntax

Dialog.Make (modal, resizable, hasTitleBar, closeable, alwaysOnTop)

Returns

Dialog


MakeSized (Dialog)
MakeSized

 Refer to the Dialog.Make request for a description of the first four parameters. The last parameter, initialSize, is used to specify the initial position and location of the dialog. You need to use this request, instead of Dialog.Make followed by aDialog.SetExtent, when you want to add controls with non-default constraints to a dialog with an initial non-default size.

Note: Because of a limitation in the number of parameters that can be passed to an Avenue request, there is no 'modal' parameter in this request. The dialog will be created as a modeless dialog. You can make it modal afterwards by sending the dialog the SetModal(TRUE) request.

Syntax

Dialog.MakeSized (resizable, hasTitleBar, closeable, alwaysOnTop, initialSize)

Returns

Dialog


Close (Dialog)
Close

Removes aDialog from the screen. aDialog still exists. This request may be sent either from an event script attached to aDialog or one of its controls, or from an external script (if aDialog is modeless). If aDialog is modal, then control will be returned to the client that sent the Open request to aDialog. The Close event script can determine what value the Open request will return by setting the aDialog's ModalReturn attribute. For example, you can add the following line of code as the Click event script for aLabelButton named Done to close the dialog.

   SELF.GetDialog.Close

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.Close


Open (Dialog)
Open

Displays aDialog. If aDialog is modal, script execution blocks at this request until an event script attached to aDialog sends it the Close request. In this case, the return value of the Open request is the object associated with aDialog's ModalResult property. If aDialog is not modal, script execution continues immediately and the return value is always the nil object.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.Open

Returns

Obj


FindByClass (Dialog)
FindByClass

Returns a list of controls of aDialog whose class is aClass or a subclass of aClass. For example,

    aDialog.FindByClass(LabelButton)

will return a list of all LabelButton controls in aDialog. To get a list of all controls in aDialog, aClass should be Control. For example,

    aDialog.FindByClass(Control)

will return a list of all controls in aDialog.

The list will include the controls that are within the dialog frame and the "working" area outside the dialog frame.

Syntax

aDialog.FindByClass (aClass)

Returns

List


FindByName (Dialog)
FindByName

Returns the control in aDialog whose name is aControlName. It returns nil if aControlName is invalid.

Syntax

aDialog.FindByName (aControlName)

Returns

Control


FindByScript (Dialog)
FindByScript

Returns the control in aDialog that has an event script named aScriptName. It returns nil if not found. If several controls have the event script named aScriptName, it returns the first control that it finds.

Syntax

aDialog.FindByScript (aScriptName)

Returns

Control


GetControlPanel (Dialog)
GetControlPanel

Gets the top-level ControlPanel for aDialog. This ControlPanel contains all controls in aDialog.

Syntax

aDialog.GetControlPanel

Returns

ControlPanel


GetActivate (Dialog)
GetActivate

Gets the name of the script that will be executed whenever aDialog is activated. This script is only used when aDialog is modeless.

Syntax

aDialog.GetActivate

Returns

String


GetActiveDoc (Dialog)
GetActiveDoc

Must be used within a script attached to the DocActivate event on aDialog or any script called from the DocActivate script because av.GetActiveDoc does not return the correct document during processing of this event. You can, however, also use this request in any script attached to the dialog.

Syntax

aDialog.GetActiveDoc

Returns

Doc


GetClose (Dialog)
GetClose

Gets the name of the script that will be executed whenever aDialog is closed.

Syntax

aDialog.GetClose

Returns

String


GetDocActivate (Dialog)
GetDocActivate

Gets the name of the script that will be executed whenever an ArcView document is activated while aDialog is open. The script can find out which document is active by sending the GetActiveDoc request to the application object. Only dialogs that define a DocActivate script and are open will be notified of document activation events.

Syntax

aDialog.GetDocActivate

Returns

String


GetOpen (Dialog)
GetOpen

Gets the name of the script that will be executed whenever aDialog is opened.

Syntax

aDialog.GetOpen

Returns

String


GetServer (Dialog)
GetServer

Returns the event server currently associated with aDialog. This server can be either a VTab or a document.

Syntax

aDialog.GetServer

Returns

Obj


GetServerActivated (Dialog)
GetServerActivated

Returns the name of the script that will be executed when aDialog receives the ServerActivated event. The ServerActivated event is sent when aDialog's server is a document and that document is activated.

Syntax

aDialog.GetServerActivated

Returns

String


GetServerClosed (Dialog)
GetServerClosed

Returns the name of the script that will be executed whenever aDialog receives the ServerClosed event.

Syntax

aDialog.GetServerClosed

Returns

String


GetServerDeactivated (Dialog)
GetServerDeactivated

Returns the name of the script that will be executed whenever aDialog receives the ServerDeactivated event. The ServerDeactivated event is sent whenever aDialog's server is a document and that document is deactivated.

Syntax

aDialog.GetServerDeactivated

Returns

String


GetServerDefinitionChanged (Dialog)
GetServerDefinitionChanged

Gets the name of the script that will be executed when aDialog receives the ServerDefinitionChanged event. See SetServerDefinitionChanged for a description of the event.

Syntax

aDialog.GetServerDefinitionChanged

Returns

String


GetServerOpened (Dialog)
GetServerOpened

Returns the name of the script that will be executed when aDialog receives the ServerOpened event.

Syntax

aDialog.GetServerOpened

Returns

String


GetServerRecordsAdded (Dialog)
GetServerRecordsAdded

Gets the name of the script that will be executed when the ServerRecordsAdded event is sent to aDialog.

Syntax

aDialog.GetServerRecordsAdded

Returns

String


GetServerRecordsDeleted (Dialog)
GetServerRecordsDeleted

Gets the name of the script that will be executed when aDialog receives the ServerRecordsDeleted event.

Syntax

aDialog.GetServerRecordsDeleted

Returns

String


GetServerSelectionChanged (Dialog)
GetServerSelectionChanged

Returns the name of the script that will be executed when aDialog receives the ServerSelectionChanged event.

Syntax

aDialog.GetServerSelectionChanged

Returns

String


GetUpdate (Dialog)
GetUpdate

Returns the name of the script that will be executed whenever somebody sends the Update request to aDialog.

Syntax

aDialog.GetUpdate

Returns

String


ResetDocActivate (Dialog)
ResetDocActivate

Send this request after aDialog has attempted to execute an erroneous DocActivate event script causing it to stop responding to DocActivate. In such an event, correct the errors in your script use this request to tell it to start responding to DocActivate events again.

Syntax

aDialog.ResetDocActivate


SetActivate (Dialog)
SetActivate

Sets the name of the script to be executed whenever aDialog becomes active (for example, when the mouse enters the window of a dialog). This script is only used when aDialog is modeless.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetActivate (aScriptName)


SetClose (Dialog)
SetClose

Sets the name of the script that will be executed whenever aDialog is closed.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetClose (aScriptName)


SetDocActivate (Dialog)
SetDocActivate
Example

Sets the name of the script that will be executed whenever an ArcView document is activated and aDialog is open. 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 docuemnt is not a view or layout, include the following code in your DocActivate script:

   theDoc = self.GetActiveDoc
   enabled = theDoc.Is(View) or theDoc.Is(Layout)
   self.GetControlPanel.SetEnabled(enabled)

If for some reason, the DocActivate script stop responding, correct the problem and use the ResetDocActivate request to tell it to start responding to DocActivate events again.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetDocActivate (aScriptName)


SetOpen (Dialog)
SetOpen

Sets the name of the script that will be executed whenever aDialog is opened. The default values that you specify for a control at design time will only initialize the control the first time aDialog is displayed. Thus, if you change the value at run time, that value is maintained and displayed when aDialog is subsequently displayed until that dialog is recompiled.

Use the open script to establish starting values for controls, broadcast-listener relationships between controls to handle Update events, and a client- server relationships between a dialog and a docuemnt. Here is an example of an open script:

    aListBox = self.FindByName("aListBox1")
    aVTab = av.FindDoc("Table1").GetVTab
    fieldNames = aVTab.GetFields
    'populate the list box
    aListBox.DefineFromVTab(aVTab,fieldNames,true)
    'set up the VTab as a server
    self.SetServer(aVTab)
    'set up listeners for update event use
    aButton1 = self.FindByName("aLabelButton1")
    aButton2 = self.FindByName("aLabelButton2")
    aListBox.SetListeners({aButton1, aButton2})

In the above example, you've set the VTab as the server. You can now add the following code as ServerSelectionChanged event script such that as you modify the selection set in Table1, the list box updates the list to show the currently selected records.

    'use this as ServerSelectionChanged event script
    aListBox = self.FindByName("aListBox1")
    aVTab = self.GetServer
    fieldNames = aVTab.GetFields
    aListBox.DefineFromVTab(aVTab,fieldNames,true)

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetOpen (aScriptName)


SetServer (Dialog)
SetServer

Sets aDialog's current server to be the specified document or VTab.

A dialog can establish a client-server relationship with a particular document or a VTab such that the dialog can find out about changes that occur to these documents. This makes it easy to effectively introduce dialogs into projects and other kinds of applications without knowing a lot about how those applications are structured.

Here is an example. Let's say that you want to create a modeless dialog that shows information about the selected features for the active theme in a view. You also want the dialog to disable itself (not go away, but become inactive), when a view is not the active document. You need to do three things to make this happen: Attach a script to the dialog's DocActivate event. This event is sent to a dialog whenever a document is activated. If that document is a view, you could then find the first active theme, and set its FTab (VTab) as the server for the dialog with the SetServer request. Finally, you attach a script to the dialog's ServerSelectionChanged event. This event informs the dialog whenever the selection changes in the server. If the user changes the selection in the theme, the dialog will be notified of it. In response you can send the Update request to the dialog, which could send an update event to all controls within the dialog that might be interested in knowing about the new selection.

The link between a dialog and its server document is maintained when you save a project. To break this link, you may want to set the server to NIL, for instance, in a dialog's close script.

Syntax

aDialog.SetServer (aDocumentOrVTab)


SetServerActivated (Dialog)
SetServerActivated

Sets the name of the script that will be executed when aDialog receives the ServerActivated event. The ServerActivated event is sent when aDialog's server is a document and that document is activated (you typically establish the server document in the dialog's open or DocActivate scripts). This property does not apply when the server is a VTab.

For example, suppose you wanted to enable the controls on a dialog when its server document became active. You could include this code in the ServerActivated script:

    self.GetControlPanel.SetEnabled(true)

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerActivated (aScriptName)


SetServerClosed (Dialog)
SetServerClosed

Sets the name of the script that will be executed when aDialog receives the ServerClosed event. The ServerClosed event is sent when aDialog's server is a document and that document's window is closed. This property does not apply when the server is a VTab.

For example, if you want to close the dialog when the server document is closed, the ServerClosed script would contain self.Close.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerClosed (aScriptName)


SetServerDeactivated (Dialog)
SetServerDeactivated

Sets the name of the script that will be executed whenever aDialog receives the ServerDeactivated event (i.e., when the server document becomes inactive). The ServerDeactivated event is sent whenever aDialog's server is a document and that document is deactivated. This property does not apply when the server is a VTab.

For example, suppose you wanted to disable the controls on a dialog when its server document became inactive. You could include this code in the ServerDeactivated script:

    self.GetControlPanel.SetEnabled(false)

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerDeactivated (aScriptName)


SetServerDefinitionChanged (Dialog)
SetServerDefinitionChanged

Sets the name of the script that will be executed when aDialog's server is a VTab and the definition bitmap of that VTab has been changed, or when records have been deleted from an editable VTab that is being set non-editable.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerDefinitionChanged (aScriptName)


SetServerOpened (Dialog)
SetServerOpened

Sets the name of the script that will be executed when aDialog receives the ServerOpened event. The ServerOpened event is sent when aDialog's server is a document and that document's window is Opened. This property does not apply when the server is a VTab.

For example, if you want to open the dialog when the server document is opened, the ServerOpened script would contain self.Open.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerOpened (aScriptName)


SetServerRecordsAdded (Dialog)
SetServerRecordsAdded

Sets the name of the script that will be executed when aDialog's server is a VTab or FTab and a record has been added to it.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerRecordsAdded (aScriptName)


SetServerRecordsDeleted (Dialog)
SetServerRecordsDeleted

Sets the name of the script that will be executed when aDialog's server is a VTab or FTab and records have been deleted from it.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerRecordsDeleted (aScriptName)


SetServerSelectionChanged (Dialog)
SetServerSelectionChanged

Sets the name of the script that will be executed whenever aDialog receives the ServerSelectionChanged event. This event is sent to aDialog whenever aDialog's server is a VTab (or FTab) and the selection of that object is changed. Some situations when this can occur are:

    - The user selects a feature using theme selection tools
    - The user selects a record in a table
    - The user deletes a data element from a chart
    - A theme on theme selection has been performed
    - The user interacts with the Query Builder

For example, suppose you wanted to update the listbox contents in aDialog based on the current selection set in a table document. To do this, first you set the server to the table's VTab in the open script. Then, add the following code to the ServerSelectionChanged script:

   aListbox = self.FindByNmae("aListBox1")
   aVTab = self.GetServer
   fieldNames = aVTab.GetFields
   aListBox.DefineFromVTab(aVTab,fieldNames,true)

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetServerSelectionChanged (aScriptName)


SetUpdate (Dialog)
SetUpdate

Sets the name of the script to be executed whenever somebody sends the Update request to aDialog.

Note: Do not use the Exit statement in scripts associated with a dialog.

Syntax

aDialog.SetUpdate (anUpdateScriptName)


Update (Dialog)
Update

Executes the update script associated with aDialog. ArcView never sends this request to aDialog. You can send this request from some other script at an appropriate time.

Syntax

aDialog.Update


GetDefaultButton (Dialog)
GetDefaultButton

Returns the label button that is the default button for aDialog. NIL is returns if no default button exists for aDialog.

Syntax

aDialog.GetDefaultButton

Returns

LabelButton


GetHelpTopic (Dialog)
GetHelpTopic

Gets the name of the help topic that will be displayed in ArcView's online help system when the help tool (or F1 key) is used on aDialog.

Syntax

aDialog.GetHelpTopic

Returns

String


GetModalResult (Dialog)
GetModalResult

Gets the object currently referenced through aDialog's ModalResult property. This object will be returned as the result of an Open request sent to aDialog when aDialog is modal.

Syntax

aDialog.GetModalResult

Returns

Obj


GetObjectTag (Dialog)
GetObjectTag

Gets the object referenced by aDialog's object tag.

Syntax

aDialog.GetObjectTag

Returns

Obj


GetTitle (Dialog)
GetTitle

Gets the title of aDialog.

Syntax

aDialog.GetTitle

Returns

String


HasTitleBar (Dialog)
HasTitleBar

Returns whether or not aDialog is currently displaying a title bar.

Syntax

aDialog.HasTitleBar

Returns

Boolean


IsAlwaysOnTop (Dialog)
IsAlwaysOnTop

Returns whether or not aDialog will always stay in front of (on top of) the application and document windows.

Syntax

aDialog.IsAlwaysOnTop

Returns

Boolean


IsCloseable (Dialog)
IsCloseable

Returns true if the user can interactively close aDialog via standard window controls in aDialog's frame. This request may return FALSE even if the Closeable property is TRUE. For example, a modal dialog without a title bar cannot be closed from controls on its frame.

Syntax

aDialog.IsCloseable

Returns

Boolean


IsEscapeEnabled (Dialog)
IsEscapeEnabled

Returns TRUE when pressing the ESCAPE key in an active (or modal) dialog dismisses that dialog by sending it the Close request.

Syntax

aDialog.IsEscapeEnabled

Returns

Boolean


IsModal (Dialog)
IsModal

Returns whether or not aDialog is modal.

Syntax

aDialog.IsModal

Returns

Boolean


IsOpen (Dialog)
IsOpen

Returns TRUE when aDialog has been sent the Open request and is still open. This request will return FALSE during processing of the Open event script.

Syntax

aDialog.IsOpen

Returns

Boolean


IsResizable (Dialog)
IsResizable

Returns whether or not aDialog can be resized.

Syntax

aDialog.IsResizable

Returns

Boolean


Move (Dialog)
Move

Moves aDialog dx pixels to the right and dy pixels down from its current position. Use negative values to move to the left and up.

Syntax

aDialog.Move (dx, dy)


MoveTo (Dialog)
MoveTo

Moves aDialog to a position x pixels from the left side of the screen and y pixels from the top. For example, the following code fragment will place the dialog in the center of ArcView's application window:

    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)

Syntax

aDialog.MoveTo (x, y)


Resize (Dialog)
Resize

Adjust the width and height of aDialog without changing its position. width and height are in pixels.

Syntax

aDialog.Resize (width, height)


ReturnExtent (Dialog)
ReturnExtent

Returns the location and the extent of aDialog. The units of the returned rectangle are in screen pixels. The first pair of coordinates in the rectangle represents the top left hand corner of the dialog and the next pair of coordinates in the rectangle represents the width and height of the dialog.

Syntax

aDialog.ReturnExtent

Returns

Rect


ReturnInnerExtent (Dialog)
ReturnInnerExtent

Returns a point that represents the width and height of the inside of aDialog - the part where you can place controls.

Syntax

aDialog.ReturnInnerExtent

Returns

Point


SetAlwaysOnTop (Dialog)
SetAlwaysOnTop

When onTop is TRUE, aDialog will always appear in front of (on top of) the application and document windows. When onTop is FALSE, aDialog can move behind those windows. Changing this property after aDialog has been created is very expensive (ArcView needs to destroy and reconstruct the dialog).

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

Syntax

aDialog.SetAlwaysOnTop (onTop)


SetCloseable (Dialog)
SetCloseable

If aBoolean is true, then a close box icon will be added to the upper left hand corner of aDialog (provided that it has a title bar). On some platforms, you must also get rid of the title bar in order to prevent a window from being closed via controls on the dialog's window frame.

Syntax

aDialog.SetCloseable (aBoolean)


SetDefaultButton (Dialog)
SetDefaultButton

Identifies the label button that will have its click script executed when the user presses RETURN while inside aDialog. Use this property in dialogs when you have reasonable default values for most of the controls that are required for the default button's click script to execute successfully. This property works while a TextLine, Slider, ListBox or ComboBox has the keyboard focus. Also, note that setting the default button will override the Apply property on a text line control. Pass in nil to remove any existing default button for aDialog.

Syntax

aDialog.SetDefaultButton (aLabelButton)


SetEscapeEnabled (Dialog)
SetEscapeEnabled

When payAttentionToEscapeKey is TRUE, you can dismiss a dialog (especially a modal dialog) by pressing the ESCAPE key. The ESCAPE key will send the Close request to the dialog. When its FALSE, the ESCAPE key has no affect. This property is TRUE by default to allow you to easily dismiss a modal dialog while developing it. You should make sure this property is set to FALSE before distributing your dialog.

Syntax

aDialog.SetEscapeEnabled (payAttentionToEscapeKey)


SetExtent (Dialog)
SetExtent

Defines the size and location of a dialog on the screen based on the dimensions of aRectangle. The units of the rectangle are in pixels, relative to the upper-left corner of the screen. For example:

    aDialog.SetExtent(Rect.Make(50@50, 300@400))

will make a dialog with a width of 300 pixels and a height of 400 pixels, positioned 50 pixels from the top and left sides of the screen.

Syntax

aDialog.SetExtent (aRectangle)


SetHelpTopic (Dialog)
SetHelpTopic

Sets the name of the help topic that will be displayed in AarcView's online help system when the help tool (or F1 key) is used on aDialog. aHelpTopicString 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. The syntax is <aTopicName>@<aHelpFileName>.

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

Syntax

aDialog.SetHelpTopic (aHelpTopicString)


SetInnerExtent (Dialog)
SetInnerExtent

Defines the extent of the inside of aDialog - the part where you can place controls. This request doesn't move aDialog. Use Move or MoveTo to specify where the upper left hand corner of the outside of aDialog should be placed.

Syntax

aDialog.SetInnerExtent (width, height)


SetModal (Dialog)
SetModal

Sets aDialog to be modal or not. If modal is TRUE, it makes aDialog the focus of input and prevents the user from working with any other part of ArcView while the modal dialog is displayed. In order to dismiss the modal dialog, you must provide a method for dismissing itself, such as an OK or Cancel button with the appropriate Avenue code behind it. If modal is FALSE, the dialog will behave as a floating window that remains on the screen till you explicitly dismiss the dialog (an example of such a dialog in in ArcView is a Symbol Window).

Syntax

aDialog.SetModal (modal)


SetModalResult (Dialog)
SetModalResult

Sets the ModalResult property of aDialog to be anObject. This object will be returned as the result of an Open request sent to aDialog when aDialog is modal.

For example, suppose you want to write a modal password dialog that obtains a username and password from a user. How do you get at those strings? One way is to know the names of the individual controls inside the dialog, and then look at the values of the controls after the dialog is dismissed. A better was is for the dialog itself to return those values to the caller. An OK button's click script could package the username and password into a list then return the list to the caller using self.GetDialog.SetModalResult(theList).

Syntax

aDialog.SetModalResult (anObject)


SetName (Dialog)
SetName

Sets the name of aDialog to aName. aDialog's name is not displayed anywhere. In particular, it is different from the title.

Syntax

aDialog.SetName (aName)


SetObjectTag (Dialog)
SetObjectTag

Sets aDialog's object tag to reference anyObject. Use the object tag to carry associated objects with the dialog.

Syntax

aDialog.SetObjectTag (anyObject)


SetResizable (Dialog)
SetResizable

Controls whether or not aDialog can be resized. Changing this attribute is expensive. The dialog has to be destroyed and then reconstructed.

Syntax

aDialog.SetResizable (resizable)


SetSlamDunkModalOpen (Dialog)
SetSlamDunkModalOpen

Send this request when your Open event script interferes with the initial drawing of aDialog. This is typically only a problem with modal dialogs that use the av.SetStatus request during the Open event. When slamDunkOpen is TRUE, the modal dialog will redraw itself twice before processing the Open event script - i.e., its "slam dunked" onto the screen. This action only happens the first time a dialog is opened after being recompiled, or the first time its opened after being loaded.

Syntax

aDialog.SetSlamDunkModalOpen (slamDunkOpen)


SetTitle (Dialog)
SetTitle

Sets the title of aDialog to aTitle. This is displayed in aDialog's window label area.

Syntax

aDialog.SetTitle (aTitle)


UseTitleBar (Dialog)
UseTitleBar

When aBoolean is TRUE, aDialog will have a visible title bar, when it is false, no title bar will be present. Changing this attribute is expensive. The dialog has to be destroyed and then reconstructed.

Syntax

aDialog.UseTitleBar (aBoolean)


Clone (Dialog)
Clone

Clones aDialog.

Syntax

aDialog.Clone

Returns

Dialog


ControlFastenerEnum

 How a control behaves when its containing dialog or control panel is resized is determined by passing a list of one or more of the following enumeration elements to that control. Not all combinations of elements are legitimate. For example, if a control is in a resizable dialog, you can't ask it to maintain a constant width, and also a constant distance from the left and right edges of the dialog.

#CONTROL_FASTENER_TOP

The control will remain a fixed distance from the top of the dialog or control panel.

#CONTROL_FASTENER_LEFT

The control will remain a fixed distance from the left of the dialog or control panel.

#CONTROL_FASTENER_RIGHT

The control will remain a fixed distance from the right of the dialog or control panel.

#CONTROL_FASTENER_BOTTOM

The control will remain a fixed distance from the bottom of the dialog or control panel.

#CONTROL_FASTENER_WIDTH

The control will always have the same width. You cannot fasten a control this way and also fasten it with both CONTROL_FASTENER_LEFT and CONTROL_FASTENER_RIGHT.

#CONTROL_FASTENER_HEIGHT

The control will always have the same height. You cannot fasten a control this way and also fasten it with both CONTROL_FASTENER_TOP and CONTROL_FASTENER_BOTTOM.


IconBox

 An IconBox is a rectangle that 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.

Related note: You cannot access dialog designer extension specific icons in ArcView's Icon Manager as they are stored in a separate file. You can explicitly associate a button, tool, or an icon box control with one of these icons by using the following requests:

   anIcon = Icon.MakeFromResName("DLogIcons.AnIconName")
   myButton.SetIcon(anIcon)

Replace "AnIconName" in the above code fragment with one of the following dialog designer specific icon names:

CheckBox, ComboBox, ControlPanel, DEd, IconBox, LabelButton, ListBox, PushButton, RadioButton, Slider, TextBox, TextLabel, TextLine, Tool.

Attributes

Icon.The Icon object displayed inside the bounding box of an icon box.

Listeners.The list of listeners that will be sent an update event whenever the BroadcastUpdate request is sent to an icon box.

Listening.When TRUE, an icon box will execute its update script when it receives an update event. Otherwise, it will ignore the update event.

Box.The bounding box of the icon box. It is expressed in the pixel coordinate system, which has coordinates in screen pixels and an origin at the upper left hand corner of the control panel or dialog containing the icon box.

Fasteners.A list of elements from the ControlFastenerEnum enumeration. These elements describe how an icon box resizes and repositions itself whenever its containing control panel or dialog is resized or repositioned.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making IconBoxes

Make  :  IconBox

Instance Requests

Using IconBoxes

Update

Listeners and Broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

Getting/Setting attributes of IconBoxs

GetDialog  :  Dialog

GetIcon  :  Icon

HasFastener ( aFastener ) :  Boolean

SetFastener ( aConstraint, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetIcon ( anIcon )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

__________

See also

ControlPanel
Icon
Dialog


Make (IconBox)
Make
Example

Creates an IconBox object.

Syntax

IconBox.Make

Returns

IconBox


Update (IconBox)
Update

Executes anIconBox's update script if it is listening to updates.

Syntax

anIconBox.Update


AddListener (IconBox)
AddListener

Adds aControl to anIconBox's list of listeners. You do not need to use the ChangedListeners request after using this request.

Syntax

anIconBox.AddListener (aControl)


BroadcastUpdate (IconBox)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aIconBox.

Syntax

anIconBox.BroadcastUpdate


ChangedListeners (IconBox)
ChangedListeners

Informs aIconBox that you have modified its list of listeners. Send this request after manipulating the list obtained from the GetListeners request. You do not need to send this request after using the SetListeners, AddListener, or RemoveListener requests.

Syntax

anIconBox.ChangedListeners


GetBroadcaster (IconBox)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aIconBox's update script. This request will return nil if the update event aIconBox is responding was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

anIconBox.GetBroadcaster

Returns

Obj


GetListeners (IconBox)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aIconBox. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aIconBox.

Syntax

anIconBox.GetListeners

Returns

List


IsListening (IconBox)
IsListening

Returns TRUE if anIconBox will execute its update script in response to an update event.

Syntax

anIconBox.IsListening

Returns

Boolean


RemoveListener (IconBox)
RemoveListener

Removes aControl from anIconBox's list of listeners. You do not need to use the ChangedListeners request after using this request.

Syntax

anIconBox.RemoveListener (aControl)


SetListeners (IconBox)
SetListeners
Example

Sets the list of controls that will be sent the update event when aIconBox is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

anIconBox.SetListeners (aListOfListeners)


StartListening (IconBox)
StartListening

anIconBox will respond to any future update events by executing its update script.

Syntax

anIconBox.StartListening


StopListening (IconBox)
StopListening

anIconBox will not execute its update script in response to an update event.

Syntax

anIconBox.StopListening


GetDialog (IconBox)
GetDialog

Gets the dialog containing anIconBox. You may only use this request after adding anIconBox to a dialog.

Syntax

anIconBox.GetDialog

Returns

Dialog


GetIcon (IconBox)
GetIcon

Gets the Icon object that is displayed inside anIconBox.

Syntax

anIconBox.GetIcon

Returns

Icon


HasFastener (IconBox)
HasFastener

Returns TRUE if anIconBox currently has aFastener defined for it.

Syntax

anIconBox.HasFastener (aFastener)

Returns

Boolean


SetFastener (IconBox)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

anIconBox.SetFastener (aConstraint, onOrOff)

Returns

Boolean


SetFasteners (IconBox)
SetFasteners

Defines resizing and repositioning fasteners for anIconBox. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, anIconBox's fasteners are not altered.

Syntax

anIconBox.SetFasteners (aListOfFasteners)

Returns

Boolean


SetIcon (IconBox)
SetIcon

Sets the icon object to be displayed inside anIconBox. For example,

  anIconBox.SetIcon(Icon.Make("$AVHOME/etc/banner".asFileName))

will draw the ArcView's startup banner inside anIconBox. You may have to adjust the bounding box handles to show the entire banner.

Syntax

anIconBox.SetIcon (anIcon)


Move (IconBox)
Move

Move anIconBox dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" anIconBox to another control panel. If anIconBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding an icon box to a dialog object. You cannot use this request to move an icon box in a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

anIconBox.Move (dx, dy)


MoveTo (IconBox)
MoveTo

Move anIconBox to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" anIconBox to another control panel. If anIconBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if anIconBox is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If anIconBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding an icon box to a dialog object. You cannot use this request to move an icon box in a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

anIconBox.MoveTo (x, y)


Resize (IconBox)
Resize

Make anIconBox dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding an icon box to a dialog object. You cannot use this request to resize an icon box in a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

anIconBox.Resize (dw, dh)


ResizeTo (IconBox)
ResizeTo

Makes anIconBox w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding an icon box to a dialog object. You cannot use this request to resize an icon box in a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

anIconBox.ResizeTo (w, h)


ReturnBox (IconBox)
ReturnBox

Returns a copy of the bounding box of anIconBox. the box's coordinates are in the coordinate system of anIconBox's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if anIconBox is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If anIconBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

anIconBox.ReturnBox

Returns

Rect


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. A particular cell is identified with a pair of cell coordinates. The first coordinate is the cell's row offset (starting from zero), and the second coordinate is the cell's column offset (also starting from zero). The object attached to a cell is referred to as a cell value. Zero or more cells can be selected. A selected cell is one in which the user of the list box is particularly interested. A selected cell is drawn differently. The term 'the selection' refers to the current set of cells that are selected.

To use a ListBox, you make it, add it to a control panel, define its contents, define its appearance, attach scripts to events, and interact with cell values. You can define its contents in several ways: By specifying the number of rows and columns it has, then filling in values manually; by specifying a list that contains the elements you want to see in it; by specifying a vtab and a list of fields that you want to see in it; by specifying a vtab and field for which you would like to see unique values; or finally, by specifying a dictionary whose keys you would like to see displayed in it.

You interact with an individual cell value by first identifying what cell you are interested in, then performing operations on that cell. You identify a cell using the FindByValue or one of the GoXXX requests. This cell is then called the "current" cell. All event scripts, with the exception of the Update script, define the current cell before the script is executed. For example, the ListBox's Select event sets the current cell to be the cell that the user clicked on, then executes the script associated with that event.

A ListBox defines these events to which you can attach scripts: Select, Apply, RangeSelect, RangeApply, Update. Any kind of select script is executed whenever the user makes a selection (either with the mouse or the keyboard). The RangeSelect script is responsible for handling a selection within a specified range of cells. There can be more than one RangeSelect script. They cannot overlap. Both RangeSelect scripts and the global Select script can be defined. The global Select script is responsible for cells not included in the range of any RangeSelect script. The Apply and RangeApply scripts behave similarly, but are executed only in response to mouse double-clicks.

Select scripts are typically used to inform other controls, or other parts of ArcView, that the selection in the list box has changed. Apply scripts are typically used to perform some action with the current selection. Thus, when the user double clicks on a cell in a list box, first the Select (or RangeSelect) script then the Apply (or RangeApply) script executes.

You can examine all cell values by using Avenue's for each loop. The current cell is advanced each time through the loop. It is always the cell from which the current value of the loop control variable is obtained. You can examine all values of selected cells by using the request GetSelection and then iterating over the returned list. In this case, the current cell is not updated.

Many ListBox requests can only be used after the ListBox has been added to a ControlPanel. This restriction is noted in the description of the request.

Inherits From

Control

Enumerations

ListBoxSelectionEnum

Required Extension

     Dialog Designer

Class Requests

Making ListBoxes

Make  :  ListBox

Instance Requests

Defining the contents of ListBoxes

DefineFromDictionary ( aDictionary )

DefineFromList ( aList )

DefineFromVTab ( aVTab, aListOfFields, selectionOnly )

DefineUniqueFromVTab ( aVTab, aField, selectionOnly, caseSensitive, sortAscending )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Moving around in a ListBox

FindByValue ( anIconOrString )

GoColumn ( aColumnOffset )

GoDown  :  Boolean

GoField ( aField )

GoFirstSelected  :  Boolean

GoLeft  :  Boolean

GoNextSelected  :  Boolean

GoRecord ( nthRecord )

GoRecordField ( nthRecord, aField )

GoRight  :  Boolean

GoRow ( aRowOffset )

GoRowColumn ( aRowOffset, aColumnOffset )

GoUp  :  Boolean

Using ListBoxes

Apply

DeleteColumns ( numColumns )

DeleteRows ( numRows )

Empty

FitColumns ( aRangeOfColumnsOffsets, adjustRowHeight )

FitRows ( aRangeOfRowOffsets, adjustColumnWidths )

Focus

InsertColumns ( numColumns )

InsertRows ( numRows )

RangeApply ( aPoint )

RangeSelect ( aPoint )

Select

SelectCurrent ( mergeSelection )

SetSelection ( aRange, appendSelection )

ShowCurrent

SortAscending ( caseSensitive )

SortDescending ( caseSensitive )

Update

Getting/Setting attributes of ListBoxes

GetApply  :  String

GetColumnCount  :  Number

GetColumnWidth  :  Number

GetCurrentColumn  :  Number

GetCurrentField  :  Field

GetCurrentLocation  :  Point

GetCurrentRecord  :  Number

GetCurrentRow  :  Number

GetCurrentValue  :  Obj

GetDialog  :  Dialog

GetDictionary  :  Dictionary

GetFieldNamesVisible  :  Boolean

GetFields  :  List

GetList  :  List

GetNextControl  :  Control

GetRangeApply ( aPoint ) :  String

GetRangeSelect ( aPoint ) :  String

GetRowCount  :  Number

GetRowHeight  :  Number

GetSelect  :  String

GetSelection  :  List

GetSelectionStyle  :  ListBoxSelectionEnum

GetVTab  :  VTab

HasFastener ( aFastener ) :  Boolean

HasHorizontalScroll  :  Boolean

HasScript ( aScriptName ) :  Boolean

HasSelection  :  Boolean

HasVerticalScroll  :  Boolean

RemoveRangeApply ( aScriptName )

RemoveRangeSelect ( aScriptName )

SetApply ( aScriptName )

SetColumnWidth ( aMeasure )

SetCurrentValue ( anObject )

SetEnabled ( enabled )

SetFastener ( fastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetFieldNamesVisible ( visible )

SetHorizontalScroll ( useScrollBar )

SetNextControl ( aControl )

SetRangeApply ( aScriptName, aRectangle )

SetRangeSelect ( aScriptName, aRectangle )

SetRowHeight ( aMeasure )

SetSelect ( aScriptName )

SetSelectionStyle ( aSelectionStyle )

SetVerticalScroll ( useScrollBar )

SetVisible ( visible )

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

ControlPanel
Icon
String
Table
VTab


Make (ListBox)
Make
Example

Create a new ListBox object. By default, the horizontal scroll bar is set to TRUE, vertical scroll bar is set to TRUE and the selection style is set to select a single cell at a time.

Syntax

ListBox.Make

Returns

ListBox


DefineFromDictionary (ListBox)
DefineFromDictionary

Populates aListBox with the keys from aDictionary. The request SetCurrentValue update the key for a particular association in that dictionary.

aListBox becomes the owner of aDictionary. You should not modify the keys of aDictionary directly without subsequently calling DefineFromDictionary again. You can, however, manipulate the values in any way at any time.

Syntax

aListBox.DefineFromDictionary (aDictionary)


DefineFromList (ListBox)
DefineFromList

Populates aListBox using the contents of aList. aList can contain objects of any kind. Each element of aList is displayed in a new row. If the element is itself a list, then its sub elements occupy multiple columns in that row. Elements that are lists need not have the same number of sub elements.

When the listbox is drawn on the dialog, elements that are symbols or icons are drawn in their cells; elements that are strings are printed in their cells; elements that are other kinds of objects get sent the AsString request, and those strings are then printed in their cells. When the end user selects an element from the listbox, the actual object is returned, not a string representation of it, as shown in the listbox.

You can manipulate aList in any way after using it as a parameter in this request. aListBox maintains separate references to its objects.

For example, the following Avenue code fragment will result in aListBox having three rows and three columns (nine cells):

  aListBox.DefineFromList(
    { {1, 2, 3},
      "hi",
      av.FindGUI("View").GetIcon
    } )

This example populates aListBox with strings and an icon. If the icon is larger than the font height, the ListBox may clip the icon. In such cases, use FitRows and FitColumns requests to automatically adjust the cell dimensions based on its contents. In the above example, append the following line at the end of the code to automatically adjust the cell dimensions:

  aListBox.FitRows(0..2, true)

You may also use SetRowHeight and SetColumnWidth requests to explicitly set the row height and column width.

Syntax

aListBox.DefineFromList (aList)


DefineFromVTab (ListBox)
DefineFromVTab

 Populates the contents of aListBox from aVTab. aListOfFields are those fields from aVTab that should be shown in aListBox. Each field occupies a different list box column. If selectionOnly is true, then only records that are selected in aVTab will be visible in aListBox. aListBox can display a maximum of 32,767 records from aVTab.

If aListBox does not have a horizontal scroll bar, the column widths will be scaled so that all columns fit in the visible area of the list box. This will probably cause most data to become illegible. For best results, make sure that aListBox has a horizontal scroll bar. In that case, column widths will be determined in one of two ways:

  If a table document is associated with aVTab, and that table
  has been opened at least once, then the column widths in aListBox
will be the same as in the table.

  If no table document exists, or has not yet been opened, then
the data width of the field is used to determine column width.

You may use FitRows, FitColums, SetRowHeight, and SetColumnWidth requests to explicitly set the row height and column width.

Assuming you have a dialog with aListBox control in it, you can use the following code fragment as aDialog's open script to populate the contents of aListBox from table1:

  'use the following script as aDialog's open script
  aListBox = self.FindByName("aListBox1")
  aVTab = av.GetProject.FindDoc("table1.dbf").GetVTab
  myFields = aVTab.GetFields
  aListBox.DefineFromVTab(aVTab, myFields, false)

Syntax

aListBox.DefineFromVTab (aVTab, aListOfFields, selectionOnly)


DefineUniqueFromVTab (ListBox)
DefineUniqueFromVTab

Populates the contents of aListBox with unique values from aField in aVTab. If selectionOnly is TRUE, then the current selection will be examined for unique values, otherwise, all the records will be examined. If caseSensitive is TRUE, then values from character fields will be considered unique if they differ only in case, otherwise they will be considered identical. If sortAscending is TRUE, then the values will be sorted in ascending order, otherwise they will be sorted in descending order.

Syntax

aListBox.DefineUniqueFromVTab (aVTab, aField, selectionOnly, caseSensitive, sortAscending)


Move (ListBox)
Move

Move aListBox dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aListBox to another control panel. If aListBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding a list box to a dialog object. You can't use this request to move a list box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aListBox.Move (dx, dy)


MoveTo (ListBox)
MoveTo

Move aListBox to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aListBox to another control panel. If aListBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aListBox is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aListBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0 ,0) will be the upper left hand corner of aDialog.

You can only use this request after adding a list box to a dialog object. You can't use this request to move a list box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aListBox.MoveTo (x, y)


Resize (ListBox)
Resize

Make aListBox dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding a list box to a dialog object. You can't use this request to resize a list box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aListBox.Resize (dw, dh)


ResizeTo (ListBox)
ResizeTo

Makes aListBox w pixels wide and h pixels tall. The position of its upper left hand corner of the bounding box is not changed.

You can only use this request after adding a list box to a dialog object. You can't use this request to resize a list box on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aListBox.ResizeTo (w, h)


ReturnBox (ListBox)
ReturnBox

Returns a copy of the bounding box for aListBox. The box's coordinates are in the coordinate system of aListBox's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aListBox is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aListBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aListBox.ReturnBox

Returns

Rect


FindByValue (ListBox)
FindByValue

Each cell in aListBox is examined to see if its value is anIcon, or if it contains a string that exactly matches the characters in aString. If such a cell is found, it becomes the current cell. Otherwise, the current cell is not changed. The search is not case sensitive. If aListBox has several values that qualify the search, the first one it finds becomes the current cell. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.FindByValue (anIconOrString)


GoColumn (ListBox)
GoColumn

The top cell that is aColumnOffset columns from the left becomes the current cell. For example, use aColumnOffset value of zero to make the first cell in aListBox the current cell. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoColumn (aColumnOffset)


GoDown (ListBox)
GoDown

Moves the current cell down by one cell.

Syntax

aListBox.GoDown

Returns

Boolean


GoField (ListBox)
GoField

Change the column of the current cell to be the one showing values from aField. The current row is not affected. aListBox must have been defined with DefineFromVTab. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoField (aField)


GoFirstSelected (ListBox)
GoFirstSelected

The first selected cell becomes the current cell. The first selected cell is found searching row-by-row. The request returns TRUE if there is a selected cell. This request is useful to go to the first selected cell when the user selects more than one cell in aListBox. See an example in the GoNextSelected request.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoFirstSelected

Returns

Boolean


GoLeft (ListBox)
GoLeft

Moves the current cell left by one cell.

Syntax

aListBox.GoLeft

Returns

Boolean


GoNextSelected (ListBox)
GoNextSelected

If there are more than one cells selected in aListBox, the next selected cell becomes the current cell. The next selected cell is found searching row-by-row. The request returns TRUE if there is a next selected cell.

Assuming that aListBox has more than one selected cells, the following code fragment will step through each selected cell and make it a current cell:

  aListBox = av.FindDialog("Dialog1").FindByName("aListBox1")
  aList = aListBox.GetSelection
  aListBox.GoFirstSelected
  msgBox.Info(aListBox.GetCurrentValue.AsString,"")
  for each i in aList
    if (aListBox.GoNextSelected) then
      msgBox.Info(aListBox.GetCurrentValue.AsString,"")
    end
  end

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoNextSelected

Returns

Boolean


GoRecord (ListBox)
GoRecord

Change the row of the current cell to to be the one whose contents are defined from nthRecord. The current column is not affected. The contents of aListBox must have been defined using DefineFromVTab. For example, use nthRecord value of zero to change the row of the current cell to the first row in aListBox. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoRecord (nthRecord)


GoRecordField (ListBox)
GoRecordField

Positions the current cell at the row-column intersection determined from nthRecord and aField. The contents of aListBox must have been defined using DefineFromVTab. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoRecordField (nthRecord, aField)


GoRight (ListBox)
GoRight

Moves the current cell right by one cell.

Syntax

aListBox.GoRight

Returns

Boolean


GoRow (ListBox)
GoRow

The left cell that is aRowOffset rows from the top becomes the current cell. You may only use this request after adding aListBox to a dialog. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

This request will have no affect if it is used in an open event script for a dialog, and the dialog has just been previously compiled.

Syntax

aListBox.GoRow (aRowOffset)


GoRowColumn (ListBox)
GoRowColumn

The cell that is aRowOffset rows from the top and aColumnOffset columns from the left becomes the current cell. For example, specify a value of zero for both aRowOffset and aColumnOffset to make the first cell in aListBox the current cell. Use SelectCurrent and ShowCurrent requests to visually highlight the current cell in aListBox.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GoRowColumn (aRowOffset, aColumnOffset)


GoUp (ListBox)
GoUp

Moves the current cell up by one cell.

Syntax

aListBox.GoUp

Returns

Boolean


Apply (ListBox)
Apply

Executes aListBox's apply script.

Apply scripts are typically used to perform some action with the current selection. Thus, when the user double clicks on a cell in aListBox, first the Select (or RangeSelect) script then the Apply (or RangeApply) script executes.

Syntax

aListBox.Apply


DeleteColumns (ListBox)
DeleteColumns

Deletes numColumns columns from aListBox. The column containing the current cell, and numColumns-1 columns to the right of that, are deleted. If less than numColumns-1 columns follow, then they will be deleted, and the total number of deleted columns will be less than numColumns. You cannot use this request on aListBox when its contents are defined from a dictionary or when it is showing unique values from a VTab. You may only use this request after adding aListBox to a dialog.

Deleting columns from aListBox defined from a VTab doesn't affect its associated VTab in any way.

Syntax

aListBox.DeleteColumns (numColumns)


DeleteRows (ListBox)
DeleteRows

Deletes numRows rows from aListBox. The row containing the current cell, and numRows-1 rows following that row, are deleted. If less than numRows-1 rows follow, then they will be deleted, and the total number of deleted rows will be less than numRows. Deleting rows from aListBox defined from a dictionary removes from the dictionary those associations whose keys were displayed in the rows. You may only use this request after adding aListBox to a dialog.

Deleting rows from aListBox defined from a VTab doesn't affect its associated VTab in any way.

Syntax

aListBox.DeleteRows (numRows)


Empty (ListBox)
Empty

Removes all elements from aListBox. If its contents were defined from the keys of a dictionary, then the dictionary is also emptied. If its contents were defined from a VTab, the VTab is not affected. The requests GetDictionary and GetVTab return nil after using this request.

Syntax

aListBox.Empty


FitColumns (ListBox)
FitColumns

Adjust the width of each column in the specified range, and optionally the height of all rows, so that the cell contents are entirely visible. aRangeOfColumnOffsets is specified as an Avenue interval object. '1..10' is an example of an interval object. Refer to the online help for class Interval for more information.

As an example, lets say you want to display a single column list of icons. You might do something like this:

    myListBox.DefineFromList({icon1, icon2, ...})
    myListBox.FitColumns(0..0, true)

This example populates myListBox with a list of icons, then calculates a column width that will show the largest icon in the list. The height of each row is adjusted independantly.

The FitColumns request will have no effect when it is sent under the following circumstances:

   - aListBox has not yet been added to a dialog
   - the dialog containing aListBox has been loaded from a project
     (or extension) but not yet opened.

Syntax

aListBox.FitColumns (aRangeOfColumnsOffsets, adjustRowHeight)


FitRows (ListBox)
FitRows

Adjusts the height of each row in the specified range, and optionally the width of all columns, so that the cell contents are entirely visible. aRangeOfRowOffsets is specified as an Avenue interval object. '1..10' is an example of an interval object. Refer to the online help for class Interval for more information.

As an example, lets say you want to adjust the width and height of all cells in a list box that contains icons in the first row, and text in the other rows.

  myListBox.DefineFromList(
    { {icon1, icon2, ..., iconN},
      {text1, text2, ..., textN},
      {more text}
    })
  myListBox.FitRows(0..(myListBox.GetRowCount-1), true)

This example populates myListBox with icons in the first row, and text strings in the other rows. The first row is adjusted so that its height is appropriate for the largest icon. The height of the other rows is adjusted for the height of the font used to print the text. The widths of the columns are adjusted to show the longest text string in each column.

Syntax

aListBox.FitRows (aRangeOfRowOffsets, adjustColumnWidths)


Focus (ListBox)
Focus

Assigns keyboard focus to aListBox. This request has now effect between the time aListBox is loaded from a project and the time its containing dialog or document is displayed.

Syntax

aListBox.Focus


InsertColumns (ListBox)
InsertColumns

Inserts numColumns into aListBox. These columns are inserted before the column containing the current cell. After the operation, the current cell maintains its cell coordinates. This means its in a column that was just added. Existing columns have moved right. You cannot insert rows or columns to aListBox when its contents are defined from a VTab or a dictionary. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.InsertColumns (numColumns)


InsertRows (ListBox)
InsertRows

Inserts numRows rows into aListBox. These rows are inserted before the row containing the current cell. After the operation, the current cell maintains its cell coordinates. This means its in a row that was just added. Existing rows have moved down. You cannot currently add rows or columns to aListBox when its contents are defined from a VTab or a dictionary. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.InsertRows (numRows)


RangeApply (ListBox)
RangeApply

Executes the range apply script responsible for handling mouse double clicks on the cell whose row and column are identified by aPoint. If no range apply script is responsible for that cell, the aListBox's apply script is executed (if it exists). See SetRangeApply request for more details.

Syntax

aListBox.RangeApply (aPoint)


RangeSelect (ListBox)
RangeSelect

Executes the range select script responsible for handling mouse clicks (single clicks) on the cell whose row and column are identified by aPoint. If no range select script is responsible for that cell, the aListBox's select script is executed (if it exists). See SetRangeSelect request for more details.

Syntax

aListBox.RangeSelect (aPoint)


Select (ListBox)
Select

Executes aListBox's select script.

Syntax

aListBox.Select


SelectCurrent (ListBox)
SelectCurrent

Selects the current cell. No event scripts are executed. If mergeSelection is TRUE, then the current cell becomes part of any existing selection, otherwise the current cell becomes the only selected cell. You may use ShowCurrent request to scroll the list box so that the current cell is visible.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SelectCurrent (mergeSelection)


SetSelection (ListBox)
SetSelection

Selects all cells in aRange. If appendSelection is true, this selection is merged with any existing selection, otherwise it replaces any existing selection.

You define aRange by creating a rectangle whose origin is the upper left hand corner of the range (expressed as offsets from the upper left hand corner of the list box), and whose width and height define the number of columns and number of rows to be included in the range.

If aRange is an empty rectangle (width or height are zero) and appendSelection is false, then any current selection will be cleared. Send the Select request to aListBox immediately afterwards if you want the Select event script to be executed with the new selection.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SetSelection (aRange, appendSelection)


ShowCurrent (ListBox)
ShowCurrent

Scrolls the list box so that the current cell is visible. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.ShowCurrent


SortAscending (ListBox)
SortAscending

Sorts the rows of aListBox in ascending order using the current column to determine row order. If caseSensitive is TRUE, differences in the case of string will influence the sorting order. Icons are sorted by its name.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SortAscending (caseSensitive)


SortDescending (ListBox)
SortDescending

Sorts the rows of aListBox in descending order using the current column to determine row order. If caseSensitive is TRUE, differences in the case of string will influence the sorting order. Icons are sorted by its name.

You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SortDescending (caseSensitive)


Update (ListBox)
Update

Executes aListBox's update script if aListBox is listening to updates.

Syntax

aListBox.Update


GetApply (ListBox)
GetApply

Returns the name of the current apply script.

Syntax

aListBox.GetApply

Returns

String


GetColumnCount (ListBox)
GetColumnCount

Gets the current number of columns in aListBox. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetColumnCount

Returns

Number


GetColumnWidth (ListBox)
GetColumnWidth

Returns the width in inches of the current column of aListBox. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetColumnWidth

Returns

Number


GetCurrentColumn (ListBox)
GetCurrentColumn

Gets the offset of the current column from the left of aListBox. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetCurrentColumn

Returns

Number


GetCurrentField (ListBox)
GetCurrentField

Get the field associated with the current column of aListBox. This request returns nil if the contents of aListBox were not defined using DefineFromVTab. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetCurrentField

Returns

Field


GetCurrentLocation (ListBox)
GetCurrentLocation

Gets the location of the current cell. The location is returned in a point object. The point's x value is the offset of the column containing the cell, and the point's y value is offset of the row containing the cell. The cell in the extreme upper left hand corner has location (0, 0). You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetCurrentLocation

Returns

Point


GetCurrentRecord (ListBox)
GetCurrentRecord

Get the VTab record number of the row containing the current cell of aListBox. This request returns nil if the contents of aListBox were not defined using DefineFromVTab. The record numbers start from zero to n-1. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetCurrentRecord

Returns

Number


GetCurrentRow (ListBox)
GetCurrentRow

Gets the offset of the current row from the top of aListBox. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetCurrentRow

Returns

Number


GetCurrentValue (ListBox)
GetCurrentValue

Gets the object associated with the current cell. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetCurrentValue

Returns

Obj


GetDialog (ListBox)
GetDialog

Gets the dialog that contains aListBox. You may only use this request when aListBox is in a dialog.

Syntax

aListBox.GetDialog

Returns

Dialog


GetDictionary (ListBox)
GetDictionary

Gets the dictionary used in the last DefineFromDictionary request sent to aListBox. This request returns NIL if any other kind of DefineFrom... was sent in the interim.

Syntax

aListBox.GetDictionary

Returns

Dictionary


GetFieldNamesVisible (ListBox)
GetFieldNamesVisible

Returns TRUE when aListBox will display field names when it is defined from a vtab.

Syntax

aListBox.GetFieldNamesVisible

Returns

Boolean


GetFields (ListBox)
GetFields

Gets the list of fields currently being displayed by aListBox. This request returns nil if aListBox is not currently being defined from a VTab. This list is read-only. Do not add, modify, or remove elements. If you need to alter the list of fields being displayed, use the DefineFromVTab request.

Syntax

aListBox.GetFields

Returns

List


GetList (ListBox)
GetList

Gets a list containing the same elements as are in aListBox. You may manipulate this list without affecting the ordering of the elements in aListBox. The list generated by this request is structured the same as a list that could be passed to DefineFromList. For example, if aListBox has three rows and three columns of data in it, this request will return a list of lists that looks something like this:

  {
   { (0,0),(0,1),(0,2) },
   { (1,0),(1,1),(1,2) },
   { (2,0),(2,1),(2,2) }
  }

This request returns nil when aListBox is defined from a VTab or a dictionary.

Syntax

aListBox.GetList

Returns

List


GetNextControl (ListBox)
GetNextControl

Gets the control which will receive keyboard focus when the user presses the TAB key. It will return nil if the NextControl property is not set.

Syntax

aListBox.GetNextControl

Returns

Control


GetRangeApply (ListBox)
GetRangeApply

Returns the name of the range script responsible for handling a mouse double click on the cell whose coordinates are specified by aPoint.

Syntax

aListBox.GetRangeApply (aPoint)

Returns

String


GetRangeSelect (ListBox)
GetRangeSelect

Returns the name of the range select script responsible for handling a click on the cell whose coordinates are specified by aPoint.

Syntax

aListBox.GetRangeSelect (aPoint)

Returns

String


GetRowCount (ListBox)
GetRowCount

Gets the current number of rows in aListBox. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetRowCount

Returns

Number


GetRowHeight (ListBox)
GetRowHeight

Returns the height in inches of the current row of aListBox. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetRowHeight

Returns

Number


GetSelect (ListBox)
GetSelect

Returns the name of the Select script used by aListBox.

Syntax

aListBox.GetSelect

Returns

String


GetSelection (ListBox)
GetSelection

Gets a list of values of all selected cells. You are free to manipulate this list in any way without affecting the nature of the aListBox's selection. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetSelection

Returns

List


GetSelectionStyle (ListBox)
GetSelectionStyle

Gets the element from the enumeration ListBoxSelectionEnum that describes how aListBox adds cells to the selection.

Syntax

aListBox.GetSelectionStyle

Returns

ListBoxSelectionEnum


GetVTab (ListBox)
GetVTab

Returns the VTab currently associated with aListBox, or nil if aListBox is not obtaining its values from any vtab. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.GetVTab

Returns

VTab


HasFastener (ListBox)
HasFastener

Returns TRUE if aListBox currently has aFastener defined for it.

Syntax

aListBox.HasFastener (aFastener)

Returns

Boolean


HasHorizontalScroll (ListBox)
HasHorizontalScroll

Returns TRUE if aListBox has a horizontal scroll bar.

Syntax

aListBox.HasHorizontalScroll

Returns

Boolean


HasScript (ListBox)
HasScript

Returns TRUE when aListBox is associated with an event script named aScriptName.

Syntax

aListBox.HasScript (aScriptName)

Returns

Boolean


HasSelection (ListBox)
HasSelection

Returns TRUE when at least one cell in aListBox is selected. This request does not change the location of the current cell. This request can only be used after aControl has been added to a dialog.

Syntax

aListBox.HasSelection

Returns

Boolean


HasVerticalScroll (ListBox)
HasVerticalScroll

Returns TRUE if aListBox has a vertical scroll bar.

Syntax

aListBox.HasVerticalScroll

Returns

Boolean


RemoveRangeApply (ListBox)
RemoveRangeApply

Removes aScriptName from the list of range apply scripts used by aListBox.

Syntax

aListBox.RemoveRangeApply (aScriptName)


RemoveRangeSelect (ListBox)
RemoveRangeSelect

Removes aScriptName from the list of range select scripts used by aListBox.

Syntax

aListBox.RemoveRangeSelect (aScriptName)


SetApply (ListBox)
SetApply

Sets the apply script for aListBox. Apply scripts are typically used to perform some action with the current selection. Thus, when the user double-clicks on a cell in aListBox, first the Select (or RangeSelect) script then the Apply (or RangeApply) script executes.

If you want to perform different actions on a different range of cells, you may use a combination of Apply and RangeApply scripts to change the behavior of what happens when the user double-clicks on a cell. For example, you can define a range of columns (and rows) and specify a different RangeApply script. Thus, when the user double-clicks on a cell, one of two things may happen - if a RangeApply script is defined for that cell, then the RangeApply script is executed. Otherwise, the Apply script is executed. You may define more than one RangeApply scripts as long as they do not overlap between cells. See SteRangeSelect and SetRangeApply requests for more details.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aListBox.SetApply (aScriptName)


SetColumnWidth (ListBox)
SetColumnWidth

Sets the width of the current column. aMeasure is a number interpreted as inches when aListBox has a horizontal scroll bar, and interpreted as a percentage of the total width when aListBox doesn't have a horizontal scroll bar. For example, if you have 3 columns in a list box (without a horizontal scroll bar), the following code fragment will make the first column half the width of the list box and equally divide the other two columns:

  aListBox.GoColumn(0)
  aListBox.SetColumnWidth(50)
  aListBox.CoColumn(1)
  aListBox.SetColumnWidth(25)
  aListBox.GoColumn(2)
  aListBox.SetColumnWidth(25)

Use FitColumns request to adjust the width of a range of columns. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SetColumnWidth (aMeasure)


SetCurrentValue (ListBox)
SetCurrentValue

Make anObject the value for the current cell. The value is represented in one of three ways:

  - If anObject is an icon, the icon is drawn
  - If anObject is a string, it is printed in the cell
  - If anObject is some other kind of object, it is sent the AsString
     request when it needs to be drawn, and that string is then printed
     in the cell.

This request does not affect any associated VTab in any way. You are responsible for posting such changes back to the VTab. The requests GetCurrentRecord and GetCurrentField can aid in doing this.

You may need to use the request ShowCurrent after this request if the current cell was visible and you want it to stay visible. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SetCurrentValue (anObject)


SetEnabled (ListBox)
SetEnabled

When enabled is TRUE, the user will be able to interact with aListBox, otherwise no user interaction will be possible.

Syntax

aListBox.SetEnabled (enabled)


SetFastener (ListBox)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aListBox.SetFastener (fastener, onOrOff)

Returns

Boolean


SetFasteners (ListBox)
SetFasteners

Defines resizing and repositioning fasteners for aListBox. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aListBox's fasteners are not altered.

Syntax

aListBox.SetFasteners (aListOfFasteners)

Returns

Boolean


SetFieldNamesVisible (ListBox)
SetFieldNamesVisible

Shows or hides field names for the listbox, when it is defined from a vtab.

Syntax

aListBox.SetFieldNamesVisible (visible)


SetHorizontalScroll (ListBox)
SetHorizontalScroll

When useScrollBar is TRUE, a horizontal scroll bar is added to aListBox. When useScrollBar is FALSE, any existing horizontal scroll bar is removed. You will need to redefine the contents of aListBox after using this request.

Syntax

aListBox.SetHorizontalScroll (useScrollBar)


SetNextControl (ListBox)
SetNextControl

Sets the control which will receive keyboard focus when the user presses the TAB key. aControl must be a TextLine, TextBox, Slider, ComboBox or ListBox control.

Syntax

aListBox.SetNextControl (aControl)


SetRangeApply (ListBox)
SetRangeApply

Sets the script responsible for handling mouse double clicks inside the range of cells specified by aRectangle. Multiple range apply scripts can be defined for aListBox. Their ranges cannot overlap. A mouse double click in a cell not enclosed in the range of any range script will trigger execution of aListBox's apply script (if it exists). See the request SetRangeSelect for a description of how aRectangle is used by this request.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aListBox.SetRangeApply (aScriptName, aRectangle)


SetRangeSelect (ListBox)
SetRangeSelect

Sets the script responsible for handling user selections inside the range of cells specified by aRectangle. Multiple range select scripts can be defined for aListBox. Their ranges cannot overlap. A mouse click in a cell not enclosed in the range of any range script will trigger execution of aListBox's select script (if it exists).

You define a range by creating a rectangle whose origin is the upper left hand corner of the range (expressed as offsets from the upper left hand corner of the list box), and whose width and height define the number of columns and number of rows to be included in the range.

You may need to have a range script whose range starts at a fixed location, but always goes to either the last row in the list, or the last column, or both regardless of how many rows and/or columns are currently in the list. You can do this by specifying a zero for either the width, or the height, or both, of the range rectangle. For example, the following Avenue code fragment defined a range select script that applies to all cells in the fourth column of aListBox.

  aListBox.SetRangeSelect("myRangeSelect",
             Rect.Make(3@0, 1@0))

If you really want to have an empty range, you'll need to use -1 for either the width or the height.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aListBox.SetRangeSelect (aScriptName, aRectangle)


SetRowHeight (ListBox)
SetRowHeight

Sets the height of the current row. aMeasure is interpreted to be inches when aListBox has a vertical scroll bar, and a percentage of the total height when aLIstBox doesn't have a vertical scroll bar. Use FitRows request to adjust the height of a range of rows in a list box. You may only use this request after adding aListBox to a dialog.

Syntax

aListBox.SetRowHeight (aMeasure)


SetSelect (ListBox)
SetSelect

Sets the Select script for aListBox. Select scripts are typically used to inform other controls, or other parts of ArcView, that the selection in the list box has changed. For example, you may use the following line of code as Select script to enable a Delete button when user selects a row:

  'This script enables the Delete button
  self.GetDialog.FindByName("btn_Delete").SetEnabled(true)

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aListBox.SetSelect (aScriptName)


SetSelectionStyle (ListBox)
SetSelectionStyle

Controls how aListBox adds cells to the selection. By default, only single cell selections are permitted.

Syntax

aListBox.SetSelectionStyle (aSelectionStyle)


SetVerticalScroll (ListBox)
SetVerticalScroll

When useScrollBar is TRUE, a vertical scroll bar is added to aListBox. When useScrollBar is FALSE, any existing vertical scroll bar is removed. By default, aListBox will have a vertical scroll bar. You will need to redefine the contents of aListBox after using this request.

Syntax

aListBox.SetVerticalScroll (useScrollBar)


SetVisible (ListBox)
SetVisible

When visible is TRUE, the list box will be displayed, otherwise it will be invisible.

Syntax

aListBox.SetVisible (visible)


AddListener (ListBox)
AddListener

Adds aControl as a listener of aListBox. If aControl is already a listener, it is not added again. You do not need to use the request ChangedListeners after using this request.

Syntax

aListBox.AddListener (aControl)


BroadcastUpdate (ListBox)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aListBox.

Syntax

aListBox.BroadcastUpdate


ChangedListeners (ListBox)
ChangedListeners

Informs aListBox that you have modified its list of listeners. Send this request after manipulating the list obtained from the GetListeners request. You do not need to send this request after using the SetListeners request.

Syntax

aListBox.ChangedListeners


GetBroadcaster (ListBox)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aListBox's update script. This request will return nil if the update event aListBox is responding was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aListBox.GetBroadcaster

Returns

Obj


GetListeners (ListBox)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aListBox. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aListBox.

Syntax

aListBox.GetListeners

Returns

List


IsListening (ListBox)
IsListening

Returns TRUE if aListBox will execute its update script in response to an update event.

Syntax

aListBox.IsListening

Returns

Boolean


RemoveListener (ListBox)
RemoveListener

Removes aControl from aListBox's list of listeners. Nothing happens if aControl is not in that list. You do not need to use the request ChangedListeners after using this request.

Syntax

aListBox.RemoveListener (aControl)


SetListeners (ListBox)
SetListeners
Example

Sets the listeners that will be sent the update event when aListBox is sent the BroadcastUpdate request. The input list, but not its elements, is cloned by this request.

Syntax

aListBox.SetListeners (aListOfListeners)


StartListening (ListBox)
StartListening

aListBox will respond to any future update events by executing its update script.

Syntax

aListBox.StartListening


StopListening (ListBox)
StopListening

aListBox will not execute its update script in response to an update event.

Syntax

aListBox.StopListening


ListBoxSelectionEnum

 You can select individual cells, rows or columns by single clicking; rectangular ranges of cells by clicking and dragging; or multiple rectangular ranges of cells by clicking and dragging with the shift key pressed. Elements from this enumeration let you specify which of these selection behaviors the list box should exhibit.

#LISTBOX_SELECTION_SINGLECELL

Only single cell selections are permitted. A mouse click always clears any existing selection and then selects a single cell. This is the default selection style when a ListBox is created.

#LISTBOX_SELECTION_SINGLEROW

Only single row selections are permitted. A mouse click always clears any existing selection and then selects an entire row.

#LISTBOX_SELECTION_SINGLECOLUMN

Only single column selections are permitted. A mouse click always clears any existing selection and then selects an entire column.

#LISTBOX_SELECTION_SINGLERANGE

Clicking and dragging selects a rectangular range of cells. Any existing selection is cleared first.

#LISTBOX_SELECTION_MULTIRANGE

Clicking and dragging without the shift key pressed works the same as LISTBOX_SELECTION_SINGLERANGE. When the shift key is pressed, the new rectangular area is added to any current selection.

#LISTBOX_SELECTION_MULTIROW

Clicking with the shift key pressed adds the row under the mouse cursor to the set of selected rows.

#LISTBOX_SELECTION_MULTICOLUMN

Clicking with the shift key pressed adds the column under the mouse cursor to the set of selected columns.


Slider

 A slider is a control that displays the current value of a real-valued variable defined over a finite interval. The variable can either take on any value, or only certain values, from that interval.

A slider has several visible parts. It has a vertical or horizontal slot that represents the range of values that it can take on. Its thumb shows its current value. It can optionally have two step buttons. The user can press a step button to move the thumb a small amount towards either the lower or upper bound. Finally, it has zero, one or two sets of ticks. Ticks simply help the user position the thumb at a known position.

Attributes

Value.The current value of the slider. It is always in the range defined by the slider's lower and upper attributes. The default value is 0.

Upper.The upper bound of the interval over which the slider's value is defined. The default value is 10.

Lower.The lower bound of the interval over which the slider's value is defined. The default value is 0.

Horizontal.When set to TRUE, the slider will draw itself with a horizontal orientation (the thumb will move left and right). When set to FALSE, the slider will draw itself with a vertical orientation (the thumb will move up and down). The default value is TRUE.

ValueIncrement.Restricts the values that a slider can take on. If ValueIncrement is greater than zero, then the slider's value will always be in the form lower + i * ValueIncrement, where i is some positive integer. When ValueIncrement is zero, the slider's value can be any real number in its defined range. The default value is 1.

MainIncrement.The separation between ticks along either the bottom or right side of the slider. This value has the same units as those used by the slider's upper, lower and current values. A MainIncrement of zero makes ticks invisible. This increment has no affect on the slider's value, it is used for display purposes only. The default value is 2.

AuxIncrement.The separation between ticks along either the top or left side of the slider. This value has the same units as those used by the slider's upper, lower, and current values. An AuxIncrement of zero prevents ticks from showing. This increment has no affect on the slider's current value. It is used for display purposes only. The default Value is 0.

Drag.The name of a script that will be executed repeatedly while the user drags on the slider.

Click.The name of a script that will be executed when the user releases the mouse inside the slider (that is, it will be executed after the drag event has been processed zero or more times).

ReadOnly.When ReadOnly is TRUE, the slider does not permit the user to interactively change its value.

StepButtons.TRUE when the slider also displays step buttons that change its current value by ValueIncrement units. If the slider's ValueIncrement property is currently zero, then the step buttons changes its current value by MainIncrement. If that's zero, the value changes by 10 percent of the interval.

NextControl.The control that will receive keyboard focus when the user presses the TAB key.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making Sliders

Make  :  Slider

Instance Requests

Using Sliders

DefineFromInterval ( anInterval )

Focus

Update

Getting/Setting attributes of Sliders

GetAuxIncrement  :  Number

GetClick  :  String

GetDialog  :  Dialog

GetDrag  :  String

GetLower  :  Number

GetMainIncrement  :  Number

GetNextControl  :  Control

GetUpper  :  Number

GetValue  :  Number

GetValueIncrement  :  Number

GetValuePercentage  :  Number

HasFastener ( aFastener ) :  Boolean

HasScript ( aScriptName ) :  Boolean

HasStepButtons  :  Boolean

IsHorizontal  :  Boolean

IsReadOnly  :  Boolean

SetAuxIncrement ( aTickDistance )

SetClick ( aScriptName )

SetDrag ( aScriptName )

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetHorizontal ( isHorizontal )

SetLower ( aLowerBound )

SetMainIncrement ( aTickDistance )

SetNextControl ( aControl )

SetReadOnly ( readOnly )

SetUpper ( anUpperBound )

SetValue ( aValue )

SetValueIncrement ( anIncrement )

SetValuePercentage ( aPercentage )

ShowStepButtons ( showThem )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Listeners and Broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

Interval


Make (Slider)
Make
Example

Creates a new Slider object. By default, it has an interval of 0 to 10, a value increment of 1, a main increment of 2, no auxiliary increment, a current value of zero, no step buttons, and is oriented horizontally.

Syntax

Slider.Make

Returns

Slider


DefineFromInterval (Slider)
DefineFromInterval

Defines aSlider's lower, upper, and ValueIncrement properties from anInterval. For example,

    aSlider.DefineFromInterval(0..100 by 10)

will set aSlider's lower value to zero, upper value to 100 and the value increment to 10.

Syntax

aSlider.DefineFromInterval (anInterval)


Focus (Slider)
Focus

Assigns keyboard focus to aSlider. This request has now effect between the time that aSlider is loaded from a project and the time its containing dialog or document is made visible.

Syntax

aSlider.Focus


Update (Slider)
Update

Executes aSlider's update event script if aSlider is listening to updates.

Syntax

aSlider.Update


GetAuxIncrement (Slider)
GetAuxIncrement

Gets the current distance between tics that are located along either the top or left of aSlider.

Syntax

aSlider.GetAuxIncrement

Returns

Number


GetClick (Slider)
GetClick

Gets the name of the script that will be executed when the user release the mouse button after dragging the thumb of aSlider.

Syntax

aSlider.GetClick

Returns

String


GetDialog (Slider)
GetDialog

Gets the dialog containing aSlider. Do not use this request when aSlider is not in a dialog.

Syntax

aSlider.GetDialog

Returns

Dialog


GetDrag (Slider)
GetDrag

Gets the name of the script that will be executed when aSlider receives the drag event.

Syntax

aSlider.GetDrag

Returns

String


GetLower (Slider)
GetLower

Gets aSlider's current lower bound.

Syntax

aSlider.GetLower

Returns

Number


GetMainIncrement (Slider)
GetMainIncrement

Gets the current distance between ticks that are located along either the bottom or right of aSlider.

Syntax

aSlider.GetMainIncrement

Returns

Number


GetNextControl (Slider)
GetNextControl

Gets the control that will receive the keyboard focus when the TAB is pressed while aSlider currently has the keyboard focus. Otherwise it returns nil.

Syntax

aSlider.GetNextControl

Returns

Control


GetUpper (Slider)
GetUpper

Gets aSlider's current upper bound.

Syntax

aSlider.GetUpper

Returns

Number


GetValue (Slider)
GetValue

Gets aSlider's current value. See SetValue request for current value behavior in special cases.

Syntax

aSlider.GetValue

Returns

Number


GetValueIncrement (Slider)
GetValueIncrement

Gets aSlider's value increment.

Syntax

aSlider.GetValueIncrement

Returns

Number


GetValuePercentage (Slider)
GetValuePercentage

Gets aSlider's current value expressed as a percentage of aSlider's interval. See SetValue request for current value behavior in special cases.

Syntax

aSlider.GetValuePercentage

Returns

Number


HasFastener (Slider)
HasFastener

Returns TRUE if Slider currently has aFastener defined for it.

Syntax

aSlider.HasFastener (aFastener)

Returns

Boolean


HasScript (Slider)
HasScript

Returns TRUE when aSlider is associated with a script named aScriptName.

Syntax

aSlider.HasScript (aScriptName)

Returns

Boolean


HasStepButtons (Slider)
HasStepButtons

Returns TRUE if aSlider is currently displaying step buttons. Step buttons are only available under the Windows operating system. On UNIX and Macintosh platforms, the step buttons won't be visible even when it returns TRUE.

Syntax

aSlider.HasStepButtons

Returns

Boolean


IsHorizontal (Slider)
IsHorizontal

Returns TRUE if aSlider is oriented horizintally (its thumb moves left and right). Returns FALSE if aSlider is oriented vertically (its thumb moves up and down). The default orientation is horizontal.

Syntax

aSlider.IsHorizontal

Returns

Boolean


IsReadOnly (Slider)
IsReadOnly

Returns TRUE if the user cannot interact with aSlider.

Syntax

aSlider.IsReadOnly

Returns

Boolean


SetAuxIncrement (Slider)
SetAuxIncrement

Sets aSlider's AuxIncrement property to be aTickDistance. ASlider will display tick marks along the top or left sides that are seperated by this distance. This number has the same units as aSlider's lower and upper bounds. If aTickDistance is zero, then no auxiliary ticks are shown. The default value is 0. aTickDistance has no effect on aSlider's current value and is only used to enhance the display of the slider. Typically you use this property to show the sub-tics of a main increment tic marks. Some operating systems don't support tic marks on sliders. Also, make sure to have sufficient space between the slider and its surrounding handles to show the tic marks correctly.

Syntax

aSlider.SetAuxIncrement (aTickDistance)


SetClick (Slider)
SetClick

Sets the script to be executed when the user release the mouse button after dragging the thumb of aSlider.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aSlider.SetClick (aScriptName)


SetDrag (Slider)
SetDrag

Sets the script to be executed when aSlider receives the drag event. For example, assuming you have aTextLabel control next to aSlider, the following code fragment will update aTextLabel (as the user drags the slider) to show the current value of aSlider:

    'get the text label control
    aLabel = self.GetDialog.FindByName("aTextLabel1")
    aLabel.SetLabel(self.getValue.AsString)

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aSlider.SetDrag (aScriptName)


SetFastener (Slider)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aSlider.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (Slider)
SetFasteners

Defines positioning and resizing fasteners for aSlider. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aSlider's fasteners are not altered. An example of a possible conflict is by specifying the fasteners to maintain aSlider's width as well as to maintain the fixed distance from the left and right sides of aDialog.

Syntax

aSlider.SetFasteners (aListOfFasteners)

Returns

Boolean


SetHorizontal (Slider)
SetHorizontal

When isHorizontal is TRUE, aSlider will be redrawn so that it is oriented horizontally inside its current bounding box. When isHorizontal is FALSE, aSlider will be redrawn so that it is oriented vertically inside its current bounding box. The default orientation is horizontal.

Syntax

aSlider.SetHorizontal (isHorizontal)


SetLower (Slider)
SetLower

Sets aSlider's lower bound to be aLowerBound. The default value is 0.

After setting aSlider's lower and upper bounds, make sure the value increment property is set appropriately for the range. An inappropriate value increment can prevent the slider handle from moving.

Syntax

aSlider.SetLower (aLowerBound)


SetMainIncrement (Slider)
SetMainIncrement

Sets aSlider's MainIncrement to aTickDistance. ASlider will display tick lines along either the bottom or right side that are seperated by this distance. This number has the same units as aSlider's lower and upper bounds. If aTickDistance is zero, then no tick marks are shown. aTickDistance has no effect on aSlider's current value and is only used to enhance the display of the slider. The default value is 2. Some operating systems don't support tic marks on sliders. Also, make sure to have sufficient space between the slider and its surrounding handles to show the tic marks correctly.

Syntax

aSlider.SetMainIncrement (aTickDistance)


SetNextControl (Slider)
SetNextControl

Sets the control that will receive the keyboard focus when the TAB key is pressed when aSlider currently has the keyboard focus. aControl can be any ListBox, Slider, TextLine, TextBox, or ComboBox in the same dialog as aSlider. Setting the NextControl of a contorl to itself stops the TAB key from moving when that control is encountered.

Syntax

aSlider.SetNextControl (aControl)


SetReadOnly (Slider)
SetReadOnly

If readOnly is TRUE, then the user cannot interact with aSlider. You can, however, interact with aSlider properties in Avenue.

Syntax

aSlider.SetReadOnly (readOnly)


SetUpper (Slider)
SetUpper

Sets aSlider's upper bound to be anUpperBound. The default value is 10.

After setting aSlider's lower and upper bounds, make sure the value increment property is set appropriately for the range. An inappropriate value increment can prevent the slider handle from moving.

Syntax

aSlider.SetUpper (anUpperBound)


SetValue (Slider)
SetValue

Sets the current value of aSlider to be aValue. If aSlider is visible, its thumb is adjusted accordingly. If aValue is less than the lower bound or greater than the upper bound of aSlider, then it's current value is set to the bound nearest aValue. If aValue is in the interior of that interval, but its distance from the lower bound is not a multiple of aSlider's value increment, then aSlider's current value is set to the value increment multiple nearest aValue. For example, when the lower and upper bounds are set to zero and 10 and the value increment is set to 2, setting the current value of 3.5 will automatically sets the value to 4 as that is the closest multiple of a value increment.

Syntax

aSlider.SetValue (aValue)


SetValueIncrement (Slider)
SetValueIncrement

Sets aSlider's value increment to be anIncrement. If anIncrement is less than zero, aSlider's value increment is set to zero. The default value increment is 1. When anIncrement is zero, aSlider can assume any real number defined within its range. When anIncrement is greater than zero, aSlider's value will always be in the form:

    aSlider lower bound + (i * ValueIncrement)

where i is a positive integer.

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

Syntax

aSlider.SetValueIncrement (anIncrement)


SetValuePercentage (Slider)
SetValuePercentage

Sets aSlider's current value to be some percentage of its interval. Use this request when you only need to set the value relative to the interval. if aPercentage is less than zero or greater than 100, the current value is set to the appropriate bound. Other issues discussed in the SetValue request also apply.

Syntax

aSlider.SetValuePercentage (aPercentage)


ShowStepButtons (Slider)
ShowStepButtons

If showThem is TRUE, a pair of step buttons will be displayed on the slider, otherwise they will be hidden. The default value is FALSE, or no step buttons. 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 the MainIncrement. If this is also zero, the slider will move 10% of the interval.

Step buttons are only available under the Windows operating system.

Syntax

aSlider.ShowStepButtons (showThem)


Move (Slider)
Move

Move aSlider dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aSlider to another control panel. If aSlider is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding a slider to a dialog object. You cannot use this request to move aSlider in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aSlider.Move (dx, dy)


MoveTo (Slider)
MoveTo

Move aSlider to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0,0). You cannot use this to "move" aSlider to another control panel. If aSlider is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aSlider is contained within a control panel under aDialog, the location (0,0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aSlider is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0,0) will be the upper left hand corner of aDialog.

You can only use this request after adding a slider to a dialog object. You cannot use this request to move aSlider in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aSlider.MoveTo (x, y)


Resize (Slider)
Resize

Make aSlider dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding a slider to a dialog object. You cannot use this request to resize aSlider in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aSlider.Resize (dw, dh)


ResizeTo (Slider)
ResizeTo

Makes aSlider w pixels wide and h pixels tall. The position of its upper left hand corner of the bounding box is not changed. Note that if you increase the value h, the slider may appear to move from its upper left hand corner. This is because the slider always position itself in the middle of the bounding box.

You can only use this request after adding a slider to a dialog object. You cannot use this request to resize aSlider in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aSlider.ResizeTo (w, h)


ReturnBox (Slider)
ReturnBox

Returns the bounding box of aSlider. The box coordinates are in the coordinate system of aSlider's containing control panel. The upper left hand corner of that control panel is at location (0,0). Its units are in screen pixels.

For example, if aSlider is contained within a control panel under aDialog, the origin (0,0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aSlider is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aSlider.ReturnBox

Returns

Rect


AddListener (Slider)
AddListener

Adds aControl to aSlider's list of listeners. If aControl is already in that list, it is not added again. You do not need to use the ChangedListeners request after using this request.

Syntax

aSlider.AddListener (aControl)


BroadcastUpdate (Slider)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aSlider.

Syntax

aSlider.BroadcastUpdate


ChangedListeners (Slider)
ChangedListeners

Informs aSlider that you have modified its list of listeners. Send this request after manipulating the list obtained from the GetListeners request. You do not need to send this request after using the SetListeners request.

Syntax

aSlider.ChangedListeners


GetBroadcaster (Slider)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aSlider's update script. This request will return nil if the update event aSlider is responding was not initiated via the request BroadcastUpdate sent to some other object.

Syntax

aSlider.GetBroadcaster

Returns

Obj


GetListeners (Slider)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aSlider. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aSlider.

Syntax

aSlider.GetListeners

Returns

List


IsListening (Slider)
IsListening

Returns TRUE if aSlider will execute its update script in response to an update event.

Syntax

aSlider.IsListening

Returns

Boolean


RemoveListener (Slider)
RemoveListener

Removes aControl from aSlider's list of listeners. If aControl is not in that list, nothing happens. You do not need to use the ChangedListeners request after using this request.

Syntax

aSlider.RemoveListener (aControl)


SetListeners (Slider)
SetListeners
Example

Sets the listeners that will be sent the update event when aSlider is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

aSlider.SetListeners (aListOfListeners)


StartListening (Slider)
StartListening

aSlider will respond to any future update events by executing its update script.

Syntax

aSlider.StartListening


StopListening (Slider)
StopListening

aSlider will not execute its update script in response to an update event.

Syntax

aSlider.StopListening


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 ControlPanel, you must specify the bounding box for that control (rather than its index relative to other controls).

A control panel defines a local coordinate system in which contained controls are located. The upper left hand corner of the control panel is the origin (0, 0). The x coordinate increases as you move to the right, the y coordinate increases as you move down. The units are screen pixels. All locations inside the control panel are measured relative to that origin. This is different from the coordinate system used by the view and layout documents.

You can add any kind of control (except menus, toolmenus, and choices) to a control panel. When you add radio button controls to it, the control will automatically make sure that only one radio button is selected at a time.

Attributes

Label.Text that describes the ControlPanel. It appears in the upper left hand corner of the panel.

VisibleBorder.TRUE when the ControlPanel will be drawn with a black line around its perimeter.

SelectedRadio.The radio button in the panel (if any) that is currently selected.

Listeners.The list of controls that will have their update scripts executed whenever the request BroadcastUpdate is sent to the control panel.

Listening.When TRUE, the control panel will respond to an update event by executing its update event script, otherwise it will ignore the update event.

Box.The bounding box of the control panel. It is expressed in the pixel coordinate system, which has coordinates in screen pixels and an origin at the upper left hand corner of the control panel or dialog containing this control panel.

Fasteners.A list of enumeration elements from the enumeration ControlFastenerEnum. They describe how the control panel will adjust its size and position when its containing control panel changes its size and position.

Inherits From

ControlSet

Required Extension

     Dialog Designer

Class Requests

Making ControlPanels

Make  :  ControlPanel

Instance Requests

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

Using ControlPanels

Update

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Manipulating the elements of ControlPanels

Add ( aControl, aBox )

Empty

FindByClass ( aControlClass ) :  List

FindByName ( aControlName ) :  Control

GetSelected  :  RadioButton

Insert ( aControl, aBox )

Remove ( aControl )

Getting/Setting ControlPanel attributes

GetDialog  :  Dialog

GetLabel  :  String

HasFastener ( aFastener ) :  Boolean

HasVisibleBorder  :  Boolean

SetEnabled ( enabled )

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetLabel ( aLabel )

SetVisibleBorder ( isVisible )

__________

See also

Dialog
DocGUI
RadioButton


Make (ControlPanel)
Make
Example

Create a new ControlPanel object. It has a visible label and border by default.

Syntax

ControlPanel.Make

Returns

ControlPanel


AddListener (ControlPanel)
AddListener

Adds aControl to aControlPanel's list of listeners. You do not need to send the ChangedListeners request after using this request.

Syntax

aControlPanel.AddListener (aControl)


BroadcastUpdate (ControlPanel)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aControlPanel.

Syntax

aControlPanel.BroadcastUpdate


ChangedListeners (ControlPanel)
ChangedListeners

Informs aControlPanel that you have modiifed its list of listeners. Send this request after manipulating the list obtained from the GetListeners request. You do not need to send this request after using the SetListeners request.

Syntax

aControlPanel.ChangedListeners


GetBroadcaster (ControlPanel)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aControlPanel's update script. This request will return nil if the update event aControlPanel is responding was not initiated via the request BroadcastUpdate sent to some other object.

Syntax

aControlPanel.GetBroadcaster

Returns

Obj


GetListeners (ControlPanel)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aControlPanel. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aControlPanel.

Syntax

aControlPanel.GetListeners

Returns

List


IsListening (ControlPanel)
IsListening

Returns TRUE if aControlPanel will execute its update script in response to an update event.

Syntax

aControlPanel.IsListening

Returns

Boolean


RemoveListener (ControlPanel)
RemoveListener

Removes aControl from aControlPanel's list of listeners. You do not need to send the ChangedListeners request after using this request.

Syntax

aControlPanel.RemoveListener (aControl)


SetListeners (ControlPanel)
SetListeners
Example

Sets the listeners that will be sent the update event when aControlPanel is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

aControlPanel.SetListeners (aListOfListeners)


StartListening (ControlPanel)
StartListening

aControlPanel will respond to any future update events by executing its update script.

Syntax

aControlPanel.StartListening


StopListening (ControlPanel)
StopListening

aControlPanel will not execute its update script in response to an update event.

Syntax

aControlPanel.StopListening


Update (ControlPanel)
Update

Executes aControlPanel's update script and propagaes the update event to contained controls if it is listening to updates.

Syntax

aControlPanel.Update


Move (ControlPanel)
Move

Move aControlPanel dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aControlPanel to another control panel. If aControlPanel is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aControlPanel to a dialog object. You cannot use this request to move aControlPanel in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aControlPanel.Move (dx, dy)


MoveTo (ControlPanel)
MoveTo

Move aControlPanel to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aControlPanel to another control panel. If aControlPanel is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aControlPanel is contained within another control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aControlPanel is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aControlPanel to a dialog object. You cannot use this request to move aControlPanel in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aControlPanel.MoveTo (x, y)


Resize (ControlPanel)
Resize

Make aControlPanel dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aControlPanel to a dialog object. You cannot use this request to resize aControlPanel in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aControlPanel.Resize (dw, dh)


ResizeTo (ControlPanel)
ResizeTo

Makes aControlPanel w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding aControlPanel to a dialog object. You cannot use this request to resize aControlPanel in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aControlPanel.ResizeTo (w, h)


ReturnBox (ControlPanel)
ReturnBox

Returns the bounding box of aControlPanel. the box's coordinates are in the coordinate system of aControlPanel's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aControlPanel is contained within another control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aControlPanel is placed directly on aDialog (not contained within another control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aControlPanel.ReturnBox

Returns

Rect


Add (ControlPanel)
Add

Adds a control to aControlPanel at the location and dimension specified by aBox. The units of the box are in pixels relative to the upper-left corner of the control panel. For example:

  cp = someDialog.GetControlPanel
  lb = LabelButton.Make
  cp.Add(lb, Rect.Make(10@10, 100@100))

will add a label button to the dialog, positioned 10 pixels from the top and left sides of the dialog, with a size of 100 by 100 pixels. The added control will be drawn on top of any existing controls.

Syntax

aControlPanel.Add (aControl, aBox)


Empty (ControlPanel)
Empty

Removes all controls from aControlPanel. For example,

  someDialog.FindByName("aControlPanel1").Empty

will remove all controls under the control panel named aControlPanel1.

To remove all controls from a dialog, use:

  someDialog.GetControlPanel.Empty

Syntax

aControlPanel.Empty


FindByClass (ControlPanel)
FindByClass

Creates and returns a list of all controls inside aControlPanel that are of class aControlClass. This request looks inside nested control panels.

Syntax

aControlPanel.FindByClass (aControlClass)

Returns

List


FindByName (ControlPanel)
FindByName

Returns the control in aControlPanel named aControlName. Returns nil if no such control is found. Nested control panels are also searched.

Syntax

aControlPanel.FindByName (aControlName)

Returns

Control


GetSelected (ControlPanel)
GetSelected

Returns the radio button in aControlPanel that is currently selected or nil if there are no radio buttons or none is currently selected.

Syntax

aControlPanel.GetSelected

Returns

RadioButton


Insert (ControlPanel)
Insert

Inserts a control into aControlPanel at the location and dimension specified by aBox. The units of the box are in pixels relative to the upper-left corner of the control panel. For example:

  cp = someDialog.GetControlPanel
  lb = LabelButton.Make
  cp.Insert(lb, Rect.Make(10@10, 100@100))

will insert a label button into the dialog, positioned 10 pixels from the top and left sides of the dialog, with a size of 100 by 100 pixels. The inserted control will be drawn beneath any existing controls.

Syntax

aControlPanel.Insert (aControl, aBox)


Remove (ControlPanel)
Remove

Removes aControl from aControlPanel. aControl must be in aControlPanel.

Syntax

aControlPanel.Remove (aControl)


GetDialog (ControlPanel)
GetDialog

Gets the dialog containing aControlPanel.

Syntax

aControlPanel.GetDialog

Returns

Dialog


GetLabel (ControlPanel)
GetLabel

Gets the label appearing in the top left corner of aControlPanel.

Syntax

aControlPanel.GetLabel

Returns

String


HasFastener (ControlPanel)
HasFastener

Returns TRUE if aControlPanel currently has aFastener defined for it.

Syntax

aControlPanel.HasFastener (aFastener)

Returns

Boolean


HasVisibleBorder (ControlPanel)
HasVisibleBorder

Returns TRUE when aControlPanel is drawn with a black border around its perimeter.

Syntax

aControlPanel.HasVisibleBorder

Returns

Boolean


SetEnabled (ControlPanel)
SetEnabled

When enabled is TRUE, a control panel will be drawn with a solid font for the label, and any contained controls will be enabled if they were enabled before. When enabled is FALSE, the control panel and all the controls within the control panel will be disabled.

For example, to disable all the controls on a dialog, you could do this:

  aDialog.GetControlPanel.SetEnabled(false)

Syntax

aControlPanel.SetEnabled (enabled)


SetFastener (ControlPanel)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aControlPanel.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (ControlPanel)
SetFasteners

Defines positioning and resizing fasteners for aControlPanel. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aControlPanel's fasteners are not altered.

Syntax

aControlPanel.SetFasteners (aListOfFasteners)

Returns

Boolean


SetLabel (ControlPanel)
SetLabel

Sets the label to appear in the upper left hand corner of aControlPanel.

Syntax

aControlPanel.SetLabel (aLabel)


SetVisibleBorder (ControlPanel)
SetVisibleBorder

When isVisible is TRUE, aControlPanel will be drawn with a black line around its perimeter.

Syntax

aControlPanel.SetVisibleBorder (isVisible)


DialogEditor

 A Dialog Editor is a kind of Layout that 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".

A DialogEditor has a display area which represents two things: a representation of a dialog box, and a "working" area outside of the dialog box. To create a dialog using a DialogEditor, you work with the tools defined by the DialogEditor's DocGUI, and you manipulate the dialog box representation. The tools let you interactively create and manipulate graphic controls anywhere in the DialogEditor's display area. After a graphic control is created, you can manipulate its properties by selecting it, then either double-clicking or right-clicking to bring up its property window. You can use the mouse and drag the sides of the dialog frame to interactively define the width and height of the dialog. You can also explicitly specify the width and height of the dialog frame using the Size... option under the Dialog Editor menu.

You can use the working area to define controls which shouldn't be initially visible in the dialog box. All controls will be added to the dialog, but those in the working area will not be visible. You can use request like "MoveTo", and "SetVisible", to make them visible while the user is interacting with the dialog box.

After you have created and positioned graphic controls inside the DialogEditor's representation of the dialog, you press the DialogEditor's compile button. This operation creates a real dialog box from the representation of the dialog box and its controls inside the DialogEditor. The Compile step also makes sure that all controls have unique names.

You can then show this resulting dialog by pressing the "Run" button.

Inherits From

Layout

Required Extension

     Dialog Designer

Class Requests

Making DialogEditors

Make  :  DialogEditor

MakeWithGUI ( aGUIName ) :  DialogEditor

Instance Requests

Using DialogEditors

Compile

EditProperties  :  Boolean

IsCompiled  :  Boolean

NeedsCompile

ReturnDialogBox  :  Rect

SetDialogBox ( aRectangle )

Getting/Setting attributes of DialogEditors

GetDialog  :  Dialog

SetName ( aName )

__________

See also

Control
Dialog
GraphicControl


Make (DialogEditor)
Make
Example

Creates a new Dialog Editor and associates it with the DocGUI named "DialogEditor". It also creates a dialog object that is associated with the Dialog Editor.

Syntax

DialogEditor.Make

Returns

DialogEditor


MakeWithGUI (DialogEditor)
MakeWithGUI

Same as Make, but you can specify the GUI you want to be initially associated with the new Dialog Editor.

Syntax

DialogEditor.MakeWithGUI (aGUIName)

Returns

DialogEditor


Compile (DialogEditor)
Compile

Update aDialogEditor's associated dialog using the graphic controls currently in aDialogEditor. This request does not check for duplicate control names in a dialog. It is your responsibility to check for duplicate names before running this request in order to avoid them. See the system script "Dialog.Compile" for an example. This request has no effect when aDialogEditor is not open.

Syntax

aDialogEditor.Compile


EditProperties (DialogEditor)
EditProperties

Interactively edit the properties of aDialogEditor. For example, change the dialog name, or type in any comments that you may want to store to document the dialog.

Syntax

aDialogEditor.EditProperties

Returns

Boolean


IsCompiled (DialogEditor)
IsCompiled

Returns TRUE when the dialog associated with aDialogEditor reflects the most recent changes made to the dialog editor's contents.

Syntax

aDialogEditor.IsCompiled

Returns

Boolean


NeedsCompile (DialogEditor)
NeedsCompile

Tell aDialogEditor that a change has been made to its contents which requires its associated dialog to be recompiled.

Syntax

aDialogEditor.NeedsCompile


ReturnDialogBox (DialogEditor)
ReturnDialogBox

Returns a rectangle defining the location and the size of the dialog frame. The location (origin of the rectangle) represents the lower left hand corner of the dialog frame and the size represents the dimensions (x is width and y is height) of the compiled dialog associated with aDialogEditor. The units are in inches relative to the lower left hand corner of aDialogEditor's display area.

For example a rectangle with values (0,0) (3,1.5) will make a dialog frame with a width of 3 inches and a height of 1.5 inches. The lower left hand corner of the dialog frame will be positioned at the lower left hand corner of the dialog editor window.

Syntax

aDialogEditor.ReturnDialogBox

Returns

Rect


SetDialogBox (DialogEditor)
SetDialogBox

Sets the location and size of the dialog frame to be used the next time the dialog associated with aDialogEditor is re-compiled. The location is the lower left hand corner of the frame and the units of the rectangle are inches. For example,

    aDialogEditor.SetDialogBox(Rect.Make(0@0,3@1.5))

will make a dialog frame with a width of 3 inches and a height of 1.5 inches. The lower left hand corner of the dialog frame will be positioned at the lower left hand corner of the dialog editor window.

Syntax

aDialogEditor.SetDialogBox (aRectangle)


GetDialog (DialogEditor)
GetDialog

Returns the dialog associated with aDialogEditor.

Syntax

aDialogEditor.GetDialog

Returns

Dialog


SetName (DialogEditor)
SetName

Sets the name of aDialogEditor (and its associated dialog) to be aName.

Syntax

aDialogEditor.SetName (aName)


GraphicControl
Example

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

When you pan and zoom either a Layout page or a View's map display, graphic shapes stick to the page or map. That is, if you zoom in, the graphic shape gets larger. If you pan, the graphic shape moves. By default, graphic controls do not do this. They will always stay in exactly the same position relative to the document window, and will always stay the same size. Using the GraphicControlConstraintEnum, you can alter this default behavior. You can either specify that it should behave exactly like a graphic shape, or you can specify that its position should stick to the page or map, but that it should always stay the same size.

A control that is associated with a graphic control cannot appear anywhere else. In particular, a graphic control will not be printed, and, if its part of a view, will not show up in any view frames attached to that view.

A graphic control interprets mouse and keyboard events in one of two ways. You can either ask it to act like a graphic, or like a control. In the former case, mouse clicks on it will be interpreted the same way mouse clicks on graphic shapes are interpreted. Keyboard events are ignored. In the second case, mouse clicks will be sent directly to the control associated with the graphic control, and so will keyboard events. A graphic control in the first case is called editable. In the second case it is called not editable. When a graphic control isn't editable, it cannot be selected.

When you send requests such as SetBounds and Offset to a graphic control, you need to redraw it before the information is propagated to its associated ArcView control.

Inherits From

Graphic

Enumerations

GraphicControlConstraintEnum

Required Extension

     Dialog Designer

Class Requests

Making GraphicControls

Make ( aControl, aRect ) :  GraphicControl

Instance Requests

Displaying Dialog Boxes

Edit ( itsGraphicList ) :  Boolean

Drawing GraphicControls

Draw

DrawSel

Manipulating GraphicControls

Offset ( aPoint )

PixelOffset ( aPoint )

Project ( aProjection )

Select

UnProject ( aProjection )

Checking Capabilities of Graphic Controls

CanProject  :  Boolean

Getting/Setting Attributes of Graphic Controls

ConstrainBounds ( anExtent )

GetConstraint  :  GraphicControlConstraintEnum

GetControl  :  Control

HasControlFastener ( aFastener ) :  Boolean

IsEditable  :  Boolean

SetBounds ( aRect )

SetConstraint ( aGraphicControlConstraintEnum )

SetControlFastener ( aFastener, isOn ) :  Boolean

SetControlFasteners ( aListOfFasteners ) :  Boolean

SetDisplay ( aDisplay )

SetEditable ( isEditable )

SetVisible ( isVisible )

Generic object management

SetName ( aName )

__________

See also

Display
GraphicList
Template
View
Layout


Make (GraphicControl)
Make
Example

Creates a new GraphicControl associated with aControl at location and with dimensions specified by aRect. Before you can draw this graphic control, you must either add it to a graphic list, or send it the SetDisplay request.

Syntax

GraphicControl.Make (aControl, aRect)

Returns

GraphicControl


Edit (GraphicControl)
Edit

Displays a property window for aGraphicControl. aGraphicControl must belong to aGraphicList.

The property sheet is modeless. If it was already visible, its contents will be replaced with aGraphicControls graphic list and aGraphicControl will become the selected control in the property sheet.

Syntax

aGraphicControl.Edit (itsGraphicList)

Returns

Boolean


Draw (GraphicControl)
Draw

Draws aGraphicControl on its Display.

Syntax

aGraphicControl.Draw


DrawSel (GraphicControl)
DrawSel

Draws the selection handles for aGraphicControl on its display.

Syntax

aGraphicControl.DrawSel


Offset (GraphicControl)
Offset
Example

Offsets aGraphicControl by the number of inches (or map units on a view) contained in aPoint. The associated control is moved accordingly when aGraphicControl is redrawn.

Syntax

aGraphicControl.Offset (aPoint)


PixelOffset (GraphicControl)
PixelOffset
Example

Offsets aGraphicControl by the number of pixels contained in the x and y coordinates of aPoint. The associated control is moved accordingly when aGraphicControl is redrawn.

Syntax

aGraphicControl.PixelOffset (aPoint)


Project (GraphicControl)
Project

Updates the bounding box of aGraphicControl to take into account the new map coordinate system. It will not appear to change size or position on screen.

Syntax

aGraphicControl.Project (aProjection)


Select (GraphicControl)
Select

Selects aGraphicControl only if it is editable. Has no effect otherwise.

Syntax

aGraphicControl.Select


UnProject (GraphicControl)
UnProject

Updates the bounding box of aGraphicControl to take into account the new map coordinate system. It will not appear to change size or position on screen.

Syntax

aGraphicControl.UnProject (aProjection)


CanProject (GraphicControl)
CanProject

Always returns TRUE. aGraphicControl is "projectable" in the sense that it can be used in a view that has a projection. Changing the projection of that view will not cause aGraphicControl to move or change size, apparently, on the screen. Its bounding box will change position and size, though, since it is expressed in map space. Its position relative to features in the view's themes will also probably change.

Syntax

aGraphicControl.CanProject

Returns

Boolean


ConstrainBounds (GraphicControl)
ConstrainBounds

Resizes the bounds of aGraphicControl but maintains the aspect ratio in anExtent.

Syntax

aGraphicControl.ConstrainBounds (anExtent)


GetConstraint (GraphicControl)
GetConstraint

Returns the element of the GraphicControlConstraintEnum which describes the current behavior for aGraphicControl when the scale and location of its owning MapDisplay or PageDisplay are altered.

Syntax

aGraphicControl.GetConstraint

Returns

GraphicControlConstraintEnum


GetControl (GraphicControl)
GetControl

Returns the Control associated with aGraphicControl.

Syntax

aGraphicControl.GetControl

Returns

Control


HasControlFastener (GraphicControl)
HasControlFastener

 Returns TRUE when aConstraintEnum is enabled for the control associated with aGraphicControl

Syntax

aGraphicControl.HasControlFastener (aFastener)

Returns

Boolean


IsEditable (GraphicControl)
IsEditable

Returns whether or not aGraphicControl is acting like a graphic shape (TRUE) or like a control (FALSE).

Syntax

aGraphicControl.IsEditable

Returns

Boolean


SetBounds (GraphicControl)
SetBounds
Example

Sets the bounds of aGraphicControl to aRect. The associated control is resized accordingly when aGraphicControl is redrawn.

Syntax

aGraphicControl.SetBounds (aRect)


SetConstraint (GraphicControl)
SetConstraint

Defines the way in which aGraphicControl adapts to changes in the scale and location of the MapDisplay or PageDisplay in which it is contained.

Syntax

aGraphicControl.SetConstraint (aGraphicControlConstraintEnum)


SetControlFastener (GraphicControl)
SetControlFastener

 Turns on or off the specified control fastener for the control associated with aGraphicControl. TRUE is returned if the result is a legal fastener configuration for the control, otherwise FALSE is returned and the fasteners are not changed.

Syntax

aGraphicControl.SetControlFastener (aFastener, isOn)

Returns

Boolean


SetControlFasteners (GraphicControl)
SetControlFasteners

 Replaces the list of fasteners associated with aGraphicControl's with aListOfFasteners.

Syntax

aGraphicControl.SetControlFasteners (aListOfFasteners)

Returns

Boolean


SetDisplay (GraphicControl)
SetDisplay

Sets the display that aGraphicControl will draw to. This happens automatically when aGraphicControl is added to the GraphicList of some view or layout document.

Syntax

aGraphicControl.SetDisplay (aDisplay)


SetEditable (GraphicControl)
SetEditable

When isEditable is TRUE, aGraphicControl behaves like a graphic shape. When isEditable is FALSE, aGraphicControl passes mouse and keyboard events to its control for interpretation. When aGraphicControl is not editable, it cannot be selected.

Syntax

aGraphicControl.SetEditable (isEditable)


SetVisible (GraphicControl)
SetVisible

Controls whether or not aGraphicControl is visible.

Syntax

aGraphicControl.SetVisible (isVisible)


SetName (GraphicControl)
SetName

Sets the name of aGraphicControl and its associated Control to aName.

Syntax

aGraphicControl.SetName (aName)


GraphicControlConstraintEnum

 By default, graphic controls do not pan or zoom as the map or page display containing it pans or zooms.

You have several levels of control over this default behavior. You can tell the control that its position should stay in map space, but not its size. This would be useful if you would like to locate, say, an information button next to a feature, but want that button to stay the same size regardless of the current map scale. Or, you can have the graphic control adjust its bounding box as well as its position when the display scale is changed.

#GRAPHICCONTROL_CONSTRAINT_NONE

The GraphicControl's size and position remain constant in screen space. Panning or zooming the display has no affect on the GraphicControl.

#GRAPHICCONTROL_CONSTRAINT_POSITION

The GraphicControl retains its location in map space, but its size never changes.

#GRAPHICCONTROL_CONSTRAINT_ALL

The GraphicControl's size and position remain constant in map space. Zooming and panning a Display containing a GraphicControl will cause it to change size and position on the screen.


PropWin
Example

 A PropWin is a modeless window that displays properties for controls embedded within graphic controls. Only one PropWin exists. Obtain a reference to 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.

The PropWin has several parts. At the top, it has a drop down combo box of control names. Pick a name form this list in order to edit the properties of the associated control. The name of the dialog also appears in this list, so you can edit properties of the dialog (such as its title, whether it can be resized, etc). as well.

Below the control list, is a text edit line that lets you change the name of the selected control or dialog.

Towards the bottom is a list of all properties for the selected control or dialog. Double click on a row in order to change the property.

At the bottom is a combo-box that lets you determine how the graphic control adjust itself when its display is panned or zooming. This option is only available when you are editing a graphic control located inside a view or layout document.

Inherits From

Window

Required Extension

     Dialog Designer

Class Requests

Getting the PropWin

The  :  PropWin

Instance Requests

Manipulating a PropWin

Activate

Close

Deactivate

Delete

Open ( aGraphicList, aGraphicControl )

OpenOnDialogEditor ( aDialogEditor )

SetSelectedControl ( aGraphicControl )

Update ( aGraphicList, aSelectedGraphicControl )

__________

See also

GraphicControl
Control


The (PropWin)
The

Create, if necessary, the PropWin and return it.

Syntax

PropWin.The

Returns

PropWin


Activate (PropWin)
Activate

If aPropWin is visible, refresh it with the contents of the active document's graphic list. Do nothing if aPropWin is not visible or the active document is not a View, Layout, or Dialog Editor.

Syntax

aPropWin.Activate


Close (PropWin)
Close

Detach aPropWin from any graphic list the it may know about and close it.

Syntax

aPropWin.Close


Deactivate (PropWin)
Deactivate

Detach aPropWin from any graphic list that it may know about. Do nothing if aPropWin is not open.

Syntax

aPropWin.Deactivate


Delete (PropWin)
Delete

Makes aPropWin eligible for garbage collection. The class request 'The' will subsequently return a new PropWin. This request is used by the dialog extension when it must get rid of the PropWin before unloading the dialog extension.

Syntax

aPropWin.Delete


Open (PropWin)
Open

Brings up the property window for aGraphicControl. aGraphicControl is a member of aGraphicList.

Syntax

aPropWin.Open (aGraphicList, aGraphicControl)


OpenOnDialogEditor (PropWin)
OpenOnDialogEditor

Opens aPropWin, loads it with the controls and dialog referenced by aDialogEditor, and selects the dialog.

Syntax

aPropWin.OpenOnDialogEditor (aDialogEditor)


SetSelectedControl (PropWin)
SetSelectedControl

Makes aGraphicControl the currently selected graphic in aPropWin. It must already be a member of the list of controls contained in aPropWin.

Syntax

aPropWin.SetSelectedControl (aGraphicControl)


Update (PropWin)
Update

 If aPropWin is visible, update its list of graphics to be aGraphicList and show the properties of aSelectedGraphicControl.

Syntax

aPropWin.Update (aGraphicList, aSelectedGraphicControl)


RadioButton

 A radio button is a control that cooperates with other radio buttons to show the current value of a variable that has a small number of possible values. Each button has a label that names one possible value. The button in the on-state shows which value the variable currently has.

To use radio buttons, you create at least two of them (if you think you need one radio button, use a checkbox instead), then add them to a control panel. The control panel automatically makes sure that only one radio button is selected at a time. If you need multiple independant groups of radio buttons, you will need to add them to seperate control panels.

Attributes

Selected.TRUE when this button is selected, FALSE otherwise. When you select a button, all others in the same control panel become unselected.

Click.The name of a script to execute when the user clicks on the radio button. This script is not executed if the user clicks on the radio button when it is already selected.

Listeners.The list of controls that will have their update scripts executed whenever the request BroadcastUpdate is sent to the radio button.

Listening.When TRUE, the radio button will respond to an update event by executing its update event script, otherwise it will ignore the update event.

Box.The bounding box of the radio button. It is expressed in the pixel coordinate system, which has coordinates in screen pixels and an origin at the upper left hand corner of the control panel or dialog containing the radio button.

Fasteners.A list of enumeration elements from the enumeration ControlFastenerEnum. They describe how the radio button will adjust its size and position when its containing control panel changes its size and position.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making RadioButtons

Make  :  RadioButton

Instance Requests

Using RadioButtons

Click

Select

Update

Getting/Setting attributes of RadioButtons

GetClick  :  String

GetDialog  :  Dialog

GetLabel  :  String

HasFastener ( aFastener ) :  Boolean

HasScript ( aScriptName ) :  Boolean

IsSelected  :  Boolean

SetClick ( aScriptName )

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetLabel ( aLabel )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Listeners and Broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

ControlPanel


Make (RadioButton)
Make
Example

Creates a RadioButton object.

Syntax

RadioButton.Make

Returns

RadioButton


Click (RadioButton)
Click

 Executes the script attached to aRadioButton's Click event.

Syntax

aRadioButton.Click


Select (RadioButton)
Select

Selects aRadioButton. Its click script is not executed.

Syntax

aRadioButton.Select


Update (RadioButton)
Update

Executes aRadioButton's update script if it is listening to updates.

Syntax

aRadioButton.Update


GetClick (RadioButton)
GetClick

 Returns the name of the event script that is executed when a user clicks on aRadioButton.

Syntax

aRadioButton.GetClick

Returns

String


GetDialog (RadioButton)
GetDialog

Gets the dialog containing aRadioButton. You may only use this request after adding aRadioButton to a dialog.

Syntax

aRadioButton.GetDialog

Returns

Dialog


GetLabel (RadioButton)
GetLabel

Gets the label used by aRadioButton.

Syntax

aRadioButton.GetLabel

Returns

String


HasFastener (RadioButton)
HasFastener

Returns TRUE if aRadioButton currently has aFastener defined for it.

Syntax

aRadioButton.HasFastener (aFastener)

Returns

Boolean


HasScript (RadioButton)
HasScript

Returns TRUE when aRadioButton is associated with a script named aScriptName.

Syntax

aRadioButton.HasScript (aScriptName)

Returns

Boolean


IsSelected (RadioButton)
IsSelected

Returns TRUE when aRadioButton is the selected button in a control panel.

Syntax

aRadioButton.IsSelected

Returns

Boolean


SetClick (RadioButton)
SetClick

 Sets aScriptName to execute when the user clicks on the radio button interactively. This script will not execute when you select aRadioButton using the Select request.

Syntax

aRadioButton.SetClick (aScriptName)


SetFastener (RadioButton)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aRadioButton.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (RadioButton)
SetFasteners

Defines positioning and resizing fasteners for aRadioButton. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aRadioButton's fasteners are not altered.

Syntax

aRadioButton.SetFasteners (aListOfFasteners)

Returns

Boolean


SetLabel (RadioButton)
SetLabel

Sets aLabel to be the label drawn next to aRadioButton.

Syntax

aRadioButton.SetLabel (aLabel)


Move (RadioButton)
Move

Move aRadioButton dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aRadioButton to another control panel. If aRadioButton is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding a radio button to a a dialog object. You can't use this request to move a radio button on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aRadioButton.Move (dx, dy)


MoveTo (RadioButton)
MoveTo

Move aRadioButton to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aRadioButton to another control panel. If aRadioButton is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aRadioButton is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aRadioButton is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding a radio button to a a dialog object. You can't use this request to move a radio button on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aRadioButton.MoveTo (x, y)


Resize (RadioButton)
Resize

Make aRadioButton dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding a radio button to a a dialog object. You can't use this request to resize a radio button on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aRadioButton.Resize (dw, dh)


ResizeTo (RadioButton)
ResizeTo

Makes aRadioButton w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding a radio button to a a dialog object. You can't use this request to resize a radio button on a View, Layout, or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aRadioButton.ResizeTo (w, h)


ReturnBox (RadioButton)
ReturnBox

Returns a copy of the bounding box of aRadioButton. the box's coordinates are in the coordinate system of aRadioButton's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aRadioButton is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aRadioButton is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aRadioButton.ReturnBox

Returns

Rect


AddListener (RadioButton)
AddListener

Adds aControl to aRadioButton's list of listeners. aControl will be sent an update when the BroadcastUpdate request is sent to aRadioButton.

Syntax

aRadioButton.AddListener (aControl)


BroadcastUpdate (RadioButton)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aRadioButton.

Syntax

aRadioButton.BroadcastUpdate


ChangedListeners (RadioButton)
ChangedListeners

Informs aRadioButton that you have modified its list of listeners. Send this request after manipulating the list obtained from the GetListeners request. You do not need to send this request after using the SetListeners request.

Syntax

aRadioButton.ChangedListeners


GetBroadcaster (RadioButton)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aRadioButton's update script. This request will return nil if the update event aRadioButton is responding was not initiated via the request BroadcastUpdate sent to some other object.

Syntax

aRadioButton.GetBroadcaster

Returns

Obj


GetListeners (RadioButton)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aRadioButton. You may modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aRadioButton.

Syntax

aRadioButton.GetListeners

Returns

List


IsListening (RadioButton)
IsListening

Returns TRUE if aRadioButton will execute its update script in response to an update event.

Syntax

aRadioButton.IsListening

Returns

Boolean


RemoveListener (RadioButton)
RemoveListener

Removes aControl from aRadioButton's list of listeners. aControl will no longer receive update events when aRadioButton is sent the BroadcastUpdate request.

Syntax

aRadioButton.RemoveListener (aControl)


SetListeners (RadioButton)
SetListeners
Example

Sets the listeners that will be sent the update event when aRadioButton is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

aRadioButton.SetListeners (aListOfListeners)


StartListening (RadioButton)
StartListening

aRadioButton will respond to any future update events by executing its update script.

Syntax

aRadioButton.StartListening


StopListening (RadioButton)
StopListening

aRadioButton will not execute its update script in response to an update event.

Syntax

aRadioButton.StopListening


TextBox

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

Attributes

Label.The label for the textbox. It appears above the textbox.

Text.The current contents of the text box.

Size.If Size is zero, then the text box can hold an unlimited amount of text. If it is greater than zero, then the text box can hold no more that that many characters.

VerticalScroll. A boolean property. When true, the text box has a vertical scrollbar. When its false, the user can still access text above or beneath the visible box by clicking and dragging or moving the cursor with the arrow keys.

HorizontalScroll. A boolean property. When true, the text box has a horizontal scrollbar. When false, the user can still scroll using techniques described above.

ReadOnly.TRUE if the contents of the text box cannot be edited interactively. The contents can still be changed using the request SetText.

Changed.The name of a script that will be executed whenever the content of a text box is changed. Every keystroke, cut, and paste operation generates a changed event.

Empty.The name of a script that will be executed whenever the text box becomes empty after being non-empty, or becomes non-empty after being empty. For example, if the text box has one character in it, pressing backspace once will generate an empty event, but pressing backspace again won't.

Use this event to disable controls that shouldn't be used if no information is in the text box.

Click.The name of a script that will execute whenever the user click (and possibly drags) the mouse inside of the text box. Use this request to inform objects about where the cursor is inside the text box, and what text is selected.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making TextBoxes

Make  :  TextBox

Instance Requests

Using TextBoxes

Changed

Click

Empty

Focus

Update

Getting/Setting attributes of TextBoxes

GetClick  :  String

GetDialog  :  Dialog

GetLabel  :  String

GetNextControl  :  Control

GetPosition  :  Number

GetSize  :  Number

GetText  :  String

HasFastener ( aFastener ) :  Boolean

HasHorizontalScroll  :  Boolean

HasVerticalScroll  :  Boolean

InsertText ( newText )

IsEmpty  :  Boolean

IsReadOnly  :  Boolean

SetClick ( aScriptName )

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetHorizontalScroll ( showHorizontalScrollBar )

SetLabel ( aLabelString )

SetNextControl ( aControl )

SetPosition ( anOffset )

SetReadOnly ( readOnly )

SetSize ( numberOfCharacters )

SetText ( newText )

SetVerticalScroll ( showVerticalScrollBar )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Getting/setting event scripts

GetChanged  :  String

GetEmpty  :  String

HasScript ( aScriptName ) :  Boolean

SetChanged ( aScriptName )

SetEmpty ( aScriptName )

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

TextLine
TextLabel
Dialog


Make (TextBox)
Make
Example

Create a new textbox object with the following default properties:

  Disable property is set to false
  Horizontal scroll bar is set to false
  Invisible property is set to false
  ReadOnly property is set to false
  Size property is set to 0 (accepts unlimited text)
  Vertical scroll bar is set to true

Syntax

TextBox.Make

Returns

TextBox


Changed (TextBox)
Changed

Executes the script associated with aTextBox's changed event. This event is sent to aTextBox every time its contents are altered interactively (this includes every keystroke, cut, and paste operations). Note that changing aTextBox's text through Avenue using SetText and Empty scripts will not trigger the Changed event script.

Syntax

aTextBox.Changed


Click (TextBox)
Click

Executes the script associated with aTextBox's click event. This event is sent immediately after the user has clicked and possibly dragged the mouse over the contents of aTextBox. Use this request to inform objects about where the cursor is inside aTextBox, and what text is selected.

Syntax

aTextBox.Click


Empty (TextBox)
Empty

Executes the script associated with aTextBox's Empty event. This event is sent every time aTextBox changed from an empty to a non-empty state, or vice versa. Use SetText("") if you want to clear the contents of aTextBox without sending this event.

Syntax

aTextBox.Empty


Focus (TextBox)
Focus

Assigns keyboard focus to aTextBox. This request has no effect between the time aTextBox is loaded from a project and the time its containing dialog or document is made visible.

Syntax

aTextBox.Focus


Update (TextBox)
Update

Executes aTextBox's update script if it is listening to updates.

Syntax

aTextBox.Update


GetClick (TextBox)
GetClick

Returns the name of the event script that is executed when a user clicks the mouse inside aTextBox.

Syntax

aTextBox.GetClick

Returns

String


GetDialog (TextBox)
GetDialog

Returns the dialog containing aTextBox. You may only use this request after adding aTextBox to a dialog.

Syntax

aTextBox.GetDialog

Returns

Dialog


GetLabel (TextBox)
GetLabel

Returns aTextBox's label string.

Syntax

aTextBox.GetLabel

Returns

String


GetNextControl (TextBox)
GetNextControl

Gets the control the will receive keyboard focus when the user presses the TAB key while aTextBox has the keyboard focus.

Syntax

aTextBox.GetNextControl

Returns

Control


GetPosition (TextBox)
GetPosition

Returns the number of characters between the current cursor position and the beginning of the document. For example, if aTextBox contains these lines of text:

  abcd
  efgh
  ij

and the user positions the cursor between the 'g' and the 'h', then GetPosition will return the number 7. You may only use this request after adding aTextBox to a dialog.

Syntax

aTextBox.GetPosition

Returns

Number


GetSize (TextBox)
GetSize

Returns the maximum number of characters that aTextBox can hold. If the result is zero, than aTextBox can hold an unlimited number of characters.

Syntax

aTextBox.GetSize

Returns

Number


GetText (TextBox)
GetText

Gets the contents of aTextBox. You can use GetText and SetText on editable or read-only text boxes.

Syntax

aTextBox.GetText

Returns

String


HasFastener (TextBox)
HasFastener

Returns TRUE if aTextBox currently has aFastener defined for it.

Syntax

aTextBox.HasFastener (aFastener)

Returns

Boolean


HasHorizontalScroll (TextBox)
HasHorizontalScroll

Returns TRUE if aTextBox is drawn with a horizontal scroll bar.

Syntax

aTextBox.HasHorizontalScroll

Returns

Boolean


HasVerticalScroll (TextBox)
HasVerticalScroll

Returns TRUE if aTextBox is drawn with a vertical scroll bar.

Syntax

aTextBox.HasVerticalScroll

Returns

Boolean


InsertText (TextBox)
InsertText

Inserts newText at the current cursor position in aTextBox. If some text in aTextBox is selected, that text will be replaced by newText. This request will not trigger Changed event script.

Syntax

aTextBox.InsertText (newText)


IsEmpty (TextBox)
IsEmpty

Returns TRUE when aTextBox has no data in it, FALSE otherwise.

Syntax

aTextBox.IsEmpty

Returns

Boolean


IsReadOnly (TextBox)
IsReadOnly

Returns TRUE if the user cannot interactively modify the contents of aTextBox.

Syntax

aTextBox.IsReadOnly

Returns

Boolean


SetClick (TextBox)
SetClick

Assigns the script named aScriptName to be executed when a user clicks the mouse inside aTextBox. For example, use this script to inform objects about where the cursor is inside aTextBox.

Syntax

aTextBox.SetClick (aScriptName)


SetFastener (TextBox)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aTextBox.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (TextBox)
SetFasteners

Defines positioning and resizing fasteners for aTextBox. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aTextBox's fasteners are not altered.

Syntax

aTextBox.SetFasteners (aListOfFasteners)

Returns

Boolean


SetHorizontalScroll (TextBox)
SetHorizontalScroll

If showHorizontalScrollBar is TRUE, then a horizontal scroll bar will be draw at the bottom of aTextBox. Otherwise, any existing vertical scroll bar will be removed. When there is a horizontal scroll bar, the user must explicitly hit the RETURN key in order to start a new line of text. When there is no horizontal scroll bar, a word will be moved to the next line if it can't be placed entirely on the current line.

Syntax

aTextBox.SetHorizontalScroll (showHorizontalScrollBar)


SetLabel (TextBox)
SetLabel

Sets aTextBox's label to be aLabelString.

Syntax

aTextBox.SetLabel (aLabelString)


SetNextControl (TextBox)
SetNextControl

Sets the control that will receive keyboard focus when the user presses the TAB key while aTextBox has the keyboard focus.

Syntax

aTextBox.SetNextControl (aControl)


SetPosition (TextBox)
SetPosition

Positions the cursor so that anOffset number of characters are between the cursor and the beginning of the document. When anOffset is greater than the number or characters in aTextBox, or is less than zero, the cursor moves to the position after the last character in aTextBox. You can only use this request after adding aTextBox to a dialog.

Syntax

aTextBox.SetPosition (anOffset)


SetReadOnly (TextBox)
SetReadOnly

If readOnly is TRUE, the user will not be able to interactively modify the contents of aTextBox. You can programmatically modify it using the request SetText.

Syntax

aTextBox.SetReadOnly (readOnly)


SetSize (TextBox)
SetSize

Sets the maximum number of characters that aTextBox can hold. If numberOfCharacters is zero, then aTextBox can hold an unlimited amount of text.

Syntax

aTextBox.SetSize (numberOfCharacters)


SetText (TextBox)
SetText

Changes aTextBox's contents to be newText. Use InsertText request to append new text to the current text. No event scripts are executed as a result of using this request.

The following example illustrates how to read the entire text file with only a few requests and show the contents of the text file in aTextBox:

   tf = TextFile.Make( "c:/temp/test.txt".AsFileName, #FILE_PERM_READ )
   source = tf.Read( tf.GetSize )
   tf.Close
   ' Assuming self being a dialog object, get the textbox control
   aTextBox = self.FindByName("aTextBox1")
   aTextBox.SetText( source )

Syntax

aTextBox.SetText (newText)


SetVerticalScroll (TextBox)
SetVerticalScroll

If showVerticalScrollBar is TRUE, then a vertical scroll bar will be drawn on the right side of aTextBox. Otherwise, any existing vertical scroll bar will be removed. Even when there is no vertical scroll bar, the user can access text by navigating with the up and down arrow keys, or by clicking and dragging the mouse in the direction the user wishes to scroll.

Syntax

aTextBox.SetVerticalScroll (showVerticalScrollBar)


Move (TextBox)
Move

Move aTextBox dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aTextBox to another control panel. If aTextBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aTextBox to a dialog object. You cannot use this request to move aTextBox in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextBox.Move (dx, dy)


MoveTo (TextBox)
MoveTo

Move aTextBox to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aTextBox to another control panel. If aTextBox is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aTextBox is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTextBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aTextBox to a dialog object. You cannot use this request to move aTextBox in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextBox.MoveTo (x, y)


Resize (TextBox)
Resize

Make aTextBox dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aTextBox to a dialog object. You cannot use this request to resize aTextBox in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextBox.Resize (dw, dh)


ResizeTo (TextBox)
ResizeTo

Makes aTextBox w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding aTextBox to a dialog object. You cannot use this request to resize aTextBox in a View, Layout or a Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextBox.ResizeTo (w, h)


ReturnBox (TextBox)
ReturnBox

Returns a copy of the bounding box of aTextBox. the box's coordinates are in the coordinate system of aTextBox's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aTextBox is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTextBox is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aTextBox.ReturnBox

Returns

Rect


GetChanged (TextBox)
GetChanged

Gets the name of the script that will be executed whenever the contents of aTextBox are changed interactively.

Syntax

aTextBox.GetChanged

Returns

String


GetEmpty (TextBox)
GetEmpty

Gets the name of the script that will be executed whenever aTextBox transitions from being non-empty to empty, or vice-versa.

Syntax

aTextBox.GetEmpty

Returns

String


HasScript (TextBox)
HasScript

Returns TRUE if one of aTextBox's event scripts is named aScriptName, FALSE otherwise.

Syntax

aTextBox.HasScript (aScriptName)

Returns

Boolean


SetChanged (TextBox)
SetChanged

Sets the script to be executed whenever the contents of aTextBox are altered interactively (this includes every keystroke, cut, and paste operations). Note that changing aTextBox's text through Avenue using SetText and Empty requests will not trigger the Changed event script.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aTextBox.SetChanged (aScriptName)


SetEmpty (TextBox)
SetEmpty

Sets the script to be executed whenever aTextBox transitions from non-empty to empty, or vice-versa.

Note: Don't use the Exit statement in scripts associated with a dialog.

Syntax

aTextBox.SetEmpty (aScriptName)


AddListener (TextBox)
AddListener

Adds aControl to aTextBox's list of listeners. aControl will then be sent an update event whenever the BroadcastUpdate request is sent to aTextBox. You do not need to send the ChangedListeners request after using this request. If aControl is already in aTextBox's listener list, it will not be added again.

Syntax

aTextBox.AddListener (aControl)


BroadcastUpdate (TextBox)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aTextBox.

Syntax

aTextBox.BroadcastUpdate


ChangedListeners (TextBox)
ChangedListeners

Tells aTextBox that its list of broadcasters has been changed. Send this request after modifying the list returned by GetListeners. You do not need to use this request after using the SetListeners request.

Syntax

aTextBox.ChangedListeners


GetBroadcaster (TextBox)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aTextBox's update script. This request will return nil if the update event aTextBox is responding was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aTextBox.GetBroadcaster

Returns

Obj


GetListeners (TextBox)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aTextBox. You are free to modify this list in any way, provided that it only contains controls. After modifying this list, send the request ChangedListeners to aTextBox.

Syntax

aTextBox.GetListeners

Returns

List


IsListening (TextBox)
IsListening

Returns TRUE if aTextBox will execute its update script in response to an update event.

Syntax

aTextBox.IsListening

Returns

Boolean


RemoveListener (TextBox)
RemoveListener

Removes aControl from aTextBox's list of listeners. aControl will no longer receive update events triggered by aTextBox. You do not need to send the ChangedListeners request after using this request. Nothing will happen if aControl is not in aTextBox's list of listeners.

Syntax

aTextBox.RemoveListener (aControl)


SetListeners (TextBox)
SetListeners
Example

Sets the listeners that will be sent the update event when aTextBox is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

aTextBox.SetListeners (aListOfListeners)


StartListening (TextBox)
StartListening

aTextBox will respond to any future update events by executing its update script.

Syntax

aTextBox.StartListening


StopListening (TextBox)
StopListening

aTextBox will not execute its update script in response to an update event.

Syntax

aTextBox.StopListening


TextLabel

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

Label.The group of words drawn in the dialog.

Listeners.The list of controls that will have their update scripts executed whenever the request BroadcastUpdate is sent to the text label.

Listening.When TRUE, the text label will respond to an update event by executing its update event script, otherwise it will ignore the update event.

Box.The bounding box of the text label. It is expressed in the pixel coordinate system, which has coordinates in screen pixels and an origin at the upper left hand corner of the control panel or dialog containing the text label.

Fasteners.A list of enumeration elements from the enumeration ControlFastenerEnum. They describe how the text label will adjust its size and position when its containing control panel changes its size and position.

Inherits From

Control

Required Extension

     Dialog Designer

Class Requests

Making TextLabels

Make  :  TextLabel

Instance Requests

Using TextLabels

Update

Getting/Setting attributes of TextLabels

GetDialog  :  Dialog

GetLabel  :  String

HasFastener ( aFastener ) :  Boolean

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetLabel ( aLabelString )

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

__________

See also

TextBox
TextLine
Dialog


Make (TextLabel)
Make
Example

Create a new text label object.

Syntax

TextLabel.Make

Returns

TextLabel


Update (TextLabel)
Update

Executes aTextLabel's update script if it is listening to updates.

Syntax

aTextLabel.Update


GetDialog (TextLabel)
GetDialog

Returns the dialog containing aTextLabel. You may only use this request after adding aTextLabel to a dialog.

Syntax

aTextLabel.GetDialog

Returns

Dialog


GetLabel (TextLabel)
GetLabel

Gets the group of words that are drawn inside aTextLabel's bounding box.

Syntax

aTextLabel.GetLabel

Returns

String


HasFastener (TextLabel)
HasFastener

Returns TRUE if aTextLabel currently has aFastener defined for it.

Syntax

aTextLabel.HasFastener (aFastener)

Returns

Boolean


SetFastener (TextLabel)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aTextLabel.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (TextLabel)
SetFasteners

Defines positioning and resizing fasteners for aTextLabel. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aTextLabel's fasteners are not altered.

Syntax

aTextLabel.SetFasteners (aListOfFasteners)

Returns

Boolean


SetLabel (TextLabel)
SetLabel

Sets aLabelString to be the group of words that are drawn inside aTextLabel's bounding box. You may use Avenue's newline object to define a multi-line string. For example:

  aTextLabel.SetLabel("This is line1"+NL+"This is line2")

will show 2 lines of text in the dialog box. You may have to adjust the bounding box handles to show the entire label.

Syntax

aTextLabel.SetLabel (aLabelString)


AddListener (TextLabel)
AddListener

Adds aControl to aTextLabel's list of listeners. aControl will be sent an update event whenever aTextLabel is sent the BroadcastUpdate request. You do not need to use the ChangedListeners request after using this request.

Syntax

aTextLabel.AddListener (aControl)


BroadcastUpdate (TextLabel)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aTextLabel.

Syntax

aTextLabel.BroadcastUpdate


ChangedListeners (TextLabel)
ChangedListeners

Notifies aTextLabel that its list of listeners has been altered. You do not need to send this request after using AddListener, RemoveListener, or SetListeners.

Syntax

aTextLabel.ChangedListeners


GetBroadcaster (TextLabel)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aTextLabel's update script. This request will return nil if the update event aTextLabel is responding was not initiated via the request BroadcastUpdate sent to some other object.

Syntax

aTextLabel.GetBroadcaster

Returns

Obj


GetListeners (TextLabel)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aTextLabel. You are free to modify this list in any way, provided that it only contains controls.

Syntax

aTextLabel.GetListeners

Returns

List


IsListening (TextLabel)
IsListening

Returns TRUE if aTextLabel will execute its update script in response to an update event.

Syntax

aTextLabel.IsListening

Returns

Boolean


RemoveListener (TextLabel)
RemoveListener

Removes aControl from aTextLabel's list of listeners. You do not need to use the ChangedListeners request after using this request.

Syntax

aTextLabel.RemoveListener (aControl)


SetListeners (TextLabel)
SetListeners
Example

Sets the listeners that will be sent the update event when aTextLabel is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

aTextLabel.SetListeners (aListOfListeners)


StartListening (TextLabel)
StartListening

aTextLabel will respond to any future update events by executing its update script.

Syntax

aTextLabel.StartListening


StopListening (TextLabel)
StopListening

aTextLabel will not execute its update script in response to an update event.

Syntax

aTextLabel.StopListening


Move (TextLabel)
Move

Move aTextLabel dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aTextLabel to another control panel. If aTextLabel is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aTextLabel to a dialog object. You cannot use this request to move aTextLabel in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLabel.Move (dx, dy)


MoveTo (TextLabel)
MoveTo

Move aTextLabel to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aTextLabel to another control panel. If aTextLabel is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aTextLabel is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTextLabel is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aTextLabel to a dialog object. You cannot use this request to move aTextLabel in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLabel.MoveTo (x, y)


Resize (TextLabel)
Resize

Make aTextLabel dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aTextLabel to a dialog object. You cannot use this request to resize aTextLabel in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLabel.Resize (dw, dh)


ResizeTo (TextLabel)
ResizeTo

Makes aTextLabel w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding aTextLabel to a dialog object. You cannot use this request to resize aTextLabel in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLabel.ResizeTo (w, h)


ReturnBox (TextLabel)
ReturnBox

Returns a copy of the bounding box of aTextLabel. The box's coordinates are in the coordinate system of aTextLabel's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aTextLabel is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTextLabel is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aTextLabel.ReturnBox

Returns

Rect


TextLine

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

Label.The label for the text line. It appears to the left of the text line's content area.

LabelSize.The width in pixels of the label. If you set LabelSize to 0 via the request SetLabelSize(0), the actual value of the property will be calculated from the length of the current label.

Text.The current contents of the text line.

TextType.An element from the enumeration TextLineTypeEnum. A text line can hold either alpha-numeric characters, strictly numeric characters, or strictly numeric characters and one radix character (the '.' in English writing systems). This enumeration specifies the kind of data that the text line should hold. If a text line contains data, and its TextType is subsequently changed, the text line will be emptied if the data is in conflict with the new TextType.

Size.If Size is zero, then the text line can hold an unlimited amount of text. If it is greater than zero, then the text line can hold at most that many characters.

NextControl.The control that will receive keyboard focus when the user presses the TAB key.

ReadOnly.TRUE when the text line cannot be edited interactively.

HiddenText.TRUE when the text can be edited but not viewed. Each character is represented visually with an '*'.

Apply.The name of a script that will be executed when the user hits the RETURN key while the text line has the keyboard focus, and if the dialog containing the control does not have a default button.

Typically, you use a text line to collect information that will be acted upon by other objects. In this case, it is inappropriate to have a script attached to the Apply event. For example, you should not use the Apply event when the text line is in a modal dialog. You might use the Apply event if the text line is in a modeless dialog, and you want something to happen immediately after the RETURN key is pressed.

FocusLost.The name of a script that will be executed when the textline control loses keyboard focus. You can use this event to prevent the user from leaving the textline if the current value of it is not acceptable. This kind of behavior can be irritating for users, though, so use it sparingly.

Changed.The name of a script that will be executed every time the content of a text line is interactively altered. Thus every keystroke, cut, and paste operation generates a changed event.

Empty.The name of a script that will be executed every time a non-empty text line becomes empty, or an empty text line becomes non-empty. Thus, pressing the backspace key twice, when the text line contains two characters, will generate one empty event (after the second backspace occurs).

Attach a script to this event when you need to change the state of other controls when a text line is empty. For example, if you have a dialog containing and "Apply" button and a "Query" text line, you might want to disable the "Apply" button if the text line is empty. Use the request IsEmpty to determine why the empty event is being sent.

Inherits From

Control

Enumerations

TextLineTypeEnum

Required Extension

     Dialog Designer

Class Requests

Making TextLines

Make  :  TextLine

Instance Requests

Using Textlines

Apply

Changed

Click

Empty

Focus

FocusLost

Update

Getting/Setting attributes of TextLines

GetClick  :  String

GetDialog  :  Dialog

GetFocusLost  :  String

GetLabel  :  String

GetLabelSize  :  Number

GetNextControl  :  Control

GetPosition  :  Number

GetSize  :  Number

GetText  :  String

GetTextType  :  TextLineTypeEnum

HasFastener ( aFastener ) :  Boolean

HasHiddenText  :  Boolean

IsEmpty  :  Boolean

IsReadOnly  :  Boolean

SetClick ( aScriptName )

SetFastener ( aFastener, onOrOff ) :  Boolean

SetFasteners ( aListOfFasteners ) :  Boolean

SetFocusLost ( aScriptName )

SetHiddenText ( isHidden )

SetLabel ( aLabelString )

SetLabelSize ( aLabelSize )

SetNextControl ( aControl )

SetPosition ( anOffset )

SetReadOnly ( readOnly )

SetSize ( numberOfCharacters )

SetText ( newText )

SetTextType ( aTextTypeEnum )

Moving/Repositioning

Move ( dx, dy )

MoveTo ( x, y )

Resize ( dw, dh )

ResizeTo ( w, h )

ReturnBox  :  Rect

Getting/setting event scripts

GetApply  :  String

GetChanged  :  String

GetEmpty  :  String

HasScript ( aScriptName ) :  Boolean

SetApply ( aScriptName )

SetChanged ( aScriptName )

SetEmpty ( aScriptName )

Listeners and broadcasters

AddListener ( aControl )

BroadcastUpdate

ChangedListeners

GetBroadcaster  :  Obj

GetListeners  :  List

IsListening  :  Boolean

RemoveListener ( aControl )

SetListeners ( aListOfListeners )

StartListening

StopListening

__________

See also

TextBox
TextLabel
Dialog


Make (TextLine)
Make
Example

Create a new textline object with the following default properties:

  Disable property is set to false
  HiddenText property is set to false
  Invisible property is set to false
  LabelSize property is set to 0
  ReadOnly property is set to false
  Size property is set to 0
  TextType enumeration is set to TEXTLINE_TYPE_ALL

Syntax

TextLine.Make

Returns

TextLine


Apply (TextLine)
Apply

Executes the script associated with aTextLine's apply event. An Apply event is generated when the user hits the RETURN key while aTextLine has the keyboard focus, and the textline isn't in a dialog that contains a default button. In the latter case, the RETURN is changed to a Click event on that default button.

Syntax

aTextLine.Apply


Changed (TextLine)
Changed

Executes the script associated with aTextLine's changed event. The Changed event is sent to aTextLine every time its contents are altered interactively. Note that changing aTextLine's text using SetText request will not execute Changed event script.

Syntax

aTextLine.Changed


Click (TextLine)
Click

Executes the script associated with the Click event. The Click event is sent immediately after the user has clicked and possibly dragged the mouse inside aTextLine.

Syntax

aTextLine.Click


Empty (TextLine)
Empty

Removes any text in aTextLine. This request will not execute any event scripts. The Empty and Changed event scripts are triggered only when the textline contents are altered interactively.

Syntax

aTextLine.Empty


Focus (TextLine)
Focus

Assigns keyboard focus to aTextLine. This request has no effect between the time aTextLine has been loaded from a project and the time its containing dialog or document has been made visible.

Syntax

aTextLine.Focus


FocusLost (TextLine)
FocusLost

Executes the script associated with the FocusLost event. The FocusLost event is sent immediately after the user has transferred focus from aTextline to some other control.

Syntax

aTextLine.FocusLost


Update (TextLine)
Update

Executes aTextLine's update script if it is listening to updates.

Syntax

aTextLine.Update


GetClick (TextLine)
GetClick

Gets the name of the script that will be executed when the Click event is sent to aTextLine.

Syntax

aTextLine.GetClick

Returns

String


GetDialog (TextLine)
GetDialog

Returns the dialog containing aTextLine. You may only use this request when aTextLine is in a dialog.

Syntax

aTextLine.GetDialog

Returns

Dialog


GetFocusLost (TextLine)
GetFocusLost

Gets the name of the script that will be executed when the FocusLost event is sent to aTextLine.

Syntax

aTextLine.GetFocusLost

Returns

String


GetLabel (TextLine)
GetLabel

Gets aTextLine's label string.

Syntax

aTextLine.GetLabel

Returns

String


GetLabelSize (TextLine)
GetLabelSize

Gets the current width in pixels of the space reserved for aTextLine's label. If the result is 0, then aTextLine calculate the size based upon the length of its label.

Syntax

aTextLine.GetLabelSize

Returns

Number


GetNextControl (TextLine)
GetNextControl

Gets the control that will receive the keyboard focus after the user hits the TAB key while aTextLine has the keyboard focus.

Syntax

aTextLine.GetNextControl

Returns

Control


GetPosition (TextLine)
GetPosition

Gets the number of characters between the current cursor position and the beginning of aTextLine. You may only use this request after aTextLIne has been added to a dialog.

Syntax

aTextLine.GetPosition

Returns

Number


GetSize (TextLine)
GetSize

Returns the maximum number of characters that aTextLine can hold. If the result is zero, then aTextLine can hold an unlimited number of characters.

Syntax

aTextLine.GetSize

Returns

Number


GetText (TextLine)
GetText

Gets the contents of aTextLine.

Syntax

aTextLine.GetText

Returns

String


GetTextType (TextLine)
GetTextType

Returns the enumeration element describing the kinds of characters that can be entered into aTextLine.

Syntax

aTextLine.GetTextType

Returns

TextLineTypeEnum


HasFastener (TextLine)
HasFastener

Returns TRUE if aTextLine currently has aFastener defined for it.

Syntax

aTextLine.HasFastener (aFastener)

Returns

Boolean


HasHiddenText (TextLine)
HasHiddenText

Returns TRUE when aTextLine always visually represents each character in its text with an '*'.

Syntax

aTextLine.HasHiddenText

Returns

Boolean


IsEmpty (TextLine)
IsEmpty

Returns TRUE when aTextLine has no data in it, FALSE otherwise.

Syntax

aTextLine.IsEmpty

Returns

Boolean


IsReadOnly (TextLine)
IsReadOnly

Returns FALSE if aTextLine can be edited interactively. Otherwise, it returns TRUE. When aTextLine is in read-only state, the information displayed in aTextLine control can still be modified in your scripts using the SetText request.

Syntax

aTextLine.IsReadOnly

Returns

Boolean


SetClick (TextLine)
SetClick

Sets the name of the script that will be executed when aTextLine receives the Click event.

Note: Don't use the Exit statement in scripts attached to a dialog.

Syntax

aTextLine.SetClick (aScriptName)


SetFastener (TextLine)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aTextLine.SetFastener (aFastener, onOrOff)

Returns

Boolean


SetFasteners (TextLine)
SetFasteners

Defines positioning and resizing fasteners for aTextLine. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aTextLine's fasteners are not altered.

Syntax

aTextLine.SetFasteners (aListOfFasteners)

Returns

Boolean


SetFocusLost (TextLine)
SetFocusLost

Sets the name of the script that will be executed when aTextLine receives the FocusLost event.

Note: Don't use the Exit statement in scripts attached to a dialog.

Syntax

aTextLine.SetFocusLost (aScriptName)


SetHiddenText (TextLine)
SetHiddenText

When isHidden is TRUE, aTextLine will always represent visually each character in its text with an '*'. For example, set this property when you want aTextLine to accept a password. The default value is FALSE.

Syntax

aTextLine.SetHiddenText (isHidden)


SetLabel (TextLine)
SetLabel

Sets aTextLine's label to be aLabelString. If you set LabelSize to 0 via the request SetLabelSize(0), the actual width of the label will be calculated from the length of aLabelString. The label is always left justified.

Syntax

aTextLine.SetLabel (aLabelString)


SetLabelSize (TextLine)
SetLabelSize

Sets the width in pixels of the space reserved for aTextLine's label. Use aLabelSize of 0 in order to have aTextLine calculate the size based upon the length of its label.

Typically, you'll set this property to a specific pixel value when you want to align the type-in area of several textline controls, making the type-in area the same width. The label will be truncated if the width you specify is not sufficient enough to display the entire text of the label.

Syntax

aTextLine.SetLabelSize (aLabelSize)


SetNextControl (TextLine)
SetNextControl

Sets the control that will receive the keyboard focus after the user hits the TAB key while aTextLine has the keyboard focus. aControl can be any ListBox, Slider, TextLine, TextBox, or ComboBox in the same dialog as aTextLine. For example, if you have a dialog with several textline controls to fill in, you may use this request to navigate the order in which the textline controls get focus when the user hits the TAB key. Setting the next control of a control to itself stops the TAB key from moving when that control is encountered.

Syntax

aTextLine.SetNextControl (aControl)


SetPosition (TextLine)
SetPosition

Moves the current cursor location so that anOffset number of characters are between the current cursor position and the beginning of aTextLine. When anOffset is greater than the number of characters in aTextLine, or is less than zero, the cursor moves to the position after the last character in a TextLine. You may only use this request after aTextLine has been added to a dialog.

Syntax

aTextLine.SetPosition (anOffset)


SetReadOnly (TextLine)
SetReadOnly

Prevents interactive editing of aTextLine when readOnly is TRUE. Allows them when readOnly is FALSE. When aTextLine is in read-only state, the information displayed in aTextLine control can still be modified in your scripts using the SetText request.

Syntax

aTextLine.SetReadOnly (readOnly)


SetSize (TextLine)
SetSize

Sets the maximum number of characters that aTextLine can hold. If numberOfCharacters is zero (the default value), then aTextLine can hold an unlimited amount of text.

Syntax

aTextLine.SetSize (numberOfCharacters)


SetText (TextLine)
SetText

Changes aTextLine's contents to be newText. This request can be used whether or not aTextLine is read-only.

Syntax

aTextLine.SetText (newText)


SetTextType (TextLine)
SetTextType

Defines the types of characters that aTextLine will accept: alpha-numeric characters, only those that make integers, or only those that make real numbers. The former will be left-justified, the latter two will be right-justified.

Syntax

aTextLine.SetTextType (aTextTypeEnum)


Move (TextLine)
Move

Move aTextLine dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aTextLine to another control panel. If aTextLine is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aTextLine to a dialog object. You cannot use this request to move aTextLine in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLine.Move (dx, dy)


MoveTo (TextLine)
MoveTo

Move aTextLine to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aTextLine to another control panel. If aTextLine is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aTextLine is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTextLine is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aTextLine to a dialog object. You cannot use this request to move aTextLine in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLine.MoveTo (x, y)


Resize (TextLine)
Resize

Make aTextLine dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aTextLine to a dialog object. You cannot use this request to resize aTextLine in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLine.Resize (dw, dh)


ResizeTo (TextLine)
ResizeTo

Makes aTextLine w pixels wide and h pixels tall. The position of its upper left hand corner of the bounding box is not changed.

You can only use this request after adding aTextLine to a dialog object. You cannot use this request to resize aTextLine in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTextLine.ResizeTo (w, h)


ReturnBox (TextLine)
ReturnBox

Returns a copy of the bounding box of aTextLine. the box's coordinates are in the coordinate system of aTextLine's containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aTextLine is contained within a control panel under a dialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTextLine is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aTextLine.ReturnBox

Returns

Rect


GetApply (TextLine)
GetApply

Gets the name of the script to be executed when the RETURN key is hit within aTextLine.

Syntax

aTextLine.GetApply

Returns

String


GetChanged (TextLine)
GetChanged

Gets the name of the script that will be executed whenever the contents of aTextLine are changed.

Syntax

aTextLine.GetChanged

Returns

String


GetEmpty (TextLine)
GetEmpty

Gets the name of the script that will be executed whenever aTextLine transitions from non-empty to empty, or vice-versa.

Syntax

aTextLine.GetEmpty

Returns

String


HasScript (TextLine)
HasScript

Returns TRUE if one of aTextLine's event scripts is named aScriptName, FALSE otherwise.

Syntax

aTextLine.HasScript (aScriptName)

Returns

Boolean


SetApply (TextLine)
SetApply

Sets the script to be executed when the RETURN key is hit within aTextLine.

Note: Don't use the Exit statement in scripts attached to a dialog.

Syntax

aTextLine.SetApply (aScriptName)


SetChanged (TextLine)
SetChanged

Sets the script to be executed whenever the contents of aTextLine are changed.

Note: Don't use the Exit statement in scripts attached to a dialog.

Syntax

aTextLine.SetChanged (aScriptName)


SetEmpty (TextLine)
SetEmpty

Sets the script to be executed whenever aTextLine transitions from non-empty to empty, or vice-versa.

Note: Don't use the Exit statement in scripts attached to a dialog.

Syntax

aTextLine.SetEmpty (aScriptName)


AddListener (TextLine)
AddListener

Adds aControl to aTextLine's list of listeners. If aControl is already in that list, nothing happens. You do not need to use the ChangedListeners request after using this request.

Syntax

aTextLine.AddListener (aControl)


BroadcastUpdate (TextLine)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aTextLine.

Syntax

aTextLine.BroadcastUpdate


ChangedListeners (TextLine)
ChangedListeners

Notifies aTextLine that its list of listeners has been changed. Use this request after manipulating the list obtained from the GetListeners request. You do not need to use this request after using SetListeners, AddListeners, or RemoveListener.

Syntax

aTextLine.ChangedListeners


GetBroadcaster (TextLine)
GetBroadcaster

Returns the control that initiated the current update event. Do not store the result of this request over multiple executions of aTextLine's update script. This request will return nil if the update event aTextLine is responding was not initiated via the request BroadcastUpdate sent to some other object.

Syntax

aTextLine.GetBroadcaster

Returns

Obj


GetListeners (TextLine)
GetListeners

Gets the list of controls that will be sent the update event when the BroadcastUpdate request is sent to aTextLine. You are free to modify this list in any way, provided that it only contains controls.

Syntax

aTextLine.GetListeners

Returns

List


IsListening (TextLine)
IsListening

Returns TRUE if aTextLine will execute its update script in response to an update event.

Syntax

aTextLine.IsListening

Returns

Boolean


RemoveListener (TextLine)
RemoveListener

Removes aControl from aTextLine's list of listeners. If aControl is not in that list, nothing happens. You do not need to use the ChangedListeners request after using this request.

Syntax

aTextLine.RemoveListener (aControl)


SetListeners (TextLine)
SetListeners
Example

Sets the listeners that will be sent the update event when aTextLine is sent the BroadcastUpdate request. The input list, but not the elements, is cloned by this request.

Syntax

aTextLine.SetListeners (aListOfListeners)


StartListening (TextLine)
StartListening

aTextLine will respond to any future update events by executing its update script.

Syntax

aTextLine.StartListening


StopListening (TextLine)
StopListening

aTextLine will not execute its update script in response to an update event.

Syntax

aTextLine.StopListening


TextLineTypeEnum

 A TextLine object can contain either arbitrary alpha-numeric characters, or only characters that form positive or negative integers, or only characters that form positive or negative real numbers.

#TEXTLINE_TYPE_ALL

all printing alpha-numeric characters are accepted.

#TEXTLINE_TYPE_INTEGER

only positive and negative integers can be input.

#TEXTLINE_TYPE_REAL

only positive and negative real numbers can be input.


FindDialog (Application)
FindDialog

Finds the dialog named aDialogName. FindDialog searches the current project first, then the User Default, then any loaded extensions. If aDialogName is not found, FindDialog returns Nil.

Syntax

av.FindDialog (aDialogName)

Returns

Dialog


AddListener (Button)
AddListener

Adds aControl to aButton’s list of listeners. aControl will be sent an update when the BroadcastUpdate request is sent to aButton. If aControl is already a listener, it is not added again. You do not need to use the ChangedListeners request after this request.

Syntax

aButton.AddListener (aControl)


BroadcastUpdate (Button)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aButton.

Syntax

aButton.BroadcastUpdate


GetBroadcaster (Button)
GetBroadcaster

Returns the control that is sending an update event to aButton. Do not store the result of this request over multiple executions of aButton’s update script. This request will return nil if the update event aButton is responding to was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aButton.GetBroadcaster

Returns

Obj


GetDialog (Button)
GetDialog

Gets the dialog containing a button. You may only use this request after adding a button to a dialog.

Syntax

aButton.GetDialog

Returns

Dialog


GetListeners (Button)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aButton. You may modify this list in any way, provided that it only contains controls.

Syntax

aButton.GetListeners

Returns

List


HasFastener (Button)
HasFastener

Returns TRUE if aButton currently has aFastener defined for it.

Syntax

aButton.HasFastener (aFastener)

Returns

Boolean


Move (Button)
Move

Move aButton dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aButton to another control panel. If aButton is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aButton to a dialog object. You cannot use this request to move aButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aButton.Move(dx, dy)


MoveTo (Button)
MoveTo

Move aButton to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aButton to another control panel. If aButton is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aButton is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aButton is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aButton to a dialog object. You cannot use this request to move aButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aButton.MoveTo (dx, dy)


RemoveListener (Button)
RemoveListener

Removes aControl from aButton’s list of listeners. aControl will no longer receive update events when aButton is sent the BroadcastUpdate request. Nothing happens if aControl is not in that list. You do not need to use the ChangedListeners request after this request.

Syntax

aButton.RemoveListener (aControl)


Resize (Button)
Resize

Make aButton dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aButton to a dialog object. You cannot use this request to resize aButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aButton.Resize (dw, dh)


ResizeTo (Button)
ResizeTo

Makes aButton w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding aButton to a dialog object. You cannot use this request to resize aButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aButton.ResizeTo (w, h)


ReturnBox (Button)
ReturnBox

Returns a copy of the bounding box of aButton. The box's coordinates are in the coordinate system of aButton’s containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aButton is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aButton is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aButton.ReturnBox

Returns

Rect


SetFastener (Button)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aButton.SetFastener (aFastener, OnOrOff)

Returns

Boolean


SetFasteners (Button)
SetFasteners

Defines positioning and resizing fasteners for aButton. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aButton’s fasteners are not altered. An example of a possible conflict is by specifying the fasteners to maintain aButton’s width as well as to maintain the fixed distance from the left and right sides of aDialog.

Syntax

aButton.SetFasteners (aListOfFasteners)

Returns

Boolean


SetListeners (Button)
SetListeners
Example

Sets the listeners that will be sent the update event when aButton is sent the BroadcastUpdate request. You are free to modify aListOfListeners after using it with this request. You do not need to use the ChangedListeners request after using this request.

Syntax

aButton.SetListeners (aListOfListeners)


AddListener (LabelButton)
AddListener

Adds aControl to aLabelButton’s list of listeners. aControl will be sent an update when the BroadcastUpdate request is sent to aLabelButton. If aControl is already a listener, it is not added again. You do not need to use the ChangedListeners request after this request.

Syntax

aLabelButton.AddListener (aControl)


BroadcastUpdate (LabelButton)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aLabelButton.

Syntax

aLabelButton.BroadcastUpdate


GetBroadcaster (LabelButton)
GetBroadcaster

Returns the control that is sending an update event to aLabelButton. Do not store the result of this request over multiple executions of aLabelButton’s update script. This request will return nil if the update event aLabelButton is responding to was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aLabelButton.GetBroadcaster

Returns

Obj


GetDialog (LabelButton)
GetDialog

Gets the dialog containing a label button. You may only use this request after adding a label button to a dialog.

Syntax

aLabelButton.GetDialog

Returns

Dialog


GetListeners (LabelButton)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aLabelButton. You may modify this list in any way, provided that it only contains controls.

Syntax

aLabelButton.GetListeners

Returns

List


HasFastener (LabelButton)
HasFastener

Returns TRUE if aLabelButton currently has aFastener defined for it.

Syntax

aLabelButton.HasFastener (aFastener)

Returns

Boolean


Move (LabelButton)
Move

Move aLabelButton dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aLabelButton to another control panel. If aLabelButton is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aLabelButton to a dialog object. You cannot use this request to move aLabelButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aLabelButton.Move(dx, dy)


MoveTo (LabelButton)
MoveTo

Move aLabelButton to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aLabelButton to another control panel. If aLabelButton is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aLabelButton is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aLabelButton is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aLabelButton to a dialog object. You cannot use this request to move aLabelButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aLabelButton.MoveTo (dx, dy)


RemoveListener (LabelButton)
RemoveListener

Removes aControl from aLabelButton’s list of listeners. aControl will no longer receive update events when aLabelButton is sent the BroadcastUpdate request. Nothing happens if aControl is not in that list. You do not need to use the ChangedListeners request after this request.

Syntax

aLabelButton.RemoveListener (aControl)


Resize (LabelButton)
Resize

Make aLabelButton dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aLabelButton to a dialog object. You cannot use this request to resize aLabelButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aLabelButton.Resize (dw, dh)


ResizeTo (LabelButton)
ResizeTo

Makes aLableButton w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding aLabelButton to a dialog object. You cannot use this request to resize aLabelButton in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aLabelButton.ResizeTo (w, h)


ReturnBox (LabelButton)
ReturnBox

Returns a copy of the bounding box of aLabelButton. The box's coordinates are in the coordinate system of aLabelButton’s containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aLabelButton is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aLabelButton is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aLabelButton.ReturnBox

Returns

Rect


SetFastener (LabelButton)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aLabelButton.SetFastener (aFastener, OnOrOff)

Returns

Boolean


SetFasteners (LabelButton)
SetFasteners

Defines positioning and resizing fasteners for aLabelButton. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aLabelButton’s fasteners are not altered. An example of a possible conflict is by specifying the fasteners to maintain aLabelButton’s width as well as to maintain the fixed distance from the left and right sides of aDialog.

Syntax

aLabelButton.SetFasteners (aListOfFasteners)

Returns

Boolean


SetListeners (LabelButton)
SetListeners
Example

Sets the listeners that will be sent the update event when aLabelButton is sent the BroadcastUpdate request. You are free to modify aListOfListeners after using it with this request. You do not need to use the ChangedListeners request after using this request.

Syntax

aLabelButton.SetListeners (aListOfListeners)


AddDialog (Project)
AddDialog

Adds, or embeds, a dialog into the current project. You might add a dialog to a project with this request when you want to remove the DialogEditor component from the project window, yet still be able to access the Dialog object. For example, you might write a script like this:

theDialogEditor = av.GetActiveDoc

av.GetProject.AddDialog(theDialogEditor.GetDialog)

av.GetProject.RemoveDoc(theDialogEditor)

This script adds the Dialog object to the project and removes the DialogEditor object. Note, however, that you can't edit a dialog interactively once you've deleted the dialog editor. When you add a dialog to the project like this, rename the dialog to some thing other than it’s default name such as Dialog1, Dialog2, etc.

Syntax

aProject.AddDialog (aDialog)


FindDialog (Project)
FindDialog

Finds the dialog named aDialogName and returns that dialog, or it returns Nil. If more than one dialog has the same name, FindDialog returns the first one it finds. FindDialog searches the embedded dialogs first and then the DialogEditor documents for aDialogName.

Syntax

aProject.FindDialog (aDialogName)

Returns

Dialog


GetDialogs (Project)
GetDialogs

Gets all the embedded dialogs in aProject. You embed dialogs with the AddDialog request on a Project. GetDialogs returns a NameDictionary containing these dialogs. To get a list of dialogs, issue the ReturnKeys request to the NameDictionary. This dictionary is read-only; do not add or delete elements from it.

Syntax

aProject.GetDialogs

Returns

NameDictionary


RemoveDialog (Project)
RemoveDialog

Removes the dialog named aDialogName from the project's dialog list. RemoveDialog only removes embedded dialogs. Use RemoveDoc to eliminate Dialog Editor documents.

Syntax

aProject.RemoveDialog (aDialogName)


AddListener (Tool)
AddListener

Adds aControl to aTool’s list of listeners. aControl will be sent an update when the BroadcastUpdate request is sent to aTool. If aControl is already a listener, it is not added again. You do not need to use the ChangedListeners request after this request.

Syntax

aTool.AddListener (aControl)


BroadcastUpdate (Tool)
BroadcastUpdate
Example

Sends an update event to all controls that are currently listening to aTool.

Syntax

aTool.BroadcastUpdate


GetBroadcaster (Tool)
GetBroadcaster

Returns the control that is sending an update event to aTool. Do not store the result of this request over multiple executions of aTool’s update script. This request will return nil if the update event aTool is responding to was not initiated via the request BroadcastUpdate sent to some other control.

Syntax

aTool.GetBroadcaster

Returns

Obj


GetDialog (Tool)
GetDialog

Gets the dialog containing a tool. You may only use this request after adding a tool to a dialog.

Syntax

aTool.GetDialog

Returns

Dialog


GetListeners (Tool)
GetListeners

Gets the list of listeners that will be sent the update event when the BroadcastUpdate request is sent to aTool. You may modify this list in any way, provided that it only contains controls.

Syntax

aTool.GetListeners

Returns

List


HasFastener (Tool)
HasFastener

Returns TRUE if aTool currently has aFastener defined for it.

Syntax

aTool.HasFastener (aFastener)

Returns

Boolean


Move (Tool)
Move

Move aTool dx pixels horizontally from its current position and dy pixels vertically. Positive values move it right and down. Negative values move it left and up. You cannot use this to "move" aTool to another control panel. If aTool is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel.

You can only use this request after adding aTool to a dialog object. You cannot use this request to move aTool in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTool.Move(dx, dy)


MoveTo (Tool)
MoveTo

Move aTool to the location (x, y) in its control panel. The upper left hand corner of its containing control panel is always at location (0, 0). You cannot use this to "move" aTool to another control panel. If aTool is moved far enough it will disappear, because it is no longer inside the bounding box of its containing control panel. The units are in screen pixels.

For example, if aTool is contained within a control panel under aDialog, the location (0, 0) is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTool is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and therefore the location (0, 0) will be the upper left hand corner of aDialog.

You can only use this request after adding aTool to a dialog object. You cannot use this request to move aTool in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTool.MoveTo (dx, dy)


RemoveListener (Tool)
RemoveListener

Removes aControl from aTool’s list of listeners. aControl will no longer receive update events when aTool is sent the BroadcastUpdate request. Nothing happens if aControl is not in that list. You do not need to use the ChangedListeners request after this request.

Syntax

aTool.RemoveListener (aControl)


Resize (Tool)
Resize

Make aTool dw pixels wider and dh pixels taller than it currently is. Positive values move the right and bottom sides to the right and down. Negative values move those sides left and up.

You can only use this request after adding aTool to a dialog object. You cannot use this request to resize aTool in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTool.Resize (dw, dh)


ResizeTo (Tool)
ResizeTo

Makes aTool w pixels wide and h pixels tall. The position of its upper left hand corner is not changed.

You can only use this request after adding aTool to a dialog object. You cannot use this request to resize aTool in a View, Layout or Dialog Editor document; see the SetBounds request on the GraphicControl class.

Syntax

aTool.ResizeTo (w, h)


ReturnBox (Tool)
ReturnBox

Returns a copy of the bounding box of aTool. The box's coordinates are in the coordinate system of aTool’s containing control panel. The upper left hand corner of that control panel is at location (0, 0). Its units are in screen pixels.

For example, if aTool is contained within a control panel under aDialog, the origin (0, 0) of the returned box is the upper left hand corner of the control panel (not the upper left hand corner of aDialog). If aTool is placed directly on aDialog (not contained within a control panel) then, the dialog itself is considered as a control panel and the origin of the returned box will be the upper left hand corner of aDialog.

Syntax

aTool.ReturnBox

Returns

Rect


SetFastener (Tool)
SetFastener

Toggles a particular fastener. Returns TRUE if the toggle succeeded, FALSE if it did not.

Syntax

aTool.SetFastener (aFastener, OnOrOff)

Returns

Boolean


SetFasteners (Tool)
SetFasteners

Defines positioning and resizing fasteners for aTool. Returns TRUE if elements of aListOfFasteners are not in conflict with each other. Returns FALSE if they are. In that case, aTool’s fasteners are not altered. An example of a possible conflict is by specifying the fasteners to maintain aTool’s width as well as to maintain the fixed distance from the left and right sides of aDialog.

Syntax

aTool.SetFasteners (aListOfFasteners)

Returns

Boolean


SetListeners (Tool)
SetListeners
Example

Sets the listeners that will be sent the update event when aTool is sent the BroadcastUpdate request. You are free to modify aListOfListeners after using it with this request. You do not need to use the ChangedListeners request after using this request.

Syntax

aTool.SetListeners (aListOfListeners)