ArcPad Developer Help - ListBox controls

Use a ListBox control to provide a list of choices from which the user can make a selection.

ListBox controls are represented by Control objects in the ArcPad object model and by LISTBOX elements in ArcPad Extensible Markup Language (XML).

Attributes

ListBox control attributes are set at design time in ArcPad Studio on the Control Properties dialog box. They cannot be changed at run time (some attributes have corresponding properties that can be accessed and changed at run time). For more information, see Attributes vs. properties.

Attributes beginning with "on" (for example, onselchange) are used to specify the script to run when an event occurs. These attributes are set in the Events page on the Control Properties dialog box. Attributes are written to the customization file (layer definition, applet, default configuration) in ArcPad XML format.

The following table shows the available ListBox control attributes and descriptions:

Attributes	Descriptions
name	The name of the ListBox control. Used to reference the ListBox control in scripts.
width	The list box's width.
height	The list box's height.
x	The x-coordinate of the upper left corner of the list box.
y	The y-coordinate of the upper left corner of the list box.
required	Specifies if the user must select an item in the list box.
defaultvalue	A simple expression that specifies the default value of the list box.
tabstop	Specifies whether the TAB key can be used to move the focus to the list box.
group	Specifies whether the list box starts a new group of controls.
border	Specifies whether the list box has a border.
readonly	Specifies whether the list box's value can be modified by the user.
hscroll	Specifies if the list box should have a horizontal scroll bar.
vscroll	Specifies if the list box should have a vertical scroll bar.
listtable	The database file format (DBF) table used to populate the list box.
listvaluefield	The field of the DBF table that contains the data used to populate the value component of the list box's items.
listtextfield	The field of the DBF table that contains the data used to populate the text component of the list box's items.
field	The field of the shapefile's DBF table that is linked to the list box.
sort	Specifies if the items in the list box are automatically sorted alphabetically.
showvalues	Specifies if the values display next to the text for items in the list box.
backgroundcolor	The background color to use for the list box. If not specified, this value is inherited from the page's backgroundcolor attribute.
color	The color to use for the list box's text. If not specified, this value is inherited from the page's color attribute.
font	The font to use for the list box's text. If not specified, this value is inherited from the page's font attribute.
fontsize	The font size to use for the list box's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style to use for the list box's text. If not specified, this value is inherited from the page's fontstyle attribute.
onselchange	The script to run when an OnSelChange event occurs.
onselcancel	The script to run when an OnSelCancel event occurs.
onsetfocus	The script to run when an OnSetFocus event occurs.
onkillfocus	The script to run when an OnKillFocus event occurs.
onvalidate	The script to run when an OnValidate event occurs.

Events

ListBox controls generate a range of events as they are operating. You can specify a script to run when any of these events occur in the Events page on the Control Properties dialog box.

The following table shows the available ListBox control events and descriptions:

Events	Descriptions
OnKillFocus	Occurs when the list box loses the focus.
OnSelCancel	Occurs when the selection within the list box is cancelled.
OnSelChange	Occurs when the selection within the list box is changed.
OnSetFocus	Occurs when the list box gets the focus.
OnValidate	Occurs when the list box is validated.

Properties

ListBox control properties can be read and set at run time via scripts.

The following table shows the available ListBox control properties and descriptions:

Properties	Descriptions
DefaultValue	Returns or sets the default value expression for the list box.
Enabled	Returns or sets a value that determines if the list box is enabled.
Field	Returns a reference to the feature attribute field to which the list box is bound.
hWnd	Returns the window handle of the list box.
Index	Returns the index of the list box.
ListCount	Returns the number of items in the list for the list box.
ListIndex	Returns or sets the index of the currently selected item in the list box.
Name	Returns the list box's name.
Parent	Returns a reference to the page that contains the list box.
Properties	Returns the value of the specified property for the list box.
Text	Returns the text of the item currently displayed in the list box.
Type	Returns the control type (for example, LISTBOX for a list box).
Value	Returns the value of the currently displayed item in the list box.
Visible	Returns or sets a value that determines whether the list box is visible.

Methods

ListBox control methods can be called at run time via scripts.

The following table shows the available ListBox methods and descriptions:

Methods	Descriptions
SetFocus	Sets the focus to the list box.
AddItem	Adds an item to the list box.
AddItemsFromTable	Adds items from a DBF table to the list box.
Clear	Clears the contents of the list box.
RemoveItem	Removes an item from the list box.

Referencing a ListBox control

You can only reference a ListBox control in a form that is currently displayed. Attempting to reference a ListBox control in a form that is not currently displayed results in a runtime error. The following discusses the approaches (Direct and Event) to referencing a ListBox control.

Direct reference

This involves referencing a ListBox control via its name, page's name, form's name, and form's parent object. For example, use the following code to reference a ListBox control with the name "lboStreetType" on a page with the name "pgPage2" in a form with the name "frmSettings" that is present in an applet with the name "Custom Settings":

