[Previous] [Contents] [Index] [Next]

PtTree

A tree of items that collapse and expand as requested

Class hierarchy:

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

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

PhAB icon:

PtTree button in PhAB

Public header:

<photon/PtTree.h>

Description:

The PtTree widget displays a tree of items that collapse or expand according to the user's selections. PtTree assumes that each tree item contains two images and a string.


PtTree


The Photon Helpviewer uses a PtTree widget to give you quick access to documentation.


To display items in columns, you can:

With both methods, the Tab character is used in the item strings as a column separator.


Note: Even if you use columns, each line in the tree remains a single item. When you select any part of the line, the entire line is selected - having columns doesn't make the tree into a spreadsheet.

The array of all available images is actually stored within the widget's Pt_ARG_TREE_IMAGES resource, and the items contain only indexes into this array. The item structure, PtTreeItem_t, also contains a "user data" pointer that isn't used by the widget. Note that there are some functions that free items. None of these functions attempts to free the user data.

The items should be allocated using the PtTreeAllocItem() function. This function uses the font and image list stored in the tree widget to determine the item's dimensions. This means that between creating an item and adding it to the widget, you mustn't change the widget's font or images. The tree widget passed to PtTreeAllocItem() must be the same widget that the item will be added to. The PtTree widget will free all its items automatically when it's destroyed.

Use PtTreeAddFirst() and PtTreeAddAfter() to build a tree. For example, suppose you wanted to build the following tree:

A sample tree

Assuming your tree widget is referenced by tree_wgt, use the following code:

PtTreeItem_t *item,*brother;
char *text;

/* Add "Item 1" as first root item */

text = "Item 1";
item = PtTreeAllocItem(tree_wgt,text,-1,-1);
PtTreeAddFirst(tree_wgt,item,NULL);
brother = item;

/* Add "Item 2" as root item after "Item 1" */

text = "Item 2";
item = PtTreeAllocItem(tree_wgt,text,-1,-1);
PtTreeAddAfter(tree_wgt,item,brother);
brother = item;

/* Add "Item 2a" as first child of "Item 2" */

text = "Item 2a";
item = PtTreeAllocItem(tree_wgt,text,-1,-1);
PtTreeAddFirst(tree_wgt,item,brother);

/* Add "Item 3" as root item after "Item 2" */

text = "Item 3";
item = PtTreeAllocItem(tree_wgt,text,-1,-1);
PtTreeAddAfter(tree_wgt,item,brother);

New resources:

Resource C type Pt type Default
Pt_ARG_TREE_BALLOON PtTreeBalloonF_t * Pointer See below
Pt_ARG_TREE_IMAGES PhImage_t *, short Array NULL
Pt_ARG_TREE_IMGMASK unsigned Scalar Pt_LIST_ITEM_SELECTED
Pt_CB_TREE_SELECTION PtCallback_t * Link NULL
Pt_CB_TREE_STATE PtCallback_t * Link NULL

Pt_ARG_TREE_BALLOON

C type Pt type Default
PtTreeBalloonF_t * Pointer See below

A function that inflates a balloon for the item the pointer is on. PtTreeBalloonF_t is a function type:

typedef PtWidget_t *PtTreeBalloonF_t(
    PtWidget_t *widget, PtWidget_t *parent,
    PhArea_t *area, PtListColumn_t *column,
    PtTreeItem_t *item, int coln, 
    const char *font);
      

The parameters are as follows:

widget
A pointer to the PtTree widget.
parent
Its parent window.
area
A PhArea_t structure that covers the item. The area->pos member is relative to the parent window.
column
The position of the column the pointer is on.
item
The item the pointer is on.
coln
The index of the column the pointer is on.
font
The widget's Pt_ARG_LIST_FONT resource.

The default function does this:

return
    PtGenListCreateTextBalloon(
      widget, parent, 
      PtGenListSetColumnBalloon ( area, column ),
      item->string, coln, font);
      

Pt_ARG_TREE_IMAGES

C type Pt type Default
PhImage_t *, short Array NULL

A list of images that can be displayed with tree items. For more information about the image structure, see PhImage_t in the Photon Library Reference.


Note: Set the flags member of the PhImage_t structures to:
Ph_RELEASE_IMAGE | Ph_RELEASE_PALETTE |
Ph_RELEASE_TRANSPARENCY_MASK | Ph_RELEASE_GHOST_BITMAP
  

before providing the images to the widget. If you do this, the memory used for the images is released when the widget is destroyed or Pt_ARG_TREE_IMAGES is set.


Pt_ARG_TREE_IMGMASK

C type Pt type Default
unsigned Scalar Pt_LIST_ITEM_SELECTED

Defines the mask for selecting an item's image.

When you create an item by calling PtTreeAllocItem(), you specify the images to be used when the item is set or unset. An item is considered set if its flags masked with the tree's Pt_ARG_TREE_IMGMASK resource give a nonzero value. The flags include:

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.
Pt_TREE_ITEM_EXPANDED
The branches of this item are currently displayed.

