ArcPad Developer Help - ComboBox controls

Use a ComboBox control to provide a list of items when there is a minimum amount of space available on your form, in which you make a selection from a list of drop-down items. A combo box combines the features of a text box and a list box. You can select an item by typing text into the combo box or by selecting an item from the list.

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

Attributes

ComboBox 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, onchange) 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 ComboBox control attributes and descriptions:

Attributes	Descriptions
name	The ComboBox control name. Used to reference the ComboBox control in scripts.
width	The combo box's width.
height	The combo box's height.
x	The x-coordinate of the upper left corner of the combo box.
y	The y-coordinate of the upper left corner of the combo box.
sip	Specifies if the soft input panel (SIP) displays on pen devices when the combo box gets the focus.
required	Specifies if the user must select an item in the combo box.
defaultvalue	A simple expression that specifies the combo box's default value.
group	Specifies if the combo box starts a new group of controls.
border	Specifies if the combo box has a border.
tabstop	Specifies if the TAB key can be used to move the focus to the combo box.
readonly	Specifies if the combo box's value can be modified by the user.
listtable	The database file format (DBF) table used to populate the combo box.
listvaluefield	The field of the DBF table that contains the data used to populate the value component of the combo box's items.
listtextfield	The field of the DBF table that contains the data used to populate the text component of the combo box's items.
field	The field of the shapefile's DBF table that is linked to the combo box.
limittolist	Specifies if the text box portion of the combo box can accept text.
maxvalue	Specifies the maximum value allowed for the combo box. This can be a numeric or text value.
minvalue	Specifies the minimum value allowed for the combo box. This can be a numeric or text value.
sort	Specifies if the items in the combo box are automatically sorted alphabetically.
backgroundcolor	The combo box's background color. If not specified, this value is inherited from the page's backgroundcolor attribute.
color	The combo box's text color. If not specified, this value is inherited from the page's color attribute.
font	The font to use for the combo box's text. If not specified, this value is inherited from the page's font attribute.
fontsize	The font size to use for the combo box's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style to use for the combo box's text. If not specified, this value is inherited from the page's fontstyle attribute.
onchange	The script to run when an OnChange event occurs.
oncloseup	The script to run when an OnCloseUp event occurs.
ondropdown	The script to run when an OnDropDown event occurs.
onselchange	The script to run when an OnSelChange event occurs.
onselcancel	The script to run when an OnSelCancel event occurs.
onselok	The script to run when an OnSelOK 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

ComboBox 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 ComboBox control events and descriptions:

Events	Descriptions
OnChange	Occurs when the user types within the text box portion of the combo box.
OnCloseUp	Occurs when the drop-down portion of the combo box closes.
OnDropDown	Occurs when the drop-down portion of the combo box displays.
OnKillFocus	Occurs when the combo box loses focus.
OnSelCancel	Occurs when the drop-down list of the combo box is triggered, but the user does not select a value. Also occurs when the combo box loses focus.
OnSelChange	Occurs when the selection within the combo box changes.
OnSelOK	Occurs when an item is selected from the list in the combo box.
OnSetFocus	Occurs when the combo box gets the focus.
OnValidate	Occurs when the combo box is validated.

Properties

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

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

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

Methods

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

The following table shows the available ComboBox control methods and descriptions:

Methods	Descriptions
SetFocus	Sets the focus to the combo box.
AddItem	Adds an item to the combo box.
AddItemsFromTable	Adds items from a DBF table to the combo box.
Clear	Clears the combo box's content.
RemoveItem	Removes an item from the combo box.

Referencing a ComboBox control

You can only reference a ComboBox control in a form that is currently displayed. Attempting to reference a ComboBox 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 ComboBox control.

Direct reference

This involves referencing a ComboBox control via its name, page's name, form's name, and form's parent object. For example, use the following code to reference a ComboBox control with the name "cboPoleType" on a page with the name "pgPage1" 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("pgPage1")
Dim objComboBox
Set objComboBox = objPage.Controls("cboPoleType")

JScript

var objForm = Applet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objComboBox = objPage.Controls("cboPoleType");

Python

objForm = Applet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objComboBox = objPage.Controls("cboPoleType")

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 ComboBox 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("pgPage1")
Dim objComboBox
Set objComboBox = objPage.Controls("cboPoleType")

JScript

var objApplet = Application.Applets("Custom Settings");
var objForm = objApplet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objComboBox = objPage.Controls("cboPoleType");

Python

objApplet = Application.Applets("Custom Settings")
objForm = objApplet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objComboBox = objPage.Controls("cboPoleType")

Event reference

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

VBScript

Dim objComboBox
Set objComboBox = ThisEvent.Object

JScript

var objComboBox = ThisEvent.object;

Python

objComboBox = ThisEvent.object

Use the following code to reference a ComboBox control with the name "cboPoleType" on a page with the name "pgPage1" in the OnLoad event handler of its form:

VBScript

Dim objPage
Set objPage = ThisEvent.Object.Pages("pgPage1")
Dim objComboBox
Set objComboBox = objPage.Controls("cboPoleType")

JScript

var objPage = ThisEvent.Object.Pages("pgPage1");
var objComboBox = objPage.Controls("cboPoleType");

Python

objPage = ThisEvent.Object.Pages("pgPage1")
objComboBox = objPage.Controls("cboPoleType")

Initializing a ComboBox control

Combo box initialization involves setting particular combo box properties when the combo 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 combo box with the name "cboPoleType" with no item selected when called in the page's OnLoad event handler:

VBScript

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

JScript

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

Python

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

Text vs. value in a ComboBox control

Items displayed in a combo box have the following components:

Text—The text displays to the user and can be read with the Text property.
Value—The value is stored in the attribute associated with the ComboBox control (if there is one) and can be read with the Value property.

At design time, specify the value and text of combo 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 combo box items when using the AddItem or AddItemsFromTable methods. The value and text can be the same for a combo box item, but you still need to specify both.

Selecting an item in a ComboBox control

To select an item in a combo 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 combo box referenced by the variable, objComboBox:

VBScript

objComboBox.ListIndex = 2

JScript

objComboBox.ListIndex = 2;

Python

objComboBox.ListIndex = 2

Populating and unpopulating a ComboBox control

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

AddItem—Use this method to add items one by one to a combo box or add multiple items from a DBF table to a combo box by using the AddItemsFromTable method.
RemoveItem—Use this method to remove items one by one from a combo box or clear the entire content of the combo box by using the Clear method.

For example, the following code clears the original content of the combo box referenced by the variable, objComboBox, then populates the combo box with several new items:

VBScript

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

JScript

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

Python

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

2/7/2013