PtRawTree

A raw tree

Class hierarchy:

PtWidgetPtBasicPtContainerPtCompoundPtGenListPtGenTreePtRawTree

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

PhAB icon:

PtRawTree button in PhAB

Public header:

<photon/PtRawTree.h>

Description:

PtRawTree is a tree that gives you more control than PtTree over the appearance and behavior of its items. You can supply various functions to draw items, react to events, and so on. If these functions aren't given, the widget uses the default functions defined for PtGenTree or PtGenList.

New resources:

Resource C type Pt type Default
Pt_ARG_RAWTREE_DRAW_F See below Pointer NULL
Pt_ARG_RAWTREE_INFLATE_F See below Pointer NULL
Pt_ARG_RAWTREE_SELECT_F See below Pointer NULL
Pt_ARG_RAWTREE_STATE_F See below Pointer NULL

Pt_ARG_RAWTREE_DRAW_F

C type Pt type Default
See below Pointer NULL

A function that's called to draw the widget. If this resource is NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeDrawItemF_t, and has this prototype:

void drawitemf( PtWidget_t *widget,
                PtGenTreeItem_t *item,
                PhRect_t const *where,
                int lmargin,
                int rmargin );

The arguments are:

widget
A pointer to the widget.
item
A pointer to the PtGenTreeItem_t structure for the item that needs to be redrawn.
where
A pointer to a PhRect_t structure (see the Photon Library Reference) that defines the extent of the item.
lmargin
If positive, an additional left margin to add to the first column.
rmargin
If positive, an additional right margin to add to the last column.

The PtGenTree List Draw method is responsible for drawing the lines and boxes representing the tree structure. This function should draw only the item.

Pt_ARG_RAWTREE_INFLATE_F

C type Pt type Default
See below Pointer NULL

A function that's called when a balloon widget needs to be created. It should create a balloon and return its widget pointer. If this resource is NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeInflateF_t, and has this prototype:

PtWidget_t *inflatef( PtWidget_t *widget,
                      PtWidget_t *parent,
                      PtGenTreeItem_t *item,
                      unsigned index,
                      int column,
                      PhArea_t *area );

The arguments are:

widget
A pointer to the raw-list widget.
parent
A pointer to the balloon's parent.
item
A pointer to the PtGenTreeItem_t structure for the item under the mouse pointer.
index
The index of the list item. The first item in the list has an index of 1.
column
The index of the column under the mouse pointer, or -1 if the pointer isn't on a column or the list has no columns.
area
A pointer to a PhArea_t structure (see the Photon Library Reference) that contains the area, relative to the parent widget, corresponding to the entire item, Use PtGenListSetColumnBalloon() to adjust the area to the specified column if you're not using PtGenListCreateTextBalloon().

Pt_ARG_RAWTREE_SELECT_F

C type Pt type Default
See below Pointer NULL

A function that's called when an item is selected or unselected. If this resource is NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeSelectF_t, and has this prototype:

void selectf( PtWidget_t *widget,
              PtGenTreeItem_t *item,
              int pos,
              int column,
              int nitems,
              int subtype,
              PhEvent_t *ev );

The arguments are:

widget
A pointer to the raw-tree widget.
item
A pointer to a PtGenTreeItem_t structure. In Pt_SELECTION_MODE_RANGE selection mode, it's a pointer to the first selected item. In other modes, it's a pointer to the item that's been selected or unselected.
pos
The index of that item. The first item on the list has an index of 1.
column
The column number.
nitems
The current number of selected items (the same as list->sel_count).
subtype
The selection subtype.
event
A pointer to a PhEvent_t structure (see the Photon Library Reference) that describes the event.

Pt_ARG_RAWTREE_STATE_F

C type Pt type Default
See below Pointer NULL

A function that's called when an item is expanded or collapsed. If this resource is NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeItemStateF_t, and has this prototype:

int statef( PtWidget_t *widget,
            PtGenTreeItem_t *item,
            PhEvent_t *event,
            int reason );

The arguments are:

PtWidget_t *widget
A pointer to the widget.
PtGenTreeItem_t *item
A pointer to the PtGenTreeItem_t structure for the item that's being collapsed or expanded.
PhEvent_t *event
A pointer to a PhEvent_t structure (see the Photon Library Reference) that describes the event.
int reason
Either Pt_TREE_EXPANDING or Pt_TREE_COLLAPSING.

If reason is Pt_TREE_EXPANDING, the item is about to be expanded. This function can update the item's branches before the actual expansion. After the function returns, the widget displays 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 are displayed too. To permit the expansion, return zero; to prevent it, return a nonzero value.

If reason is Pt_TREE_COLLAPSING, the item has been collapsed. Its branches are concealed and this function can free the associated items.

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_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LAYOUT_DATA PtWidget
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_ROW_LAYOUT_DATA 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_TREE_FLAGS PtGenTree See below.
Pt_ARG_TREE_LINE_COLOR PtGenTree
Pt_ARG_TREE_LINE_SPACING PtGenTree
Pt_ARG_TREE_MARGIN_COLOR PtGenTree
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_GEN_TREE_INPUT PtGenTree
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_ARG_TREE_FLAGS

In addition to the flags defined by PtGenTree, the following flags are defined:

By default, neither is set. The width and location of the balloon depend on these flags:


PtRawTree balloon widths


Additional Pt_ARG_TREE_FLAGS for a PtRawTree widget.

Pt_CB_DND

For Pt_CB_DND callbacks for a PtRawTree, 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 PtGenTreeItem_t structure for the target item involved in the drag-and-drop operation.
int item_pos
The index of that item.
unsigned long flags
Possible values:
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:

You can use any of the convenience functions defined for PtGenTree when working with a PtRawTree.