iwidgets::hierarchy - Create and manipulate a hierarchy widget
iwidgets::hierarchy pathName
?options?
itk::Widget <- iwidgets::Labeledwidget <-
iwidgets::Scrolledwidget <- iwidgets::Hierarchy
activeBackground activeForeground background borderWidth
cursor disabledForeground foreground highlightColor
highlightThickness relief selectBackground selectForeground
See the "options" manual entry for details on the
standard 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.
labelBitmap labelFont labelImage labelMargin
labelPos labelText labelVariable sticky
See the "labeledwidget" class manual entry for details
on the inherited 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 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 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 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 components 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 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 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: -textbackground
- 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 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 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 components 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.
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.
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:
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.
- 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:
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.
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 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
component item.
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
Mark L. Ulferts
Michael J. McLennan