Gadget Item Holders

Gadget item holders are objects of the class IlvGadgetItemHolder, an abstract class for managing gadget items. A gadget item cannot compute its size and be drawn if it is not linked to a gadget item holder. Usually, you do not have to link a gadget item with its holder since this operation is carried out by the managing gadget automatically.

Gadget items are described in Using Gadget Items.

This section covers the following topics:

When global operations have to be performed on gadget items, it is a lot more convenient to call the corresponding functions on the holder than on the gadget items themselves. For example, it might be tedious to call:

for each item in a list whose picture you want to hide.

For this reason the gadget item inherits from certain features of its holder. If a given feature is not redefined at the gadget item level, the gadget item will get it from its holder. This is the case for the editable state, label and picture visibility, label position, and label orientation.

For example, if you want to hide all the pictures of a toolbar (IlvToolBar is a subclass of IlvGadgetItemHolder), just call:

Then if you want to override this choice for the 4th item in the tool bar and show its picture, call:

The member function IlvGadgetItemHolder::getItemByName lets you find an item from its name. This method is particularly useful when searching for an item that is part of a tree structure (IlvAbstractMenu or IlvTreeGadget).

When you change the graphical representation of a gadget item using one of the IlvGadgetItem member functions, the gadget item is automatically redrawn.

In the following example, calling setLabel redraws the area of the list that was modified:

If you want to apply several graphical representation changes at the same time, you can use the redraw mechanism of the gadget item holder, as shown below:

The redraw operation is executed only when the IlvGadgetItemHolder::reDrawItems method is called.

The IlvGadgetItemHolder class contains a method for creating an item from a specified label, bitmap, or IlvGraphic object:

This method creates an IlvGadgetItem object using the label, graphic, or bitmap passed as a parameter. It can be overridden in subclasses of IlvGadgetItemHolder to return a subclass of IlvGadgetItem. This is the case for the tree gadget, where createItem has been redefined to return an instance of IlvTreeGadgetItem.

The IlvGadgetItemHolder class supports gadget item editing for the following gadgets classes: IlvMatrix, IlvStringList, and IlvTreeGadget.

To make a gadget item editable, you must call the member function setEditable with IlTrue as its parameter. You can also enable editing at the level of the managing gadget with the either IlvMatrix::allowEdit, setEditable, or IlvTreeGadget::setEditable depending on which class the gadget item belongs to.

For example, the following code allows editing for all the gadget items in the string list except the second item (specified by the index number 1).


Note: You can also enable editing from the Start Edit callback. See Controlling Editing.

Once editing has been enabled, you can edit a gadget item interactively either by clicking it or by pressing the F2 key after it has been selected. You can also edit an item by code using the member function edit.

When an item is being edited, two callbacks are invoked:

Start Edit Item is called at the beginning of the editing process. To set a Start Edit Item callback, use the symbol returned by the member function IlvGadgetItemHolder::StartEditItemCallbackType.

You can cancel the operation by setting the item to noneditable inside this callback.

End Edit Item is called at the end of the editing process. To set a End Edit Item callback, use the symbol returned by the member function IlvGadgetItemHolder::EndEditItemCallbackType.

You can cancel the editing of an item by pressing the Escape key. In this case, the End Edit Item callback is not invoked.

See “Callbacks” in Graphic Objects“.

The IlvGadgetItemHolder class implements the drag-and-drop functionality. Only instances of IlvMatrix, IlvStringList, and IlvTreeGadget support the drag-and-drop feature for gadget items.

To enable the drag-and-drop functionality for gadget items, you must call one of the following member functions with IlTrue as parameter: IlvMatrix::allowDragDrop, allowDragDrop, or IlvTreeGadget::allowDragDrop.

When the drag-and-drop functionality is enabled, you can drag a gadget item from its current location and drop it anywhere. The following callbacks are invoked:

Start Drag Item is called at the beginning of a drag-and-drop event. To set this callback, use the symbol returned by IlvGadgetItemHolder::StartDragItemCallbackType.

You can cancel the operation by calling the member function IlvGadgetItemHolder::setDraggedItem with 0 as parameter from this callback.

Drag Item is called each time the mouse is moved. To set this callback, use the symbol returned by IlvGadgetItemHolder::DragItemCallbackType.

End Drag Item is called when a dragged item is dropped anywhere in the workspace.
To set this callback, use the symbol returned by IlvGadgetItemHolder::EndDragItemCallbackType.

During a drag-and-drop operation, you can retrieve the dragged item using IlvGadgetItemHolder::getDraggedItem. You can also change the ghost image of the item that is being dragged. By default, the ghost image is the dragged item drawn in XOR mode. To use a ghost image of your own, call IlvGadgetItemHolder::setDraggedImage from the Start Drag Item or the Drag Item callback.