ListTree Widget Programmer's Reference

• Viewing this document
• Usage
  • List Items
• New Resources
• Callbacks
  • Callback Resources
  • Activate Callback
  • Highlight Callback
• Historical Callbacks
• Public Functions
  • List Refresh Functions
  • List Item Manipulation Functions
  • List Item Ordering Functions
  • List Item Searching Functions
  • List Highlighting Functions

• Back to ListTree home page

Viewing this document

This programmer's reference for the ListTree widget uses HTML3 tables, support for which is becoming very common among WWW browsers. Both Netscape and Mosaic (the most common browsers) support tables, and support for tables in Chimera (my browser of choice) will be included in version 2.0.

Usage

To use the ListTree widget in an application, include the three source code files ListTree.c, ListTree.h, and ListTreeP.h with the rest of the source code for the application. Include the object ListTree.o in the Makefile rule that compiles the application.

In source code that uses the ListTree widget, include the following two header files before references to the plot widget:

 #include <X11/Intrinsic.h>
 #include "ListTree.h"

To create the ListTree widget, use the following code as an example:

 tree=XtVaCreateManagedWidget("tree",listtreeWidgetClass,parent,
        XtNheight,      	(Dimension)500,
        XtNwidth,		(Dimension)150,
 #ifdef MOTIF
	XtNborderWidth,		(Dimension)0,
 #endif
        NULL,0);

This example creates a 500x150 empty ListTree widget as the child of some container widget named parent. List items must be added to the widget using convenience functions, because I couldn't think of a good way to add heirarchal items through resources. The convenience function method is also very easy, so this design decision wasn't difficult.

The compilation conditional for MOTIF is used to get rid of the border drawn around the widget when using the MOTIF scrolled window as the parent.

Adding items to the list is outlined below:

int i;
ListTreeItem *level1,*level2;

	level1=ListTreeAdd(tree,NULL,"Item 1");
	level1=ListTreeAdd(tree,NULL,"Item 2");
	level2=ListTreeAdd(tree,level1,"Item 3");

This adds three items to the ListTree widget tree, where Item 3 is a child of Item 2, and both Item 1 and Item 2 are root level items. See Public Functions below for descriptions of all of the convenience functions.

List Items

The following structure is returned from the ListTreeAdd convenience function, and is used whenever an item is referenced.

typedef struct _ListTreeItem {
        Boolean         open;
        Boolean         highlighted;
        char            *text;
        int             length;
        int             x,y,ytext;
        Dimension       height;
        struct _ListTreeItem    *parent,
                        *firstchild,
                        *prevsibling,*nextsibling;
        XtPointer       user_data;
} ListTreeItem;

When this structure is returned for an item, the value points to the actual item, not a copy of the item. Do not modify any value in the structure except for the user_data entry, which is provided for your use. (Use the ListTreeRenameItem() public function to modify the text in the item.)

I'll rephrase this for emphasis: the items returned from the widget are the actual items the widget uses when it draws the tree. So, unless you want to Mess Things Up Real Good and crash your program, don't fiddle with the item structure.

OK, disclaimer out of the way, there is a lot of information available here that I didn't want to take away from you, gentle programmer. Stuff like open may be safely modified, but stay away from changing any of the positions or dimensions. Bad news to mess with those.

Really, Really, Really, don't modify parent, firstchild, prevsibling, or nextsibling.

I mean it, because it is possible to throw the widget into an infinite loop.

Trust me.

New Resources

The ListTree widget defines the following new resources:

Name	Class	Type	Default
XtNbranchOpenPixmap	XtCPixmap	Pixmap	XtUnspecifiedPixmap
XtNbranchPixmap	XtCPixmap	Pixmap	XtUnspecifiedPixmap
XtNfont	XtCFont	XFontStruct *	XtDefaultFont
XtNforeground	XtCForeground	Pixel	XtDefaultForeground
XtNhorizontalSpacing	XtCMargin	Dimension	2
XtNindent	XtCMargin	Dimension	0
XtNleafOpenPixmap	XtCPixmap	Pixmap	XtUnspecifiedPixmap
XtNleafPixmap	XtCPixmap	Pixmap	XtUnspecifiedPixmap
XtNlineWidth	XtCMargin	Dimension	0
XtNmargin	XtCMargin	Dimension	2
XtNverticalSpacing	XtCMargin	Dimension	0

