The NaryTree Widget

1. Copyright and License Terms

2. Introduction

The NaryTree widget is an Xt /Motif widget developed by CGI to display and edit data structures the contain hierarchical relationships. The tree is rendered with the root at the left of the screen and grows from left to right. Each node in the tree contains 0 or more hooks. A hook is an attachment for children of the node. Application data may be associated with nodes in the tree and the application can perform actions based on user interaction with nodes and hooks in the tree in the tree.

Each node and hook in the tree can display a string, a pixmap, and a widget. API calls allow users to walk the tree, get the current selection from the tree, and add/remove nodes from the tree.

3. Distribution Kit

The source distribution kit contains the following files:

NaryTree.c

The NaryTree widget source code

NaryTree.h

Public include file for application programming with the NaryTree Widget.

NaryTreeP.h

Private include file for writing subclasses of the NaryTree Widget.

nary_tree_demo.c

Demonstration program.

Makefile

Makefile to compile source code

4. Resources

The XcgNaryTreeWidget is descended from the Motif XmManager widget. It inherits resources from Core, Composite, Constraint, and XmManager. In addition, the NaryTree widget defines the following new resources.

XcgNnodeWidth

Type = int, Default = 32, Access = C
Default width of a node if label parameters are not specified for the node. Note that the nodes of the tree grow and shrink dynamically with the titles, labels and widgets contained within them. This value specifies only the default size.

XcgNnodeHeight

Type = int, Default = 32, Access = C
Default height of a node if label parameters are not specified for the node. Note that the nodes of the tree grow and shrink dynamically with the titles, labels and widgets contained within them. This value specifies only the default size.

XcgNhookSpacing

Type = int, Default = 2, Access = C
Spacing between hooks on a node.

XcgNnodeHookWidth

Type = int, Default = 16, Access = C
Default width of a node hook if label parameters are not specified for the hook. This is the length of the hook up to the circle at the end of the hook. Note that the length of hooks of a node grow and shrink dynamically with the largest title/pixmap/widget associated with any hook.

XcgNnodeHookHeight

Type = int, Default = 16, Access = C
Defines the size of the circle drawn at the end of a hook.

XcgNnodeSelectCallback

Type = XtCallback, Default = NULL, Access = C
Callback Function that gets notified when a user selects a node in a tree. Passes back call data of type XcgNaryTreeCallbackData *. When the user presses the mouse button, a node changes color and is displayed as a depressed button.

XcgNnodeDeselectCallback

Type = XtCallback, Default = NULL, Access = C
Callback when a node changes from the selected to deselected state. This routine will get called if a different node or hook in the tree is selected, or if the user clicks on the background of the widget.

XcgNnodeHookSelectCallback

Type = XtCallback, Default = NULL, Access = C
Callback for user selection of a hook in the tree. When the user presses the mouse button, a hook will change color.

XcgNnodeHookDeselectCallback

Type = XtCallback, Default = NULL, Access = C
Callback when a hook changes from the selected to deselected state. This routine will get called if a different node or hook in the tree is selected, or if the user clicks on the background of the widget.

XcgNuserContext

Type = XtPointer, Default = NULL, Access = C
User context to associate with widget.

XcgNnodeFont

Type = XtFontSet, Default = "-adobe-new century schoolbook-medium-r-normal-*-14-*", Access = C
Font used to render labels on the tree.

XcgNnodeForeground

Type = Pixel, Default = "back", Access = C
Color to render node foreground.

XcgNnodeBackground

Type = Pixel, Default = "lightgray", Access = C
Color to render node background.

XcgNhightlightRoot

Type = Boolean, Default = False, Access = C
Indicates if the root node should be rendered in a different color from other nodes in the tree.

XcgNhightlightLeaf

Type = Boolean, Default = False, Access = C
Indicates if leaf nodes should be rendered in a different color from other nodes in the tree.

XcgNhightlightRootColor

Type = Pixel, Default = "LightGoldenrodYellow", Access = C
Color to render the root node in the tree.

XcgNhightlightLeafColor

Type = Pixel, Default = "HotPink1", Access = C
Color to render leaf nodes in the tree.

5. API

5.1 XcgNTAddNode

Function

Add a node to the tree in the widget.

C-Call

XcgNaryTreeNode XcgNTAddNode
(
	XcgNaryTreeWidget 	cw,
	XcgNaryTreeNode 	parent,
	int 			hook_num,
	char *			title,
	void 			*user_context,
	Pixmap 			pixmap,
	int			num_hooks
)

Inputs

parent

Parent of the node in the tree. Pass NULL for a root node.

hook_num

Indicates which hook of the parent this node will be attached to, 1 == first hook, ..., n == nth child.

context

user defined context to associate with this node.

title

Multibyte text string to associate with node.

pixmap

Pixmap to display with this node.

num_hooks

Number of hooks this node can support

Outputs

None.

Returns

Value of 0 indicates failure. Value > 0 is handle to associate with this node of the tree.

