Table of Contents

Name

hiertable - Create and manipulate hierarchical listbox widgets

Synopsis

hiertable pathName ?options ?

Description

The hiertable widget that displays a hierarchy of entries, drawn one per line. The hierarchy is a general ordered tree of entries. Each entry contains a list of subentries which in turn can contain their own lists of subentries. The lists of subentries can be opened (shown) or closed (hidden). Individual entries can be selected.

Introduction

Example

Syntax

The hiertable command creates a new window (given by the pathName argument) and makes it into a hiertable widget.

hiertable pathName ?option value ?...

Additional options, described above, may be specified on the command line or in the option database to configure aspects of the hiertable such as its colors, font, text, and relief. The hiertable command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName , but pathName 's parent must exist.

An entry an icon (image), text label, and optionally a data field. When first created, a new hiertable has no elements. Elements may be added or deleted using widget operations described below. one or more elements may be selected as described below.

When entries are inserted, they are given a name which can used to specify them later.

It is not necessary for all the elements to be displayed in the hiertable window at once; commands described below may be used to change the view in the window. Hiertablees allow scrolling in both directions using the standard xScrollCommand and yScrollCommand options. They also support scanning, as described below.

Hiertable Indices

Each entry in the hiertable widget is identified by unique a node serial number or index. Many of the operations in the hiertable widget take one or more entries as arguments. You can use either the entry's serial number or one of several special non-numeric indices shown below.
number
Each entry in the widget has a serial number that uniquely identifies it. The number doesn't indicate the location or position an entry (for example, you can't determine the order of two entries from their node numbers) but only identifies it, even if an entry is moved. Node "0" is always the root of the hierarchy.
active
The entry where the mouse pointer is currently located. Whenever the mouse passes over an entry, the entry is redrawn using its active icon (see the -activeicon option). The active changed automatically by moving the mouse pointer over another entry or by using the widget's activate operation. Note that there can be only one active entry at a time.
anchor
The entry where the current selection is anchored. In the case of multiple selections, it is the first entry selected. The anchor is set by the selection anchor operation.
focus
The entry that currently has focus. The entry is drawn with a dashed line around its label. You can change the focus using the focus operation.
root
The root entry. You can also use the node "0" to describe the root.
end
The last open entry in depth-first order on the tree.
up
The last open entry from the current focus. The up of the root entry (i.e. the root has focus) is also the root.
down
The next open entry from the current focus. The down of the last open entry is the same.
last
The last open entry from the current focus. But unlike up , when the focus is at root, last wraps around to the last open entry in the tree.
next
The next open entry from the current focus. But unlike down , when the focus is on last open entry, next wraps around to the root entry.
parent
The parent of the entry with the current focus. The parent of the root is also the root.
nextsibling
The next sibling from the entry with the current focus. If the entry is already the last sibling then it is the nextsibling. prevsibling The previous sibling from the entry with the current focus. If the entry is already the first sibling then it is the prevsibling.
view.top
First partially visible entry in the hiertable window.
view.bottom
Last partially visible entry in the hiertable window.
current
The entry where the mouse pointer is currently located. But unlike active , this index changes while the selection is dragged. It is used to determine the current entry during button drags.
path
Absolute path of an entry. Path names refer to the node name, not their entry labels. Paths don't have to start with a separator (see the -separator configuration option), but component names must be separated by the designated separator.
@x,y
Indicates the element that covers the point in the hiertable window specified by x and y (in pixel coordinates). If no element covers that point, then the closest element to that point is used.

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 activate index
Sets the active entry to index . Index is an entry index. When an entry is active it is drawn using its active icon (see the -activeicon option). Note that there can be only one active entry at a time. The index of the currently active entry is active .
pathName bbox ?-screen ? index...
Returns a list of 4 numbers, representing a bounding box of around the specified entries. Each entry is given an index . The numbers are
x
X-coordinate of the upper-left corner of the bounding box.
y
Y-coordinate of the upper-left corner of the bounding box.
width
Width of the bounding box.
height
Height of the bounding box.
The x-y coordinates of the bounding box are normally virtual Virtual coordinates start from 0 at the first open entry. But if the -screen flag is given, then the x-y coordinates are converted to screen coordinates.
pathName bind tagName ?sequence command ?
Associates command with tagName such that whenever the event sequence given by sequence occurs for an entry with this tag, command will be invoked. The syntax is similar to the bind command except that it operates on hiertable entries, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on command before invoking it.

