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")

2/7/2013