PtTree

Gamma/Photon: Using Gamma™ with the Photon microGUIŽ, Version 4.0
Prev |  | Next

# `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 `widget`tree.

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.

Prev | Home | Next
`PtToggleButton` | Up | `PtTty`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.