COMBOBOX Gadget
- Last UpdatedNov 07, 2024
- 4 minute read
Members
|
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 nth 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 nth 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, for example, '!!Form.gadget'. |
|
Name() |
STRING |
Get the gadget's name, for example, '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 RTEXT of the current selection. |
|
Selection(STRING text ) |
STRING |
Get RTEXT or DTEXT of the 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 (pop-up) menu from the gadget. |
|
GetPickedPopup() |
MENU |
Returns the last picked pop-up menu for the gadget. |
|
Shown() |
BOOLEAN |
Get ‘shown’ status. |
|
Type() |
STRING |
Get the gadget type as a string. |
|
Background() |
STRING |
Get Background Color Name. Some gadgets do not support this property in all circumstances, for example, gadgets, which are showing a pixmap. Gadgets whose color has not been set explicitly, may not have a color with a known colorname. 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 pop-up. |
|
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.
Behavior
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 de-selection 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.