NAME
hiertable - Create and manipulate hierarchical listbox
widgets
_________________________________________________________________
SYNOPSIS
hiertable pathName ?options?
DESCRIPTION
The hiertable widget that displays a hierarchy of entries,
drawn one per line. The hierarchy is a general ordered
tree of entries. Each entry contains a list of subentries
which in turn can contain their own lists of subentries.
The lists of subentries can be opened (shown) or closed
(hidden). Individual entries can be selected.
INTRODUCTION
EXAMPLE
SYNTAX
The hiertable command creates a new window (given by the
pathName argument) and makes it into a hiertable widget.
hiertable pathName ?option value?...
Additional options, described above, may be specified on
the command line or in the option database to configure
aspects of the hiertable such as its colors, font, text,
and relief. The hiertable command returns its pathName
argument. At the time this command is invoked, there must
not exist a window named pathName, but pathName's parent
must exist.
An entry an icon (image), text label, and optionally a
data field.
When first created, a new hiertable has no elements. Ele
ments may be added or deleted using widget operations
described below. one or more elements may be selected as
described below.
When entries are inserted, they are given a name which can
used to specify them later.
It is not necessary for all the elements to be displayed
in the hiertable window at once; commands described below
may be used to change the view in the window. Hiertablees
allow scrolling in both directions using the standard
xScrollCommand and yScrollCommand options. They also sup
port scanning, as described below.
Each entry in the hiertable widget is identified by unique
a node serial number or index. Many of the operations in
the hiertable widget take one or more entries as argu
ments. You can use either the entry's serial number or
one of several special non-numeric indices shown below.
number Each entry in the widget has a serial number
that uniquely identifies it. The number
doesn't indicate the location or position an
entry (for example, you can't determine the
order of two entries from their node numbers)
but only identifies it, even if an entry is
moved. Node "0" is always the root of the
hierarchy.
active The entry where the mouse pointer is currently
located. Whenever the mouse passes over an
entry, the entry is redrawn using its active
icon (see the -activeicon option). The active
changed automatically by moving the mouse
pointer over another entry or by using the
widget's activate operation. Note that there
can be only one active entry at a time.
anchor The entry where the current selection is
anchored. In the case of multiple selections,
it is the first entry selected. The anchor is
set by the selection anchor operation.
focus The entry that currently has focus. The entry
is drawn with a dashed line around its label.
You can change the focus using the focus oper
ation.
root The root entry. You can also use the node "0"
to describe the root.
end The last open entry in depth-first order on
the tree.
up The last open entry from the current focus.
The up of the root entry (i.e. the root has
focus) is also the root.
down The next open entry from the current focus.
The down of the last open entry is the same.
last The last open entry from the current focus.
But unlike up, when the focus is at root, last
wraps around to the last open entry in the
tree.
next The next open entry from the current focus.
open entry, next wraps around to the root
entry.
parent The parent of the entry with the current
focus. The parent of the root is also the
root.
nextsibling The next sibling from the entry with the cur
rent focus. If the entry is already the last
sibling then it is the nextsibling. prevsib
ling The previous sibling from the entry with
the current focus. If the entry is already
the first sibling then it is the prevsibling.
view.top First partially visible entry in the hiertable
window.
view.bottom Last partially visible entry in the hiertable
window.
current The entry where the mouse pointer is currently
located. But unlike active, this index
changes while the selection is dragged. It is
used to determine the current entry during
button drags.
path Absolute path of an entry. Path names refer
to the node name, not their entry labels.
Paths don't have to start with a separator
(see the -separator configuration option), but
component names must be separated by the des
ignated separator.
@x,y Indicates the element that covers the point in
the hiertable window specified by x and y (in
pixel coordinates). If no element covers that
point, then the closest element to that point
is used.
HIERTABLE OPERATIONS
The hiertable operations have the invoked by specifying
the widget's pathname, the operation, and any arguments
that pertain to that operation. The general form is:
pathName operation ?arg arg ...?
Operation and the args determine the exact behavior of the
command. The following operation are available for
hiertable widgets:
pathName activate index
Sets the active entry to index. Index is an entry
its active icon (see the -activeicon option). Note
that there can be only one active entry at a time.
The index of the currently active entry is active.
pathName bbox ?-screen? index...
Returns a list of 4 numbers, representing a bound
ing box of around the specified entries. Each entry
is given an index. The numbers are
x X-coordinate of the upper-left corner
of the bounding box.
y Y-coordinate of the upper-left corner
of the bounding box.
width Width of the bounding box.
height Height of the bounding box.
The x-y coordinates of the bounding box are normally vir
tual Virtual coordinates start from 0 at the first open
entry. But if the -screen flag is given, then the x-y
coordinates are converted to screen coordinates.
pathName bind tagName ?sequence command?
Associates command with tagName such that whenever
the event sequence given by sequence occurs for an
entry with this tag, command will be invoked. The
syntax is similar to the bind command except that
it operates on hiertable entries, rather than wid
gets. See the bind manual entry for complete
details on sequence and the substitutions performed
on command before invoking it.
If all arguments are specified then a new binding
is created, replacing any existing binding for the
same sequence and tagName. If the first character
of command is + then command augments an existing
binding rather than replacing it. If no command
argument is provided then the command currently
associated with tagName and sequence (it's an error
occurs if there's no such binding) is returned. If
both command and sequence are missing then a list
of all the event sequences for which bindings have
been defined for tagName.
pathName button args...
See the BUTTON OPERATIONS section below.
pathName cget option
Returns the current value of the configuration
option given by option. Option may have any of the
values accepted by the configure operation
described below.
Closes the level of each entry specified by index.
The Tcl script specified by the -closecommand
option is also invoked. If the -recurse flag is
set, then each subnode is recursively closed also.
If the entry is already closed, this command has no
effect.
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 path
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ
ing the one named option (this list will be identi
cal 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 and value are
described below:
-background color
Sets the background color the hiertable.
The default is white.
-borderwidth pixels
Sets the width of the 3-D border around the
outside edge of the widget. The -relief
option determines if the border is to be
drawn. The default is 2.
-closecommand string
Specifies a Tcl script to be invoked when an
entry is closed. Individual entries may
override this with their own -closecommand
option. The default is "".
-closerelief relief
Specifies the 3-D effect for gadgets of
closed entries. Relief specifies how the
gadget should appear relative to entry; for
example, raised means the gadget should
appear to protrude. The default is raised.
-cursor cursor
Specifies the widget's cursor. The default
cursor is "".
-dashes number
Sets the dash style of the horizontal and
vertical lines drawn connecting entries.
sents the lengths of the dashes and gaps.
If number is 0, solid lines will be drawn.
The default is 1.
-exportselection boolean
Indicates if the selection is exported. If
a hiertable is exporting its selection then
it will observe the standard X11 protocols
for handling the selection. Selections are
available as type STRING; the value of the
selection will be the text of the selected
elements, with newlines separating the ele
ments. The default is no.
-font fontName
Specifies the font for entry labels. Indi
vidual entries may override this with their
own -font option. The default is *-Hel
vetica-Bold-R-Normal-*-12-120-*.
-foreground color
Specifies the color of entry labels. Indi
vidual entries may override this with their
own -foreground option. The default is
black.
-gadgetactivebackground color
Specifies the background color non-image
gadgets when the pointer is placed over it.
-gadgetactiveforeground color
Specifies the foreground color non-image
gadgets when the pointer is placed over it.
-gadgetbackground color
Specifies the background color of gadgets.
The default is black.
-gadgetborderwidth pixels
Specifies a non-negative value indicating
the width of the 3-D border to draw around
the gadgets. The default is 1.
-gadgetforeground color
Specifies the foreground color of gadgets.
The default is black.
-gadgets imageList
Specifies the gadget images for open and
closed entries. If imageList contains the
name of two Tk images, that first image will
be displayed with the entry is closed, and
the second when entry is opened. If
image will be drawn regardless the entry is
opened or closed. If imageList is the empty
string, the default (+/-) symbols will be
drawn for gadgets. The default is "".
-height pixels
Specifies the requested height of widget.
The default is 400.
-highlightbackground color
Specifies the color to display in the
traversal highlight region when the
hiertable does not have the input focus.
-highlightcolor color
Specifies the color to use for the traversal
highlight rectangle that is drawn around the
widget when it has the input focus. The
default is black.
-highlightthickness pixels
Specifies a non-negative value indicating
the width of the highlight rectangle to draw
around the outside of the widget when it has
the input focus. The value may have any of
the forms acceptable to Tk_GetPixels. If
the value is zero, no focus highlight is
drawn around the widget. The default is 2.
-linecolor color
Sets the color of lines drawn connecting
entries. The default is black.
-linespacing pixels
Sets the number of pixels spacing between
entries. The default is 0.
-linewidth pixels
Set the width of the lines drawn connecting
entries. If pixels is 0, no lines are
drawn. The default is 1.
-opencommand string
Specifies a Tcl script to be invoked when an
entry is open. For example, this may be
used to populate the hierarchy as it is tra
versed. Individual entries may override
this with their own -opencommand option.
The default is "".
-openrelief relief
Specifies the 3-D effect for gadgets of open
entries. Relief specifies how the gadget
ple, raised means the gadget should appear
to protrude. The default is sunken.
-relief relief
Specifies the 3-D effect for the hiertable
widget. Relief specifies how the hiertable
should appear relative to widget it is
packed into; for example, raised means the
hiertable should appear to protrude. The
default is sunken.
-scrolltile boolean
Indicates if the tile should appear to
scroll when the widget is scrolled.
-selectbackground color
Specifies the color to use when displaying
background of selected entries. The default
is lightblue2.
-selectborderwidth pixels
Specifies a non-negative value indicating
the width of the raised 3-D border to draw
around the labels of selected entries. The
default is 1.
-selectforeground color
Specifies the color to use when drawing the
labels of selected entries. The default is
black.
-separator string
Specifies the path separator of components
of entries. The separator may several char
acters (such as "::"). This string is used
to parse entry pathnames. The default is
"".
-takefocus focus
Provides information used when moving the
focus from window to window via keyboard
traversal (e.g., Tab and Shift-Tab). If
focus is 0, this means that this window
should be skipped entirely during keyboard
traversal. 1 means that the this window
should always receive the input focus. An
empty value means that the traversal scripts
make the decision whether to focus on the
window. The default is "1".
-tile image
Specifies a tiled background for the widget.
If image isn't "", the background is tiled
ground color is drawn (see the -background
option). Image must be an image created
using the Tk image command. The default is
"".
-trimleft string
Specifies leading characters to trim from
entry pathnames.
-width pixels
Specifies the requested width of the widget.
The default is 200.
-xscrollcommand string
Specifies the prefix for a command used to
communicate with horizontal scrollbars.
Whenever the horizontal view in the widget's
window changes, the widget will generate a
Tcl command by concatenating the scroll com
mand and two numbers. If this option is not
specified, then no command will be executed.
-yscrollcommand string
Specifies the prefix for a command used to
communicate with vertical scrollbars.
Whenever the vertical view in the widget's
window changes, the widget will generate a
Tcl command by concatenating the scroll com
mand and two numbers. If this option is not
specified, then no command will be executed.
pathName curselection
Returns a list containing the numerical indices of
all of the elements in the hiertable that are cur
rently selected. If there are no elements selected
in the hiertable then an empty string is returned.
pathName delete first ?last?
Deletes one or more elements of the hiertable.
First and last are indices specifying the first and
last elements in the range to delete. If last
isn't specified it defaults to first, i.e. a single
element is deleted.
pathName entry operation ?args?
See the ENTRY OPERATIONS section.
pathName get ?-full? index...
Returns a list of the names for the indices speci
fied. If the -full flag is set, then the full
pathnames for the elements are returned.
Returns the node index of the entry specified by
index. Several forms of indices return an index
relative to currently active entry (they are
describe in the section HIERTABLE INDICES ). The
-at flag lets you get an index for some entry other
than the active one.
pathName insert ?-at index? position name... ?option
value?...
Inserts zero or more new elements in an hierarchy
list just before the entry given by position.
Position is a number indicating where in the list,
new elements should be added. If position is end
then the new elements are added to the end of the
list. Returns a list containing the indices of the
new entries.
pathName nearest x y ?varName?
Returns the index of the entry closest to the given
X-Y screen coordinate. The optional argument var
Name is the name of variable which is set to a
string over what parts of the entry the coordinate
lies. The part names are gadget and select. If
the coordinate is not directly over any entry, then
varName will contain the empty string.
pathName open ?-recurse? index...
Displays the lists of subentries for each entry
specified by index. If an entry is not already
open, the Tcl script specified by the -opencommand
option is also invoked. If the -recurse flag is
set, then each subentry is recursively opened too.
pathName scan option args
This command is used to implement scanning on
hiertablees. It has two forms, depending on
option:
pathName scan mark x y
Records x and y and the current view in the
hiertable window; used in conjunction with
later scan dragto commands. Typically this
command is associated with a mouse button
press in the widget. It returns an empty
string.
pathName scan dragto x y.
This command computes the difference between
its x and y arguments and the x and y argu
ments to the last scan mark command for the
widget. It then adjusts the view by 10
times the difference in coordinates. This
command is typically associated with mouse
effect of dragging the list at high speed
through the window. The return value is an
empty string.
pathName see index
Adjust the view in the hiertable so that the entry
given by index is visible in the middle of the
hiertable.
pathName selection option arg
This command is used to adjust the selection within
a hiertable. It has several forms, depending on
option:
pathName selection anchor index
Sets the selection anchor to the element
given by index. If index refers to a non- |
existent element, then the closest element |
is used. The selection anchor is the end of
the selection that is fixed while dragging
out a selection with the mouse. The index
anchor may be used to refer to the anchor
element.
pathName selection clear first ?last?
If any of the elements between first and
last (inclusive) are selected, they are des
elected. The selection state is not changed
for elements outside this range.
pathName selection includes index
Returns 1 if the element indicated by index
is currently selected, 0 if it isn't.
pathName selection set first ?last?
Selects all of the elements in the range
between first and last, inclusive, without
affecting the selection state of elements
outside that range.
pathName xview args
This command is used to query and change the hori
zontal position of the information in the widget's
window. It can take any of the following forms:
pathName xview
Returns a list containing two elements.
Each element is a real fraction between 0
and 1; together they describe the horizon
tal span that is visible in the window. For
example, if the first element is .2 and the
second element is .6, 20% of the hiertable's
text is off-screen to the left, the middle
text is off-screen to the right. These are
the same values passed to scrollbars via the
-xscrollcommand option.
pathName xview index
Adjusts the view in the window so that the
character position given by index is dis
played at the left edge of the window.
Character positions are defined by the width
of the character 0.
pathName xview moveto fraction
Adjusts the view in the window so that frac
tion of the total width of the hiertable
text is off-screen to the left. fraction
must be a fraction between 0 and 1.
pathName xview scroll number what
This command shifts the view in the window
left or right according to number and what.
Number must be an integer. What must be
either units or pages or an abbreviation of
one of these. If what is units, the view
adjusts left or right by number character
units (the width of the 0 character) on the
display; if it is pages then the view
adjusts by number screenfuls. If number is
negative then characters farther to the left
become visible; if it is positive then
characters farther to the right become visi
ble.
pathName yview ?args?
This command is used to query and change the verti
cal position of the text in the widget's window.
It can take any of the following forms:
pathName yview
Returns a list containing two elements, both
of which are real fractions between 0 and 1.
The first element gives the position of the
hiertable element at the top of the window,
relative to the hiertable as a whole (0.5
means it is halfway through the hiertable,
for example). The second element gives the
position of the hiertable element just after
the last one in the window, relative to the
hiertable as a whole. These are the same
values passed to scrollbars via the
-yscrollcommand option.
pathName yview index
Adjusts the view in the window so that the
top of the window.
pathName yview moveto fraction
Adjusts the view in the window so that the
element given by fraction appears at the top
of the window. Fraction is a fraction
between 0 and 1; 0 indicates the first ele
ment in the hiertable, 0.33 indicates the
element one-third the way through the
hiertable, and so on.
pathName yview scroll number what
This command adjusts the view in the window
up or down according to number and what.
Number must be an integer. What must be
either units or pages. If what is units,
the view adjusts up or down by number lines;
if it is pages then the view adjusts by num
ber screenfuls. If number is negative then
earlier elements become visible; if it is
positive then later elements become visible.
ENTRY OPERATIONS
pathName entry bbox index
Returns a list of four numbers describing the
bounding box of the text in the entry given by
index. The first two elements of the list give the
x and y coordinates of the upper-left corner of the
screen area covered by the entry (specified in pix
els relative to the widget) and the last two ele
ments give the width and height of the area, in
pixels. If no part of the entry given by index is
visible on the screen then the result is an empty
string. If the element is partially visible, the
result gives the full area of the element, includ
ing any parts that are not visible.
pathName entry cget option
Returns the current value of the configuration
option given by option. Option may have any of the
values accepted by the configure operation
described below.
pathName entry children index ?first? ?last?
Returns the list of nodes of the subentries at
index. By default, all subentries listed in index
are returned. If a rst argument is present, then
the node index of the subentry at that numeric
position is returned. If both first and last argu
ments are given, then the nodes of the subentries
in that range are returned.
Query or modify the configuration options of the
widget. If no option is specified, returns a list
describing all of the available options for path
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ
ing the one named option (this list will be identi
cal 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 and value are
described below:
pathName entry hidden index
Returns 1 if the entry is currently hidden and 0
otherwise. An entry is not hidden if all of its
ancestor entries are open.
pathName entry open index
Returns 1 if the entry is currently open and 0 oth
erwise.
pathName entry size -recurse index
Returns the number of subentries at index. If the
-recurse flag is set, then each the number of all
subentries under index is returned.
pathName entry configure -recurse index
Returns the number of subentries at index. If the
-recurse flag is set, then each the number of all
subentries under index is returned.
DEFAULT BINDINGS
Tk automatically creates class bindings for hiertablees
that give them Motif-like behavior. Much of the behavior
of a hiertable is determined by its selectMode option,
which selects one of four ways of dealing with the selec
tion.
If the selection mode is single or browse, at most one
element can be selected in the hiertable at once. In both
modes, clicking button 1 on an element selects it and des
elects any other selected item. In browse mode it is also
possible to drag the selection with button 1.
If the selection mode is multiple or extended, any number
of elements may be selected at once, including discontigu
ous ranges. In multiple mode, clicking button 1 on an
other elements. In extended mode, pressing button 1 on an
element selects it, deselects everything else, and sets
the anchor to the element under the mouse; dragging the
mouse with button 1 down extends the selection to include
all the elements between the anchor and the element under
the mouse, inclusive.
Most people will probably want to use browse mode for sin
gle selections and extended mode for multiple selections;
the other modes appear to be useful only in special situa
tions.
In addition to the above behavior, the following addi
tional behavior is defined by the default bindings:
[1] In extended mode, the selected range can be
adjusted by pressing button 1 with the Shift key
down: this modifies the selection to consist of
the elements between the anchor and the element
under the mouse, inclusive. The un-anchored end of
this new selection can also be dragged with the
button down.
[2] In extended mode, pressing button 1 with the Con
trol key down starts a toggle operation: the anchor
is set to the element under the mouse, and its
selection state is reversed. The selection state
of other elements isn't changed. If the mouse is
dragged with button 1 down, then the selection
state of all elements between the anchor and the
element under the mouse is set to match that of the
anchor element; the selection state of all other
elements remains what it was before the toggle
operation began.
[3] If the mouse leaves the hiertable window with but
ton 1 down, the window scrolls away from the mouse,
making information visible that used to be off-
screen on the side of the mouse. The scrolling
continues until the mouse re-enters the window, the
button is released, or the end of the hiertable is
reached.
[4] Mouse button 2 may be used for scanning. If it is
pressed and dragged over the hiertable, the con
tents of the hiertable drag at high speed in the
direction the mouse moves.
[5] If the Up or Down key is pressed, the location cur
sor (active element) moves up or down one element.
If the selection mode is browse or extended then
the new active element is also selected and all
other elements are deselected. In extended mode
anchor.
[6] In extended mode, Shift-Up and Shift-Down move the
location cursor (active element) up or down one
element and also extend the selection to that ele
ment in a fashion similar to dragging with mouse
button 1.
[7] The Left and Right keys scroll the hiertable view
left and right by the width of the character 0.
Control-Left and Control-Right scroll the hiertable
view left and right by the width of the window.
Control-Prior and Control-Next also scroll left and
right by the width of the window.
[8] The Prior and Next keys scroll the hiertable view
up and down by one page (the height of the window).
[9] The Home and End keys scroll the hiertable horizon
tally to the left and right edges, respectively.
[10] Control-Home sets the location cursor to the the
first element in the hiertable, selects that ele
ment, and deselects everything else in the
hiertable.
[11] Control-End sets the location cursor to the the
last element in the hiertable, selects that ele
ment, and deselects everything else in the
hiertable.
[12] In extended mode, Control-Shift-Home extends the
selection to the first element in the hiertable and
Control-Shift-End extends the selection to the last
element.
[13] In multiple mode, Control-Shift-Home moves the
location cursor to the first element in the
hiertable and Control-Shift-End moves the location
cursor to the last element.
[14] The space and Select keys make a selection at the
location cursor (active element) just as if mouse
button 1 had been pressed over this element.
[15] In extended mode, Control-Shift-space and Shift-
Select extend the selection to the active element
just as if button 1 had been pressed with the Shift
key down.
[16] In extended mode, the Escape key cancels the most
recent selection and restores all the elements in
the selected range to their previous selection
[17] Control-slash selects everything in the widget,
except in single and browse modes, in which case it
selects the active element and deselects everything
else.
[18] Control-backslash deselects everything in the wid
get, except in browse mode where it has no effect.
[19] The F16 key (labelled Copy on many Sun worksta
tions) or Meta-w copies the selection in the widget
to the clipboard, if there is a selection.
The behavior of hiertablees can be changed by defining new
bindings for individual widgets or by redefining the class
bindings.
KEYWORDS
hiertable, widget
If a hiertable is exporting its selection (see exportSe
lection option), then it will observe the standard X11
protocols for handling the selection. Hiertable selec
tions are available as type STRING; the value of the
selection will be the text of the selected elements, with
newlines separating the elements.
Man(1) output converted with
man2html