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:

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.

Several member functions for adding items to a list are available. The most important one the IlvListGadgetItemHolder::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 IlvGadgetItemHolder::createItem method. For details, see Creating Gadget Items.

For example:

is equivalent to:

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:

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.

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

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

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

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

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

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