OPTION Gadget

Software Customisation Reference Manual

Summary of Objects, Members and Methods : Object Type Details : OPTION Gadget


Name	Type	Purpose
DText	ARRAY OF STRING Get/Set	Set or get the entire list of display texts.
DText[n]	STRING Get Only	Get the display text of the n'th option.
RText	ARRAY OF STRING Get/Set	Set or get the list of replacement texts.
RText[n]	STRING Get Only	Get the replacement text of the n'th option.
Count	REAL Get only	Get count of number of fields in the list.
Val	REAL Get/Set	Selected field as integer. Zero implies no selection. Setting val to zero will cause an error if ZeroSel is not specified.

Methods


Name	Result	Purpose
Add(STRING Dtext)	NO RESULT	Append an entry to the drop down list, where Dtext is the text to display in the option list.
Add(STRING Dtext, STRING Rtext))	NO RESULT	Append and entry to the drop down list, where Dtext is the text to display in the option list, and Rtext is the replacement text for the new field. If Rtext isn’t specified, it will be set to Dtext by default.
Clear()	NO RESULT	Clear gadget’s contents.
ClearSelection()	NO RESULT	Clears selection and returns to default of first in list.
FullName()	STRING	Get the full gadget name, e.g.'!!Form.gadget'
Name()	STRING	Get the gadget's name, e.g. 'gadget'
Owner()	FORM	Get owning form.
Select(STRING text, STRING value )	NO RESULT	Select specified item in a list: text must be ‘Rtext’ or ‘Dtext’, and value is the item to be selected.
Selection()	STRING	Get current selection’s RTEXT.
Selection(STRING text )	STRING	Get RTEXT or DTEXT of current selection; text must be ‘Rtext’ or ‘Dtext’.
SetPopup(MENU menu)	NO RESULT	Links menu with the gadget as a popup.
Refresh()	NOT RESULT	Refreshes the display of the gadget.
SetFocus()	NO RESULT	Move keyboard focus to this gadget.
RemovePopup(MENU menu)	NO RESULT	Removes (popup) menu from the gadget.
GetPickedPopup()	MENU	Returns the last picked popup menu for the gadget.
Shown()	BOOLEAN	Get ‘shown’ status.
Type()	STRING	Get the gadget type as a string.
Background()	STRING	Get Background Colour Name. Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
DisplayText( )	STRING	Gets the text string currently displayed in the Option gadget's display field.
SetPopup( !menu )	NO RESULT	Assigns a menu object as the gadget's current popup.
Clear( !dtext )	NO RESULT	Delete the field with the given DTEXT string.
Clear( !fieldNumber )	NO RESULT	Delete the specified field number.

Command

The OPTION command defines an option gadget and specifies the position, tag or pixmap, and callback text of the option (or list button) gadget. Also sets the width allowed for displaying the list options when the gadget is selected.

The arrays defining the display texts and replacement texts for the gadget should be set in the form's default constructor method.

Notes:

Option gadget's display text field is non editable, so doesn't need scroll width (syntax is in fact in place for backwards compatibility).


.-------<-------. / \| >------ OPTion gname -+- <fgtagw> ------\| +- <fgpos> -------\| +- <fganch> ------\| +- CALLback text -\| +- TOOLTIP text --\| +- NORESELect ----\| +- ZEROSELection -\| +- CORE ----------* Core managed gadget \| +- PIXmap <vshap> -. '- <vwid> ---------+- TOOLTIP text -. '----------------'-->

Reselection of the Selected Field can be Disallowed

There is a new keyword NORESELECT which disables UNSELECT and SELECT events when the currently selected field is re-clicked with the mouse, for example:

option .o1 tagwid $!w |Choose| noResel width 5 tooltip 'select option'

ZeroSelection Property

Option gadgets have a ZeroSelection keyword (similar to that of single choice lists), which allows it to support the notion of no current selection (previously a selection was mandatory).

The syntax has been extended with the optional 'ZEROSELection' keyword, e.g.

option .choose tagWid 3 |Cars| . . . zeroSel noResel width 25 length 10

Behaviour

Note:

It is bad practice to place one gadget on top of another. This may lead to gadgets being obscured.

Unselected Events

Option gadgets support UNSELECT events. Typically when a field in the dropdown list is selected, an UNSELECT event is raised for the previously selected field (if any) and then a SELECT event is raised for the new field.

Notes:

UNSELECT events are not notified to PML unless an open callback has been specified (so that SELECT and UNSELECT events can be differentiated).

Typically the UNSELECT action allows Appware to manage consequences of deselection for any dependent gadgets or forms.

We recommend that you do not change the option gadget's selection programmatically in an UNSELECT event.