# XltListTree Widget Programmer's Reference

- Usage
  - List Items
- New Resources
- Callbacks
  - Callback Resources
  - Activate Callback
  - Highlight Callback
  - Menu Callback
  - Item Destroy Callback
- Historical Callbacks
- Public Functions
  - Widget Creation Functions
  - List Refresh Functions
  - List Item Manipulation Functions
  - List Item Ordering Functions
  - List Item Searching Functions
  - List Highlighting Functions

- Back to XltListTree home page

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

            tree=XltCreateScrolledXltListTree(parent,"tree",NULL,0);

This example creates an empty XltListTree widget as the child of some container widget named parent. The XltListTree widget now creates its own scrollbars and does not have to be placed in a scrolling container widget. It is also now dependent on the Motif widget set; I broke my rules about using Motif in non-free programs because the LessTif project is far enough along that the scrollbars are quite stable. Once LessTif is complete, there will be no reason to use any other toolkit.

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.

Adding items to the list is outlined below:

    int i;
    XltListTreeItem *level1,*level2;

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

This adds three items to the XltListTree 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 XltListTreeAdd convenience function, and is used whenever an item is referenced.

    typedef struct _XltListTreeItem {
      Boolean       open;
      Boolean       highlighted;
      char          *text;
      int           length;
      int           x,y,ytext;
      int           count;
      Dimension     height;
      XltListTreeItemType type;
      struct _XltListTreeItem  *parent,*firstchild,*prevsibling,*nextsibling;
      Pixmap        openPixmap,closedPixmap;
      XtPointer     user_data;
    } XltListTreeItem;

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 XltListTreeRenameItem() 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 XltListTree widget defines the following new resources:

Name | Class | Type | Default
--- | --- | --- | ---
XtNbranchOpenPixmap | XtCPixmap | Pixmap | XtUnspecifiedPixmap
XtNbranchPixmap | XtCPixmap | Pixmap | XtUnspecifiedPixmap
XtNclickPixmapToOpen | XtCBoolean | Boolean | True
XtNdoIncrementalHighlightCallback | XtCBoolean | Boolean | False
XtNfont | XtCFont | XFontStruct* | XtDefaultFont
XtNforeground | XtCForeground | Pixel | XtDefaultForeground
XtNhighlightPath | XtCBoolean | Boolean | False
XtNhorizontalSpacing | XtCMargin | Dimension | 2
XtNindent | XtCMargin | Dimension | 0
XtNleafOpenPixmap | XtCPixmap | Pixmap | XtUnspecifiedPixmap
XtNleafPixmap | XtCPixmap | Pixmap | XtUnspecifiedPixmap
XtNlineWidth | XtCMargin | Dimension | 0
XtNmargin | XtCMargin | Dimension | 2
XtNspacing | XtCMargin | Dimension | 4
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.
XtNclickPixmapToOpen
  If True, a single click on the pixmap of an item is equivalent to a double click on the item's text.
XtNdoIncrementalHighlightCallback
  Calls the highlight callback after each item is highlighted; otherwise only calls the callback after the button has been released and all items have been highlighted.
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.
XtNhighlightPath
  Highlights the item's parents when an item is opened.
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 XltListTree widget defines the following callback resources:

XtNactivateCallback
  Called when any item is opened or closed.
XtNhighlightCallback
  Called when any item is highlighted.
XtNmenuCallback
  Called when the right mouse button is pressed over an item.
XtNdestroyItemCallback
  Called for each items that is deleted. This allows for the graceful freeing of anything allocated for user_data.

### 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 _XltListTreeActivateStruct {
            int             reason;
            XltListTreeItem    *item;
            Boolean         open;
            XltListTreeItem    **path;
            int             count;
    } XltListTreeActivateStruct;

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 _XltListTreeMultiReturnStruct {
            XltListTreeItem    **items;
            int             count;
    } XltListTreeMultiReturnStruct;

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

### Menu Callback

This callback can be used to post a menu over the item, or some other application defined function may be implemented. It is passed the ItemReturn structure.

    typedef struct _XltListTreeItemReturnStruct {
      int		reason;
      XltListTreeItem	*item;
      XEvent	*event;
    } XltListTreeItemReturnStruct;

reason
  The constant XtMENU.
item
  Pointer to the highlighted item.
event
  The XEvent that triggered the callback (should be cast to a pointer to an XButtonEvent).

### Item Destroy Callback

Called whenever an item is deleted, the callback function is passed the ItemReturn structure.

    typedef struct _XltListTreeItemReturnStruct {
      int		reason;
      XltListTreeItem	*item;
      XEvent	*event;
    } XltListTreeItemReturnStruct;

