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

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

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: iconDblCommand Class: Command Command-Line Switch: -icondblcommand

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

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

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

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: selectCommand Class: Command Command-Line Switch: -selectcommand

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

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

Name: textMenuLoadCommand Class: Command Command-Line Switch: -textmenuloadcommand

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 iwidgets::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 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 ...?

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.

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

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

AUTHOR

KEYWORDS