iwidgets::hierarchy(1)

📦 version 4.1.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 iwidgets::hierarchy 💖

okay so bestie, this is the iwidgets::hierarchy manual page from the [incr Widgets] collection. It creates and manipulates a hierarchy widget. periodt. 💅

🌸 NAME 🌸

iwidgets::hierarchy — Create and manipulate a hierarchy widget. That's the whole vibe. 🦋

✨ SYNOPSIS ✨

iwidgets::hierarchy pathName ?options?

🦋 INHERITANCE 🦋

itk::Widget  <-  iwidgets::Labeledwidget  <- iwidgets::Scrolledwidget <-
iwidgets::Hierarchy

⭐ STANDARD OPTIONS ⭐

  • activeBackground
  • activeForeground
  • background
  • borderWidth
  • cursor
  • disabledForeground
  • foreground
  • highlightColor
  • highlightThickness
  • relief
  • selectBackground
  • selectForeground

Peep the options manual entry for the full tea on these standard options. 💖

🎀 ASSOCIATED OPTIONS 🎀

  • activeRelief
  • elementBorderWidth
  • jumptroughColor

The scrollbar widget manual entry has the details on those associated options above. Slay. ✨

  • spacing1
  • spacing2
  • spacing3
  • tabs

The text widget manual entry has the details on those associated options above. 🫶

🌈 INHERITED OPTIONS 🌈

  • labelBitmap
  • labelFont
  • labelImage
  • labelMargin
  • labelPos
  • labelText
  • labelVariable
  • sticky

The labeledwidget class manual entry has the details on those inherited options. 💜

👑 WIDGET-SPECIFIC OPTIONS 👑

  • Name: alwaysQuery Class: AlwaysQuery Command-Line Switch: -alwaysquery

Boolean flag, bestie. It tells the hierarchy widget whether or not every refresh of the display should go get a fresh query using the command value of the -querycommand option, or just use the values it found last time the query was made. Default? no.

  • Name: closedIcon Class: Icon Command-Line Switch: -closedicon

Names an existing closed icon image to show in the hierarchy before nodes that are collapsed. If you don't give one, a folder icon gets generated — pixmap if possible, bitmap otherwise. Iconic. 🎀

  • Name: dblClickCommand Class: Command Command-Line Switch: -dblclickcommand

Command to run when the user double-clicks (mouse button one) the text label of an entry. If it has %n, that gets swapped for the name of the selected node. If it has %s, a boolean indicator of the node's current selection status gets substituted.

  • Name: expanded Class: Expanded Command-Line Switch: -expanded

When true, the hierarchy is fully expanded the first time it's displayed. Want a fresh display? Reset the -querycommand option. Default is false.

  • Name: filter Class: Filter Command-Line Switch: -filter

When true, only branch nodes and selected items show up. Compact view of the important stuff. Default false.

  • Name: height Class: Height Command-Line Switch: -height

Sets the height of the whole hierarchy as one unit. Value can be in any form Tk_GetPixels accepts. Extra space needed for labels, margins, scrollbars etc. forces the hierarchy to squish. If you set this to zero and width to zero too, then the visibleitems option's value takes over and handles geometry constraints a different way. Default height is zero.

  • Name: iconCommand Class: Command Command-Line Switch: -iconcommand

Command to run when the user selects (mouse button one) any extra icons given in the values returned by the command tied to the -querycommand option. %n becomes the name of the node the icon belongs to. %i becomes the icon name.

  • Name: iconDblCommand Class: Command Command-Line Switch: -icondblcommand

Command to run when the user double-clicks (mouse button one) the icon of an entry. %n becomes the name of the node the icon belongs to. %i becomes the icon name.

  • Name: imageCommand Class: Command Command-Line Switch: -imagecommand

Command to run when the user selects an image of an entry. %n becomes the name of the selected node. %s becomes a boolean indicator of the node's current selection status.

  • Name: imageDblCommand Class: Command Command-Line Switch: -imagedblcommand

Command to run when the user double-clicks (mouse button one) the image of an entry. %n becomes the name of the node the icon belongs to. %i becomes the icon name.

  • Name: imageMenuLoadCommand Class: Command Command-Line Switch: -imagemenuloadcommand

