ListBox

This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Functions

The ListBox are controls that display a series of elements as a list (Figure 1), (Figure 2), (Figure 3). Depending on how it is configured, we can select one or more elements or view checkboxes to check them. The control enables scroll bars when necessary and allows keyboard navigation. In Hello ListBox! you have an example of use.

• Use listbox_create to create a list control.
• Use listbox_add_elem to add an element.
• Use listbox_multisel to enable the multiple selection.
• Use listbox_checkbox to enable the checkboxes.
• Use listbox_OnSelect to respond to the selection.

listbox_create ()

Create a new list control.

ListBox*
listbox_create(void);

Return

The newly created listbox.

listbox_OnDown ()

Sets a handler for a mouse button press.

void
listbox_OnDown(ListBox *listbox,
               Listener *listener);

1
2
3
4
5
6
7
8
9

static void i_OnDown(App *app, Event *e)
{
    const EvMouse *p = event_params(e, EvMouse);
    bool_t *r = event_result(e, bool_t);
    p->tag      // Clicked row (UINT32_MAX) if any.
    *r = FALSE; // Avoid item selection.
}
...
listbox_OnDown(list, listener(app, i_OnDown, App));

Remarks

This event is processed before listbox_OnSelect. In the tag field of EvMouse the number of the element clicked will be received or UINT32_MAX if it corresponds to an empty area of the ListBox. If the event returns FALSE on event_result, the element will be prevented from being selected (TRUE by default). See GUI Events.

listbox_OnSelect ()

Set an event handler for the selection of a new item.

void
listbox_OnSelect(ListBox *listbox,
                 Listener *listener);

1
2
3
4
5
6
7

static void i_OnSelect(App *app, Event *e)
{
    const EvButton *p = event_params(e, EvButton);
    do_something_onselect(app, p->index);
}
...
listbox_OnSelect(list, listener(app, i_OnSelect, App));

Remarks

See GUI Events.

listbox_size ()

Set the default size of the list.

void
listbox_size(ListBox *listbox,
             const S2Df size);

Remarks

It corresponds to Natural sizing of control Default 128x128.

listbox_checkbox ()

Show or hide checkboxes to the left of items.

void
listbox_checkbox(ListBox *listbox,
                 const bool_t show);

listbox_multisel ()

Enable multiple selection.

void
listbox_multisel(ListBox *listbox,
                 const bool_t multisel);

listbox_add_elem ()

Adds a new element.

void
listbox_add_elem(ListBox *listbox,
                 const char_t *text,
                 const Image *image);

listbox_set_elem ()

Edit a list item.

void
listbox_set_elem(ListBox *listbox,
                 const uint32_t index,
                 const char_t *text,
                 const Image *image);

listbox_clear ()

Remove all items from the list.

void
listbox_clear(ListBox *listbox);

listbox_color ()

Sets the text color of an element.

void
listbox_color(ListBox *listbox,
              const uint32_t index,
              const color_t color);

listbox_select ()

Select an item from the program code.

void
listbox_select(ListBox *listbox,
               const uint32_t index,
               const bool_t select);

Remarks

If multiple selection is not enabled, selecting one item implies de-selecting all the others.

listbox_check ()

Check or uncheck the checkbox of the element from the program code.

void
listbox_check(ListBox *listbox,
              const uint32_t index,
              const bool_t check);

Remarks

Checking an item is independent of selecting it. Items can be marked even if checkboxes are not visible. See listbox_checkbox.

listbox_count ()

Returns the number of elements in the list.

uint32_t
listbox_count(const ListBox *listbox);

Return

The number of elements.

listbox_text ()

Returns the text of an element.

const char_t*
listbox_text(const ListBox *listbox,
             const uint32_t index);

Return

The UTF-8 text terminated in null character '\0'.

listbox_selected ()

Returns whether or not an element is selected.

bool_t
listbox_selected(const ListBox *listbox,
                 const uint32_t index);

Return

The selection state.

listbox_checked ()

Returns whether an element is checked or not.

bool_t
listbox_checked(const ListBox *listbox,
                const uint32_t index);

Return

The checkbox state.

Remarks

Checking an item is independent of selecting it. Items can be marked even if checkboxes are not visible. See listbox_checkbox.