--- name: "hiertable" section: "3" platform: "linux" package: "blt-dev" version: "2.4u-7" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/hiertable" --- # hiertable(3) Create and manipulate hierarchical table widgets ``` ``` ## 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). 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. Above, the new tree object name is ".h". But you can use the **-tree** option to specify the name of another tree. ``` # View the tree "myTree". .h configure -tree "myTree" ``` When a new tree is created, it contains only a root entry. The entry is automatically opened. The index of the root entry is always `0` (you can use also use the index `root`). The **insert** operation lets you insert one or more new entries into the tree. The last argument is the entry's *pathname*. ``` # Create a new entry named "myEntry" set index [.h insert end "myEntry"] ``` This appends a new entry named "myEntry". It will positioned as the last child of the root of the tree (using the position "end"). You can supply another position to order the entry within its siblings. ``` # Prepend "fred". set index [.h insert 0 "fred"] ``` Entry names do not need to be unique. By default, the entry's label is its name. To supply a different text label, add the **-label** option. ``` # Create a new entry named "fred" set index [.h insert end "fred" -label "Fred Flintstone"] ``` The **insert** operation returns the index of the new node. You can also use the **index** operation to get this information. ``` # Get the index of "fred" .h index "fred" ``` To insert an entry somewhere other than root, use the **-at** switch. It takes the index of the entry where the new child will be added. ``` # Create a new entry "barney" in "fred". .h insert -at $index end "barney" ``` A pathname describes the path to an entry in the hierarchy. It's a list of entry names that compose the path in the tree. Therefore, you can also add "barney" to "fred" as follows. ``` # Create a new sub-entry of "fred" .h insert end "fred barney" ``` Every name in the list is ancestor of the next. All ancestors must already exist. That means that an entry "fred" is an ancestor of "barney" and must already exist. But you can use the **-autocreate** configuration option to force the creation of ancestor nodes. ``` # Force the creation of ancestors. .h configure -autocreate yes .h insert end "fred barney wilma betty" ``` Sometimes the pathname is already separated by a character sequence rather than formed as a list. A file name is a good example of this. You can use the **-separator** option to specify a separator string to split the path into its components. Each pathname inserted is automatically split using the separator string as a separator. Multiple separators are treated as one. ``` .h configure -separator / .h insert end "/usr/local/tcl/bin" ``` If the path is prefixed by extraneous characters, you can automatically trim it off using the **-trim** option. It removed the string from the path before it is parsed. ``` .h configure -trim C:/windows -separator / .h insert end "C:/window/system" ``` You can insert more than one entry at a time with the **insert** operation. This can be much faster than looping over a list of names. ``` # The slow way foreach f [glob $dir/*] { .h insert end $f } # The fast way eval .h insert end [glob $dir/*] ``` In this case, the **insert** operation will return a list of indices of the new entries. You can delete entries with the **delete** operation. It takes one or more indices as its argument. It deletes the entry and all its children. ``` .h delete $index ``` Entries have several configuration options. They control the appearance of the entry's icon and label. We have already seen the **-label** option that sets the entry's text label. The **entry configure** operation lets you set or modify an entry's configuration options. ``` .h entry configure $index -color red -font fixed ``` You can hide an entry and its children using the **-hide** option. ``` .h entry configure $index -hide yes ``` More that one entry can be configured at once. All entries specified are configured with the same options. ``` .h entry configure $i1 $i2 $i3 $i4 -color brown ``` An icon is displayed for each entry. It's a Tk image drawn to the left of the label. You can set the icon with the entry's **-icons** option. It takes a list of two image names: one to represent the open entry, another when it is closed. ``` set im1 [image create photo -file openfolder.gif] set im2 [image create photo -file closefolder.gif] .h entry configure $index -icons "$im1 $im2" ``` If **-icons** is set to the empty string, no icons are display. If an entry has children, a button is displayed to the left of the icon. Clicking the mouse on this button opens or closes the sub-hierarchy. The button is normally a `+` or `-` symbol, but can be configured in a variety of ways using the **button** **configure** operation. For example, the `+` and `-` symbols can be replaced with Tk images. ``` set im1 [image create photo -file closefolder.gif] set im2 [image create photo -file downarrow.gif] .h button configure $index -images "$im1 $im2" \ -openrelief raised -closerelief raised ``` Entries can contain an arbitrary number of *data fields*. Data fields are name-value pairs. Both the value and name are strings. The entry's **-data** option lets you set data fields. ``` .h entry configure $index -data {mode 0666 group users} ``` The **-data** takes a list of name-value pairs. You can display these data fields as *columns* in the **hiertable** widget. You can create and configure columns with the **column** operation. For example, to add a new column to the widget, use the **column insert** operation. The last argument is the name of the data field that you want to display. ``` .h column insert end "mode" ``` The column title is displayed at the top of the column. By default, it's is the field name. You can override this using the column's **-text** option. ``` .h column insert end "mode" -text "File Permissions" ``` Columns have several configuration options. The **column** **configure** operation lets you query or modify column options. ``` .h column configure "mode" -justify left ``` The **-justify** option says how the data is justified within in the column. The **-hide** option indicates whether the column is displayed. ``` .h column configure "mode" -hide yes ``` Entries can be selected by clicking on the mouse. Selected entries are drawn using the colors specified by the **-selectforeground** and **-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