Edit controls

Use an Edit control to display text added at design time by the user or assigned to the control in the code at run time. An Edit control is also commonly called a text box. Edit controls are represented by Control objects in the ArcPad object model and by EDIT elements in ArcPad Extensible Markup Language (XML).

Attributes

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

Attributes	Descriptions
name	The name of the Edit control. Used to reference the Edit control in scripts.
width	The width of the text box.
height	The height of the text box.
x	The x-coordinate of the upper left corner of the text box.
y	The y-coordinate of the upper left corner of the text box.
alignment	The alignment of the text box's text.
autoincrement	Specifies if the value of the text box's bound, numeric field automatically increments when a new feature is added.
autoincrementstep	Specifies the autoincrement step value.
tabstop	Specifies if the TAB key can be used to move the focus to the text box.
group	Specifies if the text box starts a new group of controls.
border	Specifies if the text box has a border.
multiline	Specifies if the text box contains multiple lines of text.
defaultvalue	A simple expression that specifies the default value of the text box.
sip	Specifies if the soft input panel (SIP) displays on pen devices when the text box gets the focus.
hscroll	Specifies if the text box should have a horizontal scroll bar.
vscroll	Specifies if the text box should have a vertical scroll bar.
required	Specifies if the user must add text in the text box.
readonly	Specifies if the text box's value can be modified by the user.
password	Specifies if the characters displayed in the text box are replaced by asterisks (*).
uppercase	Specifies if the characters displayed in the text box are all uppercase.
lowercase	Specifies if the characters displayed in the text box are all lowercase.
field	The field of the shapefile's database file (DBF) table that is linked to the text box.
backgroundcolor	The background color to use for the text box. If not specified, this value is inherited from the page's backgroundcolor attribute.
color	The color to use for the text box's text. If not specified, this value is inherited from the page's color attribute.
font	The font to use for the text box's text. If not specified, this value is inherited from the page's font attribute.
fontsize	The font size to use for the text box's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style to use for the text box's text. If not specified, this value is inherited from the page's fontstyle attribute.
maxvalue	Specifies the maximum value allowed for the text box. This can be a numeric or text value.
minvalue	Specifies the minimum value allowed for the text box. This can be a numeric or text value.
onsetfocus	The script to run when an OnSetFocus event occurs.
onkillfocus	The script to run when an OnKillFocus event occurs.
onchange	The script to run when an OnChange event occurs.
onvalidate	The script to run when an OnValidate event occurs.

Events

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

Events	Descriptions
OnChange	Occurs when the text in the text box is modified.
OnKillFocus	Occurs when the text box loses the focus.
OnSetFocus	Occurs when the text box gets the focus.
OnValidate	Occurs when the text box is validated.

Properties

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

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

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

Methods

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

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

Method	Description
SetFocus	Sets the focus to the text box.

Referencing an Edit control

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

Direct reference

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

JScript

var objForm = Applet.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objEdit = objPage.Controls("txtName");

Python

objForm = Applet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objEdit = objPage.Controls("txtName")

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 Edit 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 objEdit
Set objEdit = objPage.Controls("txtName")

JScript

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

Python

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

Event reference

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

VBScript

Dim objEdit
Set objEdit = ThisEvent.Object

JScript

var objEdit = ThisEvent.Object;

Python

objListBox = ThisEvent.Object

Use the following code to reference an Edit control with the name "txtName" 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 objEdit 
Set objEdit = objPage.Controls("txtName")

JScript

var objPage = ThisEvent.Object.Pages("pgPage1");
var objEdit = objPage.Controls("txtName");

Python

objPage = ThisEvent.Object.Pages("pgPage1")
objListBox = objPage.Controls("txtName")

Initializing an Edit control

Text box initialization involves setting particular text box properties when the text 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 disables a text box with the name "txtName" when called in the page's OnLoad event handler:

VBScript

Dim objControls
Set objControls = ThisEvent.Object.Controls 
objControls("txtName").Enabled = False

JScript

var objControls = ThisEvent.Object.Controls;
objControls("txtName").Enabled = false;

Python

objControls = ThisEvent.Object.Controls
objControls("txtName").Enabled = False

Specifying the text displayed in an Edit control

To set the text displayed in a text box at run time, set its Value property to the applicable text string. For example, use the following code to display the text "ArcPad Rocks!" in a text box referenced by the variable, objEdit:

VBScript

objEdit.Value = "ArcPad Rocks!"

JScript

objEdit.Value = "ArcPad Rocks!";

Python

objEdit.Value = "ArcPad Rocks!"