hiertable(BLT 2.4) hiertable(BLT 2.4)
______________________________________________________________________________
hiertable - Create and manipulate hierarchical table widgets
______________________________________________________________________________
hiertable pathName ?options?
The hiertable widget displays a scrollable tree of entries, one entry
per line. Each entry has a text label, an icon, and may have children
(sub-entries). A button on the left side of the entry controls whether
its children are displayed.
Entries may have data fields associated with them. Data fields are
displayed (as text or Tk image) in columns that can run vertically on
either side the entry. Each column can have its own color, font, etc.
Any data field, including the entry's label, can be edited in-place.
Single or multiple entries can be selected. Individual entries can be
hidden. There is also a find operation that can apply operations to
all entries that match user-specified criteria.
The hiertable widget represents an hierarchical table of data. Each
row entry is a node in a general-ordered tree. Entries are drawn with
both a text label and an icon. An entry may have sub-entries or chil-
dren. Each sub-entry in turn may have children. Children are revealed
or hidden by opening or closing the entry.
Entries are uniquely identified by a serial number or index. Until an
entry is deleted, its index is valid, even if the entry is moved to
another position within the tree. Note that an index doesn't indicate
anything about the entry's relative position or order in the tree.
If an entry has children, it is drawn with a button on its left side.
Clicking the mouse on this button opens or closes the sub-hierarchy.
When an entry is open, its children are exposed. When it is closed,
they are hidden again. The button is normally a + or - symbol (ala
Windows Explorer), but can be replaced with a pair of Tk images (open
and closed images).
You can bind Tcl commands to be invoked when events occur on entries
(much like Tk canvas items). You can bind an entry using its index or
its bindtags. Bindtags are simply names that associate a binding with
one or more entries. There is a built-in tag all that all entries
automatically have.
An entry can have an arbitrary number of data fields. A data field is
simply a name-value pair, representing some bit of data in the entry.
The field names and their values are strings. Entries are not required
to contain fields found in other entries. For example, each entry
could have its own unique set of field names.
Data fields can be displayed in the widget in columns. A column is
associated with a specific data field. Each entry's value for that
field is drawn in a column along side the hierarchy. Any entry that
doesn't have the specific field is left blank. The widget has a builtin
column, named after the widget, that holds the tree.
You can control the appearance and location of any column. The width
of a column is determined by the widest value in the column. Users can
override the width of a column by grabbing a side of the column and
dragging it. Columns can be hidden or reordered.
LAZY INSERTION/DELETION OF ENTRIES
In the case of a file browser, it doesn't make sense to load the contents
of the entire filesystem. There can be tens of thousands of
entries and you really need to view only a small subset of those. The
hiertable lets you do lazy insertion and deletion of entries. This
means that you insert entries for a particular directory only when necessary.
The hiertable can invoke Tcl procedures whenever an entry is opened
and/or closed. This can allow entries to be inserted only for that
directory when needed. At the same time, when an entry is closed, its
children can be removed, freeing memory and resources.
Data is not stored directly in the hiertable widget. Instead it uses
an external tree data object to the represent the hierarchy (see the
tree manual entry for details). You can create trees and then attach
the hiertable to them using the -tree configuration option.
If no tree is specified, the widget automatically creates an new tree
(the tree's name is the widget's pathname). The tree will automatically
contain one entry for the root node. When the widget is
destroyed the tree is released.
While entries and their data can be added or deleted using various widget
operations, tree data objects themselves have both C and Tcl interfaces.
If the tree is modified through one of these interfaces, the
widget is notified and will automatically redraw itself.
The hiertable command creates a new hiertable widget.
hiertable .h -bg white
A new Tcl command .h is also created. This command can be used to
query and modify the hiertable. For example, to change the background
color of the table to "green", you use the new command and the widget's
configure operation.
# Change the background color.
.h configure -background "green"
By default, the hiertable will automatically create a new tree object
to contain the data. The name of the new tree is the pathname of the
widget. Above, the new tree object name is ".h". But you can use the
-tree option to specify the name of another tree.
# View the tree "myTree".
.h configure -tree "myTree"
When a new tree is created, it contains only a root entry. The entry
is automatically opened. The index of the root entry is always 0 (you
can use also use the index root). The insert operation lets you insert
one or more new entries into the tree. The last argument is the
entry's pathname.
# Create a new entry named "myEntry"
set index [.h insert end "myEntry"]
This appends a new entry named "myEntry". It will positioned as the
last child of the root of the tree (using the position "end"). You can
supply another position to order the entry within its siblings.
# Prepend "fred".
set index [.h insert 0 "fred"]
Entry names do not need to be unique. By default, the entry's label is
its name. To supply a different text label, add the -label option.
# Create a new entry named "fred"
set index [.h insert end "fred" -label "Fred Flintstone"]
The insert operation returns the index of the new node. You can also
use the index operation to get this information.
# Get the index of "fred"
.h index "fred"
To insert an entry somewhere other than root, use the -at switch. It
takes the index of the entry where the new child will be added.
# Create a new entry "barney" in "fred".
.h insert -at $index end "barney"
A pathname describes the path to an entry in the hierarchy. It's a
list of entry names that compose the path in the tree. Therefore, you
can also add "barney" to "fred" as follows.
# Create a new sub-entry of "fred"
.h insert end "fred barney"
Every name in the list is ancestor of the next. All ancestors must
already exist. That means that an entry "fred" is an ancestor of "barney"
and must already exist. But you can use the -autocreate configuration
option to force the creation of ancestor nodes.
# Force the creation of ancestors.
.h configure -autocreate yes
.h insert end "fred barney wilma betty"
Sometimes the pathname is already separated by a character sequence
rather than formed as a list. A file name is a good example of this.
You can use the -separator option to specify a separator string to
split the path into its components. Each pathname inserted is automatically
split using the separator string as a separator. Multiple separators
are treated as one.
.h configure -separator /
.h insert end "/usr/local/tcl/bin"
If the path is prefixed by extraneous characters, you can automatically
trim it off using the -trim option. It removed the string from the
path before it is parsed.
.h configure -trim C:/windows -separator /
.h insert end "C:/window/system"
You can insert more than one entry at a time with the insert operation.
This can be much faster than looping over a list of names.
# The slow way
foreach f [glob $dir/*] {
.h insert end $f
}
# The fast way
eval .h insert end [glob $dir/*]
In this case, the insert operation will return a list of indices of the
new entries.
You can delete entries with the delete operation. It takes one or more
indices as its argument. It deletes the entry and all its children.
.h delete $index
Entries have several configuration options. They control the appearance
of the entry's icon and label. We have already seen the -label
option that sets the entry's text label. The entry configure operation
lets you set or modify an entry's configuration options.
.h entry configure $index -color red -font fixed
You can hide an entry and its children using the -hide option.
.h entry configure $index -hide yes
More that one entry can be configured at once. All entries specified
are configured with the same options.
.h entry configure $i1 $i2 $i3 $i4 -color brown
An icon is displayed for each entry. It's a Tk image drawn to the left
of the label. You can set the icon with the entry's -icons option. It
takes a list of two image names: one to represent the open entry,
another when it is closed.
set im1 [image create photo -file openfolder.gif]
set im2 [image create photo -file closefolder.gif]
.h entry configure $index -icons "$im1 $im2"
If -icons is set to the empty string, no icons are display.
If an entry has children, a button is displayed to the left of the
icon. Clicking the mouse on this button opens or closes the sub-hierarchy.
The button is normally a + or - symbol, but can be configured in
a variety of ways using the button configure operation. For example,
the + and - symbols can be replaced with Tk images.
set im1 [image create photo -file closefolder.gif]
set im2 [image create photo -file downarrow.gif]
.h button configure $index -images "$im1 $im2" \
-openrelief raised -closerelief raised
Entries can contain an arbitrary number of data fields. Data fields
are name-value pairs. Both the value and name are strings. The
entry's -data option lets you set data fields.
.h entry configure $index -data {mode 0666 group users}
The -data takes a list of name-value pairs.
You can display these data fields as columns in the hiertable widget.
You can create and configure columns with the column operation. For
example, to add a new column to the widget, use the column insert operation.
The last argument is the name of the data field that you want
to display.
.h column insert end "mode"
The column title is displayed at the top of the column. By default,
it's is the field name. You can override this using the column's -text
option.
.h column insert end "mode" -text "File Permissions"
Columns have several configuration options. The column configure operation
lets you query or modify column options.
.h column configure "mode" -justify left
The -justify option says how the data is justified within in the column.
The -hide option indicates whether the column is displayed.
.h column configure "mode" -hide yes
Entries can be selected by clicking on the mouse. Selected entries are
drawn using the colors specified by the -selectforeground and -select-
background configuration options. The selection itself is managed by
the selection operation.
# Clear all selections
.h selection clear 0 end
# Select the root node
.h selection set 0
The curselection operation returns a list of indices for all selected
entries.
set indices [.h curselection]
You can use the get operation to convert the indices to their pathnames.
set names [eval .h get -full $indices]
If an hiertable is exporting its selection (using the -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 pathnames of the selected entries,
separated by newlines.
The hiertable supports two modes of selection: single and multiple. In
single select mode, only one entry can be selected at a time, while
multiple select mode allows several entries to be selected. The mode
is set by the widget's -selectmode option.
.h configure -selectmode "multiple"
You can be notified when the list of selected entries changes. The
widget's -selectcommand specifies a Tcl procedure that is called whenever
the selection changes.
proc SelectNotify { widget } {
set indices [$widget curselection]
}
.h configure -selectcommand "SelectNotify .h"
The widget supports the standard Tk scrolling and scanning operations.
The hiertable can be both horizontally and vertically. You can attach
scrollbars to the hiertable the same way as the listbox or canvas widgets.
scrollbar .xbar -orient horizontal -command ".h xview"
scrollbar .ybar -orient vertical -command ".h yview"
.h configure -xscrollcommand ".xbar set" \
-yscrollcommand ".ybar set"
There are three different modes of scrolling: listbox, canvas, and
hierbox. In listbox mode, the last entry can always be scrolled to the
top of the widget. In hierbox mode, the last entry is always drawn at
the bottom of the widget. The scroll mode is set by the widget's
-selectmode option.
.h configure -scrollmode "listbox"
Entries can be programmatically opened or closed using the open and
close operations respectively.
.h open $index
.h close $index
When an entry is opened, a Tcl procedure can be automatically invoked.
The -opencommand option specifies this procedure. This procedure can
lazily insert entries as needed.
proc AddEntries { dir } {
eval .h insert end [glob -nocomplain $dir/*]
}
.h configure -opencommand "AddEntries %P"
Now when an entry is opened, the procedure AddEntries is called and
adds children to the entry. Before the command is invoked, special "%"
substitutions (like bind) are performed. Above, %P is translated to the
pathname of the entry.
The same feature exists when an entry is closed. The -closecommand
option specifies the procedure.
proc DeleteEntries { index } {
.h entry delete $index 0 end
}
.h configure -closecommand "DeleteEntries %#"
When an entry is closed, the procedure DeleteEntries is called and
deletes the entry's children using the entry delete operation (%# is
the index of entry).
The hiertable command creates a new window (given by the pathName argument)
and makes it into an 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.
Each entry in the hiertable widget is identified by a unique serial
number or index. Many of the operations in the hiertable widget take
one or more indices as arguments. You can use either the entry's
serial number or one of several special non-numeric indices shown
below.
number Identifies the entry. 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.
Node 0 is always the root of the hierarchy.
active The entry where the mouse pointer is currently located.
When an entry is active, it is drawn using its active
icon (see the -activeicon option). The active index is
changed automatically by moving the mouse pointer over
another entry or by using the entry activate operation.
Note that there can be only one active entry at a time.
anchor The entry representing the fixed end of the current
selection. The anchor is set by the selection anchor
operation.
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.
down The next open entry from the current focus. The down of
the last open entry is the same.
end The last open entry (in depth-first order) on the tree.
focus The entry that currently has focus. When an entry has
focus, it receives key events. To indicate focus, the
entry is drawn with a dotted line around its label. You
can change the focus using the focus operation.
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.
mark The entry representing the non-fixed end of the current
selection. The mark is set by the selection mark operation.
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.
nextsibling The next sibling from the entry with the current focus.
If the entry is already the last sibling then it is the
nextsibling.
parent The parent of the entry with the current focus. The par-
ent of the root is also the root.
prevsibling The previous sibling from the entry with the current
focus. If the entry is already the first sibling then
it is the prevsibling.
root The root entry. You can also use index 0 to indicate the
root.
up The last open entry (in depth-first order) from the current
focus. The up of the root entry (i.e. the root has
focus) is also the root.
view.top First entry that's current visible in the widget.
view.bottom Last entry that's current visible in the widget.
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 entry that covers the point in the
hiertable window specified by x and y (in pixel coordinates).
If no entry covers that point, then the closest
entry 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 bbox ?-screen? index...
Returns a list of 4 numbers, representing a bounding box of
around the specified entries. Each entry is given an index. If
the -screen flag is given, then the x-y coordinates of the
bounding box are returned as screen coordinates, not virtual
coordinates. Virtual coordinates start from 0 from the root
entry. The returned list contains the following values.
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.
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 operation ?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 entry specified by index. In addition, if a Tcl
script was specified by the -closecommand option, it is invoked.
If the entry is already closed, this command has no effect. If
the -recurse flag is present, each child entry is recursively
closed.
pathName column operation ?args?
See the COLUMN OPERATIONS section below.
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:
-activebackground color
Sets the background color for active entries. An entry
is active when the mouse passes over it or using the
activate operation.
-activeforeground color
Sets the foreground color for active entries. An entry
is active when the mouse passes over it or using the
activate operation.
-activeicons images
Specifies images to be displayed for an entry's icon when
it is active. Images is a list of two Tk images: the
first image is displayed when the entry is open, the second
when it is closed.
-autocreate boolean
Normally it is an error to insert an entry whose ancestors
do not already exist. If boolean is true, it indicates
to automatically create missing ancestor entries.
The default is no.
-allowduplicates boolean
Normally it is an error to insert an entry with the same
pathname as another entry. If boolean is true, it indicates
that duplicate entries should be allowed. The
default is no.
-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 "". Percent
substitutions are performed on string before it is executed.
The following substitutions are valid:
%W The pathname of the widget.
%p The name of the entry.
%P The full pathname of the entry.
%# The index of the node.
%% Translates to a single percent.
-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 an 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 entries, with
newlines separating the entries. The default is no.
-flat boolean
Indicates whether to display the tree as a flattened
list. If boolean is true, then the hierarchy will be a
list of full paths for the entries. This option also has
affect on sorting. See the SORT OPERATIONS section for
more information. The default is no.
-focusdashes dashList
Sets the dash style of the outline rectangle drawn around
the focused entry's label. Number is the length in pixels
which represents the lengths of the dashes and gaps. If
number is 0, a solid line will be drawn. The default is
1.
-focusforeground color
Sets the color to draw the focus rectangle. This is the
dotted rectangle drawn around the entry currently accepting
key events. The default is black.
-font fontName
Specifies the font to use 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 text color of entry labels. Individual
entries may override this with their own -foreground
option. The default is black.
-height pixels
Specifies the requested height of widget. The default is
400.
-hideroot boolean
If boolean is true, it indicates that the root entry
should no be displayed. The default is no.
-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.
-icons images
Specifies images to be displayed for the entry's icon.
Images is a list of two Tk images: the first image is
displayed when the entry is open, the second when it is
closed.
-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 vertical or horizontal 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 "". Percent substitutions are performed on
string before it is executed. The following substitutions
are valid:
%W The pathname of the widget.
%p The name of the entry.
%P The full pathname of the entry.
%# The index of the node.
%% Translates to a single percent.
-relief relief
Specifies the 3-D effect for the 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.
-scrollmode mode
Specifies the style of scrolling to be used. The following
styles are valid. This is the default is hierbox.
listbox Like the listbox widget, the last entry can
always be scrolled to the top of the widget
window. This allows the scrollbar thumb to
shrink as the last entry is scrolled upward.
hierbox Like the hierbox widget, the last entry can
only be viewed at the bottom of the widget
window. The scrollbar stays a constant size.
canvas Like the canvas widget, the entries are bound
within the scrolling area.
-selectbackground color
Specifies the color to use when displaying background of
selected entries. The default is #ffffea.
-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 0.
-selectcommand string
Specifies a Tcl script to invoked when the set of
selected entries changes. The default is "".
-selectforeground color
Specifies the color to use when drawing the labels of
selected entries. The default is black.
-selectmode mode
Specifies the selection mode. If mode is single, only one
entry can be selected at a time. If multiple more than
one entry can be selected. The default is single.
-separator string
Normally entry pathnames are Tcl lists, where each element
is a path component. But if string is not the empty
string, it specifies a character sequence to use when
spliting the path components. The separator may several
characters (such as "::"). Multiple separator are
treated as one. The default is "".
-showtitles boolean
If boolean is false, it indicates that column titles
should not be displayed. The default is yes.
-sortselection boolean
Normally entries in the selection are ordered as they are
selected. If boolean is true, then the entries are
ordered in the same way they are currently displayed
(depth-first or sorted). The default is no.
-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".
-trim string
Specifies leading characters to trim from entry pathnames
before parsing. This only makes sense if the -separator
is also set. The default is "".
-width pixels
Specifies the requested width of the widget. If pixels
is 0, then the with is computed from the contents of the
hiertable. 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.
-xscrollincrement pixels
Specifies the horizontal scrolling distance. The default
is 20 pixels.
-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.
-yscrollincrement pixels
Specifies the vertical scrolling distance. The default is
20 pixels.
pathName curselection
Returns a list containing the indices of all of the entries in
the hiertable that are currently selected. If there are no
entries selected in the hiertable then the empty string is
returned.
pathName delete index ?index...?
Deletes one or more entries of the hiertable. The entry given
by index and its children are deleted.
pathName entry operation ?args?
See the ENTRY OPERATIONS section.
pathName find ?flags? first last
Finds for all entries matching the criteria given by flags. A
list of indices for all matching entries is returned. First and
last are indices designating the range of the search in depthfirst
order. If last is before first, then entries are searched
in reverse order. The valid flags are:
-name pattern
Specifies pattern to match against entry names.
-full pattern
Specifies pattern to match against entry pathnames.
-option pattern
Specifies pattern to match against the entry's configuration
option.
-exact Patterns must match entries exactly. The is the
default.
-glob Use global pattern matching. Matching is done in a
fashion similar to that used by the C-shell. For
the two strings to match, their contents must be
identical except that the following special
sequences may appear in pattern:
* Matches any sequence of characters in
string, including a null string.
? Matches any single character in string.
[chars]
Matches any character in the set given by
chars. If a sequence of the form x-y appears in
chars, then any character between x and y,
inclusive, will match.
\x Matches the single character x. This provides
a way of avoiding the special interpretation
of the characters *?[]\ in the pattern.
-regexp Use regular expression pattern matching (i.e. the
same as implemented by the regexp command).
-nonmatching
Expose entries that don't match.
-exec string
Specifies a Tcl script to be invoked for each matching
entry. Percent substitutions are performed on
string before it is executed. The following substitutions
are valid:
%W The pathname of the widget.
%p The name of the entry.
%P The full pathname of the entry.
%# The index of the node.
%% Translates to a single percent.
-count number
Stop searching after number matches.
-- Indicates the end of flags.
pathName focus index
Sets the focus to the entry given by index. When an entry has
focus, it can receive keyboard events.
pathName get ?-full? index index...
Translates indices to their entry names. It returns a list of
names for all the indices specified. If the -full flag is set,
then the full pathnames are returned.
pathName hide ?flags? index ?index...?
Hides all entries matching the criteria given by flags. The
search is performed recursively for each entry given by index.
The valid flags are described below:
-name pattern
Specifies pattern to match against entry names.
-full pattern
Specifies pattern to match against entry pathnames.
-option pattern
Specifies pattern to match against the entry's configuration
option.
-exact Match patterns exactly. The is the default.
-glob Use global pattern matching. Matching is done in a
fashion similar to that used by the C-shell. For
the two strings to match, their contents must be
identical except that the following special
sequences may appear in pattern:
* Matches any sequence of characters in
string, including a null string.
? Matches any single character in string.
[chars]
Matches any character in the set given by
chars. If a sequence of the form x-y appears in
chars, then any character between x and y,
inclusive, will match.
\x Matches the single character x. This provides
a way of avoiding the special interpretation
of the characters *?[]\ in the pattern.
-regexp Use regular expression pattern matching (i.e. the
same as implemented by the regexp command).
-nonmatching
Hide entries that don't match.
-- Indicates the end of flags.
pathName index ?-at index? string
Returns the index of the entry specified by string. String may
be in any form listed under the HIERTABLE INDICES section above.
Some special indices are normally relative to the entry that has
focus. The -at flag lets you select another entry.
pathName insert ?-at index? position path ?options...? ?path?
?options...?
Inserts one or more entries at position. Position is the location
(number or end) where the new entries are added to the parent
entry. Path is the pathname of the new entry. Pathnames
can be formated either as a Tcl list (each element is a path
component) or as a string separated by a special character
sequence (using the -separator option). Pathnames are normally
absolute, but the -at switch lets you select a relative starting
point. Its value is the index of the starting entry.
All ancestors of the new entry must already exist, unless the
-autocreate option is set. It is also an error if an entry
already exists, unless the -allowduplicates option is set.
Option and value may have any of the values accepted by the
entry configure operation described in the ENTRY OPERATIONS section
below. This command returns a list containing the indices
of the new entries.
pathName move index how destIndex
Moves the entry given by index to the destination entry. The
entry can not be an ancestor of the destination. DestIndex is
the index of the destination entry and can not be the root of
the tree. In conjunction with how, it describes how the move is
performed.
before Moves the entry before the destination entry.
after Moves the entry after the destination entry.
into Moves the entry to the end of the destination's list of
children.
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 either button or select to indicate over
what part of the entry the coordinate lies. If the coordinate
is not directly over any entry, then varName will contain the
empty string.
pathName open ?-recurse? index...
Opens the one or more entries specified by index. If an entry
is not already open, the Tcl script specified by the -opencom-
mand option is also invoked. If the -recurse flag is set, then
each child is recursively opened too.
pathName range ?-open? first last
Returns the indices in depth-first order of the entries between
the first and last indices. If the -open flag is present, it
indicates to consider only open entries. If last is before
first, then the indices are returned in reverse order.
pathName scan option args
This command implements scanning. 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.
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 ?-anchor anchor? index
Adjusts the view (visible entries) so that the entry given by
index is visible in the widget window. By default the entry is
displayed in the middle of the window. This can changed using
the -anchor flag. Its value is a Tk anchor position.
pathName selection option arg
This command is used to adjust the selection within an
hiertable. It has several forms, depending on option:
pathName selection anchor index
Sets the selection anchor to the entry given by index. |
If index refers to a non-existent entry, then the closest |
entry 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 entry.
pathName selection cancel
Clears the temporary selection of entries back to the
current anchor. Temporary selections are created by the
selection mark operation.
pathName selection clear first ?last?
Removes the entries between first and last (inclusive)
from the selection. Both first and last are indices representing
a range of entries. If last isn't given, then
only first is deselected. Entries outside the selection
are not affected.
pathName selection clearall
Clears the entire selection.
pathName selection mark index
Sets the selection mark to the entry given by index.
This causes the range of entries between the anchor and
the mark to be temporarily added to the selection. The
selection mark is the end of the selection that is fixed
while dragging out a selection with the mouse. The index
mark may be used to refer to the anchor entry. If index |
refers to a non-existent entry, then the mark is ignored.
Resetting the mark will unselect the previous range.
Setting the anchor finalizes the range.
pathName selection includes index
Returns 1 if the entry indicated by index is currently
selected, 0 if it isn't.
pathName selection present
Returns 1 if any entries are currently selected and 0
otherwise.
pathName selection set first ?last?
Selects all of the entries in the range between first and
last, inclusive, without affecting the selection state of
entries outside that range.
pathName selection toggle first ?last?
Selects/deselects entries in the range between first and
last, inclusive, in the selection. If an entry is in the
selection, it is deselected, otherwise it is selected.
pathName show ?flags? index ?index...?
Exposes all entries matching the criteria given by flags. This
is the inverse of the hide operation. The search is performed
recursively for each entry given by index. The valid flags are
described below:
-name pattern
Specifies pattern to match against entry names.
-full pattern
Specifies pattern to match against entry pathnames.
-option pattern
Specifies pattern to match against the entry's configuration
option.
-exact Match patterns exactly. The is the default.
-glob -glob Use global pattern matching. Matching is done
in a fashion similar to that used by the C-shell.
For the two strings to match, their contents must
be identical except that the following special
sequences may appear in pattern:
* Matches any sequence of characters in
string, including a null string.
? Matches any single character in string.
[chars]
Matches any character in the set given by
chars. If a sequence of the form x-y appears in
chars, then any character between x and y,
inclusive, will match.
\x Matches the single character x. This provides
a way of avoiding the special interpretation
of the characters *?[]\ in the pattern.
-regexp Use regular expression pattern matching (i.e. the
same as implemented by the regexp command).
-nonmatching
Expose entries that don't match.
-- Indicates the end of flags.
pathName sort ?flags? index...
Sorts the children for each entries specified by index. By
default, entries are sorted by name, but you can specify a Tcl
proc to do your own comparisons.
-command string
Specifies a Tcl proc to use to compare entries when
sorting. The procedure is called with three arguments:
the pathname of the widget and the indices of
two entries. The procedure returns 1 if the first
entry is greater than the second, -1 is the second
is greater, and 0 if equal.
-recurse Recursively sort the entire branch, not just the
children.
pathName text operation ?args?
See the TEXT OPERATIONS section.
pathName toggle index
Opens or closes the entry given by index. If the corresponding
-opencommand or -closecommand option is set, then that command
is also invoked.
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 entry 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 entry
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 entry given by
index is displayed at the top of the window.
pathName yview moveto fraction
Adjusts the view in the window so that the entry given by
fraction appears at the top of the window. Fraction is a
fraction between 0 and 1; 0 indicates the first entry in
the hiertable, 0.33 indicates the entry 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 entrys become visible;
if it is positive then later entrys become visible.
GLOBAL VS. LOCAL ATTRIBUTES [Toc] [Back] Many configuration options in the hiertable widget can be set globally
or locally. For example, there is a -closecommand configuration option
for both widget and individual entries. Options set at the widget
level are global for all entries. If the entry option is set, it overrides
the global widget option. This is done to avoid wasting memory
by replicated options. Most entries will have redundant options.
The following entry operations are available.
pathName entry 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 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 a list of indices for the given range of children of
index. Index is index of the entry to be examined. If only a
first argument is present, then the index of the that child at
that numeric position is returned. If both first and last arguments
are given, then the indices of all the children in that
range are returned. Otherwise the indices of all children 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:
-activeicons images
Specifies images to be displayed for the entry's icon
when it is active. This overrides the global -activeicons
configuration option for the specific entry. Images is a
list of two Tk images: the first image is displayed when
the entry is open, the second when it is closed.
-bindtags tagList
Specifies the binding tags for entries. TagList is a
list of binding tag names. The tags and their order will
determine how events are handled for entries. Each tag
in the list matching the current event sequence will have
its Tcl command executed. The default value is all.
-button string
Indicates whether a button should be displayed on the
left side of the entry. String can be yes, no, or auto.
If auto, then a button is automatically displayed if the
entry has children. This is the default. This is typically
used when performing lazy insertions. An entry may
require a button, while it has no children yet.
-closecommand string
Specifies a Tcl script to be invoked when the entry is
closed. This overrides the global -closecommand option
for this entry. The default is "". Percent substitutions
are performed on string before it is executed. The
following substitutions are valid:
%W The pathname of the widget.
%p The name of the entry.
%P The full pathname of the entry.
%# The index of the node.
%% Translates to a single percent.
-data string
Sets data fields for the entry. String is a list of
name-value pairs to be set. Entries are not required to
contain the same fields. The default is "".
-font fontName
Specifies the font to use 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 tex
|
