Table of Contents

Name

hiertable - Create and manipulate hierarchical table widgets

Synopsis

hiertable pathName ?options ?

Description

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.

Introduction

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 children . Each sub-entry in turn may have children. Children are revealed or hidden by opening or closing the entry.

Entries

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.

Columns

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 built-in 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.

Tree Data Object

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 with a ".tree" suffix). 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.

Example

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 appended by ".tree". Above, the new tree object name is ".h.tree". 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 -selectbackground 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).

Syntax

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.

Hiertable Indices

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 parent 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.

Hiertable Operations

The hiertable operations have the invoked by specifying the widget's pathname, the operation, and any arguments that pertain to that operation. The general form is:


pathName operation ?arg arg ... ?

Operation and the arg s 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 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 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 configure 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 depth-first 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 -opencommand 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 -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 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

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.

Entry Operations

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 configure 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 text color of the entry label. This overrides the global -foreground configuration option. The default is "" .
-icons images
Specifies images to be displayed for the entry's icon. This overrides the global -icons configuration option. Images is a list of two Tk images: the first image is displayed when the entry is open, the second when it is closed.
-label string
Sets the text displayed in the entry's the label. If not set, this defaults to the name of the entry. String may contain newlines but not tabs. The default is "" .
-opencommand string
Specifies a Tcl script to be invoked when thex entry is open. For example, this may be used to populate the hierarchy as it is traversed. This overrides the global -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.
pathName entry delete index ?first ?last ?
Deletes the one or more children of the entry given by index . If present, first and last are the positions designating a range of children nodes to be deleted.
pathName entry isbefore index1 index2
Returns 1 if index1 is before index2 and 0 otherwise.
pathName entry ishidden 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 isopen index
Returns 1 if the entry is currently open and 0 otherwise.
pathName entry size -recurse index
Returns the number of children at index . If the -recurse flag is set, then number of entries in the entire branch is returned. The entry index is not counted.

Button Operations

The following operation are available for hiertable buttons.
pathName button 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 button bind tagName ?sequence command ?
Associates command with tagName such that whenever the event sequence given by sequence occurs for an button of 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 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 button 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 buttons. An button is active when the mouse passes over it or using the button activate operation.
-activeforeground color
Sets the foreground color for active buttons. An entry is active when the mouse passes over it or using the button activate operation.
-background color
Sets the background of the button. The default is white .
-borderwidth pixels
Sets the width of the 3-D border around the outside edge of the button. The -relief option determines if the border is to be drawn. The default is 1 .
-closerelief relief
Specifies the 3-D effect for the closed button. Relief specifies how the button should appear relative to the widget; for example, raised means the button should appear to protrude. The default is solid .
-cursor cursor
Specifies the widget's cursor. The default cursor is "" .
-foreground color
Specifies the foreground color of buttons. The default is black .
-images images
If set, specifies images to be displayed for the button. Images is a list of two Tk images: the first image is displayed when the button is open, the second when it is closed.
-openrelief relief
Specifies the 3-D effect for the open button. Relief specifies how the button should appear relative to the widget; for example, raised means the button should appear to protrude. The default is flat .
-size pixels
Sets the requested size for the button. The default is 0 .

Column Operations

