Warning: main(/www/www/htdocs/style/globals.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/photon/wid_build/tree.html on line 1
Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/globals.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/photon/wid_build/tree.html on line 1
Warning: main(/www/www/htdocs/style/header.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/photon/wid_build/tree.html on line 8
Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/header.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/photon/wid_build/tree.html on line 8
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;
- list
- The item structure, of type
PtGenListItem_t
(see the Photon Widget Reference) used by the
PtGenList superclass. The PtGenTree
class defines some new flags that can be set in
item->list.flags:
- Pt_TREE_ITEM_EXPANDABLE
- Set this flag to mark an item as expandable. When you add a
branch to an item,
PtGenTreeAddFirst()
(see the Photon Widget Reference)
sets
this flag in the parent item automatically.
- Pt_TREE_ITEM_EXPANDED
- The branches of this item are currently on display.
- father, son, brother
- Tree links. You can use them to traverse the tree structure, but
don't modify them directly — it's safer to use the convenience
functions to modify the tree structure.
- dim
- A
PhDim_t
structure (see the Photon Library Reference) that defines
the size of the item, excluding the tree ornaments (lines and button).
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:
- PtGenTreeWidget_t *widget
- The widget pointer.
- PtGenTreeItem_t *item
- A pointer to the
PtGenTreeItem_t
structure for the item that needs to be redrawn.
- PhRect_t const *where
- A pointer to a
PhRect_t
structure (see the Photon Library Reference) that defines
the extent of the item.
- int lmargin
- If positive, an additional left margin that should be added to the
first column.
- int rmargin
- If positive, an additional right margin that should be added to the
last column.
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:
- PtGenTreeWidget_t *widget
- The widget pointer.
- PtGenTreeItem_t *item
- A pointer to the
PtGenTreeItem_t
structure for the item that is being collapsed or expanded.
- PhEvent_t *event
- The event argument to
PtGenTreeExpand() or PtGenTreeCollapse().
See PhEvent_t
in the Photon Library Reference.
- int reason
- Either Pt_TREE_EXPANDING or
Pt_TREE_COLLAPSING.
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):
- PtGenTreeAddAfter()
- Add items after a given item.
- PtGenTreeAddFirst()
- Add items in front of any existing items.
- PtGenTreeAllItems()
- Get pointers to all the items in the tree.
- PtGenTreeClearSelection()
- Clear the selection.
- PtGenTreeCollapse()
- Collapse a subtree.
- PtGenTreeDamageItem()
- Redraw an item when its data has changed.
- PtGenTreeExpand()
- Expand a given subtree.
- PtGenTreeExpandParents()
- Expand any collapsed ancestors of a given item.
- PtGenTreeFreeAllItems()
- Free all the items in a tree.
- PtGenTreeFreeItems()
- Free the items in a subtree.
- PtGenTreeGetCurrent()
- Get a pointer to the current item.
- PtGenTreeGetSelIndexes()
- Get the indexes of the selected items.
- PtGenTreeGoto()
- Set the current item and position so that a given item is visible.
- PtGenTreeItemIndex()
- Calculate the index of a given item.
- PtGenTreeItemRealloc()
- Reallocate an item.
- PtGenTreeItemResize()
- Resize an item.
- PtGenTreeRemoveChildren()
- Unlink all the children of a given item.
- PtGenTreeRemoveItem()
- Remove a given item and its children from its parents and siblings.
- PtGenTreeRemoveList()
- Remove a given items and its siblings from their parent.
- PtGenTreeResize()
- Resize many items.
- PtGenTreeRootItem()
- Get a pointer to the first root item.
- PtGenTreeSelect()
- Select a given item.
- PtGenTreeSelectedItems()
- Get pointers to the selected items.
- PtGenTreeSetSelIndexes()
- Set the selection indexes.
- PtGenTreeShow()
- Set the current position so that a given item is visible.
- PtGenTreeUnselect()
- Unselect a given item.
- PtGenTreeUnselectNonBrothers()
- Unselect all items that aren't siblings of a given item.
- PtSuperClassGenTreeDrawItem()
- Invoke the Tree Draw Item method of a given superclass.
- PtSuperClassGenTreeItemState()
- Invoke the Tree Item State method of a superclass.
Warning: main(/www/www/htdocs/style/footer.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/photon/wid_build/tree.html on line 480
Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/footer.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/photon/wid_build/tree.html on line 480