hiertable(BLT 2.4) hiertable(BLT 2.4)
______________________________________________________________________________
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.
EXAMPLE 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 acti-
vate 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 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 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 tag-
Name. If the first character of command is + then command augments
an existing binding rather than replacing it. If no com-
mand 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 con-
figure 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 clos- |
est 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 -xscrollcom-
mand 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 onethird
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 con-
figure 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.
DEFAULT BINDINGS [Toc] [Back]
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:
[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 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.
[3] 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.
[4] 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.
[5] 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.
[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 element 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 horizontally to the
left and right edges, respectively.
[10] Control-Home sets the location cursor to the the first element
in the hiertable, selects that element, and deselects everything
else in the hiertable.
[11] Control-End sets the location cursor to the the last element in
the hiertable, selects that element, 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 state.
[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 widget, except in
browse mode where it has no effect.
[19] 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.
hiertable(BLT 2.4)
[ Back ] |
