IupList

IupList

Creates a list interface element, which is a list of two-state (on or off) items. An action is generated when an event changes the state of an item.

Creation

Ihandle* IupList(char *action); [in C]
iuplist{} -> (elem: iuplua_tag) [in IupLua3]
iup.list{} -> (elem: iuplua_tag) [in IupLua5]
list(action) [in LED]

action: String with the name of the action generated when the state of an item is changed.

This function returns the identifier of the created list, or NULL (nil in IupLua) if an error occurs.

Attributes

"1": First item in the list.
"2": Second item in the list.
"3": Third item in the list.
...
"n": n^th item in the list.

The values can be any text. Default: NULL. The first element with a NULL is considered the end of the list. The string containing the item's number does not need to be static, because IUP duplicates it internally, but the contents of each element in the list needs to be either static or stored in IUP by means of the IupStoreAttribute function.

DROPDOWN: Changes the appearance of the list for the user: only the selected item is shown beside a button with the image of an arrow pointing down. Creation-only attribute. Can be "YES" or "NO". Default "NO".

EDITBOX: Adds an edit box to the list. Creation-only attribute. Can be "YES" or "NO". Default "NO".

VISIBLE_ITEMS: Number of items that appear when a DROPDOWN list is activated. Default: Depends on the native system.

MULTIPLE: Allows selecting several items simultaneously (multiple list). Default: "NO".

SIZE: Size of the list. Default: smallest size that allows viewing the list.

VALUE: Depends on the list type:

List with edit box: Text entered by the user.  
Simple list: Integer number representing the selected element in the list (begins at 1). It can be zero if there is no selected item.
Multiple list: Sequence of '+' and '-' symbols indicating the state of each item. When setting this value, the user must provide the same amount of '+' and '-' symbols as the amount of items in the list, otherwise the specified items will be deselected.

APPEND: Inserts a text at the end of the current text. Valid only when EDITBOX=YES.

INSERT: Inserts a text in the caret's position. Valid only when EDITBOX=YES.

NC: Maximum number of characters allowed. Valid only when EDITBOX=YES.

CARET: Position of the insertion point. Valid only when EDITBOX=YES.

READONLY: Allows the user only to read the contents, without changing it. Possible values: YES, NO (default).  Valid only when EDITBOX=YES.

SELECTION: Selection interval. Valid only when EDITBOX=YES.

SELECTEDTEXT: Selection text. Valid only when EDITBOX=YES.

SHOWDROPDOWN: Opens a dropdown list. Windows Only.

Callbacks

ACTION: Action generated when the state of an item in the list is changed. Also provides information on the changed item:

int function (Ihandle *self, char *t, int i, int v); [in C]
elem:action(t: string, i, v: string) -> (ret: number) [in IupLua]

t: Text of the changed item.
i: Number of the changed item.
v: Equal to 1 if the option was selected or to 0 if the option was deselected.

EDIT_CB: Action generated when the text in the text box is manually changed by the user. Valid only when EDITBOX=YES.

int function(Ihandle *self, int c, char *after); [in C]
elem:action(c: number, after: string) -> (ret: number) [in IupLua]

text: Represents the new text value. This is the same callback definition as for the IupText.

CARET_CB: Action generated when the caret/cursor position is changed.  Valid only when EDITBOX=YES.

int function(Ihandle *self, int row, int col); [in C]
elem:caretcb(row, col: number) -> (ret: number) [in IupLua3]
elem:caret_cb(row, col: number) -> (ret: number) [in IupLua5]

row, col: Row and collumn number.

Notes

Text is always left aligned.

Examples

See Also

IupListDialog, Iuptext