PtGenTree

A generic superclass for tree widgets

Class hierarchy:

PtWidgetPtBasicPtContainerPtCompoundPtGenListPtGenTree

Immediate subclasses:

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 you expand 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:

Resource C type Pt type Default
Pt_ARG_TREE_FLAGS unsigned int Flag Pt_TREE_HAS_BUTTONS | Pt_TREE_TO_LEFT | Pt_TREE_TO_RIGHT | Pt_TREE_INDENT_BUTTONS | Pt_TREE_SHOW_CONNECTORS
Pt_ARG_TREE_LINE_COLOR PgColor_t Scalar PgRGB(239, 239, 239)
Pt_ARG_TREE_LINE_SPACING unsigned short Scalar 3
Pt_ARG_TREE_MARGIN_COLOR PgColor_t Scalar PgRGB(225, 225, 225)
Pt_CB_GEN_TREE_INPUT PtCallback_t * Link NULL

Pt_ARG_TREE_FLAGS

C type Pt type Default
unsigned int Flag Pt_TREE_HAS_BUTTONS |
Pt_TREE_TO_LEFT |
Pt_TREE_TO_RIGHT |
Pt_TREE_INDENT_BUTTONS |
Pt_TREE_SHOW_CONNECTORS

Possible values are:

Pt_TREE_HAS_BUTTONS
Display the buttons for expanding and collapsing items.
Pt_TREE_INDENT_BUTTONS
Indent the buttons.
Pt_TREE_INDENT_LINES
If Pt_TREE_SHOW_LINES is set, indent the lines to match the tree item indentation.
Pt_TREE_SHOW_CONNECTORS
Display the connectors.
Pt_TREE_SHOW_LINES
Display horizontal lines between each item in the tree.
Pt_TREE_SHOW_MARGIN
Display the margins.
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.

Note: The PtTree subclass defines some additional flags.

Pt_ARG_TREE_LINE_COLOR

C type Pt type Default
PgColor_t Scalar PgRGB( 239, 239, 239 )

The color of the lines. See PgColor_t in the Photon Library Reference.

Pt_ARG_TREE_LINE_SPACING

C type Pt type Default
unsigned short Scalar 3

The spacing between lines, in pixels.

Pt_ARG_TREE_MARGIN_COLOR

C type Pt type Default
PgColor_t Scalar PgRGB( 225, 225, 225 )

The color of the margins. See PgColor_t in the Photon Library Reference.

Pt_CB_GEN_TREE_INPUT

C type Pt type Default
PtCallback_t * Link NULL

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

reason
Pt_CB_GEN_TREE_INPUT
reason_subtype
The event type (same as event->type). For more info, see the types described for PhEvent_t in the Photon Library Reference.
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.
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 (see Current item in the description of PtGenList) after the event is normally processed by the widget.
unsigned index;
The index of the item.
PhPoint_t pos;
The pointer position relative to the item. See PhPoint_t in the Photon Library Reference.
int consumed;
Initially set to Pt_CONTINUE. Your callback function can suppress normal handling of the event by setting this field to another value. In the case of key events, set it to Pt_END to consume the event, or to Pt_HALT to pass the event to the parent widget. Mouse events are always consumed.

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.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_OVERRIDE PtContainer
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_LIST_COLUMN_ATTR PtGenList
Pt_ARG_LIST_COLUMN_POS PtGenList
Pt_ARG_LIST_DNDSEL_COLOR PtGenList
Pt_ARG_LIST_FLAGS PtGenList
Pt_ARG_LIST_FONT PtGenList
Pt_ARG_LIST_ITEM_COUNT PtGenList
Pt_ARG_LIST_SB_RES PtGenList
Pt_ARG_LIST_SCROLL_RATE PtGenList
Pt_ARG_LIST_SEL_COUNT PtGenList
Pt_ARG_LIST_TOTAL_HEIGHT PtGenList
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget
Pt_ARG_SCROLLBAR_WIDTH PtGenList
Pt_ARG_SELECTION_FILL_COLOR PtGenList
Pt_ARG_SELECTION_MODE PtGenList
Pt_ARG_SELECTION_TEXT_COLOR PtGenList
Pt_ARG_STYLE PtBasic
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_ARG_TOP_ITEM_POS PtGenList
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_VISIBLE_COUNT PtGenList
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer Not used by this class.
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget See below.
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESIZE PtContainer
Pt_CB_SCROLL_MOVE PtGenList
Pt_CB_UNREALIZED PtWidget

Pt_CB_DND

For Pt_CB_DND callbacks for a PtGenTree, the cbinfo->cbdata is a pointer to a PtTreeDndCallback_t structure, containing at least the following members:

PtDndCallbackInfo_t dnd_info
See the description of Pt_CB_DND for PtWidget.
PtGenTreeItem_t *item
A pointer to the target item involved in the drag-and-drop operation.
int item_pos
The index of that item.
unsigned long flags
Possible values:

If neither of these is set, the drop occurred inside the item.

int action
This member is initially set to Pt_LIST_ITEM_DNDSELECTED_UP | Pt_LIST_ITEM_DNDSELECTED_DOWN | Pt_LIST_ITEM_DNDSELECTED_IN. You can unset some of these values to indicate that the drag-and-drop isn't accepted in that case. For example, if you unset Pt_LIST_ITEM_DNDSELECTED_IN, the drag-and-drop can't occur inside the item, only above or below.

Convenience functions:

PtGenTree defines the following convenience functions and data structure:

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.
PtGenTreeItem_t
PtGenTree item structure
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.

The following convenience functions are useful only if you're creating a custom tree widget; they're described in the Creating a Tree Widget chapter of Building Custom Widget:

PtSuperClassGenTreeDrawItem()
Invoke the Tree Draw Item method of a given superclass.
PtSuperClassGenTreeItemState()
Invoke the Tree Item State method of a superclass.