iwidgets::hierarchy(1) [incr Widgets] iwidgets::hierarchy(1)
____________________________________________________________________________________________________________
NAME
iwidgets::hierarchy - Create and manipulate a hierarchy widget
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
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 associated 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 sticky
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 val-
ues previous 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 dis-play display
play 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 displayed. 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_GetPixels. Any additional space needed to display the other compo-nents components
nents such as labels, margins, and scrollbars force the hierarchy 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 different 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 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: 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 substituted.
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 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: 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 background 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 gener-ated, generated,
ated, 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 gener-ated, generated,
ated, 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 association 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 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 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 determine if the node has a children.
This can be cost some performace 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 avoiding 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 acceptable 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_GetPixels. The default is 3 pixels.
Name: selectCommand
Class: Command
Command-Line Switch: -selectcommand
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: -textback-ground -textbackground
ground
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. This option is only
administered if the width and height options are both set to zero, otherwise they take prece-dence. precedence.
dence. The default value is 80x24. With the visibleitems option engaged, geometry con-straints constraints
straints are maintained only on the text portion of the hierarchy. The size of the other com-ponents components
ponents 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 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 compo-nents components
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 differ-ent different
ent manner. The default width is zero.
____________________________________________________________________________________________________________
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 high-lighted. highlighted.
lighted. 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 dis-played, displayed,
played, 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 sta-tus status
tus 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 informa-tion information
tion 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 correspond-ing corresponding
ing 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 val-ues values
ues 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 sec-ondary secondary
ondary 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 chil-dren, children,
dren, 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 behav-ior behavior
ior 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 -selectionback-ground -selectionbackground
ground 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 unse-lected. unselected.
lected.
pathName toggle uid
Toggles the hierarchy beneath the node with the specified unique id. If the hierarchy is cur-rently currently
rently expanded, then it is collapsed, 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
commands 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 component 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 compo-nent component
nent 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 component item.
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
Mark L. Ulferts
Michael J. McLennan
KEYWORDS
hierarchy, text, widget
Tk iwidgets::hierarchy(1)
|