Combobox

A combobox item is used to place a combo box list in the rollout. This is a variant of the drop-down list in which the list is always fully displayed in the rollout with an additional edit-text box at the top of the list where the current selection is placed and may be edited. The user can scroll the list or click to select an item in the list. The syntax is:

combobox <name> [ <caption> ] [items:<array_of_strings>] [selection:<number>] [height:<number>]

The default alignment of combobox items is #left.

Example:

rollout combobox_test "Combo Box"

(

 combobox scale_cb "Scale" items:#("1/2", "1/4", "1/8", "1/16")

 on scale_cb selected i do

  format "You selected '%'!\n" scale_cb.items[i]

)

createDialog combobox_test

combobox_test.scale_cb.selected = "new item text"

 

Parameters

text:

The text string in the edit box.

items:

The array of text strings that are the items in the list

selection:

The 1-based number of the currently selected item in the list. Defaults to 1.

height:

The overall height of the combobox in number of item lines. Defaults to 10 lines. To have a combobox display exactly N items in the list, set height to N+2.

The minimum height value is clamped to 1 line.

Properties

<combobox>.caption String

The text of the optional caption above the combo box.

<combobox>.text String

The text in the edit box.

<combobox>.items Array of Strings

The item string array.

<combobox>.selection Integer

The currently selected item number, 1-based. If the items list is an empty array, this value is 0.

<combobox>.selected String

The text of the currently selected item. Can be used to replace individual items without resetting the entire items array. If the items list is an empty array, this value is undefined.

<combobox>.width Integer

Get/set the width of the combobox list window in pixels.

<combobox>.height Integer

Get/set the height of the combobox list window in pixels.

Notes

that as constructor parameter, the height specifies the height in lines of text!

The height property does not include the height of the edit-text box. The minimum height setting is clamped at 0 pixels.

Events

on <combobox> selected <arg> do <expr>

Called when the user selects an item in the combo box list. The <arg> argument contains the new current selection item number.

 

on <combobox> doubleClicked <arg> do <expr>

Called when the user double-clicks an item in the list. Note that the on selected handler is always called on single clicks and on the first click of a double-click. The <arg> argument will contain the number of the item double-clicked.

For example

rollout combobox_test "Combo Box"

(

 combobox scale_cb "Scale" items:#("1/2", "1/4", "1/8", "1/16")

 on scale_cb doubleClicked itm do

  format "You double-clicked '%'!\n" scale_cb.items[itm]

)

createDialog combobox_test

 

on <combobox> entered <arg> do <expr>

Called when the user changes the text in the edit box then changes the focus away from the edit box. This handler is not called if the user presses ENTER. The <arg> argument will contain the new text in the edit box.

For example

rollout combobox_test "Combo Box"

(

 combobox scale_cb "Scale" items:#("1/2", "1/4", "1/8", "1/16")

 on scale_cb entered txt do scale_cb.selected = txt

)

createDialog combobox_test

 

on <combobox> changed <arg> do <expr>

Called for each individual character change the user performs in the edit box. This handler is not called when the user presses ENTER or changes the focus away from the edit box. The <arg> argument will contain the new text in the edit box.

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types