Command to run when the user selects (mouse button three) the image or icon; it dynamically loads the itemMenu for the widget.

  • Name: markBackground Class: Foreground Command-Line Switch: -markbackground

Background color to use when displaying marked nodes.

  • Name: markForeground Class: Background Command-Line Switch: -markforeground

Foreground color to use when displaying marked nodes.

  • Name: menuCursor Class: Cursor Command-Line Switch: -menucursor

Mouse cursor for the item and background menus. Value can be any form Tk_GetCursor accepts.

  • Name: nodeIcon Class: Icon Command-Line Switch: -nodeicon

Names an existing node icon image to show in the hierarchy before nodes that are leafs. If you don't provide one, a dog-eared page icon gets generated — pixmap if possible, bitmap otherwise.

  • Name: openIcon Class: Icon Command-Line Switch: -openicon

Names an existing open icon image to show in the hierarchy before nodes that are expanded. If you don't provide one, an open folder icon gets generated — pixmap if possible, bitmap otherwise.

  • Name: queryCommand Class: Command Command-Line Switch: -querycommand

Specifies the command executed to query the contents of each node. If this command contains %n, it gets replaced with the name of the desired node. In its simplest form it should return the children of the given node as a list, which will be depicted in the display. Since the names of the children are used as tags in the underlying text widget, each child must be unique in the hierarchy. Because of that unique requirement, the nodes shall be referred to as uids or uid in the singular sense. The format of returned list is:

{uid [uid ...]}

where uid is a unique id and primary key for the hierarchy entry

If the unique requirement is a problem, the returned list can take on another, more extended form that enables associating text to be displayed with the uids. The uid must still be unique, but the text does not have to obey the unique rule. Plus, the format also allows specifying additional tags to be used on the same entry in the hierarchy as the uid, and additional icons to be displayed just before the node. The tags and icons are considered to be the property of the user — the hierarchy widget will not depend on any of their values. The extended format is:

{{uid [text [tags [icons]]]} {uid [text [tags [icons]]]} ...}

where uid is a unique id and primary key for the hierarchy entry
        text is the text to be displayed for this uid
        tags is a list of user tags to be applied to the entry
        icons is a list of icons to be displayed in front of the text

The hierarchy widget does a look ahead from each node to determine if the node has a children. This can cost some performance with large hierarchies. Users can avoid this by providing a hint in the user tags. A tag of "leaf" or "branch" tells the hierarchy widget the information it needs to know, thereby avoiding the look ahead operation.

  • Name: hscrollMode Class: ScrollMode Command-Line Switch: -hscrollmode

Display mode for the horizontal scrollbar: static, dynamic, or none. In static mode, the scrollbar is always there. dynamic shows it as needed. none disables it. Default is static.

  • Name: sbWidth Class: Width Command-Line Switch: -sbwidth

Width of the scrollbar, in any form Tk_GetPixels accepts.

  • Name: scrollMargin Class: Margin Command-Line Switch: -scrollmargin

Distance between the text part of the hierarchy and the scrollbars, in any form Tk_GetPixels accepts. Default is 3 pixels.

  • Name: selectCommand Class: Command Command-Line Switch: -selectcommand