reason
  The constant XtDESTROY.
item
  Pointer to the highlighted item.
event
  This is not used and is assigned the value NULL.

## Historical Callbacks

Three other callbacks did exist in previous versions of the widget, but I removed them. I warned ya! :)

## Public Functions

All changes to the widget are reflected immediately, unless a call to XltListTreeRefreshOff() is made before updating. XltListTreeRefreshOn() 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 XltListTreeFirstItem() and using the firstchild and nextsibling fields of the XltListTreeItem structure.

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

- ### Widget Creation Functions

  Widget XltCreateScrolledXltListTree(Widget parent, char *name, Arg *args, Cardinal count)
    Creates a XltListTree widget as a child of an XmScrolledWindow (which in turn is a child of parent), and returns its widget ID.

- ### List Refresh Functions

  void XltListTreeRefreshOff(XltListTreeWidget w)
    Turns off the automatic updating of the list. Useful when adding many items to the list.
  void XltListTreeRefreshOn(XltListTreeWidget w)
    Turns on the automatic updating.

- ### List Item Manipulation Functions

  XltListTreeItem *XltListTreeAdd(XltListTreeWidget w, XltListTreeItem *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 XltListTreeDelete(XltListTreeWidget w, XltListTreeItem *item)
    Removes item and all of its children from the list. Returns 1 if successful, 0 if failure.
  int XltListTreeDeleteChildren(XltListTreeWidget w, XltListTreeItem *item)
    Removes only the children of item from the list. Returns 1 if successful, 0 if failure.
  void XltListTreeRenameItem(XltListTreeWidget w, XltListTreeItem *item, char *string)
    Changes the text of item to string.
  int XltListTreeReparent(XltListTreeWidget w, XltListTreeItem *item, XltListTreeItem *newparent)
    Moves item to become a new child of newparent. Returns 1 if successful, 0 if failure.
  int XltListTreeReparentChildren(XltListTreeWidget w, XltListTreeItem *item, XltListTreeItem *newparent)
    Moves the children of item to become a new children of newparent. Returns 1 if successful, 0 if failure.
  void XltListTreeGetPathname(XltListTreeReturnStruct * ret, char *dir)
    Copies the path of the given list structure to the supplied pointer.
  void XltListTreeGetPathnameFromItem(XltListTreeItem * item, char *dir)
    Copies the path of the given item to the supplied pointer.
  Position XltListTreeGetItemPosition(XltListTreeWidget w, XltListTreeItem * item)
    Retrieves the Position of the given item

- ### List Item Ordering Functions

  int XltListTreeOrderChildren(XltListTreeWidget w, XltListTreeItem *item)
    Alphabetize the children of item. Returns 1 if successful, 0 if failure.
  int XltListTreeOrderSiblings(XltListTreeWidget w, XltListTreeItem *item)
    Alphabetize all siblings of item. Returns 1 if successful, 0 if failure.
  int XltListTreeUserOrderChildren(XltListTreeWidget w, XltListTreeItem *item,int (*func)())
    Orders the children of item according to a user-specified procedure. Returns 1 if successful, 0 if failure.
  int XltListTreeUserOrderSiblings(XltListTreeWidget w, XltListTreeItem *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 XltListTreeItem pointers, so each void pointer to your sorting function must cast into a pointer to a XltListTreeItem pointer. A bit of code would probably make this clearer: the following code is from XltListTree.c that is used to alphabetize the list.

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

- ### List Item Searching Functions

  XltListTreeItem *XltListTreeFirstItem(XltListTreeWidget w)
    Returns the first item in list. Returns NULL if there are no items in the list.
  XltListTreeItem *XltListTreeFindSiblingName(XltListTreeWidget w, XltListTreeItem *item, char *name)
    Searches for name among the siblings of item. Returns NULL if the name is not found.
  XltListTreeItem *XltListTreeFindChildName(XltListTreeWidget w, XltListTreeItem *item, char *name)
    Searches for name among the children of item. Returns NULL if the name is not found.

- ### List Highlighting Functions

  void XltListTreeHighlightItem(XltListTreeWidget w, XltListTreeItem *item)
    Highlights item and unhighlights previously highlighted items.
  void XltListTreeHighlightAll(XltListTreeWidget 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 XltListTreeClearHighlighted(XltListTreeWidget w)
    Unhighlights any items currently selected in the widget.
  void XltListTreeGetHighlighted(XltListTreeWidget w,XltListTreeMultiReturnStruct *ret)
    Fills the return struct with the items currently selected in the widget.
  void XltListTreeSetHighlighted(XltListTreeWidget w, XltListTreeItem **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.

XltListTree : Programmer's Reference