List Gadget Item Holders

List gadget item holders are specific types of gadget item holders for managing lists of gadget items. The class IlvListGadgetItemHolder is the base class of all the gadgets that handle gadget item lists, such as string lists and menus.

For information on gadget item holders, see Gadget Item Holders.

This section covers the following topics:

Modifying a List

All the member functions that modify a list redraw the modified area automatically. If you want to make several changes to a list without redrawing the area every time a modification is made, you can use the redraw mechanism of the IlvGadgetItemHolder class.

For details, see Redrawing Gadget Items.

Adding an Item to a List

Several member functions for adding items to a list are available. The most important one the insertItem. This member function inserts an item inside a list at the specified position. Other methods, such as addLabel and insertLabel, call the insertItem method after they have created the item using the createItem method. For details, see Creating Gadget Items.

For example:

IlvStringList* list = ....

list->insertLabel("Label 1");

is equivalent to:

IlvStringList* list = ....

IlvGadgetItem* item = list->createItem("Label 1");

list->insertItem(item);

Changing All the Items in a List

You may want to change all the items in a list at once. To do this, use the setItems method. Using this method is more efficient than adding items one by one.

Here is an example of how to use the method IlvListGadgetItemHolder::setItems:

IlvUShort count = 3;

IlvGadgetItem** items = new IlvGadgetItem*[count];

items[0] = new IlvGadgetItem("item0");

items[1] = new IlvGadgetItem("item1");

items[2] = new IlvGadgetItem("item2");

IlvStringList* list = ...

list->setItems(items, count);

delete [] items;

Note that the items are not copied and that the items array is not used by the holder, and therefore needs to be deleted.

Other member functions, such as the setLabels methods, can be used to change a whole list. All these functions call the member function IlvListGadgetItemHolder::setItems.

Removing an Item From a List

To remove an item from a list, use the removeItem member function.

Removing all Items

To remove all items from a list, use the empty member function.

Accessing Items

To know the number of items managed by a list gadget item holder, use the getCardinal member function.

To retrieve an item using its position in the list, use the getItem member function.

To find the position of an item in its holder, use the getIndex member function.

You can also find an item knowing its label using the getPosition member function.