part 2 incoming, don't touch that dial 💖
  • the node-selection command option — specifies a Tcl command to be evaluated when you select a node in the hierarchy via left mouse click. If "%n" is included in the command, it is substituted with the node name. Similarly, "%s" is substituted with the node's current selection status: 1 for selected, 0 otherwise.
  • Name: textBackground · Class: Background · Command-Line Switch: -textbackground — specifies the background color for the text portion of the hierarchy, in any of the forms acceptable to Tk_GetColor.
  • Name: textFont · Class: Font · Command-Line Switch: -textfont — specifies the font to be used in the text portion of the hierarchy. 🎀
  • Name: textMenuLoadCommand · Class: Command · Command-Line Switch: -textmenuloadcommand — specifies a command to be executed upon user selection via mouse button three, that will dynamically load the itemMenu for the widget.
  • Name: visibleitems · Class: VisibleItems · Command-Line Switch: -visibleitems — specifies the widthxheight in characters and lines for the hierarchy. Bestie, listen: this option is only administered if the width and height options are both set to zero, otherwise they take precedence. The default value is 80x24. With the visibleitems option engaged, geometry constraints are maintained only on the text portion of the hierarchy. The size of the other components such as labels, margins, and scroll bars, are additive and independent, effecting the overall size of the hierarchy. In contrast, should the width and height options have non zero values, they are applied to the hierarchy as a whole. The hierarchy is compressed or expanded to maintain the geometry constraints.
  • Name: vscrollMode · Class: ScrollMode · Command-Line Switch: -vscrollmode — specifies the display mode to be used for the vertical scrollbar: static, dynamic, or none. In static mode, the scroll bar is displayed at all times. Dynamic mode displays the scroll bar as required, and none disables the scroll bar display. The default is static. 👑
  • Name: width · Class: Width · Command-Line Switch: -width — specifies the width of the hierarchy as an entire unit. The value may be specified in any of the forms acceptable to Tk_GetPixels. Any additional space needed to display the other components such as labels, margins, and scrollbars force the text portion of the hierarchy to be compressed. A value of zero along with the same value for the height causes the value given for the visibleitems option to be applied, which administers geometry constraints in a different manner. The default width is zero.

✨ DESCRIPTION ✨

The iwidgets::hierarchy command creates a hierarchical data view widget. It lets you graphically manage a list of nodes that can be expanded or collapsed. Individual nodes can be highlighted. Clicking with the right mouse button on any item brings up a special item menu. Clicking on the background area brings up a different popup menu. Options exist to provide user control over the loading of the nodes and actions associated with node selection. Since the hierarchy is based on the scrolledtext widget, it includes options to control the method in which the scrollbars are displayed, i.e. statically or dynamically. Options also exist for adding a label to the hierarchy and controlling its position. 🦋

🌈 METHODS 🌈

The iwidgets::hierarchy command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:

pathName option ?arg arg ...?

Option and the args determine the exact behavior of the command. The following commands are possible for hierarchy widgets:

🌸 ASSOCIATED METHODS 🌸

bbox compare debug delete dlineinfo dump get index insert scan search see tag window xview yview

See the "text" manual entry for details on the standard methods. 💖

💅 WIDGET-SPECIFIC METHODS 💅

  • pathName cget option — Returns the current value of the configuration option given by option. Option may have any of the values accepted by the iwidgets::hierarchy command.
  • pathName clear — Removes all items from the hierarchy display including all tags and icons. The display will remain empty until the -filter or -querycommand options are set.
  • pathName collapse uid — Collapses the hierarchy beneath the node with the specified unique id by one level. Since this can take a moment for large hierarchies, the cursor will be changed to a watch during the collapse. Also, if any of the nodes beneath the node being collapsed are selected, their status is changed to unselected.
  • 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 may have any of the values accepted by the iwidgets::hierarchy command.
  • pathName current — Returns the tags for the node that was most recently selected by the right mouse button when the item menu was posted. Usually used by the code in the item menu to figure out what item is being manipulated.
  • pathName draw ?when? — Performs a complete redraw of the entire hierarchy. When may be either -now or -eventually where the latter means the draw can be performed after idle.
  • pathName expand uid — Expands the hierarchy beneath the node with the specified unique id by one level. Since this can take a moment for large hierarchies, the cursor will be changed to a watch during the expansion. ⭐
  • pathName expanded uid — Returns the current state of expansion for the node with the specified unique id.
  • pathName expState — Returns a list of all expanded nodes in the tree.
  • pathName mark option ?arg arg ...? — This command is used to manipulate marks, which is quite similar to selection, adding a secondary means of hilighting an item in the hierarchy. The exact behavior of the command depends on the option argument that follows the mark argument. The following forms of the command are currently supported:
    • pathName mark clear — Clears all the currently marked nodes in the hierarchy.
    • pathName mark add uid ?uid uid ...? — Marks the nodes with the specified uids in the hierarchy using the -markbackground and -markforeground options and without affecting the mark state of any other nodes that were already marked.
    • pathName mark remove uid ?uid uid ...? — Unmarks the nodes with the specified uids in the hierarchy without affecting the mark state of any other nodes that were already marked.
    • pathName mark get — Returns a list of the unique ids that are currently marked.
  • pathName refresh uid — Performs a redraw of a specific node that has the given uid. If the node is not currently visible or in other words already drawn on the text, then no action is taken.
  • pathName prune uid — Removes the node specified by the given uid from the hierarchy. Should the node have children, then all of its children will be removed as well. 😭
  • pathName selection option ?arg arg ...? — This command is used to manipulate the selection of nodes in the hierarchy. The exact behavior of the command depends on the option argument that follows the selection argument. The following forms of the command are currently supported:
    • pathName selection clear — Clears all the currently selected nodes in the hierarchy.
    • pathName selection add uid ?uid uid ...? — Selects the nodes with the specified uids in the hierarchy using the -selectionbackground and -selectionforeground options and without affecting the selection state of any other nodes that were already selected.
    • pathName selection remove uid ?uid uid ...? — Deselects the nodes with the specified uids in the hierarchy without affecting the selection state of any other nodes that were already selected.
    • pathName selection get — Returns a list of the unique ids that are currently selected.
