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
Specifies the name of an image to be used in the widgettree before
those nodes that are closed. The default icon is called "openNode,"
which is automatically generated.
Command-Line
|
Switch:
|
-closecommand
|
|
The command to execute when a node of the tree is closed.
If this command is null, clicking on the open-close button will
close the node; if not, the node id is appended
to the command and the command is executed at the global scope,
and the node will not close automatically.
Command-Line
|
Switch:
|
-createcommand
|
|
The command to execute when a node of the tree is opened
if the node does not currently contain any widgets. The node id is appended
to the command and the command is executed at the global scope.
The command should use the <b>add</b> method to create the contents of
the node. If the command is null, the node is opened but
nothing will be displayed.
Name: indent
Class: Indent
Command-Line Switch: -indent
The minimum indent for each level of the tree. This option is needed
in order that each level is indented correctly, regardless of the
presence or not of open-close buttons at each level. It sets the
minimum indent, not the actual indent: if either -closedbitmap
or -openedbitmap makes an open-close button wider than the
specified indent, that width will be used instead. (There is no
reasonable way to avoid this, since that's how Tk's grid manager
works.) The default value is 24 pixels.
Name: openIcon
Class: Icon
Command-Line Switch: -openicon
Specifies the name of an image to be used in the widgettree before
those nodes that are open. The default icon is called "openNode,"
which is automatically generated.
Command-Line
|
Switch:
|
-opencommand
|
|
The command to execute when a node of the tree is opened
and the node already has children. The node id is appended
to the command and the command is executed at the global scope.
The node is opened after the command returns.
Name: padX
Class: PadX
Command-Line Switch: -padx
The horizontal padding to use when gridding leaf widgets. By default,
all leaves are packed with the same padding. If needed, the Tk
grid configure command can be used to override this
default -- note, however, that reconfiguring this option after
widgets have been created will return all widgets to the new
value of -pady.
Name: padY
Class: PadY
Command-Line Switch: -pady
The vertical padding to use when gridding leaf widgets. By default,
all leaves are packed with the same padding. If needed, the Tk
grid configure command can be used to override this
default -- note, however, that reconfiguring this option after
widgets have been created will return all widgets to the new
value of -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.
Any other value of type is assumed to be the type of the widget to
create. The optional arguments comprise an option-value list which can
contain any valid options for type. By default, the widget's options
are integrated into the mega-widgets option-list with the usual
option handling, which will cause the following option-handling
commands to be used:
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
A leaf item of the tree. The id item is the id passed to the
add method when the item was created.
Name: nodeid
Class: Frame
A frame containing the children of a tree node. The frame is not
created until a child is added to that node with the add method.
See the "frame" widget manual entry for details.
Name: idbutton
Class: Button
The button of a tree node. See the "button" widget manual entry for
details.
Name: idlabel
Class: Label
The label of a tree node. See the "label" widget manual entry for
details.
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