If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName . If the first character of command is + then command augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (it's an error occurs if there's no such binding) is returned. If both command and sequence are missing then a list of all the event sequences for which bindings have been defined for tagName .

pathName button args...
See the BUTTON OPERATIONS section below.
pathName cget option
Returns the current value of the configuration option given by option . Option may have any of the values accepted by the configure operation described below.
pathName close ?-recurse ? index...
Closes the level of each entry specified by index . The Tcl script specified by the -closecommand option is also invoked. If the -recurse flag is set, then each subnode is recursively closed also. If the entry is already closed, this command has no effect.
pathName configure ?option ? ?value option value ... ?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value , then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option and value are described below:
-background color
Sets the background color the hiertable. The default is white .
-borderwidth pixels
Sets the width of the 3-D border around the outside edge of the widget. The -relief option determines if the border is to be drawn. The default is 2 .
-closecommand string
Specifies a Tcl script to be invoked when an entry is closed. Individual entries may override this with their own -closecommand option. The default is "" .
-closerelief relief
Specifies the 3-D effect for gadgets of closed entries. Relief specifies how the gadget should appear relative to entry; for example, raised means the gadget should appear to protrude. The default is raised .
-cursor cursor
Specifies the widget's cursor. The default cursor is "" .
-dashes number
Sets the dash style of the horizontal and vertical lines drawn connecting entries. Number is the length in pixels which represents the lengths of the dashes and gaps. If number is 0 , solid lines will be drawn. The default is 1 .
-exportselection boolean
Indicates if the selection is exported. If a hiertable is exporting its selection then it will observe the standard X11 protocols for handling the selection. Selections are available as type STRING ; the value of the selection will be the text of the selected elements, with newlines separating the elements. The default is no .
-font fontName
Specifies the font for entry labels. Individual entries may override this with their own -font option. The default is *-Helvetica-Bold-R-Normal-*-12-120-* .
-foreground color
Specifies the color of entry labels. Individual entries may override this with their own -foreground option. The default is black .
-gadgetactivebackground color
Specifies the background color non-image gadgets when the pointer is placed over it.
-gadgetactiveforeground color
Specifies the foreground color non-image gadgets when the pointer is placed over it.
-gadgetbackground color
Specifies the background color of gadgets. The default is black .
-gadgetborderwidth pixels
Specifies a non-negative value indicating the width of the 3-D border to draw around the gadgets. The default is 1 .
-gadgetforeground color
Specifies the foreground color of gadgets. The default is black .
-gadgets imageList
Specifies the gadget images for open and closed entries. If imageList contains the name of two Tk images, that first image will be displayed with the entry is closed, and the second when entry is opened. If imageList contains only one image, the same image will be drawn regardless the entry is opened or closed. If imageList is the empty string, the default (+/-) symbols will be drawn for gadgets. The default is "" .
-height pixels
Specifies the requested height of widget. The default is 400 .
-highlightbackground color
Specifies the color to display in the traversal highlight region when the hiertable does not have the input focus.
-highlightcolor color
Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. The default is black .
-highlightthickness pixels
Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. The value may have any of the forms acceptable to Tk_GetPixels . If the value is zero, no focus highlight is drawn around the widget. The default is 2 .
-linecolor color
Sets the color of lines drawn connecting entries. The default is black .
-linespacing pixels
Sets the number of pixels spacing between entries. The default is 0 .
-linewidth pixels
Set the width of the lines drawn connecting entries. If pixels is 0 , no lines are drawn. The default is 1 .
-opencommand string
Specifies a Tcl script to be invoked when an entry is open. For example, this may be used to populate the hierarchy as it is traversed. Individual entries may override this with their own -opencommand option. The default is "" .
-openrelief relief
Specifies the 3-D effect for gadgets of open entries. Relief specifies how the gadget should appear relative to entry; for example, raised means the gadget should appear to protrude. The default is sunken .
-relief relief
Specifies the 3-D effect for the hiertable widget. Relief specifies how the hiertable should appear relative to widget it is packed into; for example, raised means the hiertable should appear to protrude. The default is sunken .
-scrolltile boolean
Indicates if the tile should appear to scroll when the widget is scrolled.
-selectbackground color
Specifies the color to use when displaying background of selected entries. The default is lightblue2 .
-selectborderwidth pixels
Specifies a non-negative value indicating the width of the raised 3-D border to draw around the labels of selected entries. The default is 1 .
-selectforeground color
Specifies the color to use when drawing the labels of selected entries. The default is black .
-separator string
Specifies the path separator of components of entries. The separator may several characters (such as "::"). This string is used to parse entry pathnames. The default is "" .
-takefocus focus
Provides information used when moving the focus from window to window via keyboard traversal (e.g., Tab and Shift-Tab). If focus is 0 , this means that this window should be skipped entirely during keyboard traversal. 1 means that the this window should always receive the input focus. An empty value means that the traversal scripts make the decision whether to focus on the window. The default is "1" .
-tile image
Specifies a tiled background for the widget. If image isn't "" , the background is tiled using image . Otherwise, the normal background color is drawn (see the -background option). Image must be an image created using the Tk image command. The default is "" .
-trimleft string
Specifies leading characters to trim from entry pathnames.
-width pixels
Specifies the requested width of the widget. The default is 200 .
-xscrollcommand string
Specifies the prefix for a command used to communicate with horizontal scrollbars. Whenever the horizontal view in the widget's window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. If this option is not specified, then no command will be executed.
-yscrollcommand string
Specifies the prefix for a command used to communicate with vertical scrollbars. Whenever the vertical view in the widget's window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. If this option is not specified, then no command will be executed.
pathName curselection
Returns a list containing the numerical indices of all of the elements in the hiertable that are currently selected. If there are no elements selected in the hiertable then an empty string is returned.
pathName delete first ?last ?
Deletes one or more elements of the hiertable. First and last are indices specifying the first and last elements in the range to delete. If last isn't specified it defaults to first , i.e. a single element is deleted.
pathName entry operation ?args ?
See the ENTRY OPERATIONS section.
pathName get ?-full ? index ...
Returns a list of the names for the indices specified. If the -full flag is set, then the full pathnames for the elements are returned.
pathName index ?-at index ? index
Returns the node index of the entry specified by index . Several forms of indices return an index relative to currently active entry (they are describe in the section HIERTABLE INDICES ). The -at flag lets you get an index for some entry other than the active one.
pathName insert ?-at index ? position name... ?option value ?...
Inserts zero or more new elements in an hierarchy list just before the entry given by position . Position is a number indicating where in the list, new elements should be added. If position is end then the new elements are added to the end of the list. Returns a list containing the indices of the new entries.
pathName nearest x y ?varName ?
Returns the index of the entry closest to the given X-Y screen coordinate. The optional argument varName is the name of variable which is set to a string over what parts of the entry the coordinate lies. The part names are gadget and select . If the coordinate is not directly over any entry, then varName will contain the empty string.
pathName open ?-recurse ? index...
Displays the lists of subentries for each entry specified by index . If an entry is not already open, the Tcl script specified by the -opencommand option is also invoked. If the -recurse flag is set, then each subentry is recursively opened too.
pathName scan option args
This command is used to implement scanning on hiertablees. It has two forms, depending on option :
pathName scan mark x y
Records x and y and the current view in the hiertable window; used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string.
pathName scan dragto x y .
This command computes the difference between its x and y arguments and the x and y arguments to the last scan mark command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the list at high speed through the window. The return value is an empty string.
pathName see index
Adjust the view in the hiertable so that the entry given by index is visible in the middle of the hiertable.
pathName selection option arg
This command is used to adjust the selection within a hiertable. It has several forms, depending on option :
pathName selection anchor index
Sets the selection anchor to the element given by index . If index refers to a non-existent element, then the closest element is used. The selection anchor is the end of the selection that is fixed while dragging out a selection with the mouse. The index anchor may be used to refer to the anchor element.
pathName selection clear first ?last ?
If any of the elements between first and last (inclusive) are selected, they are deselected. The selection state is not changed for elements outside this range.
pathName selection includes index
Returns 1 if the element indicated by index is currently selected, 0 if it isn't.
pathName selection set first ?last ?
Selects all of the elements in the range between first and last , inclusive, without affecting the selection state of elements outside that range.
pathName xview args
This command is used to query and change the horizontal position of the information in the widget's window. It can take any of the following forms:
pathName xview
Returns a list containing two elements. Each element is a real fraction between 0 and 1; together they describe the horizontal span that is visible in the window. For example, if the first element is .2 and the second element is .6, 20% of the hiertable's text is off-screen to the left, the middle 40% is visible in the window, and 40% of the text is off-screen to the right. These are the same values passed to scrollbars via the -xscrollcommand option.
pathName xview index
Adjusts the view in the window so that the character position given by index is displayed at the left edge of the window. Character positions are defined by the width of the character 0 .
pathName xview moveto fraction
Adjusts the view in the window so that fraction of the total width of the hiertable text is off-screen to the left. fraction must be a fraction between 0 and 1.
pathName xview scroll number what
This command shifts the view in the window left or right according to number and what . Number must be an integer. What must be either units or pages or an abbreviation of one of these. If what is units , the view adjusts left or right by number character units (the width of the 0 character) on the display; if it is pages then the view adjusts by number screenfuls. If number is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible.
pathName yview ?args ?
This command is used to query and change the vertical position of the text in the widget's window. It can take any of the following forms:
pathName yview
Returns a list containing two elements, both of which are real fractions between 0 and 1. The first element gives the position of the hiertable element at the top of the window, relative to the hiertable as a whole (0.5 means it is halfway through the hiertable, for example). The second element gives the position of the hiertable element just after the last one in the window, relative to the hiertable as a whole. These are the same values passed to scrollbars via the -yscrollcommand option.
pathName yview index
Adjusts the view in the window so that the element given by index is displayed at the top of the window.
pathName yview moveto fraction
Adjusts the view in the window so that the element given by fraction appears at the top of the window. Fraction is a fraction between 0 and 1; 0 indicates the first element in the hiertable, 0.33 indicates the element one-third the way through the hiertable, and so on.
pathName yview scroll number what
This command adjusts the view in the window up or down according to number and what . Number must be an integer. What must be either units or pages . If what is units , the view adjusts up or down by number lines; if it is pages then the view adjusts by number screenfuls. If number is negative then earlier elements become visible; if it is positive then later elements become visible.

