Table of Contents
hiertable - Create and manipulate hierarchical
listbox widgets
hiertable pathName ?options ?
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.
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. Elements 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 support 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 arguments.
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 operation.
- 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.
But unlike down , when the focus is on last 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 current focus. If the entry is already the last
sibling then it is the nextsibling. prevsibling 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 designated 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.
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 arg s 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 index. When an entry is active it is drawn using 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 bounding
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 virtual 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 widgets. 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.
- pathName close ?-recurse ? index...
- 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 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 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. Number is the length in pixels which represents 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 elements. The default
is no .
- -font fontName
- Specifies the font for entry labels. Individual
entries may override this with their own -font option. The default is
*-Helvetica-Bold-R-Normal-*-12-120-* .
- -foreground color
- Specifies the color
of entry labels. Individual 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 imageList contains only one image, the same 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 traversed. 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 should appear relative to entry;
for example, 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 characters (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 using image . Otherwise, the normal background 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 command
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 command 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 currently 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 specified. If the -full flag is set, then the full pathnames
for the elements are returned.
- pathName index ?-at index ? index
- 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 varName 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 arguments 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 motion events
in the widget, to produce the 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 deselected.
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 horizontal 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 horizontal 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 40% is visible in the window,
and 40% of the 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 displayed 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 fraction 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 visible.
- pathName
yview ?args ?
- This command is used to query and change the vertical 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 element
given by index is displayed at 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 element 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
number screenfuls. If number is negative then earlier elements become
visible; if it is positive then later elements become visible.
- 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 pixels relative
to the widget) and the last two elements 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, including 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 arguments are given, then the nodes of the subentries in that range
are returned.
- pathName entry 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 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 otherwise.
- 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.
- 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 selection.
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 deselects 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
discontiguous ranges. In multiple mode, clicking button 1 on an element
toggles its selection state without affecting any 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 single selections and extended
mode for multiple selections; the other modes appear to be useful only
in special situations.
In addition to the above behavior, the following
additional behavior is defined by the default bindings:
- 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.
- In extended
mode, pressing button 1 with the Control 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.
- If the mouse leaves the
hiertable window with button 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.
- Mouse button
2 may be used for scanning. If it is pressed and dragged over the hiertable,
the contents of the hiertable drag at high speed in the direction the
mouse moves.
- If the Up or Down key is pressed, the location cursor (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 the new active element becomes
the selection anchor.
- 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 element in a fashion similar to dragging with mouse
button 1.
- 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.
- The Prior and Next keys scroll the hiertable view up and down by one page
(the height of the window).
- The Home and End keys scroll the hiertable
horizontally to the left and right edges, respectively.
- Control-Home sets
the location cursor to the the first element in the hiertable, selects
that element, and deselects everything else in the hiertable.
- Control-End
sets the location cursor to the the last element in the hiertable, selects
that element, and deselects everything else in the hiertable.
- 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.
- 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.
- 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.
- 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.
- In extended mode, the Escape key cancels
the most recent selection and restores all the elements in the selected
range to their previous selection state.
- 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.
- Control-backslash deselects
everything in the widget, except in browse mode where it has no effect.
- The F16 key (labelled Copy on many Sun workstations) 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.
hiertable,
widget
If a hiertable is exporting its selection (see exportSelection
option), then it will observe the standard X11 protocols for handling
the selection. Hiertable selections are available as type STRING ; the
value of the selection will be the text of the selected elements, with
newlines separating the elements.
Table of Contents