This chapter covers the following topics:
The PtGenTree class is a subclass of PtGenList. You can use a PtGenTree widget to display a hierarchy of items as lists in a tree.
When an item in the hierarchy has an item or list of items below it, that item can be expanded. An expanded item drops a list to reveal all items in the next level below. An expanded item can be collapsed. When an expandable item is collapsed, the list rolls up and its items are concealed. An item can be marked as expandable even if it doesn't have a list of items below it — you can add the list of items just before the expandable item is expanded.
Any PtGenTree widget can contain multiple items at the root level, which contains the first level of items to display. Root-level items have no other items/levels above them — they represent the top of the hierarchy.
A child class of PtGenTree isn't supposed to define a List Draw method. Instead, it should define a Tree Draw Item method that will be called by the List Draw method of PtGenTree.
PtGenTree's Draw List method assumes that the Pt_GEN_LIST_SHOW_DAMAGED flag is set. The child class should never clear this flag. |
The PtGenTree class doesn't use recursive functions. The amount of stack needed by any PtGenTree*() function doesn't depend on the tree's size or depth.
The item structure used by PtGenTree is defined as follows:
typedef struct Pt_gentree_item { PtGenListItem_t list; struct Pt_gentree_item *father, *son, *brother; PhDim_t dim; } PtGenTreeItem_t;
When an item is added to the widget, the widget calculates item->list.size based on the size specified in item->dim, the minimum height of the item, and the item's position in the tree. The height of an item in a tree widget is always an even number of pixels — if you specify an odd number for the height in the dim field, a gap of at least one pixel will be displayed between the current item and any other item directly below (see “Current item” in the description of PtGenList in the Widget Reference).
The List Draw method calls the Tree Draw Item method with the following arguments:
The PtGenTree List Draw method is responsible for drawing the lines and boxes representing the tree structure. The Tree Draw Item method should draw only the item. For example, the Tree Draw Item method of PtTree draws only the image and the string.
PtGenTreeExpand() and PtGenTreeCollapse() (see the Photon Widget Reference) call the Tree Item State method with the following arguments:
If reason is Pt_TREE_EXPANDING, the item is about to be expanded. The Tree Item State method can update the item's branches before the actual expansion. After the function returns, the widget will display a list of items in the expanded branch.
If an item in the list has its Pt_TREE_ITEM_EXPANDED flag set, the items below will be displayed too. The Tree Item State method returns zero to permit the expansion, or a nonzero value to prevent it — PtGenTreeExpand() returns this value (see the Photon Widget Reference).
If reason is Pt_TREE_COLLAPSING, the item has been collapsed. Its branches are concealed and the Tree Item State method can free the associated items. The Tree Item State method returns a nonzero value if the item is destroyed, or zero if the item still exists — PtGenTreeCollapse() returns this value (see the Photon Widget Reference).
The PtGenTree class defines the following convenience functions (see the Photon Widget Reference):