The following operation are available for hiertable columns.
pathName column activate column
Sets the active column to column . Column is the name of a column in the widget. When a column is active, it's drawn using its -activetitlebackground and -activetitleforeground options. If column is the "" , then no column will be active. If no column argument is provided, then the name of the currently active column is returned.
pathName column cget name option
Returns the current value of the column configuration option given by option for name . Name is the name of column that corresponds to a data field. Option may have any of the values accepted by the configure operation described below.
pathName column configure name ?option ? ?value option value ... ?
Query or modify the configuration options of the column designated by name . Name is the name of the column corresponding to a data field. 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 of the column. This overrides the widget's -background . The default is white .
-borderwidth pixels
Sets the width of the 3-D border around the outside edge of the column. The -relief option determines if the border is to be drawn. The default is 0 .
-edit boolean
Indicates whether the column data fields can be editted. If boolean is false, the column data fields in the column may not be edited. The default is yes .
-foreground color
Specifies the foreground color of the data fields in the column. Individual entries may override this with their own -foreground option. The default is black .
-font fontName
Specifies the font to use for column data fields. Individual entries may override this with their own -font option. The default is *-Helvetica-Bold-R-Normal-*-12-120-* .
-hide boolean
If boolean is true, then the column is not displayed. The default is yes .
-justify justify
Specifies how the column data fields title should be justified within the column. This matters only when the column is wider than the data field to be display. Justify must be left , right , or center . The default is left .
-pad pad
Sets the padding to the left and right sides of the column. Pad can be a list of one or two screen distances. If pad has two elements, the left side of the legend is padded by the first distance and the right side by the second. If pad has just one distance, both the left and right sides are padded evenly. The default is 2 .
-relief relief
Specifies the 3-D effect for the column. Relief specifies how the button should appear relative to the widget; for example, raised means the column should appear to protrude. The default is flat .
-state state
Sets the state of the column. If state is disable then the column can not be activated nor invoked. The default is normal .
-text string
Sets the title for the column. The default is "" .
-titleforeground color
Specifies the foreground color of the column title. The default is black .
-titleshadow color
Specifies the color of the drop shadow used for the column title. The default is "" .
-width pixels
Specifies the requested width of the column. This overriders the computed with of the column. If pixels is 0, the width is computed as from the contents of the column. The default is 0 .
pathName column delete field ?field ...?
Deletes one of more columns designated by field . Note that this does not delete the data fields themselves.
pathName column insert position field ?options ...?
Inserts one of more columns designated by field . A column displays each entry's data field by the same name. Entries are not required to have a data field. In this case, the cell is left blank. Position indicates where in the list of columns to add the new column. It may be either a number or end .
pathName column invoke field
Invokes the Tcl command associated with the column field , if there is one (using the column's -command option). The command is ignored if the column's -state option set to disabled .
pathName column move name dest
Moves the column name to the destination position. Dest is the name of another column or a screen position in the form @x,y .
pathName column names
Returns a list of the names of all columns in the widget. The list is ordered as the columns are drawn from left-to-right.
pathName column nearest x ?y ?
Returns the name of the column closest to the given X-Y screen coordinate. If you provide a y argument (it's optional), a name is returned only when if the point is over a column's title.

Sort Operations

pathName sort auto ?boolean
Turns on/off automatic sorting of entries. If boolean is true, entries will be automatically sorted as they are opened, closed, inserted, or deleted. If no boolean argument is provided, the current state is returned.
pathName sort 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 sort configure ?option ? ?value option value ... ?
Query or modify the sorting 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 sorting option(s) to have the given value(s); in this case the command returns an empty string. Option and value are described below:
-column string
Specifies the column to sort. Entries in the widget are rearranged according to this column. If column is "" then no sort is performed.
-command string
Specifies a Tcl procedure to be called when sorting entries. The procedure is called with three arguments: the pathname of the widget and the fields 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.
-decreasing boolean
Indicates to sort in ascending/descending order. If boolean is true, then the entries as in descending order. The default is no .
-mode string
Specifies how to compare entries when sorting. String may be one of the following:
ascii
Use string comparison based upon the ASCII collation order.
dictionary
Use dictionary-style comparison. This is the same as ascii except (a) case is ignored except as a tie-breaker and (b) if two strings contain embedded numbers, the numbers compare as integers, not characters. For example, "bigBoy" sorts between "bigbang" and "bigboy", and "x10y" sorts between "x9y" and "x11y".
integer
Compares fields as integers.
real
Compares fields as floating point numbers.
command
Use the Tcl proc specified by the -command option to compare entries when sorting. If no command is specified, the sort reverts to ascii sorting.
pathName sort once ?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.
-recurse
Recursively sort the entire branch, not just the children.

Default Bindings

To be announced.

Tk automatically creates class bindings for hiertables that give them Motif-like behavior. Much of the behavior of an hiertable is determined by its -selectmode option, which selects one of two ways of dealing with the selection.

If the selection mode is single , at most one entry can be selected in the hiertable at once. Clicking button 1 on an entry selects it and deselects any other selected item.

If the selection mode is multiple , any number of entries may be selected at once, including discontiguous ranges. Clicking Control-Button-1 on an entry toggles its selection state without affecting any other entries. Pressing Shift-Button-1 on an entry selects it, extends the entry.

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 entries between the anchor and the entry 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 entry under the mouse, and its selection state is reversed. The selection state of other entries isn't changed. If the mouse is dragged with button 1 down, then the selection state of all entries between the anchor and the entry under the mouse is set to match that of the anchor entry; the selection state of all other entries 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 entry) moves up or down one entry. If the selection mode is browse or extended then the new active entry is also selected and all other entries are deselected. In extended mode the new active entry becomes the selection anchor.
  6. In extended mode, Shift-Up and Shift-Down move the location cursor (active entry) up or down one entry and also extend the selection to that entry 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 entry in the hiertable, selects that entry, and deselects everything else in the hiertable.
  11. Control-End sets the location cursor to the the last entry in the hiertable, selects that entry, and deselects everything else in the hiertable.
  12. In extended mode, Control-Shift-Home extends the selection to the first entry in the hiertable and Control-Shift-End extends the selection to the last entry.
  13. In multiple mode, Control-Shift-Home moves the location cursor to the first entry in the hiertable and Control-Shift-End moves the location cursor to the last entry.
  14. The space and Select keys make a selection at the location cursor (active entry) just as if mouse button 1 had been pressed over this entry.
  15. In extended mode, Control-Shift-space and Shift-Select extend the selection to the active entry 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 entries 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 entry 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.

Keywords

hiertable, widget