XtNbranchOpenPixmap

Pixmap to use for an item that is open and has children.

XtNbranchOpenPixmap

Pixmap to use for an item that is closed and has children.

XtNfont

Font to use for items.

XtNforeground

Foreground color for text. Also used for the bitmap color, if any of the Pixmap resources is defined instead as a bitmap.

XtNhorizontalSpacing

Pixel distance between the Pixmap and item text.

XtNindent

Pixel distance to indent a new level of items. Note that this distance is in addition to the width of the Pixmap.

XtNleafOpenPixmap

Pixmap to use for an item that is open and does not have children.

XtNleafPixmap

Pixmap to use for an item that is closed and does not have children.

XtNlineWidth

Specifies the line width used to draw the list heirarchy.

XtNmargin

Pixel distance between the border of the widget and any text or Pixmap.

XtNverticalSpacing

Pixel distance between neighboring items in the list.

Callbacks

Callback Resources

The ListTree widget defines the following callback resources:

XtNactivateCallback

Called when any item is opened or closed.

XtNhighlightCallback

Called when any item is highlighted.

Activate Callback

This callback is called whenever an item is opened, or if an item is explicitly closed. The following structure is sent to the callback.

typedef struct _ListTreeActivateStruct {
        int             reason;
        ListTreeItem    *item;
        Boolean         open;
        ListTreeItem    **path;
        int             count;
} ListTreeActivateStruct;

reason

One of two constants, XtBRANCH or XtLEAF, indicating that the item has children or does not, respectively.

item

Pointer to the item selected (or unselected).

open

The state of the selected item.

path

The path from the root of the list to the selected item, including the selected item.

count

The number of items in path.

Highlight Callback

This callback is called whether the item is opened or closed, and is passed the following structure.

typedef struct _ListTreeMultiReturnStruct {
        ListTreeItem    **items;
        int             count;
} ListTreeMultiReturnStruct;

items

Pointer to a list of pointers that holds all of the highlighted items.

count

The number of highlighted items.

Historical Callbacks

Three other callbacks exist in the widget, but I decided not to document them.

New users, don't worry about the historical callbacks. The current callbacks are better.

Users of the previous version, please change to the new callbacks. You'll need to do the following:

1. change all references of XtNleafCallback, XtNbranchCallback, and XtNpathCallback to XtNactivateCallback
2. change the reference from ListTreeReturnStruct to ListTreeActivateStruct
3. use the reason field instead of individual path or leaf callbacks.
4. DO NOT free() THE CALLBACK STRUCTURE as you had to do with the old callbacks.

Public Functions

All changes to the widget are reflected immediately, unless a call to ListTreeRefreshOff() is made before updating. ListTreeRefreshOn() must be called before the list will start to update itself again.

I could probably have gone on forever writing convenience functions for more and more generalized states, but I'd still be typing the source code, and not working on this here primo-excellent documentation. :) So, this is where the "batteries not included" phrase enters in: it is up to you to customize the widget for your own use. The entire tree of items contained in the widget is available for parsing by you by calling ListTreeFirstItem() and using the firstchild and nextsibling fields of the ListTreeItem structure.

Be careful not to copy over the text field of a ListTreeItem, because it is a malloced string. Use ListTreeRenameItem() if you need to change a name.

• List Refresh Functions

  void ListTreeRefreshOff(ListTreeWidget w)

  Turns off the automatic updating of the list. Useful when adding many items to the list.

  void ListTreeRefreshOn(ListTreeWidget w)

  Turns on the automatic updating.