5.2 XcgNTRemoveNode

Function

Remove a node and all its children from the tree.

C-Call

void XcgNTRemoveNode
(
	Widget			w,
	XcgNaryTreeNode 	node,
	int			options
)

Input

w

Nary Tree Widget.

node

Node to remove, (or NULL if passing XcgOPT_ALL).

options

Logically or'ed list of options:

XcgOPT_ALL

Remove all nodes in tree.

XcgOPT_FREE

Call free() on user context for each node in tree.

Outputs

None.

Returns

None.

5.3 XcgNTHookSetTitle

Function

Add a label to a hook on a node.

C-Call

void XcgNTHookSetTitle
(
	Widget			w,
	XcgNaryTreeNode 	node,
	int			hook_num,
	char			*label_string
)

Inputs

w

Nary Tree Widget.

node

Node to add title to.

hook_num

Hook number to associate with title. Valid range is 1 - n where n == number of hooks node was created with.

label_string

Label to add to the hook. Replace any label previously active for hook.

Outputs

None.

Returns

None.

5.4 XcgNTHookSetPixmap

Function

Add a pixmap to a hook on a node.

C-Call

void XcgNTHookSetPixmap
(
	Widget			w,
	XcgNaryTreeNode 	node,
	int			hook_num,
	Pixmap			pixmap
)

Inputs

w

Nary Tree Widget.

node

Node to add pixmap to.

hook_num

Hook number to associate with pixmap. Valid range is 1 - n where n == number of hooks node was created with.

pixmap

Pixmap to add to the hook. Replace any pixmap previously active for hook.

Outputs:

None.

Returns

None.

5.5 XcgNTHookSetWidget

Function

Associate a widget with a hook.

C-Call

void XcgNTHookSetWidget
(
	Widget			w,
	XcgNaryTreeNode 	node,	
	int			hook_num,
	Widget			child
)

Inputs

w

Nary Tree Widget.

node

Node to add the widget to.

hook_num

Hook number to associate this widget with. Valid range is 1 - n where n == number of hooks node was created with.

child

Widget to display in this node.

Outputs

None.

Returns

None.

5.6 XcgNTWalkTree

Function

Walk the tree and call the specified callback function at each node.

C-Call

void XcgNTWalkTree
(
	Widget			w,
	XcgNaryTreeNode		start_node,
	XcgNTTraversalOrderEnum	traversal_order,
	void			*walk_context,
	XcgNTWalkCallback	callback
)

Inputs

w

The NaryTree Widget

start_node

Node to start from or NULL to walk the tree starting at the root node.

traversal_order

Specifies when to call the callback function in the walk. Valid values are:

XcgTO_PreOrder

Call the callback for the current node *before* calling it for its children.

XcgTO_PostOrder

Call the callback for the current node *after* calling it for its children.

walk_context

User data passed to the callback function for each node.

callback

Function to call for each node. XcgNTWalkCallback is defined as:

typedef int (*XcgNTWalkCallback)
(
	Widget w,
	XcgNaryTreeNode node,
	void *walk_context,
	void *node_context
);

Outputs

None.

Returns

None.

5.7 XcgNTQueryNode

Function

Get info about a node in the tree.

C-Call

int XcgNTQueryNode
(
	Widget 		w,
	XcgNaryTreeNode	node,
	void		**ret_user_context,
	int		*ret_num_hooks,
	int		*ret_num_children,
	XcgNaryTreeNode *ret_parent,
	int		*ret_hook_num,
	char 		*ret_title,
	Pixmap		*ret_pixmap,
	int		*is_selected
)

Inputs

w

Nary Tree Widget.

node

The node to query.

Outputs

ret_user_context

User context associated with this node.

ret_num_hooks

Number of hooks this node has.

ret_parent

Parent of this node in the tree.

ret_num_children

Number of children that are directly beneath this node.

ret_hook_num

Hook number of parent that this node is attached to.

ret_title

copy of the title of hook is copied into this buffer (caller is responsible for supplying space for the buffer).

ret_pixmap

Pixmap associated with the hook.

Returns

Returns 0 on success, returns -1 on error.

5.8 XcgNTQueryTree

Function

Return information about the tree widget

C-Call

int XcgNTQueryTree
(
	Widget 		w,
	XcgNaryTreeNode *root,
	int		*width,
	int		*height,
	int		*num_nodes,
)

Inputs

w

Nary Tree Widget.

Outputs

ret_root

Root node of the tree or NULL if tree is empty.

ret_width

Width of the tree in pixels.

ret_height

Height of tree in pixels.

ret_num_nodes

Number of nodes in the tree.

Returns

Returns 0 on success, returns -1 on error.

5.9 XcgNTQueryHook

Function

Return information about a hook in the tree.

C-Call

void * XcgNTQueryHook
(
	Widget		w,
	XcgNaryTreeNode	node,
	int		hook_num,
	int		*ret_num_children,
	char		*ret_title,
	Pixmap		*ret_pixmap
	int		*is_selected
)

