treectrl(n) Tk Commands treectrl(n)
NAME
treectrl - Create and manipulate hierarchical multicolumn widgets
SYNOPSIS
package require treectrl 1.0
treectrl pathName ?options?
pathName activate itemDesc
pathName canvasx screenx
pathName canvasy screeny
pathName cget option
pathName collapse ?-recurse? ?itemDesc ...?
pathName column option column ?arg ...?
pathName column bbox column
pathName column cget column option
pathName column configure column ?option? ?value? ?option value ...?
pathName column delete column
pathName column index column
pathName column move column before
pathName column neededwidth column
pathName column width column
pathName compare itemDesc1 op itemDesc2
pathName configure ?option? ?value option value ...?
pathName contentbox
pathName debug option ?arg arg ...?
pathName debug cget element option
pathName debug configure element ?option? ?value? ?option value ...?
pathName debug dinfo
pathName debug scroll
pathName depth ?itemDesc?
pathName dragimage option ?arg ...?
pathName dragimage add itemDesc ?column? ?element?
pathName dragimage cget option
pathName dragimage clear
pathName dragimage configure ?option? ?value? ?option value ...?
pathName dragimage offset ?x y?
pathName dragimage visible ?boolean?
pathName element option ?element? ?arg arg ...?
pathName element cget element option
pathName element configure element ?option? ?value? ?option value ...?
pathName element create element type ?option value ...?
pathName element delete ?element ...?
pathName element names
pathName element type element
pathName expand ?-recurse? ?itemDesc ...?
pathName identify x y
pathName index itemDesc
pathName item option ?arg ...?
pathName item ancestors itemDesc
pathName item bbox itemDesc ?column? ?element?
pathName item children itemDesc
pathName item complex itemDesc list ...
pathName item create
pathName item delete first ?last?
pathName item dump itemDesc
pathName item element command itemDesc column element ?arg ...?
pathName item element actual itemDesc column element option
pathName item element cget itemDesc column element option
pathName item element configure itemDesc column element ?option?
?value? ?option value ...?
pathName item firstchild parent ?child?
pathName item hasbutton itemDesc ?boolean?
pathName item index itemDesc
pathName item isancestor itemDesc descendant
pathName item isopen itemDesc
pathName item lastchild parent ?child?
pathName item nextsibling sibling ?next?
pathName item numchildren itemDesc
pathName item parent itemDesc
pathName item prevsibling sibling ?prev?
pathName item remove itemDesc
pathName item rnc itemDesc
pathName item sort itemDesc ?option ...?
pathName item state get itemDesc ?stateName ...?
pathName item state set itemDesc ?lastItem? ?stateDescList?
pathName item style command itemDesc ?arg ...?
pathName item style elements itemDesc column
pathName item style map itemDesc column style map
pathName item style set itemDesc ?column? ?style? ?column style ...?
pathName item text itemDesc column ?text? ?column text ...?
pathName item visible itemDesc ?boolean?
pathName marquee option ?arg ...?
pathName marquee anchor ?x y?
pathName marquee cget option
pathName marquee configure ?option? ?value? ?option value ...?
pathName marquee coords ?x1 y1 x2 y2?
pathName marquee corner ?x y?
pathName marquee identify
pathName marquee visible ?boolean?
pathName notify option ?arg ...?
pathName notify bind ?object? ?pattern? ?script?
pathName notify configure window pattern ?option? ?value? ?option value
...?
pathName notify detailnames eventName
pathName notify eventnames
pathName notify generate pattern ?charMap?
pathName notify install detail eventName detail ?percentsCommand?
pathName notify install event eventName ?percentsCommand?
pathName notify linkage eventName ?detail?
pathName notify uninstall detail eventName detail
pathName notify uninstall event eventName
pathName numcolumns
pathName numitems
pathName orphans
pathName range first last
pathName state option ?stateName?
pathName state define stateName
pathName state linkage stateName
pathName state names
pathName state undefine ?stateName ...?
pathName see itemDesc
pathName selection option arg
pathName selection add first ?last?
pathName selection anchor ?itemDesc?
pathName selection clear ?first? ?last?
pathName selection count
pathName selection get
pathName selection includes itemDesc
pathName selection modify select deselect
pathName style option ?element? ?arg arg ...?
pathName style cget style option
pathName style configure style ?option? ?value? ?option value ...?
pathName style create style ?option value ...?
pathName style delete ?style ...?
pathName style elements style ?elementList?
pathName style layout style element ?option? ?value? ?option value ...?
pathName style names
pathName toggle ?-recurse? ?itemDesc ...?
pathName xview ?args?
pathName xview
pathName xview moveto fraction
pathName xview scroll number what
pathName yview ?args?
pathName yview
pathName yview moveto fraction
pathName yview scroll number what
DESCRIPTION
treectrl pathName ?options?
The treectrl command creates a new window (given by the pathName argu-
ment) and makes it into a treectrl widget. Additional options,
described above, may be specified on the command line or in the option
database to configure aspects of the treectrl such as its background
color and relief. The treectrl command returns the path name of the
new window. At the time this command is invoked, there must not exist
a window named pathName, but pathName's parent must exist.
A treectrl is a widget which displays items one per line. Every item
has a set of states, which are boolean properties. The item may be
spread about one or more columns. For each column of an item there is
a style associated, which determines how to display the item's column
respecting the item's current state set. One column can be defined to
display the data in a hierarchical structure.
Normally the origin of the coordinate system is at the upper-left cor-
ner of the window containing the treectrl. It is possible to adjust
the origin of the coordinate system relative to the origin of the win-
dow using the xview and yview widget commands; this is typically used
for scrolling.
A treectrl widget can be horizontal or vertical oriented like many
other Tk widgets. For displaying hierarchical data only vertical ori-
entation is useful, since only then the children of an item are dis-
played directly below their parent. If the treectrl widget is used
only to display data in a multicolumn listbox, the specification of an
orientation will give useful results.
STANDARD OPTIONS
-background
-borderwidth
-cursor
-font
-highlightbackground
-highlightcolor
-highlightthickness
-orient
-relief
-takefocus
-xscrollcommand
-yscrollcommand
-foreground
See the option manual entry for details on the standard options.
WIDGET SPECIFIC OPTIONS
Command-Line Switch: -backgroundmode
Database Name: backgroundMode
Database Class: BackgroundMode
Specifies the desired mode for changing the background of indi-
vidual items. The value should be one of row, column, index, or
visindex. The default is row. This option has only an effect
for columns which have -itembackground defined as list of two or
more colors (see section COLUMNS below for more on this). The
color of items is changed for any row or column, if row or col-
umn is specified respectively. When index is specified, col-
lapsed items are counted also for evaluating the background
color, for visindex only the visible items are counted.
Command-Line Switch: -buttoncolor
Database Name: buttonColor
Database Class: ButtonColor
Specifies the foreground color which should be used for drawing
the outline and the plus or minus sign of the button to the left
of an item.
Command-Line Switch: -buttonsize
Database Name: buttonSize
Database Class: ButtonSize
Specifies the diameter of the button drawn to the left of an
item in any of the forms acceptable to Tk_GetPixels.
Command-Line Switch: -buttonthickness
Database Name: buttonThickness
Database Class: ButtonThickness
Specifies the width of the outline and the plus or minus sign of
the button to the left of an item in any of the forms acceptable
to Tk_GetPixels.
Command-Line Switch: -closedbuttonbitmap
Database Name: closedButtonBitmap
Database Class: ClosedButtonBitmap
Specifies the bitmap to be used as the button to the left of an
closed item in any of the forms acceptable to Tk_GetPixels.
Command-Line Switch: -closedbuttonimage
Database Name: closedButtonImage
Database Class: ClosedButtonImage
Specifies the image to be used as the button to the left of an
closed item in any of the forms acceptable to Tk_GetImage.
Command-Line Switch: -columnproxy
Database Name: columnProxy
Database Class: ColumnProxy
If this option specifies a non empty value, it should be a
screen distance in any of the forms acceptable to Tk_GetPixels.
Then a 1 pixel thick vertical line will be drawn at the speci-
fied screen distance from the left edge of the treectrl widget,
which reaches from top to bottom of the treectrl widget and uses
an inverting color (i.e black on lighter background, white on
darker background). This line can be used to give the user a
visual feedback during column resizing.
Command-Line Switch: -doublebuffer
Database Name: doubleBuffer
Database Class: DoubleBuffer
Specifies if double-buffering should be used to improve display-
ing. The value should be one of none, window, or item. For
none no double-buffering is used at all, which may be most mem-
ory efficient, but will probably generate some flickering on the
screen. For window the complete tree is double-buffered, which
requires a buffer big enough to contain the complete widget.
For item, which is the default, every item is separately double-
buffered, so it works with a buffer size as big as the biggest
item.
Command-Line Switch: -height
Database Name: height
Database Class: Height
Specifies the desired height for the window in any of the forms
acceptable to Tk_GetPixels. The default is 200 pixel. If this
option is less than or equal to zero then the window will not
request any size at all.
Command-Line Switch: -indent
Database Name: indent
Database Class: Indent
Specifies the amount of indentation in any of the forms accept-
able to Tk_GetPixels. The default is 19 pixel. Indentation is
the screen distance an item is displayed more to the right than
its father.
Command-Line Switch: -itemheight
Database Name: itemHeight
Database Class: ItemHeight
Specifies the minimal height of an item in any of the forms
acceptable to Tk_GetPixels. The default is 0, which means that
every item has exactly the height of it stallest element.
Command-Line Switch: -linecolor
Database Name: lineColor
Database Class: LineColor
Specifies the color which should be used for drawing the con-
necting lines between related items.
Command-Line Switch: -linestyle
Database Name: lineStyle
Database Class: LineStyle
Specifies the style of the connecting lines between related
items, should be dot which is the default, or solid.
Command-Line Switch: -linethickness
Database Name: lineThickness
Database Class: LineThickness
Specifies the thickness of the connecting lines between related
items in any of the forms acceptable to Tk_GetPixels.
Command-Line Switch: -openbuttonbitmap
Database Name: openButtonBitmap
Database Class: OpenButtonBitmap
Specifies the bitmap to be used as the button to the left of an
opened item in any of the forms acceptable to Tk_GetBitmap.
Command-Line Switch: -openbuttonimage
Database Name: openButtonImage
Database Class: OpenButtonImage
Specifies the image to be used as the button to the left of an
opened item in any of the forms acceptable to Tk_GetImage.
Command-Line Switch: -scrollmargin
Database Name: scrollMargin
Database Class: ScrollMargin
The interpretation of this option is left to Tcl scripts that
implement scrolling: the widget implementation ignores this
option entirely. Defaults to 0.
Command-Line Switch: -selectmode
Database Name: selectMode
Database Class: SelectMode
Specifies one of several styles for manipulating the selection.
The value of the option may be arbitrary, but the default bind-
ings expect it to be either single, browse, multiple, or
extended; the default value is browse.
Command-Line Switch: -showbuttons
Database Name: showButtons
Database Class: ShowButtons
Specifies a boolean value that determines whether this widget
displays a button to the left of any item. If the button is
actually drawn can be configured for every item with the item
hasbutton widget command, but if this option is set to false,
the configuration of an item has no effect. The default value
is true.
Command-Line Switch: -showheader
Database Name: showHeader
Database Class: ShowHeader
Specifies a boolean value that determines whether this widget
should display the header line with the column names at the top
of the widget. The default value is true.
Command-Line Switch: -showlines
Database Name: showLines
Database Class: ShowLines
Specifies a boolean value that determines whether this widget
should draw the connecting lines between related items. The
default value is true.
Command-Line Switch: -showroot
Database Name: showRoot
Database Class: ShowRoot
Specifies a boolean value that determines whether this widget
should draw the root item. By suppressing the drawing of the
root item the widget can have multiple items that appear as
toplevel items. The default value is true.
Command-Line Switch: -showrootbutton
Database Name: showRootButton
Database Class: ShowRootButton
Specifies a boolean value that determines whether this widget
should draw a button before the root item. The default value is
false.
Command-Line Switch: -treecolumn
Database Name: treeColumn
Database Class: TreeColumn
Specifies an integer value that determines which column displays
the data in an hierarchical fashion. Default is 0 meaning that
the first column displays the tree.
Command-Line Switch: -width
Database Name: width
Database Class: Width
Specifies the desired width for the window in any of the forms
acceptable to Tk_GetPixels. The default is 200 pixel. If this
option is less than or equal to zero then the window will not
request any size at all.
Command-Line Switch: -wrap
Database Name: wrap
Database Class: Wrap
Specifies how to arrange items inside treectrl's window. The
value must be an emtyp string, window, or a list with an integer
as first element and either items or pixels as second element.
The empty string as wrap mode means that each item appears on
exactly one line on the screen. In the other modes multiple
items may be displayed in one screen line. In window mode a
screen line break may occur after any element; in items mode a
line break will only be made after the specified number of
items; in pixels mode a line break will only be made after the
specified screen distance is reached.
Command-Line Switch: -xscrolldelay
Database Name: xScrollDelay
Database Class: ScrollDelay
Specifies the amount of time before the default binding should
handle repeating mouse motion events in horizontal direction
with button 1 pressed. The value should be a list of upto 2
integers. The first integer specifies the timespan in microsec-
onds before the active item should be changed to get nearer to
the current mouse position. If there are two integers specified,
the first is only used for the first motion event, any repeating
motion events are handled after the seconds amount of milisec-
onds is elapsed.
Command-Line Switch: -xscrollincrement
Database Name: xScrollIncrement
Database Class: ScrollIncrement
Specifies an increment for horizontal scrolling, in any of the
usual forms permitted for screen distances. If the value of
this option is greater than zero, the horizontal view in the
window will be constrained so that the x coordinate at the left
edge of the window is always an even multiple of -xscrollincre-
ment; furthermore, the units for scrolling (e.g., the change in
view when the left and right arrows of a scrollbar are selected)
will also be -xscrollincrement. If the value of this option is
less than or equal to zero, then horizontal scrolling is uncon-
strained.
Command-Line Switch: -yscrolldelay
Database Name: yScrollDelay
Database Class: ScrollDelay
Specifies the amount of time before the default binding should
handle repeating mouse motion events in vertical direction with
button 1 pressed. The value should be a list of upto 2 inte-
gers. The first integer specifies the timespan in microseconds
before the active item should be changed to get nearer to the
current mouse position. If there are two integers specified, the
first is only used for the first motion event, any repeating
motion events are handled after the seconds amount of milisec-
onds is elapsed.
Command-Line Switch: -yscrollincrement
Database Name: yScrollIncrement
Database Class: ScrollIncrement
Specifies an increment for vertical scrolling, in any of the
usual forms permitted for screen distances. If the value of
this option is greater than zero, the vertical view in the win-
dow will be constrained so that the y coordinate at the top edge
of the window is always an even multiple of -yscrollincrement;
furthermore, the units for scrolling (e.g., the change in view
when the top and bottom arrows of a scrollbar are selected) will
also be -yscrollincrement. If the value of this option is less
than or equal to zero, then vertical scrolling is unconstrained.
WIDGET COMMAND
The treectrl command creates a new Tcl command whose name is the same
as the path name of the treectrl's window. This command may be used to
invoke various operations on the widget. It has the following general
form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as the treectrl
widget's path name. Option and the args determine the exact behavior
of the command. The following commands are possible for treectrl wid-
gets:
pathName activate itemDesc
Sets the active item to the one described by itemDesc, and
switches on the state active for this item. From now on the
item can be retrieved with the item description active. An
<ActiveItem> event is generated.
pathName canvasx screenx
Given a window x-coordinate in the treectrl screenx, this com-
mand returns the treectrl x-coordinate that is displayed at that
location.
pathName canvasy screeny
Given a window y-coordinate in the treectrl screeny, this com-
mand returns the treectrl y-coordinate that is displayed at that
location.
pathName cget option
Returns the current value of the configuration option given by
option. Option may have any of the values accepted by the tree
command.
pathName collapse ?-recurse? ?itemDesc ...?
Switches off the open state of the item(s) described by
itemDesc. If the item has descendants, they are no longer dis-
played. If the item is configured to have a button, the button
will now display the image or bitmap configured with the widget
options -closedbuttonimage or -closedbuttonbitmap, or a + sign
if no image or bitmap is configured. If the item is already
closed, this command has no effect. ItemDesc may also be the
string all, in which case all items of the treectrl widget are
collapsed. If -recurse is specified, all descendants of
itemDesc will also be collapsed. For every item, that actually
will be collapsed, two events are generated: a <Collapse-before>
event before the item state is changed, and a <Collapse-after>
event after the item state was changed.
pathName column option column ?arg ...?
This command is used to manipulate the columns of the treectrl
widget (see section COLUMNS below). The exact behavior of the
command depends on the option argument that follows the column
argument. The following forms of the command are supported:
pathName column bbox column
Returns a list with four elements giving an approximate
bounding box for the column header specified by column.
If the treectrl is configured to don't display the column
headers by means of the -showheader option, an empty list
is returned instead.
pathName column cget column option
This command returns the current value of the option
named option for the column specified by column, Column
may also be the string tail to specify the tail column.
Option may have any of the values accepted by the column
configure widget command.
pathName column configure column ?option? ?value? ?option value
...?
This command is similar to the configure widget command
except that it modifies options associated with the col-
umn specified by column instead of modifying options for
the overall treectrl widget. Column may also be the
string tail to specify the tail column. If no option is
specified, the command returns a list describing all of
the available options for column (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 modi-
fies the given option(s) to have the given value(s) for
column; in this case the command returns an empty string.
The specified column is created, if it not already exists
and if at least one option-value pair is specified. See
COLUMNS below for details on the options available for
columns.
pathName column delete column
Deletes the specified column from the treectrl widget.
All remaining columns of the treectrl widget will get new
column numbers: in an unchanged order, but with succesive
numbers.
pathName column index column
This command returns a decimal string giving the column
number of the column specified by column, which may also
be the string tail to specify the tail column.
pathName column move column before
Moves the specified column to the left of the column
specified by before. If before is the string tail, the
column column will become the last column.
pathName column neededwidth column
This command returns a decimal string giving the needed
width of the column specified by column. The needed
width is the maximum of the width of the column header
and the width of the widest currently visible item.
pathName column width column
This command returns a decimal string giving the width of
the column specified by column, even if the treectrl is
configured to don't display the column headers by means
of the -showheader option.
pathName compare itemDesc1 op itemDesc2
From both items described by the itemDescs the index is
retrieved (as returned from the item index widget command).
Then these indexes are compared using the operator op, which
must be either <, <=, ==, >=, >, or !=. The return value of
this command is 1 if the comparison evaulated to true, 0 other-
wise.
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 treectrl command.
pathName contentbox
Returns a list with four elements giving an approximate bounding
box for the space used to display the items inside the columns,
i.e. the space of the treectrl widget without the surrounding
borders and the column headers.
pathName debug option ?arg arg ...?
This command is used to facilitate debugging of the treectrl
widget. The exact behavior of the command depends on the option
argument that follows the debug argument. The following forms
of the command are supported:
pathName debug cget element option
This command returns the current value of the debugging
option named option. Option may have any of the values
accepted by the debug configure widget command.
pathName debug configure element ?option? ?value? ?option value
...?
This command is similar to the configure widget command
except that it modifies debugging options instead of mod-
ifying options for the overall treectrl widget. If no
option is specified, the command returns a list describ-
ing all of the available debugging options (see Tk_Con-
figureInfo 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 debugging option(s) to have the given
value(s); in this case the command returns an empty
string.
The following debugging options are supported:
-displaydelay millis
Specifies a time duration in milliseconds, which
should be waited after something has been drawn to
the screen. Setting this option has only an
effect, if the debugging options -enable and -dis-
play are switched on.
-data boolean
If this option is switched on (together with the
debugging option -enable), at various places a
consistence check on the internal data structure
is made (e.g. for every item is checked, if the
registered number of children is equal to the num-
ber of child items). If an inconsistency was
found, a Tcl background error is raised.
-display boolean
If this option is switched on (together with the
debugging option -enable), at varios places addi-
tional debugging output is printed to stdout.
-enable boolean
All other debugging options only take effect, if
this option is also switched on.
-erasecolor color
Use this color, when parts of the treectrl widget
should be deleted. If you use an unusual color
for this option (like pink), superflous screen
redraws can be spotted more easily. Setting this
option has only an effect, if the debugging
options -enable and -display are switched on.
pathName debug dinfo
For every of the treectrl widget a line with some inter-
nal valuess info about all items is printed to stdout.
The command returns the empty string.
pathName debug scroll
Returns a string useful for debugging vertical scrolling.
pathName depth ?itemDesc?
If the additional argument itemDesc is specified, returns a dec-
imal string giving the depth of the item describing by itemDesc,
whereas depth is defined as the number of steps you must go
upward to reach to root item. If no itemDesc is specified, the
maximum depth of all items in the treectrl widget is returned
instead.
pathName dragimage option ?arg ...?
This command is used to manipulate the dragimage, one or more
dotted lines around rectangular regions of the treectrl widget.
The exact behavior of the command depends on the option argument
that follows the dragimage argument. The following forms of the
command are supported:
pathName dragimage add itemDesc ?column? ?element?
Adds the shapes of the item described by itemDesc to the
shapes of the dragimage. Specifying additional arguments
reduces the number of rectangles that are added to the
dragimage. If no additional arguments is specified, for
every element of the item in every column a dotted rec-
tangles is added. If column is specified, all elements
in other columns are ignored. If also element is speci-
fied, only a rectangle for this one element of the speci-
fied item in the given column is added.
pathName dragimage cget option
This command returns the current value of the dragimage
option named option. Option may have any of the values
accepted by the dragimage configure widget command.
pathName dragimage clear
Removes all shapes (if there are any) from the dragimage.
This command does not modify the dragimage offset.
pathName dragimage configure ?option? ?value? ?option value ...?
This command is similar to the configure widget command
except that it modifies the dragimage options instead of
modifying options for the overall treectrl widget. If no
option is specified, the command returns a list describ-
ing all of the available dragimage options (see Tk_Con-
figureInfo 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 dragimage 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 com-
mand modifies the given dragimage option(s) to have the
given value(s); in this case the command returns an empty
string.
The following dragimage options are supported:
-visible boolean
Specifies a boolean value which determines whether
the dragimage should currently be visible. This
option should not be modified by means of the
dragimage configure widget command; instead use
the dragimage visible widget command.
pathName dragimage offset ?x y?
Returns a list containing the x and y offsets of the
dragimage, if no additional arguments are specified. The
dragimage offset is the screen distance, the image is
displayed relative to the item its shape is derived from.
If two coordinates are specified, sets the dragimage off-
set to the given coordinates x and y.
pathName dragimage visible ?boolean?
If the additional argument specifies true, the dotted
lines will become visible and the dragimage option -visi-
ble becomes 1; if it specifies false, the dotted lines
will be hidden and the dragimage option -visible becomes
0. Returns 1 if the dragimage is currently visible, 0
otherwise.
pathName element option ?element? ?arg arg ...?
This command is used to manipulate elements (see ELEMENTS
below). The exact behavior of the command depends on the option
argument that follows the element argument. The following forms
of the command are supported:
pathName element cget element option
This command returns the current value of the option
named option associated with the element given by ele-
ment. Option may have any of the values accepted by the
element configure widget command.
pathName element configure element ?option? ?value? ?option
value ...?
This command is similar to the configure widget command
except that it modifies options associated with the ele-
ment given by element instead of modifying options for
the overall treectrl widget. If no option is specified,
the command returns a list describing all of the avail-
able options for element (see Tk_ConfigureInfo for infor-
mation on the format of this list). If option is speci-
fied with no value, then the command returns a list
describing the one named option (this list will be iden-
tical 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
option(s) to have the given value(s) in element; in this
case the command returns an empty string. See ELEMENTS
below for details on the options available for elements.
pathName element create element type ?option value ...?
Create a new elememt in pathName of type type with name
element. The exact format of the arguments after type
depends on type, but generally consist of specifications
for zero or more element options. See the subsections on
individual element types below for more on the syntax of
this command. This command returns the name for the new
element.
pathName element delete ?element ...?
Deletes each of the named elements and returns an empty
string. If an element is deleted while it is still con-
figured as an element of one or more styles by means of
the style elements widget command, it is also removed
from the element lists of these styles.
pathName element names
Returns a list containing the names of all existing ele-
ments.
pathName element type element
Returns the type of the elements given by element, such
as rect or text.
pathName expand ?-recurse? ?itemDesc ...?
Switches on the open state of the item(s) described by itemDesc.
If the item has descendants, they are now displayed. If the
item is configured to have a button, the button will now display
the image or bitmap configured with the widget options -openbut-
tonimage or -openbuttonbitmap, or a - sign if no image or bitmap
is configured. If the item is already open, this command has no
effect. ItemDesc may also be the string all, in which case all
items of the treectrl widget are expanded. If -recurse is spec-
ified, all descendants of itemDesc will also be expanded. For
every item, that actually will be expanded, two events are gen-
erated: an <Expand-before> event before the item state is
changed, and an <Expand-after> event after the item state was
changed.
pathName identify x y
Returns a list containing some diagnostics about what is dis-
played at the given windows coordinates x and y. The resulting
list may be empty, if nothing is displayed at the given coordi-
nates, otherwise the first list element is header or item.
If the coordinates are in the header area and thus the first
element of the result is header, the number of the column or the
string tail is the second element in the resulting list; if the
x coordinate is near the left or right end of the header, a
third element left or right is added respectively.
If the coordinates are below the header area and thus the first
element of the result is item, the numerical id of the item is
the second element in the resulting list. If the x coordinate
doesn't fall into the column displaying the hierarchical struc-
ture, the elements column and the column number are added. If
the x coordinate if above the column displaying the hierarchical
structure, the following elements are added to the resulting
list: line and the numerical id of the item the line comes from,
if the x coordinate is above an item connecting line; button, if
the x coordinate is above a button; column, the column number,
elem, and the element name, if the x coordinate is above an ele-
ment of the item; column and the column number, if the x coordi-
nate is to the right of the elements; nothing otherwise.
pathName index itemDesc
This command returns a decimal string giving the numerical id of
the item specified by itemDesc (see ITEM DESCRIPTION below).
pathName item option ?arg ...?
This command is used to manipulate items. The exact behavior of
the command depends on the option argument that follows the item
argument. The following forms of the command are supported:
pathName item ancestors itemDesc
Returns a list containing the numerical indexes of all
ancestors of the item specified by itemDesc from its par-
ent upto the root item.
pathName item bbox itemDesc ?column? ?element?
Returns a list with four elements giving an approximate
bounding box for the item described by itemDesc. If no
further argument is specified, the bbox spans the area of
the item over all columns. If a column is specified, only
the area of the item in this column is considered, if an
additional element is specified, the area of this element
in column of the specified item is returned.
pathName item children itemDesc
Returns a list containing the numerical indexes of all
children of the item specified by itemDesc in the correct
order from the first child to the last child.
pathName item complex itemDesc list ...
Modifies the elements of the item described by itemDesc.
For every column of the treectrl there may be specified
one list, which in turn is an odd elemented list with at
least three elements: the name of an element followed by
option-value pairs. Every option must be known by the
element's type (see ELEMENTS below). The corresponding
value will overwrite the value of the element for this
one column in this item.
pathName item create
Creates a new item and returns its numerical indexes.
The new item has set the states open and enabled. If the
treectrl widget has currently the focus, also the state
focus is set.
pathName item delete first ?last?
Deletes the specified item(s). First must be the string
all or an itemDesc, last must be an itemDesc if speci-
fied. If first is specified as all, all items are
deleted; if first is specified as itemDesc and last isn't
specified, the item described by first is delete. If
both first and last are specified, the must decribe items
with the same root item; then the range of items between
first and last is deleted. There is no way to delete the
root item of the treectrl widget; in all cases the speci-
fication of the root item is ignored;
pathName item dump itemDesc
Returns a list with six elements in the form index index
indexVis indexVis neededHeight neededHeight.
pathName item element command itemDesc column element ?arg ...?
This command is used to manipulate elements of the item.
The exact behavior of the command depends on the command
argument that follows the element argument. The follow-
ing forms of the command are supported:
pathName item element actual itemDesc column element
option
This command returns the current value of the
option named option associated with element inside
column of the item described by itemDesc; if it
was already configured for the actual item, the
return value is the same as if the item element
actual widget command was used; otherwise the
option value of the underlynig element is
returned. Option may have any of the values
accepted by the type of the specified element (see
ELEMENTS below)
pathName item element cget itemDesc column element option
This command returns the value of the option named
option associated with element inside column of
the item described by itemDesc, if it was already
configured for the actual item. Option may have
any of the values accepted by the type of the
specified element (see ELEMENTS below)
pathName item element configure itemDesc column element
?option? ?value? ?option value ...?
This command is similar to the configure widget
command except that it modifies options associated
with element inside column of the item described
by itemDesc instead of modifying options for the
overall treectrl widget. If no option is speci-
fied, the command returns a list describing all of
the available options for the element (see Tk_Con-
figureInfo 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 option(s) to have the given value(s) in the
element inside column of the item described by
itemDesc; in this case the command returns an
empty string.
pathName item firstchild parent ?child?
If child is not specified, returns the numerical index of
the first child of the item described by parent. If
child is specified, it must described an item that is not
an ancestor of parent. Then it will become the new first
child of parent.
pathName item hasbutton itemDesc ?boolean?
If boolean is not specified, returns 1 if to the left of
the item described by itemDesc a button should be drawn,
0 otherwise. If boolean is specified, it must be a valid
boolean value specifying if a button should be displayed
to the left of this item.
pathName item index itemDesc
Returns a list of two integers, which corresponds to the
row of the item described by itemDesc, if all items above
are counted and if only the displayed items are counted.
This command should not be confused with the index widget
command, which return the invariable item id. The index
here is basically the row of the item.
pathName item isancestor itemDesc descendant
Returns 1 if the item described by itemDesc is a direct
or indirect parent of the item decribed by descendant, 0
otherwise.
pathName item isopen itemDesc
Returns 1, if the item described by itemDesc has
cuurently the state open switched on, 0 otherwise.
pathName item lastchild parent ?child?
If child is not specified, returns the numerical index of
the last child of the item described by parent. If child
is specified, it must described an item that is not an
ancestor of parent. Then it will become the new last
child of parent.
pathName item nextsibling sibling ?next?
If next is not specified, returns the numerical index of
the next sibling of the item described by sibling. If
next is specified, it must described an item that is not
an ancestor of sibling. Then it will become the new next
sibling of sibling.
pathName item numchildren itemDesc
Returns the number of children of the item described by
itemDesc.
pathName item parent itemDesc
Returns the numerical index of the parent of the item
described by itemDesc.
pathName item prevsibling sibling ?prev?
If prev is not specified, returns the numerical index of
the previous sibling of the item described by sibling.
If prev is specified, it must described an item that is
not an ancestor of sibling. Then it will become the new
previous sibling of sibling.
pathName item remove itemDesc
Removes the item described by itemDesc from the children
list of its father, so that it will become an orphan.
pathName item rnc itemDesc
Returns a list of two integers, which corresponds to the
row and column of the item described by itemDesc.
pathName item sort itemDesc ?option ...?
Sorts the children of the item described by itemDesc, and
redisplays the tree with the items in the new order.
The range of items which should be sorted can be
restricted by means of the -first and/or -last options,
which should be children of the item described by
itemDesc; the order between these two limiting items
doesn't matter.
The sort column can be specified by means of the -column
option; this option can be used repeatedly to define a
multi column sort. The sorting is done by looking at the
text of the element specified by the -element option,
which must be a text element defined in the style of the
sorting column, by default the first text element is
used.
If the -notreally option is specified, no rearranging of
the items is done; instead the sorted items are returned
as result of the command.
By default ASCII sorting is used with the result returned
in increasing order. The order can be modified by means
of the -increasing (the default) or -decreasing flag.
Any of the following options may be specified to control
the sorting process of the previously specified column
(unique abbreviations are accepted):
-ascii Use string comparison with ASCII collation order.
This is the default.
-command command
Use command as a comparison command. To compare
two items, evaluate a Tcl script consisting of
command with the numerical ids of the two items
appended as additional arguments. The script
should return an integer less than, equal to, or
greater than zero if the first item is to be con-
sidered less than, equal to, or greater than the
second, respectively.
-dictionary
Use dictionary-style comparison. This is the same
as -ascii except (a) case is ignored except as a
tie-breaker and (b) if two strings contain embed-
ded numbers, the numbers compare as integers, not
characters. For example, in -dictionary mode,
bigBoy sorts between bigbang and bigboy, and x10y
sorts between x9y and x11y.
-integer
Convert to integers and use integer comparison.
-real Convert to floating-point values and use floating
comparison.
pathName item state get itemDesc ?stateName ...?
If no stateName is specified, returns a list containing
the names of all (predefined and user defined) states
which are currently switched on for the item described by
itemDesc. If a stateName is specified, 1 is returned if
the specified state is currently switched on for the
item, 0 otherwise.
pathName item state set itemDesc ?lastItem? ?stateDescList?
Every element of stateDescList must describe a user
defined state (see STATES below), with the particularity
that the state name may have also a leading ~. Every
state with a leading ! will be switched off for the item
described by itemDesc, every state with a leading ~ will
be toggled, and every state without leading ! or ~ will
be switched on. If lastItem is specified, the state
changes will be made for all items in the range betwen
itemDesc and lastItem. ItemDesc may be the string all,
then the state changes are made for all items of the
treectrl widget.
pathName item style command itemDesc ?arg ...?
This command is used to manipulate the style of the item.
The exact behavior of the command depends on the command
argument that follows the style argument. The following
forms of the command are supported:
pathName item style elements itemDesc column
A list is returned containing the currently
defined elements of the style, which is set for
the item described by itemDesc in column.
pathName item style map itemDesc column style map
Map must be a list with an even number of ele-
ments, and each element must be the name of an
element created by the element create widget com-
mand. Replaces elements in the style of the item
described by itemDesc in column based on the from-
to pairs in map.
pathName item style set itemDesc ?column? ?style? ?column
style ...?
If no column is specified, returns a list contain-
ing the names of the styles set for all columns of
the item described by itemDesc. If no style argu-
ment is specified, returns the name of the style
set for the item described by itemDesc in column.
If there are one or more style arguments speci-
fied, it must be column-style pairs; then the
style(s) of item in column will be set to style.
pathName item text itemDesc column ?text? ?column text ...?
If no text argument is specified, returns the text of the
item described by itemDesc in column. If there are one
or more text arguments specified, it must be column-text
pairs; then the text(s) of item in column will be set to
text.
pathName item visible itemDesc ?boolean?
If boolean is not specified, returns 1 if the item
described by itemDesc is currently visible, 0 otherwise.
If boolean is specified, it must be a valid boolean value
specifying if the item should be visible. The visibility
of an item is independend from the state of its ances-
tors. So if the state of one of the ancestors is cur-
rently not opened, the item may be considered visible
although it is not displayed on the screen.
pathName marquee option ?arg ...?
This command is used to manipulate the marquee, a rectangular
region of the treectrl widget optionally marked with a surround-
ing dotted line. One corner point of the marquee is fixed as
long as the marquee is visible and called the anchor; the diago-
nally opposite corner is dragged with the mouse while resizing
the marquee and simply called the corner. All coordinates han-
dled by this widget command are treectrl coordinates, i.e. the
canvasx or canvasy widget command should be used before any win-
dow coordinates can be used. The exact behavior of the command
depends on the option argument that follows the marquee argu-
ment. The following forms of the command are supported:
pathName marquee anchor ?x y?
Returns a list containing the x and y coordinates of the
anchor, if no additional arguments are specified. If two
coordinates are specified, sets the anchor to the given
coordinates x and y.
pathName marquee cget option
This command returns the current value of the marquee
option named option. Option may have any of the values
accepted by the marquee configure widget command.
pathName marquee configure ?option? ?value? ?option value ...?
This command is similar to the configure widget command
except that it modifies the marquee options instead of
modifying options for the overall treectrl widget. If no
option is specified, the command returns a list describ-
ing all of the available marquee options (see Tk_Config-
ureInfo 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 marquee 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 com-
mand modifies the given marquee option(s) to have the
given value(s); in this case the command returns an empty
string.
The following marquee options are supported:
-visible boolean
Specifies a boolean value which determines whether
the dotted line surrounding the region of the mar-
quee should currently be visible. This option
should not be modified by means of the marquee
configure widget command; instead use the marquee
visible widget command.
pathName marquee coords ?x1 y1 x2 y2?
Returns a list containing the x and y coordinates of the
anchor followed by the x and y coordinates of the corner,
if no additional arguments are specified. If four coor-
dinates are specified, sets the anchor to the given coor-
dinates x1 and y1 and the corner to the coordinates x2
and y2.
pathName marquee corner ?x y?
Returns a list containing the x and y coordinates of the
corner, if no additional arguments are specified. If two
coordinates are specified, sets the corner to the given
coordinates x and y.
pathName marquee identify
Returns a list with information about the items inside
the marquee. The list has as elements a list itself for
every item which is displayed inside the marquee. The
first element of these lists is the numerical item id,
followed by another list with information about every
column of the item inside the marque. These lists start
with the column number, followed by the elements of the
style defined for the item in this column if there are
any.
pathName marquee visible ?boolean?
If the additional argument specifies true, the dotted
line will become visible and the marquee option -visible
becomes 1; if it specifies false, the dotted line will be
hidden and the marquee option -visible becomes 0.
Returns 1 if the dotted line surrounding the marquee is
currently visible, 0 otherwise.
pathName notify option ?arg ...?
This command is used to manipulate the event mechanism of a
treectrl widget, which stands in parallel to Tk's event mecha-
nism. It has two major advantages: arbitrary new events can be
defined together with arbitrary details, and before the event is
triggered the called Tcl command underlys a customizable percent
substitution.
The exact behavior of the command depends on the option argument
that follows the notify argument. The following forms of the
command are supported:
pathName notify bind ?object? ?pattern? ?script?
This command associates script with the object given by
object such that whenever the event sequence given by
pattern occurs for the object the command will be
invoked. This widget command is similar to the bind com-
mand except that it operates on any object in a treectl
rather than entire widgets, and it works also for non X11
event pattern. If all arguments are specified then a new
binding is created, replacing any existing binding for
the same pattern and object (if the first character of
script is + then script augments an existing binding
rather than replacing it). In this case the return value
is an empty string. If script is omitted then the com-
mand returns the script associated with object and pat-
tern (an error occurs if there is no such binding). If
both script and pattern are omitted then the command
returns a list of all the sequences for which bindings
have been defined for object. If no optional argument is
specified, a list of all objects to which a pattern-
script combination is bound yet, is returned.
pathName notify configure window pattern ?option? ?value?
?option value ...?
This command is similar to the configure widget command
except that it modifies event options defined for pattern
in window instead of modifying options for the overall
treectrl widget. If no option is specified, the command
returns a list with option-value pairs describing all the
available event options for pattern in window. If option
is specified with no value, then the command does noth-
ing. If one or more option-value pairs are specified,
then the command modifies the given option(s) to have the
given value(s) for the layout; in this case the command
returns an empty string.
The following event options are supported:
-active boolean
Specifies if the event should be active. As long
as this option is specified as false, the event
will not trigger.
pathName notify detailnames eventName
Returns a list containing the names of all details, which
are installed for the event with the name eventName by
means of the notify install detail widget command or by
the treectrl widget itself.
pathName notify eventnames
Returns a list containing the names of all events, which
are installed by means of the notify install event widget
command or by the treectrl widget itself.
pathName notify generate pattern ?charMap?
The event with the pattern pattern is generated, if it is
configured as active. If there are details defined for
the event, pattern must describe an eventName-detail
pair, otherwise pattern should be a simple event name.
The optional charMap is a list of key-value pairs as in
the form returned by array get; each key has to be
exactly one character. If this argument is specified,
the following substitution will be done in the script
registered for the generated event before it will be
evaluated: every occurence of a percent character (%)
followed by a key will be replaced with its corresponding
value.
pathName notify install detail eventName detail ?percentsCom-
mand?
Installs a new detail detail for the event with the name
eventName. A detail create by this command is called
dynamic, whereas details created by the treectrl widget
itself are called static.
The optional percentsCommand will be called before the
event is triggered for every two character sequence
starting with a percent character (%). The script is
called with at least four additional arguments: the sec-
ond character of the sequence, the window for which the
event is triggered, eventName and detail, and finally the
field-value pairs specified as arguments in the notify
generate call to generate the event (the leading dash is
dropped from the fields). The two character sequence of
the command will be replaced by the returning string, or
by an empty string if the command returns with a return-
Code other than 0.
pathName notify install event eventName ?percentsCommand?
Installs a new event with the name eventName. An event
create by this command is called dynamic, whereas events
created by the treectrl widget itself are called static.
For the optional percentsCommand argument see the
description of the notify install detail widget command
above; the value for the argument detail is the empty
string.
pathName notify linkage eventName ?detail?
Returns a string indicating whether the specified event
or detail is created by means of the notify install wid-
get command (dynamic) or by the treectrl widget itself
(static).
pathName notify uninstall detail eventName detail
If the specified detail detail of the event with the name
eventName is static (i.e. created by the treectrl widget
itself), an error is generated. Otherwise the dynamic
detail is removed from the event.
pathName notify uninstall event eventName
If the specified event with the name eventName is static
(i.e. created by the treectrl widget itself), an error is
generated. Otherwise the dynamic event is removed.
pathName numcolumns
Returns a decimal string giving the number of columns configured
in the treectrl widget. Since the always existant tail column
is ignored by this command, the number can be 0 if no column is
configured yet.
pathName numitems
Returns a decimal string giving the number of items created in
the treectrl widget. This number is always positive, since a
newly created treectrl widget has already the root item, which
cannot be deleted.
pathName orphans
Returns a list containing the numerical ids of all items which
has no parent item. An item is created without having a parent,
and can later become an orphan again by means of the item remove
widget command.
pathName range first last
First and last must be an itemDesc. Returns a list containing
the numerical ids of all items in the range between first and
last, inclusive. The order between first and last doesn't mat-
ter, and the result is always ordered by the increasing index of
the items.
pathName state option ?stateName?
This command is used to manipulate the list of user defined
states, see section STATES below. The exact behavior of the
command depends on the option argument that follows the state
argument. The following forms of the command are supported:
pathName state define stateName
Defines a new state with the name stateName, which must
not be the name of a predefined or already user defined
state.
pathName state linkage stateName
Returns a string indicating whether the specified state
is user defined by means of the state define widget com-
mand (dynamic) or predefined by the treectrl widget
itself (static).
pathName state names
Returns a list containing the names of all user defined
states.
pathName state undefine ?stateName ...?
Every stateName must be the name of a user defined state.
Removes this state from the list of user defined states.
pathName see itemDesc
Adjust the view in the treectrl so that the item described by
itemDesc is visible. If the item is already visible then the
command has no effect; otherwise the treectrl scrolls to bring
the item into view, and the corresponding <Scroll-x> and/or
<Scroll-y> events are generated.
pathName selection option arg
This command is used to adjust the selection within a treectrl.
It has several forms, depending on option:
pathName selection add first ?last?
First and last (if specified) must be the string all or
an itemDesc. Selects all of the items in the range
between first and last, inclusive, without affecting the
selection state of items outside that range. If one of
the arguments is the string all, all items of the treec-
trl widget are added to the selection instead. A <Selec-
tion> event is generated.
pathName selection anchor ?itemDesc?
If itemDesc is specified, the selection anchor is set to
the described item. The selection anchor is the end of
the selection that is fixed while dragging out a selec-
tion with the mouse. The item description anchor may be
used to refer to the anchor item. This command doesn't
modify the selection state of any item. Returns the
numerical id of the selection anchor item.
pathName selection clear ?first? ?last?
First and last (if specified) must be the string all or
an itemDesc. If any of the items between first and last
(inclusive) are selected, they are deselected. The
selection state is not changed for items outside this
range. If no additional arguments is given or one of the
arguments is the string all, the selection is completely
cleared instead. A <Selection> event is generated.
pathName selection count
Returns an integer indicating the number of items in the
treectrl that are currently selected.
pathName selection get
Returns a list containing the numerical ids of all of the
items in the treectrl that are currently selected. If
there are no items selected in the treectrl then an empty
string is returned.
pathName selection includes itemDesc
Returns 1 if the item indicated by itemDesc is currently
selected, 0 if it isn't.
pathName selection modify select deselect
Both arguments select and deselect must be the string all
or a possibly empty list of itemDescs. Selects all of
the items described by select, then deselects all items
described by deselect, without affecting the selection
state of any item not mentioned in both arguments. If
one item is described in both arguments select and dese-
lect, it is added to the selection. A <Selection> event
is generated.
pathName style option ?element? ?arg arg ...?
This command is used to manipulate styles, which could be con-
sidered as a geometry manager for the elements of one item. The
exact behavior of the command depends on the option argument
that follows the style argument. The following forms of the
command are supported:
pathName style cget style option
This command returns the current value of the option
named option associated with the style given by style.
Option may have any of the values accepted by the style
configure widget command.
pathName style configure style ?option? ?value? ?option value
...?
This command is similar to the configure widget command
except that it modifies options associated with the style
given by style instead of modifying options for the over-
all treectrl widget. If no option is specified, the com-
mand returns a list describing all of the available
options for style (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 cor-
responding sublist of the value returned if no option is
specified). If one or more option-value pairs are speci-
fied, then the command modifies the given option(s) to
have the given value(s) in style; in this case the com-
mand returns an empty string.
The options of a style have effect on all elements man-
aged by the style. The following options are supported:
-orient varName
This option specifies which orientation should be
used when laying out the elements associated with
this style. Must be either horizontal (the
default) or vertical or an abbreviation of one of
these.
pathName style create style ?option value ...?
Create a new style in pathName with name style. After
style there may be any number of option-value pairs, each
of which sets one of the configuration options for the
style. These same option-value pairs may be used in
style configure widget commands to change the styles's
configuration. Returns the name of the new style.
pathName style delete ?style ...?
Deletes each of the named styles and returns an empty
string. If a style is deleted while it is still used to
display one or more items, it is also removed from the
style list of these items.
pathName style elements style ?elementList?
Specifies the elements which should be layed out by this
style. Each element of elementList must be the name of
an element created by the widget command element create.
Duplicate names in elementList are ignored. An element
which was specified in a former call of this command for
style but is not included in elementList, will be deleted
from the elements layed out by style.
If the elementList argument is not specified, a list is
returned containing the currently defined elements of
style.
pathName style layout style element ?option? ?value? ?option
value ...?
This command is similar to the configure widget command
except that it modifies options used by style for laying
out element instead of modifying options for the overall
treectrl widget. If no option is specified, the command
returns a list with option-value pairs describing all of
the available options for the layout. If option is spec-
ified with no value, then the command returns the value
of the named option. If one or more option-value pairs
are specified, then the command modifies the given
option(s) to have the given value(s) for the layout; in
this case the command returns an empty string.
The options of a layout have effect on exactly the one
element element managed by style. The following options
are supported:
-padx amount
-pady amount
Amount specifies how much external padding to
leave on the left and right (for -padx) or top and
bottom (for -pady) side of the element. Amount
may be a list of two values to specify padding for
the two sides separately, it defaults to 0.
-ipadx amount
-ipady amount
Amount specifies how much internal padding to
leave on the left and right (for -ipadx) or top
and bottom (for -ipady) side of the element.
Amount may be a list of two values to specify pad-
ding for the two sides separately, it defaults to
0.
-expand style
-iexpand style
It can happen that the element's space is larger
than its requested dimensions. These options may
be used to position (or stretch) the slave within
its cell. Style is a string that contains zero
or more of the characters n, s, e or w. The
string can contain other characters, but they are
ignored. Each letter refers to a side (north,
south, east, or west) in which direction the ele-
ment will grow to.
-squeeze style
If an elements's area is smaller than its
requested dimensions, this option may be used to
allow shrinking of the element. Style is a
string that contains zero or more of the charac-
ters x or y. The string can contain other charac-
ters, but they are ignored. x shrinks the element
horizontally, y shrinks it vertically.
-union elementList
Specifies a list of other elements, which should
be layed out inside the space of this element.
-detach boolean
Specifies whether the element should be positioned
by themselves, i.e. independent from the other
elements.
pathName style names
Returns a list containing the names of all existing
styles.
pathName toggle ?-recurse? ?itemDesc ...?
Changes the open state of the item(s) described by itemDesc. If
the state is currently switched off, this command does the same
as the expand widget command, otherwise the same as the collapse
widget command. ItemDesc may also be the string all, in which
case the state of all items of the treectrl widget are toggled.
If -recurse is specified, the state of all descendants of
itemDesc will also be toggles.
pathName xview ?args?
This command is used to query and change the horizontal position
of the information displayed in the treectrl's window. It can
take any of the following forms:
pathName xview
Returns a list containing two elements. Each element is
a real fraction between 0 and 1; together they describe
the horizontal span that is visible in the window. For
example, if the first element is .2 and the second ele-
ment is .6, 20% of the tree's area is off-screen to the
left, the middle 40% is visible in the window, and 40% of
the tree is off-screen to the right. These are the same
values passed to scrollbars via the -xscrollcommand
option.
pathName xview moveto fraction
Adjusts the view in the window so that fraction of the
total width of the tree is off-screen to the left. Frac-
tion must be a fraction between 0 and 1. A <Scroll-x>
event is generated.
pathName xview scroll number what
This command shifts the view in the window left or right
according to number and what. Number must be an integer.
What must be either units or pages or an abbreviation of
one of these. If what is units, the view adjusts left or
right in units of the -xscrollincrement option, if it is
greater than zero, or in units of one-tenth the window's
width otherwise. If what is pages then the view adjusts
in units of nine-tenths the window's width. If number is
negative then information farther to the left becomes
visible; if it is positive then information farther to
the right becomes visible. A <Scroll-x> event is gener-
ated.
pathName yview ?args?
This command is used to query and change the vertical position
of the information displayed in the treectrl's window. It can
take any of the following forms:
pathName yview
Returns a list containing two elements. Each element is
a real fraction between 0 and 1; together they describe
the vertical span that is visible in the window. For
example, if the first element is .6 and the second ele-
ment is 1.0, the lowest 40% of the tree's area is visible
in the window. These are the same values passed to
scrollbars via the -yscrollcommand option.
pathName yview moveto fraction
Adjusts the view in the window so that fraction of the
tree's area is off-screen to the top. Fraction is a
fraction between 0 and 1. A <Scroll-y> event is gener-
ated.
pathName yview scroll number what
This command adjusts the view in the window up or down
according to number and what. Number must be an integer.
What must be either units or pages. If what is units,
the view adjusts up or down in units of the
-yscrollincrement option, if it is greater than zero, or
in units of one-tenth the window's height otherwise. If
what is pages then the view adjusts in units of nine-
tenths the window's height. If number is negative then
higher information becomes visible; if it is positive
then lower information becomes visible. A <Scroll-y>
event is generated.
COLUMNS
A treectrl widget is capable of displaying multiple columns next to
each other. An item can be considered as a row, which reaches over all
columns.
Many of the widget commands for a treectrl take as one argument an
indicator of which column of the treectrl to operate on. These indica-
tors are called columns and may be specified as numerical index as
given by the first column configure widget command which created the
column or by its name, which can be configured my means of the -tag
column option.
There is always one special column, the tail column, which fills all
space to the right of the last ordinary column. This column has no
number; it can only be specified by its tag tail, which cannot be modi-
fied. It is explicitely mentioned for a widget command, if its column
argument can also specify the tail column.
The following options are supported for columns:
-arrow direction
Indicates whether or not an arrow should be drawn in the column
header to the right of the column title. Direction must have
one of the values none (the default), up, or down.
-arrowside side
Indicates on which side an arrow should be drawn, if at all.
Side must be either left or right (the default).
-arrowgravity side
Indicates onto which side an arrow should be packed, if there is
more space available for drawing the arrow then needed. Side
must be either left (the default) or right.
-arrowpad amount
Amount specifies how much padding to leave on the left and right
side of the arrow. Amount may be a list of two values to spec-
ify padding for left and right separately, it defaults to 0.
-bitmap bitmap
Specifies the bitmap to display in the element to the left of
the column title.
-background color
Specifies the color to use for the background of the column
header.
-borderwidth size
Specifies a non-negative value indicating the width of the 3-D
border to draw around the outside of the column header (if such
a border is being drawn; the -relief column option determines
this). The value may have any of the forms acceptable to
Tk_GetPixels.
-button boolean
Indicates whether or not a mouse click on the column header
should change the sorting order of the tree.
-expand boolean
Indicates whether or not any extra spaces should be distributed
to this column. This option will actually only work, if the
column has no fix width defined by means of the -width column
option.
-font fontName
Specifies the font to use for the column title inside the column
header.
-image image
Specifies the image to display in the element to the left of the
column title. This option overrides the -bitmap column option.
-imagepadx amount
-imagepady amount
Amount specifies how much padding to leave on the left and right
(for -imagepadx) or top and bottom (for -imagepady) side of the
image. Amount may be a list of two values to specify padding
for the two sides separately, it defaults to 0.
-itembackground colorList
Specifies a list of colors, which should be used as alternating
background color for the items of this column. See also the
-backgroundmode widget option for more on this.
-justify justification
This option determines how the items (and the title) line up
with each other. Must be one of left (the default), center, or
right.
-minwidth size
Specifies the minimum size, in screen units, that will be per-
mitted for this column.
-relief relief
Specifies the 3-D effect desired for the column header contain-
ing the title. Acceptable values are the typical relief values,
but the value seems to be ignored anyway; better use the -sunken
column option instead.
-stepwidth size
Specifies a sort of tabbed alignment for columns that displays
more than one item next to each other (typically in a treectrl
widget with horizontal orientation). Every item will get an x-
coordinate which is a multiple of size.
-sunken boolean
Indicates whether or not the column header containing the column
title will be displayed with a sunken relief.
-tag tag
Defines a unique name for the columns which can be used in sub-
sequent calls of the treectrl widget commands, wherever a column
must be specified.
-text text
Specifies a text to be displayed inside the column title.
-textcolor color
Specifies a color, which should be used as foreground color to
display the column title.
-textpadx amount
-textpady amount
Amount specifies how much padding to leave on the left and right
(for -textpadx) or top and bottom (for -textpady) side of the
text. Amount may be a list of two values to specify padding for
the two sides separately, it defaults to 0.
-width size
Specifies the width of the column.
-visible boolean
Indicates whether or not the column should be displayed.
-widthhack boolean
Indicates whether or not all items inside the column should have
the same width (typically in a treectrl widget with horizontal
orientation).
STATES
A state consists basically of just a string: its stateName. For every
item a set of these states is managed, which means that every item can
have every state switched on or off. The following states are prede-
fined for every item:
active At every time this state is set for exactly one item, which
therefore is called the active item. When the treectrl widget
is created or when the active item is deleted, the root item
will become the active element. This state can be modified by
means of the widget command activate.
enabled
This state is set for every item, when it is created. It cannot
be modified.
focus This state is set for every item, if the treectrl widget has
currently the focus. It cannot be modified by means of a widget
command, but is maintained as reaction of a <FocusIn> or <Focu-
sOut> event.
open If this state is switched on, the descendants of the item are
displayed - the item is expanded. If this state is switched
off, the descendants of the item are not displayed - the item is
collapsed. For a new item this state is switched on. It can be
modified by means of the widget commands expand, collapse, or
toggle.
selected
This state is set for every item, which is included in the
selection. It can be modified by means of the widget command
selection.
By means of the state define widget command upto 27 additional state-
Names can be defined.
Some widget commands expect a stateDesc argument, which is a stateName
optionally preceded by an exclamation mark (!). If the stateName has
no leading ! it describes a currently switched on state, if it has a
leading ! it describes a currently switched off state.
Some widget commands expect a statePattern argument, which should be a
non empty list of stateDescs. The pattern matches, if for every ele-
ment of the list the stateDesc describes the same state as the item
currently has.
ELEMENTS
Elements are the smallest building block which are handled by a treec-
trl widget. One or more elements together can be combined to a style,
which can be considered as a blueprint for an item. They can also be
used to create an item directly by means of the item complex widget
command. An element can be of type bitmap, border, image, rect, or
text. For each element type there is a section below describing all
options which can modify the behaviour of an element of this type.
There are some options which can be configured to get different values
dependent on the state of the item in which their element is included.
The values of these options are basically a list. If the list has one
element, the value is valid regardless of the item state. A list with
an even number of elements (value-statePattern pairs) specifies differ-
ent values for different states. For acceptable values of statePattern
see the section STATES above. The last statePattern can be empty,
implementing a sort of otherwise clause. The options with this behav-
iour are called per state options.
BITMAP ELEMENT
An element of type bitmap can be used to display a bitmap in an item.
The following options are supported for bitmap elements:
-background color
Specifies as a per state option the color to use for each of the
bitmap's '0' valued pixels.
-bitmap bitmap
Specifies as a per state option the bitmap to display in the
element.
-foreground color
Specifies as a per state option the color to use for each of the
bitmap's '1' valued pixels.
BORDER ELEMENT
An element of type border can be used to add a border to an item. The
following options are supported for border elements:
-background color
Specifies as a per state option the color to use for the back-
ground of the border.
-filled boolean
Specifies whether the interior of the border should also be
filled with the specified background color. Default to false,
which means that the background color of the tree is visible
between the borders.
-height size
Specifies the height of the area of the border.
-relief reliefList
Specifies as a per state option relief of the border. For
acceptable values see the description of the -relief option in
the options manual page.
-thickness thickness
Specifies the thickness of the border.
-width size
Specifies the width of the area of the border.
IMAGE ELEMENT
An element of type image can be used to display an image in an item.
The following options are supported for image elements:
-height size
Specifies the height of the image.
-image image
Specifies as a per state option the image to display in the ele-
ment.
-width size
Specifies the width of the image.
RECTANGLE ELEMENT
An element of type rect can be used to display a rectangle in an item.
The following options are supported for rectangle elements:
-fill fillColor
Specifies as a per state option the color to be used to fill
rectangle's area. Color may have any of the forms accepted by
Tk_GetColor. If color is an empty string (the default), then
the rectangle will not be filled.
-height size
Specifies the height of the rectangle.
-open open
This option may be used to get an incomplete drawing of the out-
line. Open is a string that contains zero or more of the char-
acters n, s, e or w. Each letter refers to a side (north,
south, east, or west) that the outline will not be drawn. The
default is , which causes the outline to be drawn completely.
-outline outlineColor
Specifies as a per state option the color that should be used to
draw the outline of the rectangle. Color may have any of the
forms accepted by Tk_GetColor. If color is specified as an
empty string (the default), then no outline is drawn for the
rectangle.
-outlinewidth outlineWidth
Specifies the width of the outline to be drawn around the rec-
tangle's region. outlineWidth may be in any of the forms
acceptable to Tk_GetPixels. If the -outline option has been
specified as an empty string (the default), then no outline is
drawn.
-showfocus boolean
Specifies a boolean value indicating whether a "focus ring"
should be drawn around the rectangle, if the item containing the
rectangle is the active item and the treectrl widget has cur-
rently the focus.
-width size
Specifies the width of the rectangle.
TEXT ELEMENT
An element of type text can be used to display a text in an item. The
following options are supported for text elements:
-data data
Specifies raw data to be printed as text.
-datatype dataType
Specifies the datatype which should be used to convert the value
of the -data option to the text to be printed. Acceptable values
are double, integer, long, string, or time.
-fill color
Specifies as a per state option the color to be used as fore-
ground color of the text. Color may have any of the forms
accepted by Tk_GetColor. If color is an empty string (the
default), then the text will be displayed with the color speci-
fied as foreground color of the treectrl widget.
-format format
This option overwrites the default format choosen by means of
the -datatype option. For a datatype time format should be a
valid format string for the clock command, for all other
datatypes it should be a valid format element of the format com-
mand.
-font fontName
Specifies as a per state option the font to use for the text.
FontName may be any string acceptable to Tk_GetFont. If this
option isn't specified, it defaults to the font configured for
the treectrl widget.
-justify how
Specifies how to justify the text within its bounding region.
How must be one of the values left, right, or center. This
option will only matter if the text is displayed as multiple
lines. If the option is omitted, it defaults to left.
-lines lineCount
Specifies the maximal number of lines the text should be
printed. If the doesn't fit into the area of lineCount lines
with the configured width, it will be truncated at the right end
and filled up with an ellipsis.
-text string
String specifies the characters to be displayed in the text.
Non printable characters are displayed in their escaped form
(e.g. a new line character is displayed as the two characters
0fR). If this option is specified, any values of -data,
-datatype, and -format are ignored. -width size Specifies the
width of the area of the text.
-wrap mode
Mode specifies how to handle lines that are wider than the
text's area. Acceptable values are char or word.
ITEM DESCRIPTION
Many of the widget commands for a treectrl take as one argument an
indicator of which item of the treectrl to operate on. These indica-
tors are called itemDescs and may be specified in any of the following
forms:
number Specifies the item numerically, where number should be the
return value of a prior call of the item create widget command,
or 0 to specify the root item.
active Indicates the item that is currently active, i.e. normally the
item specified as argument of the last successful activate wid-
get command, or the root item if no such call happened yet.
anchor Indicates the anchor item of the selection, i.e. normally the
item specified as argument of the last successful selection
anchor widget command, or the root item if no such call happened
yet.
first ?visible?
Indicates the first item of the treectrl, i.e. the root item.
If visible is specified and the widget is configured with -show-
root no, the first visible child of the root node is specified
instead.
last ?visible?
Indicates the last item of the treectrl. If visible is speci-
fied and the last item is currently not visible, i.e. one of its
father nodes is collapsed, the last visible item is specified
instead.
nearest x y
Indicates the item nearest to the point given by x and y.
rnc row column
Indicates the item in the given row and column. You can memo-
rize rnc as abbreviation of "row 'n' column".
root Indicates the root item of the treectrl.
The itemDesc may be followed by one or more modifiers. A modifier
changes the item described by the itemDesc relative to the description
upto this point. It may be specified in any of the following forms,
all optionally followed by visible:
above Use the item one row above in this column.
below Use the item one row below in this column.
bottom Use the item in the last row of this column.
child n
Use the nth child of the item.
firstchild
Use the first child of the item.
lastchild
Use the last child of the item.
left Use the item one column to the left in the same row.
leftmost
Use the item of the first column in the same row.
next Use the next item, which is the first existant (or visible) item
of the following list: the first child, the next sibling or the
next sibling of the nearest parent which has one.
nextsibling
Use the next sibling of the item.
parent Use the parent of the item.
prev Use the last child of the previous sibling, or the parent if
there is no previos sibling.
prevsibling
Use the previous sibling of the item.
right Use the item one column to the right in the same row.
rightmost
Use the item of the last column in the same row.
sibling n
Use the nth child of the item's parent.
top Use the item in the first row of this column.
EVENTS AND SCRIPT SUBSTITUTIONS
Beside of all the normal Tk events, which are generated as reaction of
e.g. mouse movements or key presses, the treectrl widget generates at
various places events created by treectrl widget:
<ActiveItem>
Generated without detail whenever the active item changes.
<Collapse>
Generated with the detail after or before, whenever an item is
collapsed.
<Expand>
Generated with the detail after or before, whenever an item is
expanded.
<Scroll>
Generated with the detail x or y, whenever the origin of the
window changes.
<Selection>
Generated without detail whenever the selection changes.
By means of the notify bind widget command Tcl scripts can be speci-
fied, which will be executed whenever the event triggers. The command
will be executed in the same interpreter that the notify bind command
was executed in, and it will run at global level (only global variables
will be accessible). If the script contains any % characters, then the
script will not be executed directly. Instead, a new script will be
generated by replacing each %, and the character following it, with
information from the current event. The replacement depends on the
character following the %, as defined in the list below. Unless other-
wise indicated, Some of the substitutions are only valid for certain
types of events; if they are used for other types of events the value
substituted is undefined.
%% Replaced with a single percent.
%c Replaced with the number of items that are currently selected
for a selection event, or with the numerical id of the item,
which will become the active item for an activation event,
invalid for other event types.
%d Replaced with the detail of the event, or with the empty string
if the event has no detail. Valid for all event types.
%D Replaced with a (possibly empty) list of item ids; all mentioned
items will be removed from the selection. Valid only for selec-
tion events.
%e Replaced with the name of the event. Valid for all event types.
%I Replaced with the numerical id of the item, which is to be col-
lapsed or expanded. Valid only for collapse or expand events.
%l Replaced with the lower bound, i.e. the first fraction as
returned by the widget command xview for horizontal scrolling or
yview for vertical scrolling. Valid only for scrolling events.
%p Replaced with the numerical id of the item, which was the
active item upto now. Valid only for activation events.
%S Replaced with a (possibly empty) list of item ids; all mentioned
items will be added to the selection. Valid only for selection
events.
%T Replaced with the path name of the treectrl widget. Valid for
all event types.
%u Replaced with the upper bound, i.e. the second fraction returned
by the widget command xview for horizontal scrolling or yview
for vertical scrolling. Valid only for scrolling events.
%W Replaced with the name of the object the event is bound for.
This can be a widget path (then the string starts with .), or a
generic tag. Valid for all event types.
DEFAULT BINDINGS
Tk automatically creates class bindings for treectrls that give them
the following default behavior.
[1] Clicking mouse button 1 over an item positions the active cursor
on the item, sets the input focus to this widget, and resets the
selection of the widget to this item, if it is not already in
the selection.
[2] Clicking mouse button 1 with the Control key down will reposi-
tion the active cursor and add the item to the selection without
ever removing any items from the selection.
[3] If the mouse is dragged out of the widget while button 1 is
pressed, the treectrl will automatically scroll to make more
items visible (if there are more items off-screen on the side
where the mouse left the window).
[4] The Left and Right keys move the active cursor one item to the
left or right; for an hierarchical tree with vertical orienta-
tion nothing will happen, since it has no two items in the same
row. The selection is set to include only the active item. If
Left or Right is typed with the Shift key down, then the active
cursor moves and the selection is extended to include the new
item.
[5] The Up and Down keys move the active cursor one item up or down.
The selection is set to include only the active item. If Up or
Down is typed with the Shift key down, then the active cursor
moves and the selection is extended to include the new item.
[6] The Next and Prior keys move the active cursor forward or back-
wards by one screenful, without affecting the selection.
[7] Control-Next and Control-Prior scroll the view right or left by
one page without moving the active cursor or affecting the
selection. Control-Left and Control-Right behave the same.
[8] The Home and End keys scroll to the left or right end of the
widget without moving the active cursor or affecting the selec-
tion.
[9] The Control-Home and Control-End keys scroll to the top or bot-
tom of the widget, they also activate and select the first or
last item. If also the Shift key is down, then the active cur-
sor moves and the selection is extended to include the new item.
[10] The Space and Select keys set the selection to the active item.
[11] Control-/ selects the entire contents of the widget.
[12] Control-\ clears any selection in the widget.
[13] The + and - keys expand or collapse the active item, the Return
key toggles the active item.
[14] The mousewheel scrolls the view of the widget four lines up or
down depending on the direction, the wheel was turned. The
active cursor or the selection is not affected.
SEE ALSO
listbox(n), image(n), bitmap(n), bind(n), options(n)
KEYWORDS
tree, widget
treectrl 1.0 treectrl(n)
Mac OS X 10.5 - Generated Sun Oct 28 21:51:11 EDT 2007