Using IlvHierarchicalSheet

The class is a subclass of IlvSheet that displays a tree structure in one of its columns. It can be considered as a special IlvTreeGadget object that handles several columns. The tree items are of the type IlvTreeGadgetItem, which means that the API used to handle a tree hierarchy is very close to the IlvTreeGadget object. See Using IlvTreeGadget.

A Hierarchical Sheet

This section covers the following topics:

• Changing the Tree Hierarchy

• Navigating through a Tree Hierarchy

• Changing the Characteristic of a Tree Item

• Expanding and Collapsing a Gadget Item

• Changing the Look of the Tree Gadget Hierarchy

• Event Handling and Callbacks

Changing the Tree Hierarchy

The hierarchical sheet has an invisible root item that can be retrieved using the getRoot member function.

Changing a Hierarchy

When you want to modify the tree hierarchy, you must not use IlvSheet member functions, such as set, removeRow, and so on. Instead, use the IlvHierarchicalSheet methods described below.

To create a hierarchical list of items, you can do the following:

• Create tree gadget items as explained in Creating a Hierarchy and add them one by one to the hierarchical sheet with addItem member function.

• Create a complete new hierarchy and add it to the tree gadget in a single operation. To do so, create tree gadget items as explained above and add them as children using insertChild. This solution is more efficient than the first one.

Then you can add the root of your new hierarchy to the tree with addItem as shown below:

IlvTreeGadgetItem* item = new IlvTreeGadgetItem("New Item");

item->insertChild(new IlvTreeGadgetItem("Leaf 1"));

item->insertChild(new IlvTreeGadgetItem("Leaf2"));

hsheet->addItem(0 /* hsheet->getRoot() */, item);

Removing Items

When you remove an item from the hierarchical sheet, all its children are also removed from the tree. Use removeItem to remove a single item from a tree or removeAllItems to remove all its items at once.

Note When you add a new item to the tree gadget, its corresponding row is created automatically. Similarly, when you remove an item, its row is deleted.

Navigating through a Tree Hierarchy

To move inside a hierarchical tree, use the member functions described in Navigating Through a Tree Hierarchy. You can also use IlvHierarchicalTree::getTreeItem and IlvHierarchicalSheet::getItemRow.

Changing the Characteristic of a Tree Item

See Changing the Characteristic of an Item.

Expanding and Collapsing a Gadget Item

You can expand or collapse a gadget item by clicking its Expand button. Expanding an item shows all its subitems; collapsing an item hides all its subitems. You can also perform the same operations using shrinkItem and expandItem.

When an item becomes invisible because one of its parents has been collapsed, its corresponding row in the sheet disappears. Note, however, that it is not deleted.

Changing the Look of the Tree Gadget Hierarchy

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

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

Event Handling and Callbacks

The Expand Callback

When the user expands a tree gadget item, the Expand callback is invoked. The callback type can be retrieved with ExpandCallbackType. See Associating a Callback with a Gadget.

The Shrink Callback

When the user collapses a tree gadget item, the Shrink callback is invoked. The callback type can be retrieved with ShrinkCallbackType. See Associating a Callback with a Gadget.