Using IlvTreeGadget

An IlvTreeGadget is a gadget that displays a hierarchical list of items. Each item is an instance of the IlvTreeGadgetItem class, a subclass of IlvGadgetItem. The user may expand or collapse an item to display or hide its subitems.

The IlvTreeGadget class handles scrollbars. For details about handling scrollbars, see the base class IlvScrolledGadget.

This section covers the following topics:

The tree gadget has an invisible root item which you can retrieve using the getRoot member function.

To create a hierarchical list of items, you first have to create the items that will be part of that list. Here are a few examples:

item1 = new IlvTreeGadgetItem("item1"); // Creates an item with a label.

item2 = new IlvTreeGadgetItem("item1", // Creates an item with a label

item3 = new IlvTreeGadgetItem(bitmap); // Creates an item with a bitmap.

item4 = new IlvTreeGadgetItem(graphic); // Creates an item with a graphic.

Once tree gadget items are created, you can arrange them as a tree structure in the following ways:

Create tree gadget items as explained above and add them one by one to the tree gadget using the member function IlvTreeGadget::addItem.

Create a complete new hierarchy and add it to the tree gadget in a single operation. This solution is far more efficient. To do so, create tree gadget items as explained above and add them as children using insertChild. Then add the root item with IlvTreeGadget::addItem:

When you remove an item from a tree gadget, all its children are also removed from the tree.

To remove an item without destroying it, use IlvTreeGadgetItemHolder::detachItem. To remove all the items at once, call IlvTreeGadget::removeAllItems.

You can move an item and all its children from its current parent item to a new parent item with IlvTreeGadgetItemHolder::moveItem.

Once you have created a tree hierarchy, you can navigate in the tree using the member functions getParent, getFirstChild, getNextSibling, getPrevSibling.

To change the visible characteristic of an IlvTreeGadgetItem, such as its label and bitmap, see the base class IlvGadgetItem.

You can specify whether the number of children of an item is known with setUnknownChildCount. In this case, the tree gadget allows you to expand the item with the Expand button. This lets you have an Expand callback which is invoked even if the item does not have any subitems. You can then add items in the expand callback.

You can expand or collapse a gadget item either by clicking its Expand button or by double-clicking it. Expanding an item shows all its subitems; collapsing an item hides all its subitems. You can also perform the same operations using the following member functions IlvTreeGadget::shrinkItem and IlvTreeGadget::expandItem.

The way in which the IlvTreeGadget hierarchy is displayed can be customized to meet application requirements. To do so, use the following IlvTreeGadget member functions.

The lines that link items to their parents can be displayed or hidden with the IlvTreeGadget::showLines member function.

Lines can be drawn to connect the root item to its children using the IlvTreeGadget::setLinesAtRoot member function.

A line can be drawn to connect (or disconnect) the children of the root item using the IlvTreeGadget::linkRoots member function.

The buttons for expanding/collapsing may be set as visible or invisible using the IlvTreeGadget::showButtons member function.

You can define the indentation between an item and its parent using the IlvTreeGadget::setIndent member function.

You can change the visibility of all the pictures in a tree gadget by calling this method:

In the same way, you can change the visibility of all the labels in a tree gadget by calling this method:

By default, the tree gadget displays both labels and pictures.

Note: You can override these global settings for a specific item through the API of the IlvGadgetItem class. For details, see the methods showLabel and showPicture.

You may want to change the position of an item label relative to its picture. To do so, use the method:

By default, the label is placed to the right of the picture (IlvRight).

Note: You can override these global settings for a specific item through the API of the IlvGadgetItem class. For details, see the setLabelPosition method.

The tree gadget has several predefined callbacks. Callbacks are always related to a particular item. To retrieve the item associated with the callback in your code, use the member function IlvTreeGadget::getCallbackItem.

The tree gadget has two different selection modes:

Extended selection mode You can select several items and expand the selection.

The selection modes are defined by the following type:

To modify the selection mode, use the following IlvTreeGadget member functions:

When the user selects an item or cancels the selection, the Select callback is invoked. Its type can be retrieved with the member function IlvTreeGadget::SelectCallbackType. See Associating a Callback with a Gadget.

When the user expands an item, the Expand callback is invoked. Its type can be retrieved with the member function IlvTreeGadget::ExpandCallbackType. See Associating a Callback with a Gadget.

When the user collapses an item, the Shrink callback is invoked. Its type can be retrieved with the member function IlvTreeGadget::ShrinkCallbackType. See Associating a Callback with a Gadget.

When the user double-clicks an item that has no subitems, the Activate callback is invoked. Its type can be retrieved with IlvGadgetItemHolder::ActivateCallbackType. See Associating a Callback with a Gadget.

You can edit tree gadget items. See Editing Gadget Items.

The IlvTreeGadget class provides an easy-to-use, drag-and-drop mechanism. See Dragging and Dropping Gadget Items.