Pt_CB_TREE_SELECTION

C type Pt type Default
PtCallback_t * Link NULL

A list of callbacks invoked when an item is selected from the tree.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_TREE_SELECTION
reason_subtype
This value depends on the selection mode. One of:
event
The event that triggered this callback.
cbdata
This points to a PtTreeCallback_t structure that contains at least the following members:
unsigned sel_mode;
The current selection mode (Pt_ARG_SELECTION_MODE).
PtTreeItem_t *item;
If the selection mode isn't set to Pt_RANGE_MODE, item is the item the user clicked on. If the selection mode is set to Pt_RANGE_MODE, item is the first of the selected items.
unsigned nitems;
This contains the number of selected items, excluding collapsed subtrees.
int click_count;
The number of mouse clicks (0 for keyboard events or if event is NULL).

These callbacks should return Pt_CONTINUE.

If you multi-click on a tree, its Pt_CB_TREE_SELECTION callbacks are invoked once for each click. The callback data includes the click count (1 for the first click, 2 for the second, and so on).

If you want to process only the last of a series of clicks, use a Pt_CB_RAW callback to look for a Ph_EV_BUT_RELEASE event with a subtype of Ph_EV_RELEASE_ENDCLICK. For more information, see PhEvent_t in the Photon Library Reference.


Note: The Ph_EV_BUT_RELEASE event with a subtype of Ph_EV_RELEASE_ENDCLICK occurs approximately half a second after the click, which could be annoying to the user. Most Photon applications don't use multiple clicks because of this.

Pt_CB_TREE_STATE

C type Pt type Default
PtCallback_t * Link NULL

Defines the state callbacks. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
Pt_CB_TREE_STATE
reason_subtype
Pt_TREE_COLLAPSING or Pt_TREE_EXPANDING.
event
The event that triggered this callback.
cbdata
This points to a PtTreeCallback_t structure that contains at least the following members:
unsigned sel_mode;
The current selection mode (Pt_ARG_SELECTION_MODE).
PtTreeItem_t *item;
The item that's being collapsed or expanded.
int expand;
If reason_subtype is Pt_TREE_EXPANDING, this may be assigned a nonzero value to suppress expansion.

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 PtContainer
Pt_ARG_ANCHOR_OFFSETS PtContainer
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BALLOON_COLOR PtGenList
Pt_ARG_BALLOON_FILL_COLOR PtGenList
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BORDER_WIDTH PtWidget
Pt_ARG_BOT_BORDER_COLOR PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_LIST_COLUMN_ATTR PtGenList
Pt_ARG_LIST_COLUMN_POS 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_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_TOP_BORDER_COLOR PtBasic
Pt_ARG_TOP_ITEM_POS PtGenList
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_TREE_FLAGS PtGenTree See below.
Pt_ARG_USER_DATA PtWidget
Pt_ARG_VISIBLE_COUNT PtGenList
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer Not used by this class.
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_FILTER PtContainer
Pt_CB_GEN_TREE_INPUT PtGenTree
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
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:


PtTree balloon widths


The Pt_ARG_TREE_FLAGS for a PtTree widget.


Convenience functions:

The PtTree widget defines the following convenience functions that make it easier to use the tree once it's been created:

PtTreeAddAfter()
Insert an item after the specified item
PtTreeAddFirst()
Add a root item to the widget, or adds an item as the first child of a specified item
PtTreeAddImages()
Add images to the PtTree widget's image list
PtTreeAllItems()
Fill a buffer with pointers to all items
PtTreeAllocItem()
Allocate a new item
PtTreeClearSelection()
Clear the selection
PtTreeCollapse()
Collapse an expandable item
PtTreeExpand()
Expand an expandable item
PtTreeFreeAllItems()
Unlink and free all items
PtTreeFreeItems()
Free an unlinked item
PtTreeGetCurrent()
Get the current item
PtTreeGetSelIndexes()
Fill a buffer with indexes of selected items
PtTreeGoto()
Set the current item
PtTreeItem_t
PtTree item structure
PtTreeItemIndex()
Calculate the index of the specified item
PtTreeModifyItem()
Change item resources
PtTreeRemoveChildren()
Unlink the children of the specified item
PtTreeRemoveItem()
Unlink an item
PtTreeRemoveList()
Unlink the given item and any siblings that follow
PtTreeRootItem()
Return the first root item of the tree
PtTreeSelect()
Select the specified item
PtTreeSelectedItems()
Fill a buffer with pointers to the selected items
PtTreeSetSelIndexes()
Set the selection indexes
PtTreeShow()
Set the position so that the specified item is visible
PtTreeUnselect()
Unselect the specified item
PtTreeUnselectNonBrothers()
Unselect all items that aren't siblings of the specified item

[Previous] [Contents] [Index] [Next]