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:
- Text—Can be read with the Text property and displays to the user.
- Value—Can be read with the Value property and is stored in the attribute associated with the DomainField control.
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