# ListTree Widget

A low resource widget designed to display text strings in a "directory list" sort of structure.

- BETA
- Screen Shots
  - Basic Demo
- Important version 3.0 changes
- Overview
- Features
- Requirements
- History
- Author's Note
- Thanks
- Copyright

- Programmer's Documentation

## BETA

The current beta version is 3.0b3. Source is available at ftp.x.org.

This web page is not entirely up to date with respect to version 3.0 features. Caveat Emptor; USL!

I plan on adding several more features to a final version 3 release; I have received lots of mail asking about new features, and 3.0 addresses most of the shortcomings.

The previous stable version is 2.0, also available at ftp.x.org.

## Screen Shots

### Basic Demo

This picture shows the formatting of the ListTree widget:

## Important version 3.0 changes

The ListTree is now entirely Motif/LessTif based! Due to my involvement with the LessTif project, it only operates as a child of an XmScrolledWindow. (I think that standardization on one user interface for unix is necessary for the survival of our favorite class of operating system, but that's another discussion. :)

One of the most important changes (besides the Motif dependency) is that Version 3 doesn't suffer from the ~64,000 pixel limit height of an X11 widget. This version only draws items that are shown in the window, rather than rendering the entire list while clipping to the visible window.

All features from version 2.0 have been retained, and many new features have been added. New features include the ability to specify pixmaps on a per-item basis, and multiple discontinuous select. To be added before the final version 3 release will be keyboard traversal.

## Overview

The ListTree Widget is small list widget capable of displaying lists of text strings (with an optional pixmap) in a heirarchal directory list sort of format. Unlike all of the other freely available tree widgets that I could find, this widget does not use widgets for each item displayed in the tree. Instead, it is a list of text strings that contain pointers to parents and children in the tree. This reduces memory usage over widget tree widgets, and also simplifies use.

This widget was designed for use in file manager type programs, so an optional pixmap is available for displaying to the left of the text item. The pixmap has an open and closed state, and different types of pixmaps are available for items with and without children. Currently, pixmaps for different file types are not available.

The lists are activated by clicking the left mouse button on the Pixmap of the item, or double clicking ond the name of the item. The state of the item is then toggled, and if the item is open, its children are displayed. Ranges of items can also be toggled by clicking and dragging the left mouse button over the names of the items you want to highlight.

## Features

Features provided in the widget include the following:

- Pixmap displayed to the left of the text string
- Individually specified pixmaps per item
- Default pixmaps for open and closed states
- Item highlighting (single, multiple, or discontinuous select)
- Double click name or single click on icon to open or close
- Callbacks: (called when selected or unselected)
  - Activate
  - Highlight
  - Menu (when right button pressed)
  - Item Destroy
    - Any item
    - Item with children
    - Item without children
- Selectable line width
- Selectable font
- Various spacing options
- Convenience Functions:
  - Add Item
  - Delete Item (also deletes dependent children)
  - Reparent Item
  - Reparent item's children
  - Order items
  - Order item's children
  - Search for item text
  - Highlight item

## Requirements

The ListTree code requires X11R5 or later and an ANSI C compiler. The code may compile on a non-ANSI compiler if it supports new style function definitions.

The widget now requires Motif or LessTif.

## History

This code was originally developed on an IBM RS/6000 running AIX 4.1 and X11R5. Version 2.0 was developed on a Linux machine running kernel 1.3.* and XFree86 3.1.2 (X11R6). Version 3.0 was developed on Linux 2.0 using the LessTif toolkit. It was also tested on two other machines: a DEC Alpha/AXP running OSF/1 3.0 with X11R5; and an SGI Indigo running IRIX 4.0.5 with X11R4.

## Author's Note

This widget is supplied as freeware, in the hope that it will be useful for developers in the X community. If you do use this widget, I do request that you include mention of the ListTree widget in the documentation. Also, remember to include a copy of the entire copyright and permission notice! Thanks.

Patches, improvements, suggestions, bug reports, job offers, volleyball games, and money you love donating to programmers who make your life so much easier are welcome at `<rwmcm@orion.ae.utexas.edu>`. I will periodically post patches and improvements to ftp.x.org and the ListTree web page at http://www.ae.utexas.edu/~rwmcm/ListTree.html

## Thanks

Thanks to the following people for providing fixes and suggestions:

- Alan Marcinkowski `<alan@paragon.com>`
- Kevin Carson `<kcarson@direct.ca>`
- Tessa Lau `<tlau@allegra.att.com>`
- Pierre Duchene `<pierre@ovs.com>`
- Oyvind Yrke `<oyvind@stavanger.geco-prakla.slb.com>`
- Douglas Kosovic `<douglask@dstc.edu.au>`
- Lance Holden `<Lance.Holden@dsto.defence.gov.au>`

## Copyright

Copyright (c) 1996 Robert W. McMullen

###### This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

###### This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

###### You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

SciPlot : Programmer's Reference | Demo Programs
ListTree : Programmer's Reference

Web Page Design by Rob McMullen
E-mail: rwmcm@mail.ae.utexas.edu
Updated: 29 Jul 96