Entry Operations

pathName entry bbox index
Returns a list of four numbers describing the bounding box of the text in the entry given by index . The first two elements of the list give the x and y coordinates of the upper-left corner of the screen area covered by the entry (specified in pixels relative to the widget) and the last two elements give the width and height of the area, in pixels. If no part of the entry given by index is visible on the screen then the result is an empty string. If the element is partially visible, the result gives the full area of the element, including any parts that are not visible.
pathName entry cget option
Returns the current value of the configuration option given by option . Option may have any of the values accepted by the configure operation described below.
pathName entry children index ?first ? ?last ?
Returns the list of nodes of the subentries at index . By default, all subentries listed in index are returned. If a rst argument is present, then the node index of the subentry at that numeric position is returned. If both first and last arguments are given, then the nodes of the subentries in that range are returned.
pathName entry configure ?option ? ?value option value ... ?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value , then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option and value are described below:
pathName entry hidden index
Returns 1 if the entry is currently hidden and 0 otherwise. An entry is not hidden if all of its ancestor entries are open.
pathName entry open index
Returns 1 if the entry is currently open and 0 otherwise.
pathName entry size -recurse index
Returns the number of subentries at index . If the -recurse flag is set, then each the number of all subentries under index is returned.
pathName entry configure -recurse index
Returns the number of subentries at index . If the -recurse flag is set, then each the number of all subentries under index is returned.

