hierarchy - Create and manipulate a hierarchy widget

SYNOPSIS

hierarchy pathName ?options?

INHERITANCE

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

STANDARD OPTIONS

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

See the "options" manual entry for details on the standard options.

ASSOCIATED OPTIONS

activeRelief
elementBorderWidth
jump
troughColor

See the "scrollbar" widget manual entry for details on the above associated options.

spacing1
spacing2
spacing3
tabs

See the "text" widget manual entry for details on the above associated options.

INHERITED OPTIONS

labelBitmap
labelPos
labelFont
labelText
labelImage
labelVariable
labelMargin

See the "labeledwidget" class manual entry for details on the inherited options.

WIDGET-SPECIFIC OPTIONS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Name:                   textBackground
Class:                  Background
Command-Line Switch:	-textbackground

Name:                   textFont
Class:                  Font
Command-Line Switch:	-textfont

Name:                   visibleitems
Class:                  VisibleItems
Command-Line Switch:	-visibleitems

Name:                   vscrollMode
Class:                  ScrollMode
Command-Line Switch:	-vscrollmode

Name:                   width
Class:                  Width
Command-Line Switch:	-width


DESCRIPTION

The hierarchy command creates a hierarchical data view widget. It allows the graphical management of a 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 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
dlineinfo
insert
tag
compare
dump
scan
window
debug
get
search
xview
delete
index
see
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 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 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 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 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:
A nodes 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

Name:                   list
Class:                  Text

Name:                   bgMenu
Class:                  Menu

Name:                   horizsb
Class:                  Scrollbar

Name:                   itemMenu
Class:                  Menu

Name:                   vertsb
Class:                  Scrollbar

EXAMPLE

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
}

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

AUTHORS

Mark L. Ulferts

Michael J. McLennan

KEYWORDS

hierarchy, text, widget