Inputs

w

Nary tree Widget.

node

Node to get user context for.

hook_num

Position of this hook on the node.

Outputs

ret_num_children

Number of children attached to this hook.

ret_title

Copy of the title of hook is copied into this buffer (caller is responsible for supplying space for the buffer).

ret_pixmap

Pixmap associated with the hook.

Returns

void * - user context stored with node or NULL if none was stored.

5.10 XcgNTGetRoot

Function

Convenience routine to return the root node. [More convenient than calling XcgNTQueryTree()].

C-Call

XcgNaryTreeNode XcgNTGetRoot
(
	Widget 	w
)

Inputs

w

Nary Tree widget.

Outputs

None.

Returns

The root node on success, NULL if there is no root node.

5.11 XcgNTNodeSetContext

Function

Add User Context to a node in the tree.

C-Call

void XcgNTNodeSetContext
(
	Widget		w,
	XcgNaryTreeNode	node,
	void 		*context
)

Inputs

w

Nary Tree Widget.

node

Node to add context to.

context

User context value to assign to node.

Outputs

None.

Returns

None.

5.12 XcgNTNodeSetWidget

Function

Add a widget to a node in the tree.

C-Call

void XcgNTNodeSetWidget
(
	Widget		w,
	XcgNaryTreeNode	node,
	Widget		child
)

Inputs

w

Nary Tree Widget.

node

Node to add title.

child

Widget to show inside this node.

Outputs

None.

Returns

None.

5.13 XcgNTNodeSetTitle

Function

Add a title to a node in the tree.

C-Call

void XcgNTNodeSetTitle
(
	Widget		w,
	XcgNaryTreeNode	node,
	char		*title
)

Inputs

w

Nary Tree Widget.

node

Node to add title to.

title

String to set title to or NULL for no title.

Outputs

None.

Returns

None.

5.14 XcgNTNodeSetPixmap

Function

Set the pixmap for a node in the tree.

C-Call

void XcgNTNodeSetPixmap
(
	Widget		w,
	XcgNaryTreeNode	node,
	Pixmap		pixmap
)

Inputs

w

Nary Tree Widget.

node

Node to assign pixmap to.

pixmap

Pixmap to assign to node.

Outputs

None.

Returns

None.

5.15 XcgNTNodeGetContext

Function

Get user context value associated with a node in the tree.

C-Call

void * XcgNTNodeGetContext
(
	Widget		w,
	XcgNaryTreeNode	node
)

Inputs

w

Nary tree Widget.

node

Node to get user context for.

Outputs

None.

Returns

void * - user context stored with node or NULL if none was stored.

5.16 XcgNTNodeGetParent

Function

Get the XcgNaryTreeNode value of the parent of this node, or NULL if the specified node is the root of the tree.

C-Call

XcgNaryTreeNode * XcgNTNodeGetParent
(
	Widget		w,
	XcgNaryTreeNode	node
)

Inputs

w

Nary tree Widget.

node

Node to get user context for.

Outputs

None.

Returns

Parent of the given node or NULL if the node is the root of the tree or no node is passed.

5.17 XcgNTHookGetChildren

Function

Return an array of XcgNaryTreeNode handles for all children that are attached to the specified hook. The caller is responsible for freeing the returned value with free().

C-Call

XcgNaryTreeNode * XcgNTHookGetChildren
(
	Widget		w,
	XcgNaryTreeNode	node,
	int		hook_num,
	int		*ret_num_children,
)

Inputs

w

Nary tree Widget.

node

Node to get user children for.

hook_num

Position of this hook in the node.

Outputs

ret_num_children

Number of children attached to this hook.

Returns

Array of XcgNaryTree nodes that are attached to this hook or NULL if no nodes are attached to the hook. NOTE: If non-null, the user is responsible for freeing these items with free().

5.18 XcgNTGetSelection

Function

Return an array of XcgNaryTreeSelection structures for all nodes/hooks that are currently selected. Although the current selection policy allows only one selection in the tree, a future implementation might allow multiple items in the tree to be selected.
The caller is responsible for freeing the returned value with free().

C-Call

XcgNaryTreeSelection * XcgNTGetSelection
(
	Widget		w,
	XcgNaryTreeNode	node,
	int		hook_num,
	int 		*ret_num_selections,
)

Inputs

w

Nary tree Widget

Outputs

ret_num_selections

Number of selections in tree.

Returns

On success, returns an array of XcgNaryTreeSelection. If no nodes are selected, returns NULL. NOTE: The user is responsible for freeing the returned items with free().

5.19 XcgNTSelect

Function

Selects a node.

C-Call

void XcgNTSelect
(
	Widget		w,
	XcgNaryTreeNode	node,
	int		hook_num,
	int		option
)

Inputs

w

Nary tree Widget.

node

Node parameter. if NULL, deselect all items.

hook_num

Hook number parameter.

option

List of options logically OR'ed together **currently unused. Will add options when alternate selection policies are in place.

Outputs

None.

Returns

None.