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