• List Item Manipulation Functions

  ListTreeItem *ListTreeAdd(ListTreeWidget w, ListTreeItem *parent, char *string)

  Adds an item to the list as a child of parent. If parent is NULL, adds the item as a root item. All items are added at the end of the list of children of that parent; i.e. they are not sorted. Returns NULL if an error occurs.

  int ListTreeDelete(ListTreeWidget w, ListTreeItem *item)

  Removes item and all of its children from the list. Returns 1 if successful, 0 if failure.

  int ListTreeDeleteChildren(ListTreeWidget w, ListTreeItem *item)

  Removes only the children of item from the list. Returns 1 if successful, 0 if failure.

  void ListTreeRenameItem(ListTreeWidget w, ListTreeItem *item, char *string)

  Changes the text of item to string.

  int ListTreeReparent(ListTreeWidget w, ListTreeItem *item, ListTreeItem *newparent)

  Moves item to become a new child of newparent. Returns 1 if successful, 0 if failure.

  int ListTreeReparentChildren(ListTreeWidget w, ListTreeItem *item, ListTreeItem *newparent)

  Moves the children of item to become a new children of newparent. Returns 1 if successful, 0 if failure.

• List Item Ordering Functions

  int ListTreeOrderChildren(ListTreeWidget w, ListTreeItem *item)

  Alphabetize the children of item. Returns 1 if successful, 0 if failure.

  int ListTreeOrderSiblings(ListTreeWidget w, ListTreeItem *item)

  Alphabetize all siblings of item. Returns 1 if successful, 0 if failure.

  int ListTreeUserOrderChildren(ListTreeWidget w, ListTreeItem *item,int (*func)())

  Orders the children of item according to a user-specified procedure. Returns 1 if successful, 0 if failure.

  int ListTreeUserOrderSiblings(ListTreeWidget w, ListTreeItem *item,int (*func)())

  Orders all siblings of item according to a user-specified procedure. Returns 1 if successful, 0 if failure.

  Note for the user order subroutines: func() should be a pointer to a function that can be fed to qsort(). I.e. it takes two void pointers and returns an integer that is negative if the first item should be listed before the second, positive if the first should be listed after the second, and zero if the two items go in the same position. The list that is sorted by qsort is a list of ListTreeItem pointers, so each void pointer to your sorting function must cast into a pointer to a ListTreeItem pointer. A bit of code would probably make this clearer: the following code is from ListTree.c that is used to alphabetize the list.

  int
  AlphabetizeItems(const void *item1, const void *item2)
  {
    return strcmp((*((ListTreeItem **) item1))->text,
  		(*((ListTreeItem **) item2))->text);
  }
  

• List Item Searching Functions

  ListTreeItem *ListTreeFirstItem(ListTreeWidget w)

  Returns the first item in list. Returns NULL if there are no items in the list.

  ListTreeItem *ListTreeFindSiblingName(ListTreeWidget w, ListTreeItem *item, char *name)

  Searches for name among the siblings of item. Returns NULL if the name is not found.

  ListTreeItem *ListTreeFindChildName(ListTreeWidget w, ListTreeItem *item, char *name)

  Searches for name among the children of item. Returns NULL if the name is not found.

• List Highlighting Functions

  void ListTreeHighlightItem(ListTreeWidget w, ListTreeItem *item)

  Highlights item and unhighlights previously highlighted items.

  void ListTreeHighlightedAll(ListTreeWidget w)

  Highlights all items currently visible in the widget. Only top level items and items that are direct descendants of open items are highlighted. I.e. items whose parents are closed are not highlighted.

  void ListTreeClearHighlighted(ListTreeWidget w)

  Unhighlights any items currently selected in the widget.

  void ListTreeGetHighlighted(ListTreeWidget w,ListTreeMultiReturnStruct *ret)

  Fills the return struct with the items currently selected in the widget.

  void ListTreeSetHighlighted(ListTreeWidget w, ListTreeItem **items, int count, Boolean clear)

  Unhighlights any previously highlighted items if clear is True. Then, highlights count items from the list items. If count is negative, the list items should be NULL terminated.