Option and Combobox Gadgets

The OPTION and COMBOBOX gadgets offer a single choice from a list of items. Clicking the down-arrow icon opens the drop-down list to allow a selection of a field from the choices. The currently selected field is highlighted. The two gadget types are similar, the main differences being:

• Option gadget's display text field cannot be edited.

• Combobox gadget's display text field is editable, just like a TEXT gadget.

• Combobox does not support the display of pixmaps.

The drop-down list is very similar to a Single Choice List Gadget and supports DTEXT, RTEXT, ZEROSELECT and NORESELECT properties. The same methods are used to manage the list's content. In just the same way it also allows UNSELECT and SELECT events. When the user presses the option gadget, the entire set of items is shown as a drop- down list and the user can then select a new item by clicking the option required. There is always a selected value unless the option list is empty. You can use the Add methods to add a single new entry to be appended to OPTION

gadgets:

Add( !Dtext is STRING )

Add( !Dtext is STRING, !Rtext is STRING )

Where Dtext is the text to be displayed in the option list, and Rtext is the replacement text for the new field. If Rtext is not specified, it will be set to the Dtext string by default.

20.8.1. Textual Option Gadgets

The width of a textual option gadget, in grid units, must be specified. A tag name is optional and is displayed to the left of the gadget.

option .Colour 'Colour' width 10

The current value in a textual option gadget is scrollable using the left- and right-arrow keys. This means you can specify a gadget that’s narrower than the options displayed in the dropdown list. The OPTION gadget actually contains two parallel lists of the same length, the display values (or Dtext ) and the replacement values (or Rtext). The list of display values must be supplied by assigning an array of values to the gadget's Dtext member. This is the list of choices displayed to the user. In Examples, the lines in the default constructor method define the Colour option gadget values as follows:

!ColourArray[1]='Black' !ColourArray[2]='White' !ColourArray[3]='Red' !ColourArray[4]='Green' !ColourArray[5]='Blue' !This.Layout2.Colour.Dtext=!ColourArray Other examples:

20.8.2. Combobox Gadgets

A COMBObox is a combination of an option gadget and text field. It can be defined by the command combo .Colour tagwid 5 'Colour' scroll 20 width 5 When the ComboBox is editable(default), with the drop-down list closed, the user can search for a required option by typing the first few letters into the display field and clicking the down-arrow. The list will open with the first matching option highlighted. This is useful for large lists.

The display field is accessible to the user, who can edit the contents by typing or pasting text into the field. If the user clicks ENTER while the gadget's text field has focus and has been modified, a VALIDATE event is raised. You can trap this event by assigning a PML Open callback to the gadget. This allows you to give meaning to the action of typing text into the display field. The Open callback is necessary to differentiate the VALIDATE event from the SELECT and UNSELECT events. On receipt of the VALIDATE event, your callback method can retrieve the displayed text by means of the DisplayText method and decide what action is associated. Additionally you can assign a popup menu to the gadget, which gives the user the choice of several actions. For example, you might append the current display text to the drop-down list as a new choice, possibly ensuring that there are no duplicate entries. An assigned popup menu could allows options to be removed from the drop-down list and the editable status of the combobox to be toggled. (PML example code is available as User Manual example Layout2.pmlfrm which can be obtained from AVEVA's support web site.) 20.8.3. Pixmap Option Gadgets

The gadget-shape must be specified, using the WIDTH keyword and either HEIGHT or ASPECT. A tag name is optional and is displayed to the left of the gadget. The display text should be set to pixmap’s filename and assigned to the Dtext member:

!CircleDtextsArray[1] = '/directory/circle/cenrad' !CircleDtextsArray[2] = '/directory/circle/3pts' !!MyForm.Circle.Dtext = !CircleArray

option .Circle1 AT . . . callback '!!MyFunc()' PIXMAP width 256 height 128 option .Circle2 AT . . . callback '!!MyFunc()' PIXMAP width 256 aspect 2.0

The replacement-texts, if needed, are set by assigning an array of values to the Rtext member.

!CircleRtextsArray[1] = 'Specify centre and radius' !CircleRtextsArray[2] = 'Pick three points on the circumference'

!!MyForm.Circle.Rtext = !CircleArray

20.8.4. Setting and Getting the Current Selection

The default selection is the first value in the list. You can explicitly set the currently selected value by means of the option gadget's select() method:

!!Layout2.Colour.select('Dtext','Orange')

!!MyForm.Circle.select('directory/circle/cenrad')

You can read the current selection using the selection() method. This will return the replacement-text (or the display-text if replacement-texts were not defined):

!SelectedText = !This.List.Selection()

The .val member reads the index number of the currently selected value: !ChosenNumber = !!Form.List.Val

The clear() method will discard both display- and replacement-text lists: !!MyForm.Colours.clear()