Gamma/Photon : Using Gamma™ with the Photon microGUI®, Version 1.1
	Widget Classes

`PtTree`

PtTree — An expanding/collapsing tree-style list of items.

Synopsis

class PtTree PtGenTree
{
    flags;           // flag
    tree_images;     // PhImage array  (Pt_ARG_TREE_IMAGES)    
    tree_imgmask;    // unsigned long  (Pt_ARG_TREE_IMGMASK)    
}

Base Classes

PtWidget <-- PtBasic <-- PtContainer <-- PtGenList <-- PtGenTree <-- PtTree

Description

This widget displays items in a tree-style list, such as in a file listing or table of contents. Each item has a string for displaying its name, and two images to indicate whether it is currently expanded or collapsed.

For detailed information, please refer to PtTree in the Photon documentation.

Instance Variables

flags

This is a Gamma extension which has no corresponding Photon resource. It is not yet documented.

tree_images

An array of two PhImages used to show the expanded/collapsed state of tree items.

tree_imgmask

This instance variable defines the image selection mask, and may have one of the following values:

Constant	Description
`Pt_LIST_ITEM_SELECTED`	The item is selected.
`Pt_LIST_ITEM_CURRENT`	The item is the current item.
`Pt_TREE_ITEM_EXPANDABLE`	The item can be expanded to show its branches.
`Pt_TREE_ITEM_EXPANDED`	The item is expanded.

Callbacks

The following callbacks are associated with this widget:

Callback	Description
`Pt_CB_TREE_STATE`	This callback is generated when the state of the tree changes (expands/collapses).
`Pt_CB_TREE_SELECTION`	This callback is generated when a tree item is selected.

Associated Classes

PtTreeItem, PtTreeCallback, PtCallbackInfo

Convenience Functions

Arguments

`brother`	A `PtTreeItem` at the same level as another `PtTreeItem`.
`child`	A `PtTreeItem` one level below another `PtTreeItem`.
`event`	An event to be passed to the tree_state callback.
`images`	A list of PhImage structures.
`indexes`	A sorted list or array of indexes.
`item`	A `PtTreeItem`.
`parent`	A `PtTreeItem` one level above another `PtTreeItem`.
`sel_image`	The index of the image to be displayed when the `PtTreeItem` is set.
`string`	The string resource of a `PtTreeItem`.
`unsel_image`	The index of the image to be displayed when the `PtTreeItem` is not set.
`widget`	A `PtTree` widget.

Functions

Most of these functions are extensions of QNX Photon functions. You can refer to the PtTree function documentation in QNX Helpviewer for more information about them.

PtTreeAddAfter (widget, item, brother) -- inserts a tree item below the brother item in the widget.

Returns t.

PtTreeAddFirst (widget, item, brother) -- inserts an item as a child item, directly below the parent item in the tree, in front of any existing children items. If parent is nil, the item will be placed at the root level of the tree, before all other items. The tree argument can be nil, as long as parent is not attached to any tree widget.

Returns t.

index = PtTreeAddImages (widget, images) -- adds the images in the images list to the widget's image list. The added images are indexed starting with the last of the widget's existing images. The widget makes a copy of the PhImage structures of images, but it doesn't copy the palettes or image data of the structure members.

Returns the index of the first of the added images on success, or nil on failure.

array = PtTreeAllItems (widget) -- fills an array with all items in the widget. Items that belong to collapsed subtrees aren't included in the array.

Returns an array.

item = PtTreeAllocItem (widget, string, sel_image, unsel_image) -- allocates a new item added by PtTreeAddFirst or PtTreeAddAfter. Images in sel_img and unsel_img are displayed as the item is set or not. (An item is considered set when its flags masked with tree_imgmask are not nil.) These images must already be present in the widget. If an index passed to PtTreeAllocItem is higher than the current image count, it will be changed to -1, meaning "no image."

Returns a PtTreeItem.

PtTreeClearSelection (widget) -- clears a selection.

Returns t.

PtTreeCollapse (widget, item, event) -- collapses the item subtree. The widget tree must contain the item, or be nil if the item doesn't belong to any tree. If there is a tree, the tree_state callback is invoked, and the event is passed to it.