VBScript

Dim objForm 
Set objForm = Applet.Forms("frmSettings")
Dim objPage
Set objPage = objForm.Pages("pgPage2")
Dim objListBox
Set objListBox = objPage.Controls("lboStreetType")

JScript

var objForm = Applet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage2");
var objListBox = objPage.Controls("lboStreetType");

Python

objForm = Applet.Forms("frmSettings")
objPage = objForm.Pages("pgPage2")
objListBox = objPage.Controls("lboStreetType")

The previous code assumes that it is present in the applet (that is, in the .apa file or its associated script file). If you need to reference the same ListBox control from a different applet or other customization file, explicitly reference the applet. See the following code:

VBScript

Dim objApplet
Set objApplet = Application.Applets("Custom Settings")
Dim objForm 
Set objForm = objApplet.Forms("frmSettings")
Dim objPage
Set objPage = objForm.Pages("pgPage2")
Dim objListBox
Set objListBox = objPage.Controls("lboStreetType")

JScript

var objApplet = Application.Applets("Custom Settings");
var objForm = objApplet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage2");
var objListBox = objPage.Controls("lboStreetType");

Python

objApplet = Application.Applets("Custom Settings")
objForm = objApplet.Forms("frmSettings")
objPage = objForm.Pages("pgPage2")
objListBox = objPage.Controls("lboStreetType")

Event reference

This involves referencing a ListBox control in an event handling script. For example, use the following code to reference a ListBox control in its OnSelChange event handler:

VBScript

Dim objListBox
Set objListBox = ThisEvent.Object

JScript

var objListBox = ThisEvent.Object;

Python

objListBox = ThisEvent.Object

Use the following code to reference a ListBox control with the name "lboStreetType" on a page with the name "pgPage2" in the OnLoad event handler of its form:

VBScript

Dim objPage
Set objPage = ThisEvent.Object.Pages("pgPage2")
Dim objListBox
Set objListBox = objPage.Controls("lboStreetType")

JScript

var objPage = ThisEvent.Object.Pages("pgPage2");
var objListBox = objPage.Controls("lboStreetType");

Python

ThisEvent.Object.Pages("pgPage2").Controls("lboStreetType")

Initializing a ListBox control

List box initialization involves setting particular list box properties when the list box first displays. Generally, the OnLoad event handler of the page or form is the most appropriate place to do this. For example, the following code displays a list box with the name "lboStreetType" with no item selected when called in the page's OnLoad event handler:

VBScript

Dim objControls
Set objControls = ThisEvent.Object.Controls 
objControls("lboStreetType").ListIndex = -1

JScript

var objControls = ThisEvent.Object.Controls;
objControls("lboStreetType").ListIndex = -1;

Python

objControls = ThisEvent.Object.Controls
objControls("lboStreetType").ListIndex = -1

Text vs. value in a ListBox control

Items displayed in a list box have the following components:

Text—Read with the Text property
Value—Read with the Value property

The text displays to the user and the value gets stored in the attribute associated with the ListBox control (if there is one). At design time, specify the value and text of list box items by clicking the List Items button in the Control Properties page on the Form Editor dialog box. At run time, specify the value and text of list box items when using the AddItem or AddItemsFromTable methods. The value and text can be the same for a list box item, but you still need to specify both.

Selecting an item in a ListBox control

To select an item in a list box at run time, set its ListIndex property to the index of the applicable list item. For example, use the following code to select the third list item in a list box referenced by the objListBox variable:

VBScript

objListBox.ListIndex = 2

JScript

objListBox.ListIndex = 2;

Python

objListBox.ListIndex = 2

Populating and unpopulating a ListBox control

The following are the ways to populate and unpopulate a list box at run time:

Use the AddItem method to individually add items to a list box.
- You can also add multiple items from a DBF table to a list box by using the AddItemsFromTable method.
Use the RemoveItem method to individually remove items from a list box.
- You can also clear the entire contents of the list box by using the Clear method. For example, the following code clears the original contents of the list box referenced by the objListBox variable, then populates the list box with several new items:

VBScript

objListBox.Clear
objListBox.AddItem "BP2","2 inch brass pipe"
objListBox.AddItem "BP3","3 inch brass pipe"
objListBox.AddItem "CP2","2 inch copper pipe"
objListBox.AddItem "CP3","3 inch copper pipe"

JScript

objListBox.Clear ();
objListBox.AddItem ("BP2","2 inch brass pipe");
objListBox.AddItem ("BP3","3 inch brass pipe");
objListBox.AddItem ("CP2","2 inch copper pipe");
objListBox.AddItem ("CP3","3 inch copper pipe");

Python

objListBox.Clear()
objListBox.AddItem ("BP2","2 inch brass pipe")
objListBox.AddItem ("BP3","3 inch brass pipe")
objListBox.AddItem ("CP2","2 inch copper pipe")
objListBox.AddItem ("CP3","3 inch copper pipe")

2/7/2013