CheckBox controls

Use a CheckBox control to show a yes or no choice, or a true or false choice. When associated with an attribute field, a selected check box represents a true value and a check box that is not selected represents a false value.

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

Attributes

CheckBox 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, onsetfocus) 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 CheckBox control attributes and descriptions:

Attributes	Descriptions
name	The CheckBox control name. Used to reference the control in scripts.
width	The check box's width.
height	The check box's height.
x	The x-coordinate of the upper left corner of the check box.
y	The y-coordinate of the upper left corner of the check box.
alignment	The alignment of the check box's caption.
group	Specifies if the check box starts a new group of controls.
border	Specifies if the check box has a border.
tabstop	Specifies if the TAB key can be used to move the focus to the check box.
caption	The caption displayed to the right of the check box.
defaultvalue	A simple expression that specifies the check box's default value.
required	Specifies if the user must select the check box.
field	The field of the shapefile's database file format (DBF) that is linked to the check box.
readonly	Specifies if the check box's value can be modified by the user.
backgroundcolor	The check box's background color. If not specified, the value is inherited from the page's backgroundcolor attribute.
color	The check box's text color. If not specified, this value is inherited from the page's color attribute.
font	The font for the check box's text. If not specified, this value is inherited form the page's font attribute.
fontsize	The font size for the check box's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style for the check box's text. If not specified, this value is inherited from the page's fontstyle attribute.
onsetfocus	The script to run when an OnSetFocus event occurs.
onkillfocus	The script to run when an OnKillFocus event occurs.
onclick	The script to run when an OnClick event occurs.
onvalidate	The script to run when an OnValidate event occurs.

Events

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

Events	Descriptions
OnClick	Occurs when the user clicks (to select or clear) the check box.
OnKillFocus	Occurs when the check box loses the focus.
OnSetFocus	Occurs when the check box gets the focus.
OnValidate	Occurs when the check box is validated.

Properties

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

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

Properties	Descriptions
DefaultValue	Returns or sets the default value expression for the check box.
Enabled	Returns or sets a value that determines if the check box is enabled.
Field	Returns a reference to the feature attribute field to which the check box is bound.
hWnd	Returns the check box's window handle.
Index	Returns the check box's index.
Name	Returns the check box's name.
Parent	Returns a reference to the page that contains the check box.
Text	Returns or sets the text displayed to the right of the check box.
Type	Returns the control type ("CHECKBOX" for a check box).
Value	Returns or sets a value that determines if the check box is selected.
Visible	Returns or sets a value that determines if the check box is visible.

Methods

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

The following table shows the available CheckBox control method and description:

Method	Description
SetFocus	Sets the focus to the check box.

Referencing a CheckBox control

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

Direct reference

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

JScript

var objForm = Applet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objCheckBox = objPage.Controls("chkActivate");

Python

objForm = Applet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objCheckBox = objPage.Controls("chkActivate")

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 CheckBox 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 objCheckBox
Set objCheckBox = objPage.Controls("chkActivate")

JScript

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

Python

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

Event reference

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

VBScript

Dim objCheckBox
Set objCheckBox = ThisEvent.Object

JScript

var objCheckBox = ThisEvent.Object;

Python

objCheckBox = ThisEvent.Object

Use the following code to reference a CheckBox control with the name "chkActivate" 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 objCheckBox
Set objCheckBox = objPage.Controls("chkActivate")

JScript

var objPage = ThisEvent.Object.Pages("pgPage1");
var objCheckBox = objPage.Controls("chkActivate");

Python

objPage = ThisEvent.Object.Pages("pgPage1")
objCheckBox = objPage.Controls("chkActivate")

Initializing a CheckBox control

Check box initialization involves setting particular check box properties when the check 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 check box with the name "chkActivate" as selected when called in the page's OnLoad event handler:

VBScript

Dim objControls
Set objControls = ThisEvent.Object.Controls 
objControls("chkActivate").Value = True

JScript

var objControls = ThisEvent.Object.Controls;
objControls("chkActivate").Value = true;

Python

objControls = ThisEvent.Object.Controls
objControls("chkActivate").Value = true

Selecting and clearing a CheckBox control

To select a check box at run time, set its Value property to True. To clear a check box, set its Value property to False. For example, use the following code to clear a check box referenced by the variable, objCheckBox:

VBScript

objCheckBox.Value = False

JScript

objCheckBox.Value = false;

Python

objCheckBox.Value = False