Button controls

Use a Button control to begin or end a process. A button contains a text label that indicates what the button does when clicked. Button controls are represented by Control objects in the ArcPad object model and by BUTTON elements in ArcPad Extensible Markup Language (XML).

Attributes

Button 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 Button control attributes and descriptions:

Attributes	Descriptions
name	The name of the Button control. Used to reference the Button control in scripts.
caption	The text appearing in the button.
width	The button's width.
height	The button's height.
x	The x-coordinate of the upper left corner of the button.
y	The y-coordinate of the upper left corner of the button.
alignment	The alignment of the button's caption.
group	Specifies if the button starts a new group of controls.
border	Specifies if the button has a border.
tabstop	Specifies if the TAB key can be used to move the focus to the button.
backgroundcolor	The button's background color. If not specified, this value is inherited from the page's backgroundcolor attribute.
color	The button's text color. If not specified, this value is inherited from the page's color attribute.
font	The font for the button's text. If not specified, this value is inherited from the page's font attribute.
fontsize	The font size for the button's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style for the button'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.

Events

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

Events	Descriptions
OnClick	Occurs when the button is clicked.
OnKillFocus	Occurs when the button loses the focus.
OnSetFocus	Occurs when the button gets the focus.

Properties

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

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

Properties	Descriptions
Enabled	Returns or sets a value that determines if the button is enabled.
hWnd	Returns the button's window handle.
Index	Returns the button's index.
Name	Returns the button's name.
Parent	Returns a reference to the page that contains the button.
Text	Returns or sets the text to display for the button.
Type	Returns the control type (for example, BUTTON for a button).
Value	Returns or sets the button's value.
Visible	Returns or sets a value that determines if the button is visible.

Methods

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

The following table shows the available Button method and description:

Method	Description
SetFocus	Sets the focus to the button.

Referencing a Button control

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

Direct reference

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

JScript

var objForm = Applet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objButton = objPage.Controls("btnClickMe");

Python

objForm = objApplet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objButton = objPage.Controls("btnClickMe")

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 Button 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 objButton
Set objButton = objPage.Controls("btnClickMe")

JScript

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

Python

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

Event reference

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

VBScript

Dim objButton
Set objButton = ThisEvent.Object

JScript

var objButton = ThisEvent.Object;

Python

objButton = ThisEvent.Object

Initializing a Button control

Button initialization involves setting specific button properties when the button first displays. Generally, the OnLoad event handler on the page or form is the most appropriate place to do this. For example, the following code makes a button with the name "btnClickMe" inactive and changes its caption to "Click Me" when called in the page's OnLoad event handler:

VBScript

Dim objPage
Set objPage = ThisEvent.Object
Dim objButton
Set objButton = objPage.Controls("btnClickMe")
objButton.Text = "Click Me"	
objButton.Enabled = False

JScript

var objPage = ThisEvent.Object;
var objButton = objPage.Controls("btnClickMe");
objButton.Text = "Click Me";
objButton.Enabled = false;

To demonstrate the same example using Python, the script must be saved in a script file associated with the edit form and not embedded inside the edit form. Inside the edit form's page OnLoad event, the script function, ClickButton, is referenced:

Python

ClickButton()

Inside the associated script file, the ClickButton function sets the caption for the button to be "Click Me", and the button is made inactive.

Python

def ClickButton():
    objPage = ThisEvent.Object
    objButton = objPage.Controls("btnClickMe")
    objButton.Text = "Click Me"
    objButton.Enabled = False

Clicking a Button control

To click a button (and fire the Button control's OnClick event), set its Value property to True. For example, the following code clicks a button referenced by the variable, objButton:

VBScript

objButton.Value = True

JScript

objButton.Value = true;

Python

objButton.Value = True