DomainField controls

Use a DomainField control when you have a field with a subtype, coded value domain, or range domain in an ArcPad Exchange File (AXF) layer and you want ArcPad to automatically restrict the control to valid values from the subtype or domain.

The DomainField control also automatically switches between different domains (that is, no domain, range domain, or coded value domain) when governed by a subtype field associated with another DomainField control. DomainField controls can only be added to layer forms (Edit, Identify, or Query).

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

Although DomainField controls expose properties, methods, and events to the ArcPad object model, it is not expected that you will customize these controls. DomainFields are highly automated controls that work directly with the database schema to ensure validation for a particular field.

Attributes

DomainField 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, onchange) 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 layer definition in ArcPad XML format.

The following table shows the available DomainField control attributes and descriptions:

Attributes

Descriptions

name

The name of the DomainField control. Used to reference the DomainField control in scripts.

width

The control's width.

height

The control's height.

x

The x-coordinate of the upper left corner of the control.

y

The y-coordinate of the upper left corner of the control.

sip

Specifies if the soft input panel (SIP) displays on pen devices when the control gets the focus.

required

Specifies if the user must select an item on the control.

defaultvalue

A simple expression that specifies the control's default value.

group

Specifies if the DomainField control starts a new group of controls.

border

Specifies if the control has a border.

tabstop

Specifies if the TAB key can be used to move the focus to the control.

readonly

Specifies if the control's value can be modified by the user.

field

The field of the layer that is linked to the DomainField control.

sort

Specifies if the items in the control are automatically sorted alphabetically.

background color

The control's background color. If not specified, this value is inherited from the page's backgroundcolor attribute.

color

The color to use for the control's text. If not specified, this value is inherited from the page's color attribute.

font

The font to use for the control's text. If not specified, this value is inherited from the page's font attribute.

fontsize

The font size to use for the control's text. If not specified, this value is inherited from the page's fontsize attribute.

fontstyle

The font style to use for the control's text. If not specified, this value is inherited from the page's fontstyle attribute.

onchange

The script to run when an OnChange event occurs.

oncloseup

The script to run when an OnCloseUp event occurs.

ondropdown

The script to run when an OnDropDown event occurs.

onselchange

The script to run when an OnSelChange event occurs.

onselcancel

The script to run when an OnSelCancel event occurs.

onselok

The script to run when an OnSelOK event occurs.

onsetfocus

The script to run when an OnSetFocus event occurs.

onkillfocus

The script to run when an OnKillFocus event occurs.

onvalidate

The script to run when an OnValidate event occurs.

Events

DomainField 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. DomainField is a highly automated control that works directly with the database schema to ensure validation for a particular field.

The following table shows the available DomainField control events and descriptions; however, except in specialized cases, it is not recommended that you write event handler script code for DomainField controls:

Events

Descriptions

OnChange

Occurs when the user types within the text box portion of the domain field.

OnCloseUp

Occurs when the drop-down portion of the domain field is closed.

OnDropDown

Occurs when the drop-down portion of the domain field is displayed.

OnKillFocus

Occurs when the domain field loses the focus.

OnSelCancel

Occurs when the drop-down list of the domain field is triggered, but the user does not select a value. Also occurs when the domain field loses focus.

OnSelChange

Occurs when the selection within the domain field is changed.

OnSelOK

Occurs when an item is selected from the list in the domain field.

OnSetFocus

Occurs when the domain field gets the focus.

OnValidate

Occurs when the domain field is validated.

Properties

DomainField control properties can be read and set at run time via scripts. DomainField is a highly automated control that works directly with the database schema to ensure validation for a particular field.

The following table shows the available DomainField control properties and descriptions; however, except in specialized cases, it is not recommended that you write script code for DomainField controls:

Properties

Descriptions

DefaultValue

Returns or sets the default value expression for the domain field.

Enabled

Returns or sets a value that determines if the domain field is enabled.

Field

Returns a reference to the feature attribute field to which the domain field is bound.

hWnd

Returns the domain field's window handle.

Index

Returns the domain field's index.

ListCount

Returns the number of items in the list for the domain field.

ListIndex

Returns or sets the index of the currently selected item in the domain field.

Name

Returns the domain field's name.

Parent

Returns a reference to the page that contains the domain field.

Properties

Returns the value of the specified property for the domain field.

Text

Returns the text of the currently displayed item in the domain field.

Type

Returns the control type (DOMAINFIELD) for a domain field.

Value

Returns the value of the item currently displayed in the domain field.

Visible

Returns or sets a value that determines if the domain field is visible.

Methods

DomainField control methods can be called at run time via scripts. DomainField is a highly automated control that works directly with the database schema to ensure validation for a particular field.

The following table shows the available DomainField control method and description; however, except in specialized cases, it is not recommended that you write script code for DomainField controls:

Method

Description

SetFocus

Sets the focus to the domain field.

Referencing a DomainField control

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

Direct reference

This involves referencing a DomainField control via its name, page's name, form's name, and form's parent object. For example, use the following code to reference a DomainField control with the name "dfPoleType" on a page with the name "pgPage1" in an Edit form with the name "EDITFORM" that is present in a layer with the name "Poles":

VBScript

Dim objLayer
Set objLayer = Layers("Poles")
Dim objForm 
Set objForm = objLayer.Forms("EDITFORM")
Dim objPage
Set objPage = objForm.Pages("pgPage1")
Dim objDomainField
Set objDomainField = objPage.Controls("dfPoleType")

JScript

var objLayer = Layers("Poles");
var objForm = objLayer.Forms("frmSettings");
var objPage = objForm.Pages("pgPage1");
var objDomainField = objPage.Controls("dfPoleType");

Python

objForm = objLayer.Forms("frmSettings")
objForm = Applet.Forms("frmSettings")
objPage = objForm.Pages("pgPage1")
objDomainField = objPage.Controls("dfPoleType")

The previous code assumes that it is present in the layer definition. You can not reference a DomainField control from a different layer definition in your current layer definition.

Event reference

This is the recommended approach and involves referencing a DomainField control in an event handling script. For example, use the following code to reference a DomainField control in its OnSelChange event handler:

VBScript

Dim objDomainField
Set objDomainField = ThisEvent.Object

JScript

var objDomainField = ThisEvent.Object;

Python

objDomainField = ThisEvent.Object

Use the following code to reference a DomainField control with the name "dfPoleType" 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("dfPoleType")

JScript

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

Python

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

Text vs. Value in a DomainField control

Items displayed in a domain field have the following components:

Selecting an item in a DomainField control

To select an item in a domain field at run time, set its ListIndex property to the index of the applicable list item. For example, use the following code to select the third list item in a domain field referenced by the variable, objDomainField:

VBScript

objDomainField.ListIndex = 2

JScript

objDomainField.ListIndex = 2;

Python

objDomainField.ListIndex = 2

2/7/2013