Table of Contents

listbox

`listbox()` creates a list selection control. Row indexes start at `0`; `-1` means no selection.

Constructor

listbox()

Creates a listbox object.

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

Example: 

list = listbox().add('First').add('Second').row(0);

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.
`count` number Number of rows.
`row` number Current selected row. `-1` means no selection.
`row_text` string Text of the selected row, or empty string when no row 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 `listbox`.

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 a row at the end of the list.

Item Description
Syntax `listbox.add(text)`
Arguments `text`: row text
Returns listbox object

Example: 

list = listbox().add('probe.expr').add('warmup.expr');

insert(index, text)

Inserts a row. Index is clamped to the valid insert range.

Item Description
Syntax `listbox.insert(index, text)`
Arguments `index`: 0-based insert index; `text`: row text
Returns listbox object

Example: 

list.insert(0, 'first.expr');

remove(index)

Removes a row by 0-based index.

Item Description
Syntax `listbox.remove(index)`
Arguments `index`: 0-based row index
Returns listbox object

Example: 

list.remove(1);

clear()

Removes all rows and clears selection.

Item Description
Syntax `listbox.clear()`
Arguments none
Returns listbox object

Example: 

list.clear();

row(index)

Selects a row by 0-based index. Use `-1` to clear selection.

Item Description
Syntax `listbox.row(index)`
Arguments `index`: 0-based row index, or `-1`
Returns listbox object

Example: 

list.row(0);

double_click(index)

Simulates double-clicking a row by 0-based index.

Item Description
Syntax `listbox.double_click(index)`
Arguments `index`: 0-based row index
Returns listbox object

Example: 

list.double_click(0);

on_select(callback)

Sets a callback called when selection changes.

Item Description
Syntax `listbox.on_select(callback)`
Arguments `callback`: callable with one argument, the selected row index
Returns listbox object

Example: 

function selected(row)
{
    print('row: ', row);
}
 
list = listbox().on_select(selected);

on_double_click(callback)

Sets a callback called when a row is double-clicked.

Item Description
Syntax `listbox.on_double_click(callback)`
Arguments `callback`: callable with one argument, the double-clicked row index
Returns listbox object

Example: 

function row_open(row)
{
    print('open row: ', row);
}
 
list = listbox().on_double_click(row_open);

Example

programs = listbox()
    .position(20, 20)
    .size(220, 120)
    .add('probe.expr')
    .add('warmup.expr')
    .row(0);
 
window().title('ListBox').size(280, 190).add(programs).show();

Previous: combobox

Next: progressbar