TreeWidgets 1.0a1 Documentation

1. README
   1. Introduction
   2. Modules in the Package
   3. What's New
   4. Usage
2. INSTALL
3. BUGS
4. TODO
5. LICENSE

README

August 29, 2002

Introduction

TreeWidgets is a Python-Tkinter library that provides general-purpose tree widgets. I decided to write it because I found that, though there are several Tkinter tree widgets available, the ones I have tried were all designed to work with one particular type of data structure, and were hard to adapt to other data structure.

My goals in creating the TreeWidgets library are:

• The widget must be able to display any hierarchical data structure, and should have built-in support for common structures such as XML DOMs and directory trees.
• You should be able either to pass the widget a data structure and have it automatically build and display the graphical tree, or to exercise more precise control through a low-level API.
• It should be possible to display a tree with built-in icons, icons provided by the application, or no icons at all. Similarly, it should be possible to specify different fonts according to the needs of your application.
• The widget should provide a reasonable set of default mouse and key bindings, but it should also be easy to override the defaults.
• The widget should support all relevant Tkinter configuration options.

This being the first Alpha release, there are numerous bugs and unimplemented features, but at least the first goal is substantially realized, and the package should be usable with a little work.

Modules in the Package

What's New

• Added showContent(), showAtts(), glimpse(), and unGlimpse() to TreeWidget. It is important to note that these methods do nothing by themselves; in order for them to do something useful, you must supply the TreeWidget constructor a dictionary of callbacks:

  {'showContent': <callable>, 'showAtts': <callable>,
   'glimpse': <callable>, 'unGlimpse': <callable>}
            

  Each callback must take a single argument, which will be a node in the tree data structure.

• Added default key bindings for <Return> (AKA the Enter key) and <Escape>. <Return> invokes TreeWidget.showContent(), and <Escape> invokes TreeWidget.deselectNode().

• Added behavior to the default mouse bindings for <Enter>, <Leave>, and <Double-Button>: <Enter> invokes TreeWidget.glimpse(), <Leave> invokes TreeWidget.unGlimpse(), and <Double-Button> invokes TreeWidget.showContent().

See ChangeLog for detailed changes, and API docs for usage.

Usage

Please see the API documentation in apidocs/ and the examples in the demos/ subdirectory.

INSTALL

If you have Python 2.0 or later installed, you should be able to install TreeWidgets with the command:

python setup.py install
    

Otherwise, you can either install the DistUtils package from:

http://www.python.org/sigs/distutils-sig/download.html
    

or you can simply unpack the archive in your Python site-packages directory (typically found at /usr/lib/python<version>/site-packages or /usr/local/lib/python<version>/site-packages on POSIX systems, or at C:\Python<version>\Lib\site-packages on Windows).

BUGS

Known Bugs and Limitations as of 8/26/2002
==========================================

Bugs:
-----

* When a tree is first displayed, Nodes with children appear
  with a 'minus' icon instead of a 'plus', even if they are
  collapsed. The icon does not change to a 'plus' unless the
  node's parent is collapsed and re-expanded.

* When you double-click a node, text may be selected across 
  multiple lines.

* Long node names wrap across lines, with no indentation on
  the second and subsequent lines.

* When a TextTree is displayed with no icons, selecting a 
  node causes the background and foreground to change 
  starting with the *second* character in the label instead
  of the first.


Limitations:
------------

* Most Tkinter configuration options are currently ignored.

* Functions for showing the content and attributes of a node
  are unimplemented.

* Font selection is unimplemented.
    

TODO

To-Do List for TreeWidgets
==========================

* Implement CanvasTree

* Implement lazy instantiation of sub-trees. This is
  particularly valuable for potentially large data structures
  such as file systems; currently, regardless of how many 
  levels are expanded in the display, the entire data
  structure must be read in and wrapped in TreeNode objects 
  before the tree is displayed.

* Implement Tkinter configuration options and font selection.

* Implement TreeWidget.showContentFunc, TreeWidget.showAttsFunc,
  and TreeWidget.glimpseFunc.
    

LICENSE

Copyright (c) 2002, Matthew C. Gushee
All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

  Redistributions of source code must retain the above
  copyright notice, this list of conditions and the following 
  disclaimer.

  Redistributions in binary form must reproduce the above
  copyright notice, this list of conditions and the following 
  disclaimer in the documentation and/or other materials provided
  with the distribution.

  Neither the name of the author nor the names of contributors 
  may be used to endorse or promote products derived from this 
  software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.