SymbologyField controls

Use a SymbologyField control to show a list of symbols and labels as defined in the layer's symbology in a drop-down list. SymbologyField controls can only be added to layer attribute forms (Edit or Identify).

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

Although SymbologyField controls expose properties, methods, and events to the ArcPad object model, it is not expected that you will customize these controls. SymbologyField controls are highly automated controls that work directly with a layer's symbology definition (that is, the legend).

Attributes

SymbologyField 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 layer definition in ArcPad XML format.

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

Attributes	Descriptions
name	The name of the SymbologyField control. Used to reference the SymbologyField control in scripts.
width	The control's width.
height	The control's height.
x	The x-coordinate of the upper left corner of the button.
y	The y-coordinate of the upper left corner of the button.
sip	Specifies if the soft input panel (SIP) shows on pen devices when the control gets the focus.
defaultvalue	A simple expression that specifies the default value of the control.
group	Specifies if the SymbologyField 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.
backgroundcolor	The control's background color. If not specified, this value is inherited from the page's backgroundcolor attribute.
color	The control's text color. If not specified, this value is inherited from the page's color attribute.
font	The font for the control's text. If not specified, this value is inherited from the page's font attribute.
fontsize	The font size for the control's text. If not specified, this value is inherited from the page's fontsize attribute.
fontstyle	The font style for the control's text. If not specified, this value is inherited from the page's fontstyle attribute.
onsetfocus	The script to run when an OnSetFocus event occurs.
onkillfocus	The script to run when an OnKillFocus event occurs.

Events

SymbologyField 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 SymbologyField control events are available; however, except in specialized cases, it is not recommended that you write event handler script code for SymbologyField controls. SymbologyField is a highly automated control that works directly with the layer's legend.

The following table shows the available SymbologyField control events and descriptions:

Events	Description
OnKillFocus	Occurs when the control loses focus.
OnSetFocus	Occurs when the control gets the focus.

Properties

SymbologyField control properties can be read and set at run time via scripts. The following SymbologyField control properties are available; however, except in specialized cases, it is not recommended that you write script code for SymbologyField controls. SymbologyField is a highly automated control that works directly with the layer's legend.

Properties	Descriptions
DefaultValue	Returns or sets the default value expression for the symbology field.
Enabled	Returns or sets a value that determines if the symbology field is enabled.
hWnd	Returns the symbology field's window handle.
Index	Returns the symbology field's index.
ListCount	Returns the number of items in the list for the symbology field.
ListIndex	Returns or sets the index of the currently selected item in the symbology field.
Name	Returns the symbology field's name.
Parent	Returns a reference to the page that contains the symbology field.
Properties	Returns the value of the specified property for the symbology field.
Text	Returns the text of the item currently displayed in the symbology field.
Type	Returns the control type (for example, SYMBOLOGYFIELD for a symbology field).
Value	Returns the value for the item currently displayed in the symbology field.
Visible	Returns or sets a value that determines if the symbology field is visible.

Methods

SymbologyField control methods can be called at run time via scripts. The following SymbologyField control methods are available; however, except in specialized cases, it is not recommended that you write script code for SymbologyField controls. SymbologyField is a highly automated control that works directly with the layer's legend.

The following table shows the available SymbologyField method and description:

Method	Description
SetFocus	Sets the focus to the symbology field.

Referencing a SymbologyField control

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

Direct reference

This involves referencing a SymbologyField control via its name, page's name, form's name, and form's parent object. For example, use the following code to reference a SymbologyField control with the name "sfPoles" 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 objForm
Set objForm = Layer.Forms("EDITFORM")
Dim objPage
Set objPage = objForm.Pages("pgPage1")
Dim objSymbologyField
Set objSymbologyField = objPage.Controls("sfPoles")

JScript

var objForm = Layer.Forms("EDITFORM");
var objPage = objForm.Pages("pgPage1");
var objSymbologyField = objPage.Controls("sfPoles");

Python

objForm = Layer.Forms("EDITFORM")
objPage = objForm.Pages("pgPage1")
objSymbologyField = objPage.Controls("sfPoles")

The previous code assumes that it is present in the layer definition. If you need to reference the same SymbologyField control from a different layer definition or other customization file, explicitly reference the layer definition. See the following code:

VBScript

Dim objLayer
Set objLayer = Application.Map.Layers("Poles")
Dim objForm
Set objForm = objLayer.Forms("EDITFORM")
Dim objPage
Set objPage = objForm.Pages("pgPage1")
Dim objSymbologyField
Set objSymbologyField = objPage.Controls("sfPoles")

JScript

var objLayer = Application.Map.Layers("Poles");
var objForm = objLayer.Forms("EDITFORM");
var objPage = objForm.Pages("pgPage1");
var objSymbologyField= objPage.Controls("sfPoles");

Python

objLayer = Application.Map.Layers("Poles")
objForm = objLayer.Forms("EDITFORM")
objPage = objForm.Pages("pgPage1")
objSymbologyField = objPage.Controls("sfPoles")

Event reference

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

VBScript

Dim objSymbologyField
Set objSymbologyField = ThisEvent.Object

JScript

var objSymbologyField = ThisEvent.Object;

Python

objSymbologyField = ThisEvent.Object

To reference a "objSymbologyField" control with the name "sfPole" on a page with the name "pgPage1" in the OnLoad event handler of its form, use the following code:

VBScript

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

JScript

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

Python

objPage = ThisEvent.Object.Pages("pgPage1")
objSymbologyField = objPage.Controls("sfPole")