PtGenTree

A generic superclass for tree widgets

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtCompound --> PtGenList --> PtGenTree

For more information, see the diagram of the widget hierarchy.

PhAB icon:

None - not normally instantiated.

Public header:

<photon/PtGenTree.h>

Description:

The PtGenTree widget displays a tree of items. When the user expands an item, another list of items drops down from it. Additional items can be added to an expandable item when it's about to be expanded. Expanded items can be collapsed, which results in the exclusion of items from the displayed list.

The tree can actually be a "forest" - the widget can contain multiple items at the root level. The root items are always visible (included on the displayed list) because they don't have a parent that could be collapsed.

You can build a tree (or a "forest") that isn't linked to any widget and then add the whole tree to a widget as a root or subtree. Alternatively, you can add each item to the widget tree separately, but once the widget is realized, you'll have to use PtHold() and PtUpdate() to avoid multiple redraws.

PtGenTreeItem_t is the data structure used for the items. For more information about this class, see Building Custom Widgets.

New resources:

Pt_ARG_TREE_FLAGS

Possible values are:

Pt_TREE_HAS_BUTTONS

The [+] and [-] buttons are displayed.

Pt_TREE_HAS_LINES

The lines are displayed.

Pt_TREE_ROOT_LINES

The root items have lines (and maybe buttons).

Pt_TREE_TO_RIGHT

Extend the items to the right edge of the widget.

Pt_TREE_TO_LEFT

Extend the item background to the left edge.

The PtTree subclass defines some additional flags.

Pt_CB_GEN_TREE_INPUT

A list of callbacks invoked on mouse and key events. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource (Pt_CB_GEN_TREE_INPUT) that caused this callback to be invoked.

reason_subtype

The event type (same as event->type). For more info, see the event types described for the PhEvent_t structure in the Photon Library Reference.

cbdata

A pointer to a PtGenTreeInput_t structure that contains at least the following members:

PtGenTreeItem_t *item;

For mouse events, the item pointed to by the mouse or NULL if the mouse doesn't point to an item. For key events, the item that is going to be the current item after the event is normally processed by the widget.

unsigned index;

The index of the item.

PhPoint_t pos;

Pointer position relative to the item.

int consumed;

Initially set to Pt_CONTINUE. The callback function can suppress normal handling of the event by setting this field to another value. In the case of key events, a value of Pt_END causes the event to be consumed, while Pt_HALT passes the event to the parent widget. Mouse events are always consumed. You can set it to anything else to consume the event and suppress further processing.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.

Convenience functions:

PtGenTree's convenience functions are useful only if you're creating a custom tree widget; they're described in the Creating a Tree Widget chapter of the Building Custom Widget manual.

PtGenTree defines the following data structure:

PtGenTreeItem_t

PtGenTree item structure