PtRawTree

A raw tree

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtCompound → PtGenList → PtGenTree → PtRawTree

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

PhAB icon:

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:

Pt_ARG_RAWTREE_DRAW_F

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

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

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

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.

Pt_ARG_TREE_FLAGS

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

• Pt_TREE_BALLOON_ON_IMAGE — the balloon is permitted to cover the image and the text
• Pt_TREE_BALLOON_ON_TREE — the balloon is permitted to cover the tree, the image, and the text

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

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:

• Pt_LIST_ITEM_DNDSELECTED_UP — the drop occurred above the item.
• Pt_LIST_ITEM_DNDSELECTED_DOWN — the drop occurred below the item.
• Pt_LIST_ITEM_DNDSELECTED_IN — 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:

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