hierarchy
hierarchy(1) [incr Widgets] hierarchy(1)
______________________________________________________________________________
NAME
hierarchy - Create and manipulate a hierarchy widget
SYNOPSIS
hierarchy pathName ?options?
INHERITANCE
itk::Widget <- Labeledwidget <- Scrolledwidget <- Hierarchy
STANDARD OPTIONS
activeBackground activeForegroundbackgroundborderWidth
cursor disabledForeground foregroundhighlightColor
highlightThickness relief selectBackgroundselectForeground
See the "options" manual entry for details on the standard options.
ASSOCIATED OPTIONS
activeRelief elementBorderWidth jumptroughColor
See the "scrollbar" widget manual entry for details on the above asso-
ciated options.
spacing1 spacing2 spacing3 tabs
See the "text" widget manual entry for details on the above associated
options.
INHERITED OPTIONS
labelBitmap labelFont labelImage labelMargin
labelPos labelText labelVariable
See the "labeledwidget" class manual entry for details on the inherited
options.
WIDGET-SPECIFIC OPTIONS
Name: alwaysQuery
Class: AlwaysQuery
Command-Line Switch: -alwaysquery
Boolean flag which tells the hierarchy widget weather or not
each refresh of the display should be via a new query using the
command value of the -querycommand option or use the values pre-
vious found the last time the query was made. The default is
no.
Name: closedIcon
Class: Icon
Command-Line Switch: -closedicon
Specifies the name of an existing closed icon image to be used
in the hierarchy before those nodes that are collapsed. Should
one not be provided, then a folder icon will be generated,
pixmap if possible, bitmap otherwise.
Name: dblClickCommand
Class: Command
Command-Line Switch: -dblclickcommand
Specifies a command to be executed upon user double clicking via
mouse button one of the text label of an entry. If this command
contains "%n", it is replaced with the name of the selected
node. Should it contain "%s" then a boolean indicator of the
node's current selection status is substituted.
Name: expanded
Class: Expanded
Command-Line Switch: -expanded
When true, the hierarchy will be completely expanded when it is
first displayed. A fresh display can be triggered by resetting
the -querycommand option. The default is false.
Name: filter
Class: Filter
Command-Line Switch: -filter
When true only the branch nodes and selected items are dis-
played. This gives a compact view of important items. The
default is false.
Name: height
Class: Height
Command-Line Switch: -height
Specifies the height of the hierarchy as an entire unit. The
value may be specified in any of the forms acceptable to Tk_Get-
Pixels. Any additional space needed to display the other compo-
nents such as labels, margins, and scrollbars force the hierar-
chy to be compressed. A value of zero along with the same value
for the width causes the value given for the visibleitems option
to be applied which administers geometry constraints in a dif-
ferent manner. The default height is zero.
Name: iconCommand
Class: Command
Command-Line Switch: -iconcommand
Specifies a command to be executed upon user selection via mouse
button one of any additional icons given in the values returned
by the command associated with the -querycommand option. If
this command contains "%n", it is replaced with the name of the
node the icon belongs to. Should it contain "%i" then the icon
name is substituted.
Name: iconDblCommand
Class: Command
Command-Line Switch: -icondblcommand
Specifies a command to be executed upon user double clicking via
mouse button one of the icon of an entry. If this command con-
tains "%n", it is replaced with the name of the node the icon
belongs to. Should it contain "%i" then the icon name is substi-
tuted.
Name: imageCommand
Class: Command
Command-Line Switch: -imagecommand
Specifies a command to be executed upon user selecting an image
of an entry. If this command contains "%n", it is replaced with
the name of the selected node. Should it contain "%s" then a
boolean indicator of the node's current selection status is sub-
stituted.
Name: imageDblCommand
Class: Command
Command-Line Switch: -imagedblcommand
Specifies a command to be executed upon user double clicking via
mouse button one of the image of an entry. If this command con-
tains "%n", it is replaced with the name of the node the icon
belongs to. Should it contain "%i" then the icon name is substi-
tuted.
Name: imageMenuLoadCommand
Class: Command
Command-Line Switch: -imagemenuloadcommand
Specifies a command to be executed upon user selection via mouse
button three, on the image or icon, that will dynamically load
the itemMenu for the widget.
Name: markBackground
Class: Foreground
Command-Line Switch: -markbackground
Specifies the background color to use when displaying marked
nodes.
Name: markForeground
Class: Background
Command-Line Switch: -markforeground
Specifies the foreground color to use when displaying marked
nodes.
Name: menuCursor
Class: Cursor
Command-Line Switch: -menucursor
Specifies the mouse cursor to be used for the item and back-
ground menus. The value may have any of the forms accept able
to Tk_GetCursor.
Name: nodeIcon
Class: Icon
Command-Line Switch: -nodeicon
Specifies the name of an existing node icon image to be used in
the hierarchy before those nodes that are leafs. Should one not
be provided, then a dog-eared page icon will be generated,
pixmap if possible, bitmap otherwise.
Name: openIcon
Class: Icon
Command-Line Switch: -openicon
Specifies the name of an existing open icon image to be used in
the hierarchy before those nodes that are expanded. Should one
not be provided, then an open folder icon will be 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 is replaced with the
name of the desired node. In its simpilest 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. Due to the unique requirement, the
nodes shall be reffered 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
Should the unique requirement pose a problem, the list returned
can take on another more extended form which enables the associ-
ation of text to be displayed with the uids. The uid must still
be unique, but the text does not have to obey the unique rule.
In addition, the format also allows the specification of addi-
tional 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
in that 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 deter-
mine if the node has a children. This can be cost some perfor-
mace with large hierarchies. User's 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 avoid-
ing the look ahead operation.
Name: hscrollMode
Class: ScrollMode
Command-Line Switch: -hscrollmode
Specifies the the display mode to be used for the horizontal
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: sbWidth
Class: Width
Command-Line Switch: -sbwidth
Specifies the width of the scrollbar in any of the forms accept-
able to Tk_GetPixels.
Name: scrollMargin
Class: Margin
Command-Line Switch: -scrollmargin
Specifies the distance between the text portion of the hierarchy
and the scrollbars in any of the forms acceptable to Tk_GetPix-
els. The default is 3 pixels.
Name: textBackground
Class: Background
Command-Line Switch: -textbackground
Specifies the background color for the text portion of the hier-
archy 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 hierar-
chy.
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 hier-
archy. 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 indepen-
dent, 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 com-
pressed or expanded to maintain the geometry constraints.
Name: vscrollMode
Class: ScrollMode
Command-Line Switch: -vscrollmode
Specifies the 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_Get-
Pixels. Any additional space needed to display the other compo-
nents 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 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 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 hier-
archy 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 col-
lapsed 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 avail-
able 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 hierar-
chies, the cursor will be changed to a watch during the expan-
sion.
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 hierar-
chy 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 fol-
lowing 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 hierar-
chy using the -selectionbackground and -selectionfore-
ground 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 hier-
archy 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 col-
lapsed, and vice-versa.
COMPONENTS
Name: list
Class: Text
The list component is the text widget in which the hierarchy is
displayed. See the "text" widget manual entry for details on
the text component item.
Name: bgMenu
Class: Menu
The bgMenu component is the popup menu which is displayed upon
pressing the right mouse button in the background, i.e. not over
a specific node. Menu items can be added along with their com-
mands via the component command. See the "menu" widget manual
entry for details on the bgMenu component item.
Name: horizsb
Class: Scrollbar
The horizsb component is the horizontal scroll bar. See the
"scrollbar" widget manual entry for details on the horizsb com-
ponent item.
Name: itemMenu
Class: Menu
The itemMenu component is the popup menu which is displayed upon
selection of a hierarchy node with the right mouse button. 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. See the
"scrollbar" widget manual entry for details on the vertsb compo-
nent item.
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
AUTHOR
Mark L. Ulferts
Michael J. McLennan
KEYWORDS
hierarchy, text, widget
Tk hierarchy(1)