Heads up bestie, this one matters: a node's selection status is also dependent on it being visible. If a node is selected and its parent is then collapsed making the selected node not visible, then its selection status is changed to unselected. 💀
  • pathName toggle uid — Toggles the hierarchy beneath the node with the specified unique id. If the hierarchy is currently expanded, then it is collapsed, and vice-versa. 🫶

✨ COMPONENTS ✨

okay bestie, this widget is literally built out of five little sub-widgets and they all have names, classes, and jobs. let's meet the whole squad 💖

  • Name: list Class: Text

the list component is the text widget where the whole hierarchy actually shows up. it's the main character of the display, fr fr. for all the deets on the text component item, go read the "text" widget manual entry. 👑

  • Name: bgMenu Class: Menu

the bgMenu component is the popup menu that shows up when you press the right mouse button in the background — like, not over any specific node. so you right-click the empty void and boom, menu. 🌸 you can add menu items and their commands through the component command. for all the deets on the bgMenu component item, check the "menu" widget manual entry.

  • Name: horizsb Class: Scrollbar

the horizsb component is the horizontal scroll bar. that's it, that's the vibe. sideways scrolling energy ✨ see the "scrollbar" widget manual entry for the details on the horizsb component item.

  • Name: itemMenu Class: Menu

the itemMenu component is the popup menu that pops off when you select a hierarchy node with the right mouse button. right-click on a node instead of the void → different menu, slay. 🎀 menu items can be added along with their commands via the component command. see the "menu" widget manual entry for details on the itemMenu component item.

  • Name: vertsb Class: Scrollbar

the vertsb component is the vertical scroll bar. up-and-down, the classic. 🦋 see the "scrollbar" widget manual entry for details on the vertsb component item.

🌈 EXAMPLE 🌈

okay this is the part where it all comes together. here's the actual example, copied exactly so you can just vibe and run it:

package require Iwidgets 4.0 proc get_files {file} {
    global env

    if {$file == ""} {
        set dir $env(HOME)
    } else {
        set dir $file
    }

    if {[catch {cd $dir}] != 0} {
        return ""
    }

    set rlist ""

    foreach file [lsort [glob -nocomplain *]] {
        lappend rlist [list [file join $dir $file] $file]
    }

    return $rlist }

iwidgets::hierarchy .h -querycommand "get_files %n" -visibleitems 30x15
-labeltext $env(HOME) pack .h -side left -expand yes -fill both

lowkey iconic. a get_files proc that walks a directory and hands back {path name} pairs, wired straight into -querycommand "get_files %n", with -visibleitems 30x15 and -labeltext $env(HOME), then packed -side left -expand yes -fill both. periodt. 💅

👑 AUTHOR 👑

Mark L. Ulferts Michael J. McLennan

🔑 KEYWORDS 🔑

hierarchy, text, widget

that's the whole page bestie!! this one came out of the Tk source, and it's the iwidgets::hierarchy(1) manual entry — the classic manpage footer energy, just with way better vibes. go build something cute with it 💖✨🎀

📦 where this page comes from