Pages

Use a page to organize one or more related controls in a form. A page is the canvas upon which you place your controls. Every form must have at least one page. Pages are represented by Page objects in the ArcPad object model and by PAGE elements in ArcPad Extensible Markup Language (XML).

Attributes

Page attributes are set at design time in ArcPad Studio on the Page 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 Page 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 Page attributes and descriptions:

Attributes	Descriptions
name	The name of the page. Used to reference the page in scripts.
backgroundcolor	The page's background color. This can be overridden by setting a control's backgroundcolor attribute. If not specified, this value is inherited from the form's backgroundcolor attribute.
caption	The text appearing in the page's tab.
color	The color to use for the page. This can be overridden by setting a control's color attribute. If not specified, this value is inherited from the form's color attribute.
font	The font for the page. This can be overridden by setting a control's font attribute. If not specified, this value is inherited from the form's font attribute.
fontsize	The font size for the page. This can be overridden by setting a control's fontsize attribute. If not specified, this value is inherited from the form's fontsize attribute.
fontstyle	The font style for the page. This can be overridden by setting a control's fontstyle attribute. If not specified, this value is inherited from the form's fontstyle attribute.
sip	Specifies whether 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.
onquerycancel	The script to run when an OnQueryCancel event occurs.
onvalidate	The script to run when an OnValidate event occurs.

Events

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

The following table shows the available Page events and descriptions:

Events	Descriptions
OnCancel	Occurs when the Cancel button is clicked on the page.
OnKillActive	Occurs when the page loses the focus.
OnLoad	Occurs when the page is loaded.
OnOK	Occurs when the OK button is clicked on the page.
OnQueryCancel	Occurs for every page before the OnCancel event occurs when the Cancel button is clicked on a form.
OnSetActive	Occurs when the page gets the focus.
OnUnload	Occurs when the page is unloaded.
OnValidate	Occurs after all Control objects' OnValidate events fire on the page.

Properties

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

The following table shows the available Page properties and descriptions:

Properties	Descriptions
Caption	Returns or sets the caption to display for the page.
Controls	Returns a reference to the controls' object for the page.
hWnd	Returns the window handle of the page.
Index	Returns the index of the page.
IsActive	Returns True if the page is currently displayed; otherwise, returns False.
Name	Returns the name of the page.
Parent	Returns a reference to the form that contains the page.

Methods

Page methods can be called at run time via scripts.

The following table shows the available Page methods and descriptions:

Methods	Descriptions
Activate	Displays the page.
Validate	Fires the OnValidate event for all controls on the page.

Referencing a page

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

Direct reference

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

JScript

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

Python

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

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 page 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")
Dim objPage
Set objPage = objForm.Pages("pgPage1")

JScript

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

Python

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

• 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 page in an event handling script. For example, use the following code to reference a page in its OnLoad event handler:

VBScript

Dim objPage
Set objPage = ThisEvent.Object

JScript

var objPage = ThisEvent.Object;

Python

objPage = ThisEvent.Object

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

VBScript

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

JScript

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

Python

objPage = ThisEvent.Object.Pages("pgPage1")

Displaying a page

By default, the first page of a form shows when the form initially displays. Use the Activate method to display a different page. The IsActive property tells you if a page is currently displayed. For example, if you have a form with two pages ("pgPageOne" and "pgPageTwo"), you can display the second page initially by using the following code in the form's OnLoad event handler:

VBScript

Dim objForm
Set objForm = ThisEvent.Object
objForm.Pages("pgPageTwo").Activate

JScript

var objForm = ThisEvent.Object;
objForm.Pages("pgPageTwo").Activate();

When using Python inside an ArcPad XML file, only single line scripts can be used. In Python, the preceding example looks like the following:

Python

ThisEvent.Object.Pages("pgPageTwo").Activate()

Initializing a page

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

VBScript

ThisEvent.Object.Caption = "New Page Caption"

JScript

ThisEvent.Object.Caption = "New Page Caption";

Python

ThisEvent.Object.Caption = "New Page Caption"

Preventing the Cancel button from closing the form

When the Cancel button is clicked on a form, an OnQueryCancel event is fired by the active page. By handling this event, you can add logic to prevent the form from closing. Since the OnQueryCancel event is fired by the Page object and not the Form object, you must handle this event in every page for a form if you want to handle it at all. For example, the following code prompts the user before closing the form when called in each page's OnQueryCancel event handler:

VBScript

Dim bResult
bResult = Application.MessageBox ("Cancel for sure?", apYesNo, "Cancel?")
If bResult = apNo Then
		 ThisEvent.Result = False
End If

JScript

var bResult = Application.MessageBox ("Cancel for sure?", apYesNo, "Cancel?");
if (bResult == apNo){
    ThisEvent.Result = false;
}

To 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

getCancel()

Inside the associated script file, the getCancel function displays a message box asking the user to confirm if they want to cancel the form.

Python

def getCancel():
    bResult = Application.MessageBox ("Cancel for sure?", Global.apYesNo, "Cancel?")
    if (bResult == Global.apNo):
		      ThisEvent.Result = False

Note:

In the VBScript and JScript examples above, the global ArcPad object is implied. In Python, the global ArcPad object must be explicit. Hence in the Python example, the yes/no object is explicitly written as Global.apYesNo, and in VBScript and JScript, apYesNo is sufficient.