--- name: "hierbox" section: "3" platform: "linux" package: "blt-dev" version: "2.4u-7" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/hierbox" --- # hierbox(3) Create and manipulate hierarchical listbox widgets ``` ``` ## 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. - Tk automatically creates class bindings for hiertablees that give them ## DEFAULT BINDINGS 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.