ListBoxItem

 

ListBoxItems are items of a ListBox.

 

ListBox with 3 ListBoxItems inserted in a Grid panel as seen in Lycia Form Designer

 

 

Form XML code:

 

<ListBoxItem text="value1" identifier="f1_1"/>

 

CSS element selector code:

 

qx-aum-list-box-item

 

Most commonly used form properties:

identifier

text

value

 

Inheritance diagram:

 

 

Associated ui methods:

AddItem ↓

GetItemCount →

GetItemName ↓

GetItemText ↓

GetTextOf ↓

RemoveItem ↓

SetSelectedItems

GetSelectedItems

 

Influence and behavior:

 

 

 

 

 

To add a ListBoxItem to your form,

 

Step 1

Choose a ListBoxItem widget from the widgets palette by left-clicking its icon:

 

 

Step 2

Move the cursor to the ListBox (ListBoxItems are added directly to the ListBox):

 

 

Step 3

Left-click to add a ListBoxItem to the ListBox:

 

 

 

The ListBoxItem is now added to your form, and you can see it in the Structure view.

 

 

 

 

 

 

 

Every ListBoxItem can have three properties and is thus characterized by three parameters - identifier, text, and value - where identifier is set automatically, and both text and value can be set by the user:

 

 

At runtime, the ListBoxItem is displayed with its text, and its value is passed to a variable receiving the input (refer here for the INPUT example):

 

 

If the text is not specified, the ListBoxItem will have no text at runtime and will seem to be invisible but can be selected (and its value will be passed to a variable):

 

 

If the value is not specified, the text of the ListBoxItem will be passed to a receiving variable:

 

 

 

 

 

 

At runtime, textAreas can be manipulated with ui methods.

 

There is NO such a ui object as ui.ListBoxItem.

All the methods described below must be applied to the ui.Listbox object:

DEFINE listbox_var ui.ListBox

...

LET listbox_var = ui.ListBox.ForName("listbox_id")

 

All the examples given below are taken from the example program.

 

addItem adds a new ListBoxItem with a specified text and/or value to a ListBox:

 

CALL listbox_var.addItem("<item_value>", "<item_text>")

 

 

What ListBoxItem is removed depends on the value specified:

 

CALL lbx.AddItem("4", "Four")

-- adds an item with text = Four and value = 4

CALL lbx.AddItem("4", "")

-- adds an item with  value = 4 which is displayed as the item text as well

CALL lbx.AddItem("", "Four")

-- adds an item with text = Four and no value

CALL lbx.AddItem("", "")

-- adds an item with no text and no value (can be selected)

CALL lbx.AddItem("")

-- adds an item with no text and no value (can be selected)

 

Here you can find out how to remove all ListBoxItems from a ListBox at runtime by using the Clear method.

 

Here you can find out how to get the number of ListBoxItems in a ListBox at runtime by using the getItemCount method.

 

getItemName returns the value of a ListBoxItem identified by its position. Requires an integer index of a ListBoxItem's position as a parameter:

 

CALL listbox_var.getItemName(2)

 

 

getItemText returns the text of a ListBoxItem identified by its position. Requires an integer index of a ListBoxItem's position as a parameter:

 

CALL listbox_var.getItemText(2)

 

 

getTextOf returns the text of a ListBoxItem identified by its value and-or text:

 

CALL listbox_var.getTextOf("<item_value>", "<item_text>")

 

 

Generally, the value specifies the ListBoxItem which text will be returned:

 

CALL lbx.GetTextOf("3", "Three")

-- returns the text of the item with text = Three and value = 3

CALL lbx.GetTextOf("3", "")

-- returns the text of the item with text = Three and value = 3

CALL lbx.GetTextOf("3")

-- returns the text of the item with text = Three and value = 3

CALL lbx.GetTextOf("3", "Two")

-- returns the text of the item with text = Three and value = 3

CALL lbx.GetTextOf("", "Three")

-- returns NO text including the text of the item with text = Three and value = 3

CALL lbx.GetTextOf("Three")

-- returns NO text including the text of the item with text = Three and value = 3

CALL lbx.GetTextOf("2", "Three")

-- returns the text of the item with text = Two and value = 2

 

Only if a ListBoxItem has no specified value, its text can be returned by specifying the text only.

 

removeItem removes a ListBoxItem with a specified text and/or value from the ListBox:

 

CALL listbox_var.removeItem("<item_value>", "<item_text>")

 

 

What ListBoxItem is removed depends on the value specified:

 

CALL lbx.RemoveItem("4", "Four")

-- removes the item with text = Four and value = 4

CALL lbx.RemoveItem("4", "")

-- removes the item with text = Four and value = 4

CALL lbx.RemoveItem("", "Four")

-- removes NO items including the item with text = Four and value = 4

CALL lbx.RemoveItem("5", "Four")

-- removes the item with text = Five and value = 5

CALL lbx.RemoveItem("4", "Five")

-- removes the item with text = Four and value = 4

CALL lbx.RemoveItem("4")

-- removes the item with text = Four and value = 4

CALL lbx.RemoveItem("Four")

-- removes NO items including the item with text = Four and value = 4

 

Only a ListBoxItem without the specified value can be removed by specifying the text only.

 

 

Example programs:

CVS server: client.querix.com

CVS repository: /lycia_doc_examples

User: client

Project: user_interface/widgets

Program: listbox

 

Related articles:

ListBox

RadioButtonListItem

ComboBoxItem