[incr Widgets] - hierarchy manpage
NAME
hierarchy - Create and manipulate a hierarchy widget
SYNOPSIS
hierarchy pathName ?options?
INHERITANCE
itk::Widget <- Labeledwidget <- Scrolledwidget <- Hierar
chy
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 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
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 previous
found the last time the query was made. The
default is no.
Name: closedIcon
Class: Icon
Command-Line Switch: -closedicon
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 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 impor
tant 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 hier
archy 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
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 selec
tion 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
Name: markForeground
Class: Background
Command-Line Switch: -markforeground
Specifies the foreground color to use when display
ing 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 possi
ble, 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 pos
sible, bitmap otherwise.
Name: queryCommand
Class: Command
Command-Line Switch: -querycommand
Specifies the command executed to query the con
tents 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 for
mat of returned list is
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
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 sta
tus: 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 selec
tion 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 adminis
tered 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
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 hier
archy 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 con
straints 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.
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 hierar
chy 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 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 path
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ
ing the one named option (this list will be identi
cal to the corresponding sublist of the value
returned if no option is specified). If one or
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 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 fol
lowing forms of the command are currently sup
ported:
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 affect
ing 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
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.
Name: list
Class: Text
The list component is the text widget in which the
hierarchy is displayed. See the "text" widget man
ual 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 com
mand. 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
proc get_files {file} {
global env
if {$file == ""} {
set dir $env(HOME)
} else {
set dir $file
}
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
Man(1) output converted with
man2html