Forms

Use a form to organize a single task or set of related tasks onto a single window. A form contains one or more pages. The following screen shot shows a form with two pages (tabs):

Forms are represented by form objects in the ArcPad object model and by FORM elements in ArcPad Extensible Markup Language (XML).

Attributes

Form attributes are set at design time in ArcPad Studio on the Form 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, onload) are used to specify the script to run when an event occurs. These attributes are set in the Events page on the Form 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 form attributes and descriptions:

Attributes	Descriptions
name	The form name. Used to reference the form in scripts.
backgroundcolor	The form's background color. This can be overridden by setting a page's or control's backgroundcolor attribute.
caption	The text appearing on the form's title bar.
color	The form's text color. This can be overridden by setting a page's or control's color attribute.
width	The form's width.
height	The form's height.
tabsvisible	Specifies if the form contains tabs (pages).
font	The font used for the form.
fontsize	The font size used for the form.
fontstyle	The font style used for the form.
attributespagevisible	Specifies if the attributes page displays with the form (Edit and Identify forms only).
symbologypagevisible	Specifies if the symbology page displays with the form (Edit and Identify forms only).
geographypagevisible	Specifies if the geography page displays with the form (Edit and Identify forms only). This attribute can not be set to false if averaging is enabled.
picturepagevisible	Specifies if the picture page displays with the form (Edit and Identify forms only).
sip	Specifies if the soft input panel (SIP) displays on pen devices by default when controls get the focus.
onload	The script to run when an OnLoad event occurs.
onunload	The script to run when an OnUnload event occurs.
onsetactive	The script to run when an OnSetActive event occurs.
onkillactive	The script to run when an OnKillActive event occurs.
onok	The script to run when an OnOK event occurs.
oncancel	The script to run when an OnCancel event occurs.
onrefresh	The script to run when an OnRefresh event occurs (Edit and Identify forms only).

Events

Forms generate a range of events as they are operating. You can specify a script to run when any of these events occur.

The following table shows the available form events and descriptions:

Events	Descriptions
OnCancel	Occurs when the Cancel button is clicked on the form.
OnKillActive	Occurs when the form loses the focus.
OnLoad	Occurs when the form is loaded.
OnOK	Occurs when the OK button is clicked on the form.
OnRefresh	Occurs when the displayed Identify form is updated.
OnSetActive	Occurs when the form gets the focus.
OnUnload	Occurs when the form is unloaded.

Properties

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

The following table shows the available form properties and descriptions:

Properties	Descriptions
ActivePage	Returns a reference to the currently displayed page on the form.
Caption	Returns or sets the caption that displays for the form.
Fields	Returns a reference to the fields of the current record (Edit and Identify forms only).
hWnd	Returns the form's window handle.
Mode	Returns a value that indicates how the form is used.
Name	Returns the form's name.
Pages	Returns a reference to the form's pages.

Methods

Form methods can be called at run time via scripts.

The following table shows the available form methods and descriptions.

Methods	Descriptions
Close	Shuts the form.
Show	Displays the General form.

Referencing a form

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

Direct reference

This involves referencing a form via its name and parent object. For example, use the following code to reference 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")

JScript

var objForm = Applet.Forms("frmSettings");

Python

objForm = Applet.Forms("frmSettings")

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 form from a different applet or other customization file, explicitly reference the applet. See the following code:

VBScript

Dim objApplet
Set objApplet = Applets("Custom Settings")
Dim objForm
Set objForm = objApplet.Forms("frmSettings")

JScript

var objApplet = Applets("Custom Settings");
var objForm = objApplet.Forms("frmSettings");

Python

objApplet = Applets("Custom Settings")
objForm = objApplet.Forms("frmSettings")

• Use Layer.Forms to reference forms from within a particular layer.
• Use Applet.Forms to reference forms from within an applet.
• Use Application.Forms to reference forms from within the default configuration file (ArcPad.apx).

Event reference

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

VBScript

Dim objForm
Set objForm = ThisEvent.Object

JScript

var objForm = ThisEvent.Object;

Python

objForm = ThisEvent.Object

Use the following code to reference a form in the OnLoad event handler on one of the form's pages:

VBScript

Dim objForm
Set objForm = ThisEvent.Object.Parent

JScript

var objForm = ThisEvent.Object.Parent;

Python

objForm = ThisEvent.Object.Parent

Displaying a general form

To display a form, reference the form and call its Show method, passing in the name of the form. For example, use the following code to display a form named "frmSettings" that is present in an applet with the name "Custom Settings":

VBScript

Applet.Forms("frmSettings").Show

JScript

Applet.Forms("frmSettings").Show();

Python

Applet.Forms("frmSettings").Show()

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 display the same form 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")
objForm.Show

JScript

var objApplet = Application.Applets("Custom Settings");
var objForm = objApplet.Forms("frmSettings");
objForm.Show();

Python

objApplet = Application.Applets("Custom Settings")
objForm = objApplet.Forms("frmSettings")
objForm.Show()

• Use Layer.Forms to display forms from within a particular layer.
• Use Applet.Forms to display forms from within an applet.
• Use Application.Forms to display forms from within the default configuration file (ArcPad.apx).

If you want to display data-related forms, such as Edit forms programmatically within ArcPad, the following commands can be used:

• Map.addFeature or Map.addFeatureXY invokes the Edit form for a feature.
• Map.IdentifyXY invokes an Identify form.
• Application.ExecuteCommand("Find") invokes a Query form.

Initializing a form

Form initialization involves setting particular form properties when the form first displays. Generally, the form's OnLoad event handler is the most appropriate place to do this. For example, the following code changes the form's caption to "New Caption" when called in the OnLoad event handler:

VBScript

ThisEvent.Object.Caption = "New Caption"

JScript

ThisEvent.Object.Caption = "New Caption";

Python

ThisEvent.Object.Caption = "New Caption"

Referencing attribute fields for the current feature on an Edit form

You can reference the Fields object that represents the fields of the feature currently being edited in an Edit form. This is useful if you want to read or modify field values that are not present on the Edit form.

Generally, the form's OnLoad event handler is the most appropriate place to do this. For example, the following code writes the current date to a field called LASTEDIT when called in the Edit form's page OnLoad event handler:

Note:

The LASTEDIT field must be present in the layer or the script generates an error.

VBScript

Dim objFields
Set objFields = ThisEvent.Object.Parent.Fields
objFields("LASTEDIT").Value = FormatDateTime(Now(),vbShortDate)

JScript

var objFields, dtDate, strToday;
Set objFields = ThisEvent.Object.Parent.Fields();
dtDate = new Date();
strToday = (dtDate.getMonth() + 1) + "/";
strToday += dtDate.getDate() + "/";
strToday += dtDate.getYear();
objFields("LASTEDIT").Value = strToday;

To do demonstrate the same example using Python, the script must be saved in a script file associated to the Edit form, and not embedded inside the Edit form. Inside the Edit form's page OnLoad event, the script function, getDate, would be referenced:

Python

getDate()

Inside the associated script file, first the Python datetime module must be imported, then the getData function sets the LASTEDIT field to the current date.

Python

import datetime

def getDate():
	   objFields = ThisEvent.Object.Parent.Fields
	   objFields("LASTEDIT").Value = datetime.date.today()