COMBOBOX Gadget

Software Customisation Reference Manual

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


Name	Type	Purpose
Val	REAL Get/Set	Selected option number.
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.
Editable	BOOLEAN Get/Set	Controls editable status of the text display field (ComboBox only)
Scroll	INTEGER Get/Set	Controls the maximum length of a text string which can be held and scrolled in the display text field (ComboBox only)
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’.
SetDisplayText( STRING text )	NO RESULT	Set the display text field value, if the gadget is editable.
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

                            .-------<-------.

                           /                |

      >-- COMBObox gname -+- <fgtagw> ------|

                          +- <fgpos> -------|

                          +- <fganch> ------|

                          +- CALLback text -|

                          +- TOOLTIP text --|

                          +- NORESELect ----|

                          +- ZEROSELection -|

                          +- CORE ----------* Core managed gadget

                          | .-------<-------.

                          |/                |

                          +- SCRoll int ----|

                          +- <vwid> --------*

|

                          +- TOOLTIP text -.

                          '----------------'-->

When the ComboBox is editable, with the drop-down list closed, you 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.

Behaviour

The COMBOBOX command is a combination of an option list and an editable text display field similar to a windows combobox. It shares most of the properties and methods of the Option gadget.

Combo gadget has editable display text field (default) and so supports scroll width. Combobox does not support display of pixmaps.

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.

Text Entry and Editing

When the editable property is set (default), the display field is accessible to you, who can edit the contents by typing at the keyboard or pasting text into the field. It behaves in a similar way to a Text field, and can be 'actioned' by 'Tabbing away', or by clicking another gadget or form, or by pressing the ENTER key. When 'actioned' a VALIDATE event is raised. You can trap this event by assigning a PML Open callback to the gadget. This callback 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 you the choice of several actions.