widgettree - Create and manipulate a widgettree widget

SYNOPSIS

widgettree pathName ?options?

INHERITANCE

itk::Widget <- Widgettree

STANDARD OPTIONS

background
foreground
cursor
highlightColor
font
highlightThickness
disabledForeground

See the "options" manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Name:                   closedIcon
Class:                  Icon
Command-Line Switch:	-closedicon

Command-Line
Switch:
-closecommand

Command-Line
Switch:
-createcommand

Name:                   indent
Class:                  Indent
Command-Line Switch:	-indent

Name:                   openIcon
Class:                  Icon
Command-Line Switch:	-openicon

Command-Line
Switch:
-opencommand

Name:                   padX
Class:                  PadX
Command-Line Switch:	-padx

Name:                   padY
Class:                  PadY
Command-Line Switch:	-pady


DESCRIPTION

The widgettree command creates an unfolding tree of widgets, with a button at each node to open and close the node. The widget is designed for implementing unfolding preference and dialog boxes as well as viewers of tree-like structures.

Each item in the tree is referenced by a unique id, which is constructed in the same manner as hierarchical Tk widget names, but without the leading period. For example, a node at the top level may have the id <code>foo</code>, and a widget contained within that node the id <code>foo.bar</code>. Widgets and nodes are added to the tree with the add method.

Widgets can be added to the tree either when the Widgettree is created or as each node is opened. To add widgets as node are opened, supply the -createcommand option. This command will be evaluated when a node with no children is opened -- it should call add to add children to the node.

TREE TRAVERSAL

If the -traversal option is true, the widget tree can be navigated using tab traversal and cursor keys. Each button will accept the focus, and can be traversed using the standard Tk traversal mechanism. The Return key opens or closes the node with the focus. In addition, cursor keys navigate the tree as follows:
down
Move to the next button in the same node. If at the bottom, stay there.
up
Move to the previous button in the same node. If at the top, stay there.
left
Move up to the parent node, if there is one. If there isn't, stay there.
right
If the node is closed, open it. If there are child nodes, move to the first child. If there aren't any, stay there.

Widgettree does not implement a selection mechanism, but does provides some support for it with the locate method. If required, selection can be implemented by wrapping or subclassing Widgettree.

METHODS

The widgettree command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:

pathName option ?arg arg ...?
Option and the args determine the exact behavior of the command. The following commands are possible for widgettree widgets:

WIDGET-SPECIFIC METHODS

pathName add type id ?arg ...?
Add a new widget to the tree. The first argument is the widget type, and the second is its unique id. Raise an error if an item with id already exists. IDs are hierarchical, as in <code>foo.bar</code> -- the parent node must already exist (<code>foo</code>, in this case). The special type node is used to create a new node, in which case options are passed directly to the constructor of the node label, which is a Tk label. Usually, the options will include at least the -text option.
    keep -font -background -cursor -disabledforeground -foreground \
    	-highlightthickness -highlightcolor
	rename -labelfont -font font Font
To override this behaviour, the optioncmds argument can be appended to the option list. This is in the same form as the second argument to the itk_component add method of itk::Archetype. For example, we could add an entry widget to the tree and rename its background to a new option called -entrybackground:
  $widgettree add entry {
      usual
      rename -background -entrybackground entryBackground Background
  }
pathName cget option
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the widgettree command.
pathName close nodeid
Close a node of the tree. If the node is already closed, this method does nothing. If the -closecommand option is not null, append the id and evaluate the command in the global scope. In this case, the node is not closed -- the close command must explicitly close it with the hide method. If the -closecommand option is null, the node is just closed. Raise an error if the node does not exist or if nodeid is a leaf.
pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the widgettree command.
pathName delete id
Delete an item from the tree. If the item is a node, then all descendents are deleted too. Raise an error if the item does not exist. Note that the grid rows occupied by the item are not reclaimed, but this should not be visible.
pathName disable nodeid
Disable a node. Raise an error if the node does not exist or nodeid is not a node. The open-close button is disabled, and the label foreground changed to the value given by the -disabledforeground option.
pathName enable nodeid
Enable a node. Raise an error if the node does not exist or nodeid is not a node. The open-close button is enabled, and the label foreground changed to the value given by the -foreground option.
pathName hide nodeid
Unconditionally close a node of the tree, without checking the -closecommand option. If the node is already closed, this method does nothing. Raise an error if the node does not exist or if nodeid is a leaf.
pathName itemcget id option
Return a configuration option of an item. Raise an error if the item does not exist or if the option is invalid. Legal options are exactly those described for the add method.
pathName itemconfigure id ?option? ?arg ...?
Configure options of an item. If only id is supplied, return the list of options of that item. If option is supplied, return that option. If additional arguments are supplied, configure each option with the given value. Raise an error if the item does not exist or an invalid option is supplied. Legal options are exactly those described for the add method.
pathName locate x y ?id?
Return the id of the item at the given x and y coordinates. If the id argument is given, it must be a node, and the x and y coordinates are relative to the interior of that node. If x is negative, then the x coordinate is ignored in figuring out which item is under the mouse -- this is most useful when drag-selecting a region of the tree. If x is non-negative, then an id is returned only if the mouse is actually over an item.
pathName names ?nodeid?
Return the ids of children of a node. If the nodeid argument is not supplied, return the list of items at the top level of the tree. If nodeid is supplied, it must be a node or an error is raised. The result in this case will be a list of children of that item.
pathName open nodeid
Open a node of the tree. If the node is already open, do nothing. If the node has no children and -createcommand is not null, append the id and evaluate at the global scope. If the node has children and -opencommand is not null, append the id and evaluate at the global scope. Raise an error if the node does not exist or if nodeid is not a node.
pathName toggle nodeid
Toggle the state of a node of the tree: if the node is open, close it; if it is closed, open it. The effects of this operation are as described for the open and close methods.
pathName traverse mode ?nodeid?
Traverse the tree. This method is provided because Tk's default Tab traversal doesn't give the user enough control over where the traversal goes. The mode controls the traversal operation, while the nodeid is the id of the button that currently has the focus. If nodeid is null or not supplied, then no button has the focus. To aid construction of call-backs, the nodeid can either be a node id or a widget path. mode is case-insensitive, and can be one of down, return, up, left, or right, with the effect described for the default bindings. It can also be to, which moves the focus to the given node. If the -traversal option is false, the method returns without doing anything.
pathName type id
Return the type of id. The type will be value of the type argument passed to the add method when the item was created. Raise an error if the item does not exist.

COMPONENTS

Widgettree dynamically creates components as widgets and nodes are added to the tree.

Name:                   id
Class:                  widgetclass

Name:                   nodeid
Class:                  Frame

Name:                   idbutton
Class:                  Button

Name:                   idlabel
Class:                  Label

EXAMPLE

FIXME

AUTHOR

John Reekie, johnr@eecs.berkeley.edu

ACKNOWLEDGMENTS

Widgettree is inspired by the SubPanel and MultiPanel widgets written by Farhana Sheikh and Cliff Cordeiro of UC Berkeley. Widgettree is contributed to [incr Widgets] by the Tycho project at UC Berkeley: http://ptolemy.eecs.berkeley.edu/tycho.

KEYWORDS

widgettree, hierarchy, widget