Table of Contents

combobox

`combobox()` creates a drop-down list. Item indexes start at `1`; `0` means no selection. Adding text `—` creates a separator and does not increase `count`.

Constructor

combobox()

Creates a combobox object.

Item Description
Syntax `combobox()`
Arguments none
Returns combobox object

Example: 

combo = combobox().add('One').add('Two').item(1);

Properties

Properties are read-only. Use methods to change GUI object state.

Property Type Description
`position_x` number Current x position.
`position_y` number Current y position.
`size_width` number Current width.
`size_height` number Current height.
`visible` boolean Current visible state.
`enabled` boolean Current enabled state.
`text` string Current displayed text.
`item` number Current selected item index. `0` means no selection.
`count` number Number of selectable items. Separators are not counted.
`item_text` string Text of the selected item, or empty string when no item is selected.

Common Object Methods

to_string()

Returns a display string for the object.

Item Description
Syntax `value.to_string()`
Arguments none
Returns string

Example: 

text = value.to_string();

`clone()` is not supported for `combobox`.

Most visible GUI controls support these methods.

position(x, y)

Sets the component position in pixels.

Item Description
Syntax `component.position(x, y)`
Arguments `x`: x position; `y`: y position
Returns component object

Example: 

label().position(20, 10);

size(width, height)

Sets the component size in pixels. Width and height are clamped to at least `1`.

Some container objects, such as `panel()` and `group()`, use `size(-1, -1)` as a special fit-parent mode.

Item Description
Syntax `component.size(width, height)`
Arguments `width`: width in pixels; `height`: height in pixels
Returns component object

Example: 

textinput().size(220, 26);

visible(enabled)

Shows or hides the component.

Item Description
Syntax `component.visible(enabled)`
Arguments `enabled`: boolean
Returns component object

Example: 

status.visible(false);

enabled(enabled)

Enables or disables user interaction with the component.

Item Description
Syntax `component.enabled(enabled)`
Arguments `enabled`: boolean
Returns component object

Example: 

run_button.enabled(false);

Methods

add(text)

Adds an item. Text `—` adds a separator. Separators are displayed in the list but are not counted by `count` and do not receive item indexes.

Item Description
Syntax `combobox.add(text)`
Arguments `text`: item text, or `—` for a separator
Returns combobox object

Example: 

combo = combobox()
    .add('One')
    .add('---')
    .add('Two');

text(value)

Sets current displayed text.

Item Description
Syntax `combobox.text(value)`
Arguments `value`: text value
Returns combobox object

Example: 

combo = combobox().text('Custom');

item(index)

Selects item by 1-based index. `0` clears selection. Index is clamped to `0..count`.

Item Description
Syntax `combobox.item(index)`
Arguments `index`: item index
Returns combobox object

Example: 

combo = combobox().add('One').add('Two').item(2);

on_change(callback)

Sets a callback called when selection changes.

Item Description
Syntax `combobox.on_change(callback)`
Arguments `callback`: callable with one argument, the selected item index
Returns combobox object

Example: 

function mode_changed(index)
{
    print('mode index: ', index);
}
 
combo = combobox().on_change(mode_changed);

Example

mode = combobox()
    .position(20, 20)
    .size(180, 26)
    .add('Roughing')
    .add('Finishing')
    .item(1);
 
window().title('ComboBox').size(240, 100).add(mode).show();

Previous: slider

Next: listbox