Returns t.

PtTreeExpand (widget, item, event) -- expands the item subtree. The widget tree must contain the item, or be nil if the item doesn't belong to any tree. If there is a tree, the tree_state callback is invoked, and the event is passed to it. If the callback function prevents expansion by setting the callback expand field to a non-zero value, that value will be returned.

Returns 0 on success, else a value that prevented the expansion.

PtTreeFreeAllItems (widget) -- unlinks and frees all items in the widget tree. It is automatically called whenever a PtTree widget is deleted.

Returns t.

PtTreeFreeItems (item) -- frees the item, its brothers, and its subtrees. The item must not belong to any tree, or else it must be removed first with a call to PtTreeRemoveChildren, PtTreeRemoveItem, or PtTreeRemoveList.

Returns t.

item = PtTreeGetCurrent (widget) -- gets the current item from the widget tree.

Returns the current item.

array = PtTreeGetSelIndexes (widget) -- makes an index array of all the selected items in the widget. Items belonging to collapsed subtrees are not indexed in the array.

Returns an array of indexes.

integer = PtTreeGoto (widget, item) -- sets the current item and (if necessary) the current position so that the new current item is visible. If item is nil, there will be no current item. A non-zero return value means the item belongs to a collapsed subtree, and a callback function prevented the subtree from being expanded.

Returns 0 on success, else a non-zero integer.

item = PtTreeItemBrother (item) -- gets the first brother of an item.

Returns the first brother of the item, or nil.

item = PtTreeItemFather (item) -- gets the father of an item.

Returns the father of the item, or nil.

index = PtTreeItemIndex (item) -- calculates the index of the item in the tree. The index of the first item is 1.

Returns the index of the item, or 0 if it belongs to a collapsed subtree.

item = PtTreeItemSon (item) -- gets the first son of an item.

Returns the first son of the item, or nil.

item = PtTreeModifyItem (widget, item, string, sel_image, unsel_image) -- modifies the item according to the string, sel_img, and usel_img passed to it. If string is nil, the item's string resource won't be changed.

Returns the item, modified.

Don't use this function to modify an item that hasn't yet been added to the tree.

item = PtTreeRemoveChildren (item) -- unlinks all the children of the item and returns the first child. They can then all be freed by a call to PtTreeFreeItems on this child.

Returns the first child, a PtTreeItem.

This function will return nil if any children are expanded. All children must be collapsed by a call to PtTreeCollapse before this function will work.

PtTreeRemoveItem (widget, item) -- unlinks the item and all its children from its parent and brothers. If the item doesn't belong to a tree, widget must be set to nil. If widget is nil, and the item has no parent, but has a previous brother, the function will unlink the item from its brother. This function never clears the tree_item_expandable flag in the item's parent.

Returns t.

PtTreeRemoveList (widget, item) -- strips off the entire bottom of the tree, starting at the item, taking all subsequent brothers and children, setting their parent resources to nil. If the item has no parent, nil can be passed for widget, but if a parentless item does have a previous brother, the function won't be able to find it or unlink the item from it.

Returns t.

item = PtTreeRootItem (widget) -- gets the first root item of a the widgettree.

Returns the first root item, or nil.

PtTreeSelect (widget, item) -- selects the item.

Returns t.

array = PtTreeSelectedItems (widget) -- makes an array and fills it with the items of the widget. Those items that belong to collapsed subtrees aren't included in the array.

Returns an array of items.

integer = PtTreeSetSelIndexes (widget, indexes) -- sets the selection indexes. The array or list of indexes must be sorted. Otherwise the number of items returned may be smaller than the actual size of the list or array.

Returns the number of indexes.

PtTreeShow (widget, item) -- sets the current position so the item is visible. If item is nil, the function does nothing.

Returns 0 on success, else a non-zero value, indicating that the item belongs to a collapsed subtree which could not be expanded.

PtTreeUnselect (widget, item) -- unselects the item.

Returns t.

PtTreeUnselectNonBrothers (widget, item) -- unselects all items that are not brothers of the item. If you pass nil for item, the current item is used.

Returns t.


PtToggleButton		PtTrend