Default Bindings

Tk automatically creates class bindings for hiertablees that give them
Motif-like behavior. Much of the behavior of a hiertable is determined by its selectMode option, which selects one of four ways of dealing with the selection.

If the selection mode is single or browse , at most one element can be selected in the hiertable at once. In both modes, clicking button 1 on an element selects it and deselects any other selected item. In browse mode it is also possible to drag the selection with button 1.

If the selection mode is multiple or extended , any number of elements may be selected at once, including discontiguous ranges. In multiple mode, clicking button 1 on an element toggles its selection state without affecting any other elements. In extended mode, pressing button 1 on an element selects it, deselects everything else, and sets the anchor to the element under the mouse; dragging the mouse with button 1 down extends the selection to include all the elements between the anchor and the element under the mouse, inclusive.

Most people will probably want to use browse mode for single selections and extended mode for multiple selections; the other modes appear to be useful only in special situations.

In addition to the above behavior, the following additional behavior is defined by the default bindings:

  1. In extended mode, the selected range can be adjusted by pressing button 1 with the Shift key down: this modifies the selection to consist of the elements between the anchor and the element under the mouse, inclusive. The un-anchored end of this new selection can also be dragged with the button down.
  2. In extended mode, pressing button 1 with the Control key down starts a toggle operation: the anchor is set to the element under the mouse, and its selection state is reversed. The selection state of other elements isn't changed. If the mouse is dragged with button 1 down, then the selection state of all elements between the anchor and the element under the mouse is set to match that of the anchor element; the selection state of all other elements remains what it was before the toggle operation began.
  3. If the mouse leaves the hiertable window with button 1 down, the window scrolls away from the mouse, making information visible that used to be off-screen on the side of the mouse. The scrolling continues until the mouse re-enters the window, the button is released, or the end of the hiertable is reached.
  4. Mouse button 2 may be used for scanning. If it is pressed and dragged over the hiertable, the contents of the hiertable drag at high speed in the direction the mouse moves.
  5. If the Up or Down key is pressed, the location cursor (active element) moves up or down one element. If the selection mode is browse or extended then the new active element is also selected and all other elements are deselected. In extended mode the new active element becomes the selection anchor.
  6. In extended mode, Shift-Up and Shift-Down move the location cursor (active element) up or down one element and also extend the selection to that element in a fashion similar to dragging with mouse button 1.
  7. The Left and Right keys scroll the hiertable view left and right by the width of the character 0 . Control-Left and Control-Right scroll the hiertable view left and right by the width of the window. Control-Prior and Control-Next also scroll left and right by the width of the window.
  8. The Prior and Next keys scroll the hiertable view up and down by one page (the height of the window).
  9. The Home and End keys scroll the hiertable horizontally to the left and right edges, respectively.
  10. Control-Home sets the location cursor to the the first element in the hiertable, selects that element, and deselects everything else in the hiertable.
  11. Control-End sets the location cursor to the the last element in the hiertable, selects that element, and deselects everything else in the hiertable.
  12. In extended mode, Control-Shift-Home extends the selection to the first element in the hiertable and Control-Shift-End extends the selection to the last element.
  13. In multiple mode, Control-Shift-Home moves the location cursor to the first element in the hiertable and Control-Shift-End moves the location cursor to the last element.
  14. The space and Select keys make a selection at the location cursor (active element) just as if mouse button 1 had been pressed over this element.
  15. In extended mode, Control-Shift-space and Shift-Select extend the selection to the active element just as if button 1 had been pressed with the Shift key down.
  16. In extended mode, the Escape key cancels the most recent selection and restores all the elements in the selected range to their previous selection state.
  17. Control-slash selects everything in the widget, except in single and browse modes, in which case it selects the active element and deselects everything else.
  18. Control-backslash deselects everything in the widget, except in browse mode where it has no effect.
  19. The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection.

The behavior of hiertablees can be changed by defining new bindings for individual widgets or by redefining the class bindings.

Keywords

hiertable, widget If a hiertable is exporting its selection (see exportSelection option), then it will observe the standard X11 protocols for handling the selection. Hiertable selections are available as type STRING ; the value of the selection will be the text of the selected elements, with newlines separating the elements.


Table of Contents