path: root/doc/treectrl.man

[comment {Copyright (c) 2002-2003 Christian Krone.

  See the file "license.terms" for information on usage and redistribution
  of this file, and for a DISCLAIMER OF ALL WARRANTIES.

  $Id: treectrl.man,v 1.12 2005/03/29 21:20:41 treectrl Exp $}
][manpage_begin treectrl n 1.1]
[moddesc {Tk Commands}]
[titledesc {Create and manipulate hierarchical multicolumn widgets}]
[require treectrl 1.1]

[description]
[list_begin definitions] 
[call [cmd treectrl] [arg pathName] [opt [arg options]]]
[list_end]

[para]
The [cmd treectrl] command creates a new window (given by the
[arg pathName] argument) 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 [cmd treectrl] command returns the
path name of the new window.
At the time this command is invoked, there must not
exist a window named [arg pathName], but [arg pathName]'s parent must exist.

[para]
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.

[para]
Normally the origin of the coordinate system is at the
upper-left corner of the window containing the treectrl.
It is possible to adjust the origin of the coordinate system
relative to the origin of the window using the
[cmd xview] and [cmd yview] widget commands;
this is typically used for scrolling.

[para]
A treectrl widget can be horizontal or vertical oriented
like many other Tk widgets.
For displaying hierarchical data only vertical orientation is useful,
since only then the children of an item
are displayed 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.

[section {STANDARD OPTIONS}]
[list_begin opt]
[opt_def [option -background]]
[opt_def [option -borderwidth]]
[opt_def [option -cursor]]
[opt_def [option -font]]
[opt_def [option -highlightbackground]]
[opt_def [option -highlightcolor]]
[opt_def [option -highlightthickness]]
[opt_def [option -orient]]
[opt_def [option -relief]]
[opt_def [option -takefocus]]
[opt_def [option -xscrollcommand]]
[opt_def [option -yscrollcommand]]
[opt_def [option -foreground]]
[list_end]
See the [cmd option] manual entry for details on the standard options.

[section {WIDGET SPECIFIC OPTIONS}]
[list_begin tkoption]
[tkoption_def -backgroundimage backgroundImage BackgroundImage]
Specifies the name of an image to draw as the list background. The image is
tiled horizontally and vertically to fill the content area of the list. If
the image is transparent it is drawn on top of the background color(s).

[tkoption_def -backgroundmode backgroundMode BackgroundMode]
Specifies the desired mode for changing the background of individual items.
The value should be one of [const row], [const column], [const index],
or [const visindex]. The default is [const row].
This option has only an effect
for columns which have [option -itembackground] defined as list of two or more
colors (see section [sectref COLUMNS] below for more on this). The color
of items is changed for any row or column, if [const row] or [const column]
is specified respectively. When [const index] is specified, collapsed
items are counted also for evaluating the background color,
for [const visindex] only the visible items are counted.

[tkoption_def -buttoncolor buttonColor 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.

[tkoption_def -buttonsize buttonSize ButtonSize]
Specifies the diameter of the button drawn to the left of an item
in any of the forms acceptable to [fun Tk_GetPixels].

[tkoption_def -buttonthickness buttonThickness 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 [fun Tk_GetPixels].

[tkoption_def -closedbuttonbitmap closedButtonBitmap ClosedButtonBitmap]
Specifies the bitmap to be used as the button to the left of a closed item
in any of the forms acceptable to [fun Tk_GetPixels].

[tkoption_def -closedbuttonimage closedButtonImage ClosedButtonImage]
Specifies the image to be used as the button to the left of a closed item
in any of the forms acceptable to [fun Tk_GetImage].

[tkoption_def -columnproxy columnProxy ColumnProxy]
If this option specifies a non empty value,
it should be a screen distance
in any of the forms acceptable to [fun Tk_GetPixels].
Then a 1 pixel thick vertical line will be drawn
at the specified 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.

[tkoption_def -defaultstyle defaultStyle DefaultStyle]
Specifies a list of styles, one per column, to apply to each item created by
the [cmd "item create"] command. The number of styles in the list can be
different from the number of tree columns.
Each list element should be a valid style name or an empty string to
indicate no style should be applied to a specific column. The list of styles
is updated if a style is deleted or if a column is moved.

[tkoption_def -doublebuffer doubleBuffer DoubleBuffer]
Specifies if double-buffering should be used to improve displaying.
The value should be one of [const none], [const window], or [const item].
For [const none] no double-buffering is used at all, which may be most memory
efficient, but will probably generate some flickering on the screen.
For [const window] the complete tree is double-buffered, which requires
a buffer big enough to contain the complete widget.
For [const item], which is the default, every item is separately
double-buffered, so it works with a buffer size as big as the biggest item.

[tkoption_def -height height Height]
Specifies the desired height for the window
in any of the forms acceptable to [fun 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.

[tkoption_def -indent indent Indent]
Specifies the amount of indentation
in any of the forms acceptable to [fun Tk_GetPixels].
The default is 19 pixel.
Indentation is the screen distance an item is displayed more to
the right than its father.

[tkoption_def -itemheight itemHeight ItemHeight]
Specifies a fixed height for every item
in any of the forms acceptable to [fun Tk_GetPixels].
The default is 0, which means that
every item has the height requested by the arrangement of elements
in each column.

[tkoption_def -linecolor lineColor LineColor]
Specifies the color which should be used for drawing
the connecting lines between related items.

[tkoption_def -linestyle lineStyle LineStyle]
Specifies the style of the connecting lines between related items,
should be [const dot] which is the default, or [const solid].

[tkoption_def -linethickness lineThickness LineThickness]
Specifies the thickness of the connecting lines between related items
in any of the forms acceptable to [fun Tk_GetPixels].

[tkoption_def -openbuttonbitmap openButtonBitmap OpenButtonBitmap]
Specifies the bitmap to be used as the button to the left of an opened item
in any of the forms acceptable to [fun Tk_GetBitmap].

[tkoption_def -openbuttonimage openButtonImage OpenButtonImage]
Specifies the image to be used as the button to the left of an opened item
in any of the forms acceptable to [fun Tk_GetImage].

[tkoption_def -scrollmargin scrollMargin ScrollMargin]
The interpretation of this option is left to Tcl scripts
that implement scrolling:
the  widget implementation ignores this option entirely.
Defaults to 0.

[tkoption_def -selectmode selectMode SelectMode]
Specifies one of several styles for manipulating the selection.
The value of the option may be arbitrary, but the default bindings
expect it to be either [const single], [const browse], [const multiple],
or [const extended];  the default value is [const browse].

[tkoption_def -showbuttons showButtons 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 [cmd {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.

[tkoption_def -showheader showHeader 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.

[tkoption_def -showlines showLines ShowLines]
Specifies a boolean value that determines whether this widget
should draw the connecting lines between related items.
The default value is true.

[tkoption_def -showroot showRoot 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 [emph toplevel] items.
The default value is true.

[tkoption_def -showrootbutton showRootButton ShowRootButton]
Specifies a boolean value that determines whether this widget
should draw a button before the root item.
The default value is false.

[tkoption_def -showrootlines showRootLines ShowRootLines]
Specifies a boolean value that determines whether this widget
should draw the connecting lines between children of the root item.
The default value is true.

[tkoption_def -treecolumn treeColumn 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.

[tkoption_def -width width Width]
Specifies the desired width for the window
in any of the forms acceptable to [fun 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.

[tkoption_def -wrap wrap Wrap]
Specifies how to arrange items inside treectrl's window.
The value must be an empty string, [const window],
or a list with an integer as first element
and either [const items] or [const 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 [const window] mode a screen line break may occur after any element;
in [const items] mode a line break will only be made after the specified
number of items;
in [const pixels] mode a line break will only be made after the
specified screen distance is reached.

[tkoption_def -xscrolldelay xScrollDelay 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 1 or 2 integers.
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 miliseconds is elapsed.

[tkoption_def -xscrollincrement xScrollIncrement 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 [option -xscrollincrement];  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 [option -xscrollincrement].  If the value of
this option is less than or equal to zero, then horizontal scrolling
is unconstrained.

[tkoption_def -yscrolldelay yScrollDelay 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 1 or 2 integers.
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 miliseconds is elapsed.

[tkoption_def -yscrollincrement yScrollIncrement 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 window will be constrained so that
the y coordinate at the top edge of the window is always an even
multiple of [option -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 [option -yscrollincrement].  If the value of
this option is less than or equal to zero, then vertical scrolling
is unconstrained.
[list_end]

[section {WIDGET COMMAND}]
The [cmd 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:

[para]
[arg pathName] [arg option] [opt [arg {arg arg ...}]]

[para]
[arg PathName] is the name of the command, which is the same as
the treectrl widget's path name.  [arg Option] and the [arg arg]s
determine the exact behavior of the command.  The following
commands are possible for treectrl widgets:

[list_begin definitions]

[call [arg pathName] [cmd activate] [arg itemDesc]]
Sets the active item to the one described by [arg itemDesc],
and switches on the state [const active] for this item.
From now on the item can be retrieved with the item description [const active].
An [const <ActiveItem>] event is generated.

[call [arg pathName] [cmd canvasx] [arg screenx]]
Given a window x-coordinate in the treectrl [arg screenx],
this command returns the treectrl x-coordinate
that is displayed at that location.

[call [arg pathName] [cmd canvasy] [arg screeny]]
Given a window y-coordinate in the treectrl [arg screeny],
this command returns the treectrl y-coordinate
that is displayed at that location.

[call [arg pathName] [cmd cget] [arg option]]
Returns the current value of the configuration option given
by [arg option].
[arg Option] may have any of the values accepted by the [cmd tree]
command.

[call [arg pathName] [cmd collapse] [opt [option -recurse]] \
     [opt [arg {itemDesc ...}]]]
Use [cmd {item collapse}] instead.

[call [arg pathName] [cmd column] [arg option] [arg column] \
     [opt [arg {arg ...}]]]
This command is used to manipulate the columns of the treectrl widget
(see section [sectref COLUMNS] below).
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd column] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {column bbox}] [arg column]]
Returns a list with four elements giving an approximate bounding box
for the column header specified by [arg column].
If the treectrl is configured to don't display the column headers
by means of the [option -showheader] option,
an empty list is returned instead.

[call [arg pathName] [cmd {column cget}] [arg column] [arg option]]
This command returns the current value of the option named [arg option]
for the column specified by [arg column],
[arg Column] may also be the string [const tail] to specify the tail column.
[arg Option] may have any of the values accepted by the
[cmd {column configure}] widget command.

[call [arg pathName] [cmd {column configure}] [arg column] \
     [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies options associated with the column specified by [arg column]
instead of modifying options for the overall treectrl widget.
[arg Column] may also be the string [const tail] to specify the tail column.
If no [arg option] is specified, the command returns a list describing
all of the available options for [arg column] (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given option(s) to have the given value(s) for [arg column];
in this case the command returns an empty string.
[nl]

See [sectref COLUMNS] below for details on the options available for columns.

[call [arg pathName] [cmd {column create}] [opt [arg {option value ...}]]]
This command creates a new column in the treectrl widget. The new column is
placed to the right of all other columns (except the [const tail] column). Any
[arg option]-[arg value] arguments configure the new column according to the
[cmd "column configure"] command. The return value is the zero-based index
of the new column.

[call [arg pathName] [cmd {column delete}] [arg column]]
Deletes the specified [arg 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.

[call [arg pathName] [cmd {column index}] [arg column]]
This command returns a decimal string giving the column number
of the column specified by [arg column],
which may also be the string [const tail] to specify the tail column.

[call [arg pathName] [cmd {column move}] [arg column] [arg before]]
Moves the specified [arg column] to the left of the column
specified by [arg before].
If [arg before] is the string [const tail],
the column [arg column] will become the last column.

[call [arg pathName] [cmd {column neededwidth}] [arg column]]
This command returns a decimal string giving the needed width
of the column specified by [arg column].
The needed width is the maximum of the width of the column header
and the width of the [emph widest] currently visible item.

[call [arg pathName] [cmd {column width}] [arg column]]
This command returns a decimal string giving the width in pixels
of the column specified by [arg column],
even if the treectrl is configured to not display the column headers
by means of the [option -showheader] option.
[list_end]

[call [arg pathName] [cmd compare] [arg itemDesc1] [arg op] [arg itemDesc2]]
From both items described by the [arg itemDesc]s the index is retrieved
(as returned from the [cmd {item index}] widget command).
Then these indexes are compared using the operator [arg op], which must
be either [const <],  [const <=],  [const ==], [const >=], [const >],
or [const !=].
The return value of this command is 1 if the comparison evaulated to true,
0 otherwise.

[call [arg pathName] [cmd configure] [opt [arg option]] \
     [opt [arg {value option value ...}]]]
Query or modify the configuration options of the widget.
If no [arg option] is specified, returns a list describing all of
the available options for [arg pathName] (see [fun Tk_ConfigureInfo] for
information on the format of this list).  If [arg option] is specified
with no [arg 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 [arg option] is specified).  If
one or more [arg option]-[arg 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.
[arg Option] may have any of the values accepted by the [cmd treectrl]
command.

[call [arg pathName] [cmd 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.

[call [arg pathName] [cmd debug] [arg option] [opt [arg {arg arg ...}]]]
This command is used to facilitate debugging of the treectrl widget.
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd debug] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {debug cget}] [arg element] [arg option]]
This command returns the current value of the debugging option
named [arg option].
[arg Option] may have any of the values accepted by the
[cmd {debug configure}] widget command.

[call [arg pathName] [cmd {debug configure}] [arg element] \
     [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies debugging options
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list describing
all of the available debugging options (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg 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.
[nl]

The following debugging options are supported:
[list_begin opt]
[opt_def [option -displaydelay] [arg 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 [option -enable] and [option -display] are switched on.

[opt_def [option -data] [arg boolean]]
If this option is switched on
(together with the debugging option [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 number of child items).
If an inconsistency was found, a Tcl background error is raised.

[opt_def [option -display] [arg boolean]]
If this option is switched on
(together with the debugging option [option -enable]),
at varios places additional debugging output is printed to stdout.

[opt_def [option -enable] [arg boolean]]
All other debugging options only take effect,
if this option is also switched on.

[opt_def [option -erasecolor] [arg color]]
Use this color, when parts of the treectrl widget should be deleted.
If you use an unusual color for this option (like [const pink]),
superflous screen redraws can be spotted more easily.
Setting this option has only an effect, if the
debugging options [option -enable] and [option -display] are switched on.
[list_end]

[call [arg pathName] [cmd {debug dinfo}]]
For every of the treectrl widget
a line with some internal valuess info about all items
is printed to stdout.
The command returns the empty string.

[call [arg pathName] [cmd {debug scroll}]]
Returns a string useful for debugging vertical scrolling.
[list_end]

[call [arg pathName] [cmd depth] [opt [arg itemDesc]]]
If the additional argument [arg itemDesc] is specified,
returns a decimal string giving the depth of
the item describing by [arg itemDesc], whereas depth is defined as
the number of steps you must go upward to reach to root item.
If no [arg itemDesc] is specified, the maximum depth of all
items in the treectrl widget is returned instead.

[call [arg pathName] [cmd dragimage] [arg option] [opt [arg {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 [arg option] argument
that follows the [cmd dragimage] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {dragimage add}] [arg itemDesc] \
     [opt [arg column]] [opt [arg element]]]
Adds the shapes of the item described by [arg 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 rectangles is added.
If [arg column] is specified, all elements in other columns are ignored.
If also [arg element] is specified, only a rectangle for this one element
of the specified item in the given column is added.

[call [arg pathName] [cmd {dragimage cget}] [arg option]]
This command returns the current value of the dragimage option
named [arg option].
[arg Option] may have any of the values accepted by the
[cmd {dragimage configure}] widget command.

[call [arg pathName] [cmd {dragimage clear}]]
Removes all shapes (if there are any) from the dragimage.
This command does not modify the dragimage offset.

[call [arg pathName] [cmd {dragimage configure}] [opt [arg option]] \
     [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies the dragimage options
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list describing
all of the available dragimage options (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given dragimage option(s) to have the given value(s);
in this case the command returns an empty string.
[nl]

The following dragimage options are supported:

[list_begin opt]
[opt_def [option -visible] [arg boolean]]
Specifies a boolean value which determines
whether the dragimage should currently be visible.
[list_end]

[call [arg pathName] [cmd {dragimage offset}] [opt [arg {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 offset to the given coordinates [arg x] and [arg y].

[list_end]

[call [arg pathName] [cmd element] [arg option] [opt [arg element]] \
     [opt [arg {arg arg ...}]]]
This command is used to manipulate elements (see [sectref ELEMENTS] below).
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd element] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {element cget}] [arg element] [arg option]]
This command returns the current value of the option named [arg option]
associated with the element given by [arg element].
[arg Option] may have any of the values accepted by the
[cmd {element configure}] widget command.

[call [arg pathName] [cmd {element configure}] [arg element] \
     [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies options associated with the element given by [arg element]
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list describing
all of the available options for [arg element] (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given option(s) to have the given value(s) in [arg element];
in this case the command returns an empty string.
See [sectref ELEMENTS] below for details on the options available for elements.

[call [arg pathName] [cmd {element create}] [arg element] [arg type] \
     [opt [arg {option value ...}]]]
Create a new elememt in [arg pathName] of type [arg type]
with name [arg element].
The exact format of the arguments after [arg type] depends on [arg 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.

[call [arg pathName] [cmd {element delete}] [opt [arg {element ...}]]]
Deletes each of the named elements and returns an empty string.
If an element is deleted while it is still configured
as an element of one or more styles
by means of the [cmd {style elements}] widget command,
it is also removed from the element lists of these styles.

[call [arg pathName] [cmd {element names}]]
Returns a list containing the names of all existing elements.

[call [arg pathName] [cmd {element type}] [arg element]]
Returns the type of the elements given by [arg element],
such as [const rect] or [const text].
[list_end]

[call [arg pathName] [cmd expand] [opt [option -recurse]] \
     [opt [arg {itemDesc ...}]]]
Use [cmd {item expand}] instead.

[call [arg pathName] [cmd identify] [arg x] [arg y]]
Returns a list containing some diagnostics about what
is displayed at the given windows coordinates [arg x] and [arg y].
The resulting list may be empty,
if nothing is displayed at the given coordinates,
otherwise the first list element is [const header] or [const item].
[nl]

If the coordinates are in the header area
and thus the first element of the result is [const header],
the number of the column or the string [const 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 [const left] or [const right] is added respectively.
[nl]

If the coordinates are below the header area
and thus the first element of the result is [const 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 structure,
the elements [const column] and the column number are added.
If the x coordinate is within the column
displaying the hierarchical structure,
the following elements are added to the resulting list:
[const line] and the numerical id of the item the line comes from,
if the x coordinate is above an item connecting line;
[const button], if the x coordinate is above a button;
[const column], the column number, [const elem], and the element name,
if the x coordinate is above an element of the item;
[const column] and the column number,
if the x coordinate is to the right of the elements;
nothing otherwise.

[call [arg pathName] [cmd index] [arg itemDesc]]
This command returns a decimal string giving the numerical id
of the item specified by [arg itemDesc]
(see [sectref {ITEM DESCRIPTION}] below).

[call [arg pathName] [cmd item] [arg option] [opt [arg {arg ...}]]]
This command is used to manipulate items.
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd item] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {item ancestors}] [arg itemDesc]]
Returns a list containing the numerical indexes of all ancestors
of the item specified by [arg itemDesc] from its parent up to the
root item.

[call [arg pathName] [cmd {item bbox}] [arg itemDesc] [opt [arg column]] \
     [opt [arg element]]]
Returns a list with four elements giving an approximate bounding box
for the item described by [arg itemDesc].
If no further argument is specified, the bbox spans the area of the item
over all columns. If a [arg column] is specified, only the area of the item
in this column is considered, if an additional [arg element] is specified,
the area of this [arg element] in [arg column] of the specified item is
returned.

[call [arg pathName] [cmd {item cget}] [arg itemDesc] [arg option]]
Returns the current value of the configuration option for the item specified by
[arg itemDesc] whose name is [arg option]. [arg Option] may have any of the
values accepted by the [cmd "item create"] command when the item was created.

[call [arg pathName] [cmd {item children}] [arg itemDesc]]
Returns a list containing the numerical indexes of all children
of the item specified by [arg itemDesc] in the correct order from
the first child to the last child.

[call [arg pathName] [cmd {item collapse}] [arg itemDesc] [opt [option -recurse]]]
Switches off the [const open] state of the item(s)
described by [arg itemDesc].
If the item has descendants, they are no longer displayed.
If the item is configured to have a button,
the button will now display the image or bitmap configured with the
widget options [option -closedbuttonimage] or [option -closedbuttonbitmap],
or a [emph +] sign if no image or bitmap is configured.
If the item is already closed, this command has no effect.
[arg ItemDesc] may also be the string [const all],
in which case all items of the treectrl widget are collapsed.
If [option -recurse] is specified, all descendants of [arg itemDesc]
will also be collapsed.
For every item, that actually will be collapsed,
two events are generated:
a [const <Collapse-before>] event before the item state is changed,
and a [const <Collapse-after>] event after the item state was changed.

[call [arg pathName] [cmd {item complex}] [arg itemDesc] [arg list] [arg ...]]
Modifies the elements of the item described by [arg itemDesc].
For every column of the treectrl there may be specified one [arg list],
which in turn is an odd elemented list with at least three elements:
the name of an element followed by [arg option]-[arg value] pairs.
Every [arg option] must be known by the element's type
(see [sectref ELEMENTS] below).
The corresponding [arg value] will overwrite the value of the element for this
one column in this item.

[call [arg pathName] [cmd {item configure}] [arg itemDesc] [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]]
If no [arg option] is specified, returns a list describing all of the available
options for the item given by [arg itemDesc] (see [fun Tk_ConfigureInfo] for
information on the format of this list). If [arg 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 [arg option] is specified). If one or more [arg option]-[arg 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. The options
and values are the same as those permissible in the [cmd "item create"] command
when the item was created.

[call [arg pathName] [cmd {item create}] [opt [arg {option value ...}]]]
Creates a new item and returns its unique identifier.
The new item has the states [const open] and [const enabled] set by default.
If the treectrl widget currently has the focus,
the state [const focus] is also set. Each [arg option]-[arg value] pair sets one
of the configuration options for the item. These same [arg option]-[arg value]
pairs may be used in the [cmd "item configure"] command to change the item's
configuration.
[nl]
The following options are supported by items:

[list_begin opt]

[opt_def [option -button] [arg boolean]]
[arg Boolean] must have one of the forms accepted by [fun Tk_GetBoolean]. It
indicates whether or not an expand/collapse button should be drawn next to this
item, typically to indicate the item has children. The button will only be
displayed if:
a) the column specified by the widget option [option -treecolumn] is visible;
and b) the widget option [option -showbuttons] is true

[opt_def [option -visible] [arg boolean]]
[arg Boolean] must have one of the forms accepted by [fun Tk_GetBoolean]. It
indicates that the item should be displayed in the list. The item will only be
displayed if:
a) each ancestor is a descendant of the root item (not an orphan);
and b) each ancestor's [option -visible] option is true 

[list_end]

[call [arg pathName] [cmd {item delete}] [arg first] [opt [arg last]]]
Deletes the specified item(s).
[arg First] and [arg last] must be the string [const all] or an [arg itemDesc].
If either [arg first] or [arg last] is specified as [const all], all items are
deleted; if [arg first] is specified as [arg itemDesc] and [arg last] isn't
specified, the item described by [arg first] is deleted.
If both [arg first] and [arg last] are specified,
they must decribe items with a common ancestor;
then the range of items between [arg first] and [arg last] is deleted.
[nl]
Deleting an item deletes any child items of the deleted item recursively.
If the current [const active] item is deleted, the root item becomes the new active item.
If the current selection [const anchor] item is deleted, the root item becomes the new anchor item.
There is no way to delete the root item of the treectrl widget;
in all cases the specification of the root item is ignored.

[call [arg pathName] [cmd {item dump}] [arg itemDesc]]
Returns a list with six elements in the form
[const index] [emph index] [const indexVis] [emph indexVis]
[const neededHeight] [emph neededHeight].

[call [arg pathName] [cmd {item element}] [arg command] [arg itemDesc] \
     [arg column] [arg element] [opt [arg {arg ...}]]]
This command is used to manipulate elements of the item.
The exact behavior of the command depends on the [arg command] argument
that follows the [cmd element] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {item element actual}] [arg itemDesc] [arg column] \
     [arg element] [arg option]]
This command returns the current value of the configuration option named [arg option]
associated with [arg element] inside [arg column] of the item described by
[arg itemDesc]. If [arg option] was configured using the
[cmd "item element configure"] command, the
return value is the same as if the [cmd {item element cget}] command
was used. Otherwise the value of the configuration option of the underlying element is returned.
[arg Option] may have any of the values accepted by the type of the
specified element (see [sectref ELEMENTS] below)

[call [arg pathName] [cmd {item element cget}] [arg itemDesc] [arg column] \
     [arg element] [arg option]]
This command returns the value of the option named [arg option]
associated with [arg element] inside [arg column] of the item described by
[arg itemDesc], if it was already configured for the actual item.
[arg Option] may have any of the values accepted by the type of the
specified element (see [sectref ELEMENTS] below)

[call [arg pathName] [cmd {item element configure}] [arg itemDesc] \
     [arg column] [arg element] [opt [arg option]] [opt [arg value]] \
     [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies options associated with
[arg element] inside [arg column] of the item described by [arg itemDesc]
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list describing
all of the available options for the element (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given option(s) to have the given value(s) in the
[arg element] inside [arg column] of the item described by [arg itemDesc];
in this case the command returns an empty string.
[list_end]

[call [arg pathName] [cmd {item expand}] [arg itemDesc] [opt [option -recurse]]]
Switches on the [const open] state of the item(s) described by [arg 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 [option -openbuttonimage] or [option -openbuttonbitmap],
or a [emph -] sign if no image or bitmap is configured.
If the item is already open, this command has no effect.
[arg ItemDesc] may also be the string [const all],
in which case all items of the treectrl widget are expanded.
If [option -recurse] is specified, all descendants of [arg itemDesc]
will also be expanded.
For every item, that actually will be expanded,
two events are generated:
an [const <Expand-before>] event before the item state is changed,
and an [const <Expand-after>] event after the item state was changed.

[call [arg pathName] [cmd {item firstchild}] [arg parent] [opt [arg child]]]
If [arg child] is not specified, returns the numerical index of the first
child of the item described by [arg parent].
If [arg child] is specified, it must described an item
that is not an ancestor of [arg parent].
Then it will become the new first child of [arg parent].

[call [arg pathName] [cmd {item index}] [arg itemDesc]]
Returns a list of two integers, which corresponds to the row 
of the item described by [arg itemDesc],
if all items above are counted and if only the displayed items are counted.
This command should not be confused with the [cmd index] widget command,
which return the invariable item id.
The index here is basically the row of the item.

[call [arg pathName] [cmd {item isancestor}] [arg itemDesc] [arg descendant]]
Returns 1 if the item described by [arg itemDesc] is a direct or indirect
parent of the item decribed by [arg descendant], 0 otherwise.

[call [arg pathName] [cmd {item isopen}] [arg itemDesc]]
Returns 1, if the item described by [arg itemDesc] has cuurently the
state [const open] switched on, 0 otherwise.

[call [arg pathName] [cmd {item lastchild}] [arg parent] [opt [arg child]]]
If [arg child] is not specified, returns the numerical index of the last
child of the item described by [arg parent].
If [arg child] is specified, it must described an item
that is not an ancestor of [arg parent].
Then it will become the new last child of [arg parent].

[call [arg pathName] [cmd {item nextsibling}] [arg sibling] [opt [arg next]]]
If [arg next] is not specified, returns the numerical index of the next
sibling of the item described by [arg sibling].
If [arg next] is specified, it must described an item
that is not an ancestor of [arg sibling].
Then it will become the new next sibling of [arg sibling].

[call [arg pathName] [cmd {item numchildren}] [arg itemDesc]]
Returns the number of children of the item described by [arg itemDesc].

[call [arg pathName] [cmd {item parent}] [arg itemDesc]]
Returns the numerical index of the parent of the item
described by [arg itemDesc].

[call [arg pathName] [cmd {item prevsibling}] [arg sibling] [opt [arg prev]]]
If [arg prev] is not specified, returns the numerical index of the previous
sibling of the item described by [arg sibling].
If [arg prev] is specified, it must described an item
that is not an ancestor of [arg sibling].
Then it will become the new previous sibling of [arg sibling].

[call [arg pathName] [cmd {item remove}] [arg itemDesc]]
Removes the item described by [arg itemDesc]
from the children list of its father, so that it will become an orphan.

[call [arg pathName] [cmd {item rnc}] [arg itemDesc]]
Returns a list of two integers, which corresponds to the row and column
of the item described by [arg itemDesc].

[call [arg pathName] [cmd {item sort}] [arg itemDesc] [opt [arg {option ...}]]]
Sorts the children of the item described by [arg itemDesc],
and redisplays the tree with the items in the new order.
[nl]

The range of items which should be sorted can be restricted
by means of the [option -first] and/or [option -last] options,
which should be children of the item described by [arg itemDesc];
the order between these two limiting items doesn't matter.
[nl]

The sort column can be specified by means of the [option -column] option;
this option can be used repeatedly to define a multi column sort.
The sorting is done by looking at the [arg text]
of the element specified by the [option -element] option,
which must be a text element defined in the style of the sorting column,
by default the first text element is used.
[nl]

If the [option -notreally] option is specified,
no rearranging of the items is done;
instead the sorted items are returned as result of the command.
[nl]

By default ASCII sorting is used with the result returned in increasing order.
Any of the following options may be specified to control
the sorting process of the previously specified column
(unique abbreviations are accepted):

[list_begin opt]
[opt_def [option -ascii]]
Use string comparison with ASCII collation order. This is the default.

[opt_def [option -command] [arg command]]
Use [arg command] as a comparison command.
To compare two items, evaluate a Tcl script consisting of
[arg 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 considered less than, equal to, or greater than the second,
respectively.

[opt_def [option -decreasing]]
Sort the items in decreasing order ("largest" items first).

[opt_def [option -dictionary]]
Use dictionary-style comparison. This is the same as [option -ascii]
except (a) case is ignored except as a tie-breaker and (b) if two
strings contain embedded numbers, the numbers compare as integers,
not characters.  For example, in [option -dictionary] mode, [term bigBoy]
sorts between [term bigbang] and [term bigboy], and [term x10y]
sorts between [term x9y] and [term x11y].

[opt_def [option -increasing]]
Sort the items in increasing order ("smallest" items first). This is the default.

[opt_def [option -integer]]
Convert to integers and use integer comparison.

[opt_def [option -real]]
Convert to floating-point values and use floating comparison.
[list_end]

[call [arg pathName] [cmd {item state}] [arg command] [arg itemDesc] \
     [opt [arg {arg ...}]]]
This command is used to manipulate the states of an item.
The exact behavior of the command depends on the [arg command] argument
that follows the [cmd style] argument.
The following forms of the command are supported:

[list_begin definitions]

[call [arg pathName] [cmd {item state forcolumn}] [arg itemDesc] [arg column] \
     [opt [arg stateDescList]]]
Just like [cmd {item state set}] but manipulates user-defined states for a single
item column, not the item as a whole.

[call [arg pathName] [cmd {item state get}] [arg itemDesc] \
     [opt [arg {stateName ...}]]]
If no [arg 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 [arg itemDesc].
If a [arg stateName] is specified,
1 is returned if the specified state is currently switched on for the item,
0 otherwise.

[call [arg pathName] [cmd {item state set}] [arg itemDesc] \
     [opt [arg lastItem]] [opt [arg stateDescList]]]
Every element of [arg stateDescList]
must describe a user defined state (see [sectref STATES] below),
with the particularity that the state name may have also a leading [const ~].
Every state with a leading [const !] will be switched off for the
item described by [arg itemDesc],
every state with a leading [const ~] will be toggled, and
every state without leading [const !] or [const ~] will be switched on.
If [arg lastItem] is specified, the state changes will be made for all items
in the range betwen [arg itemDesc] and [arg lastItem].
[arg ItemDesc] may be the string [const all],
then the state changes are made for all items of the treectrl widget.

[list_end]

[call [arg pathName] [cmd {item style}] [arg command] [arg itemDesc] \
     [opt [arg {arg ...}]]]
This command is used to manipulate the styles of an item.
The exact behavior of the command depends on the [arg command] argument
that follows the [cmd style] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {item style elements}] [arg itemDesc] [arg column]]
A list is returned
containing the currently defined elements of the style,
which is set for the item described by [arg itemDesc] in [arg column].

[call [arg pathName] [cmd {item style map}] [arg itemDesc] [arg column] \
     [arg style] [arg map]]
Like the [cmd "item style set"] command, this command may be used to assign a
style to a specific column of an item. Unlike [cmd "item style set"], this
command can transfer configuration values of elements in the current style
to elements in the new style specified by [arg style].

[arg Map] must be a list of [arg elementOld]-[arg elementNew] pairs, where
[arg elementOld] is an element in the current style, and [arg elementNew] is
an element in the style specified by [arg style]. Both [arg elementOld] and
[arg elementNew] must be of the same type ([const bitmap], [const text] etc).

[call [arg pathName] [cmd {item style set}] [arg itemDesc] [opt [arg column]] \
     [opt [arg style]] [opt [arg {column style ...}]]]
If no [arg column] is specified, returns a list containing the names of the
styles set for all columns of the item described by [arg itemDesc].
If no [arg style] argument is specified,
returns the name of the style set for the item described by
[arg itemDesc] in [arg column].
If there are one or more [arg style] arguments specified,
it must be [arg column]-[arg style] pairs;
then the style(s) of item in [arg column] will be set to [arg style].
[list_end]

[call [arg pathName] [cmd {item text}] [arg itemDesc] [arg column] \
     [opt [arg text]] [opt [arg {column text ...}]]]
If no [arg text] argument is specified,
returns the text of the first text element in [arg column] for the item
described by [arg itemDesc].
If there are one or more [arg text] arguments specified,
it must be [arg column]-[arg text] pairs;
then the text(s) of item in [arg column] will be set to [arg text]. Note that
this command is provided as a convenience. Use the
[cmd "item element configure"] command if you want to set the text of a
specific text element.

[call [arg pathName] [cmd {item toggle}] [arg itemDesc] [opt [option -recurse]]]
Changes the [const open] state of the item(s) described by [arg itemDesc].
If the state is currently switched off,
this command does the same as the [cmd {item expand}] widget command,
otherwise the same as the [cmd {item collapse}] widget command.
[arg ItemDesc] may also be the string [const all],
in which case the state of all items of the treectrl widget are toggled.
If [option -recurse] is specified, the state of all descendants of
[arg itemDesc] will also be toggled.

[list_end]

[call [arg pathName] [cmd marquee] [arg option] [opt [arg {arg ...}]]]
This command is used to manipulate the marquee,
a rectangular region of the treectrl widget
optionally marked with a surrounding dotted line.
One corner point of the marquee is fixed as long as the marquee is visible
and called the anchor; the diagonally opposite corner is dragged with the
mouse while resizing the marquee and simply called the corner.
All coordinates handled by this widget command are treectrl coordinates,
i.e. the [cmd canvasx] or [cmd canvasy] widget command should be
used before any window coordinates can be used.
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd marquee] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {marquee anchor}] [opt [arg {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 [arg x] and [arg y].

[call [arg pathName] [cmd {marquee cget}] [arg option]]
This command returns the current value of the marquee option
named [arg option].
[arg Option] may have any of the values accepted by the
[cmd {marquee configure}] widget command.

[call [arg pathName] [cmd {marquee configure}] [opt [arg option]] \
     [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies the marquee options
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list describing
all of the available marquee options (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given marquee option(s) to have the given value(s);
in this case the command returns an empty string.
[nl]

The following marquee options are supported:

[list_begin opt]
[opt_def [option -visible] [arg boolean]]
Specifies a boolean value which determines
whether the dotted line surrounding the region of the marquee
should currently be visible.
[list_end]

[call [arg pathName] [cmd {marquee coords}] [opt [arg {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 coordinates are specified,
sets the anchor to the given coordinates [arg x1] and [arg y1]
and the corner to the coordinates [arg x2] and [arg y2].

[call [arg pathName] [cmd {marquee corner}] [opt [arg {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 [arg x] and [arg y].

[call [arg pathName] [cmd {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.

[list_end]

[call [arg pathName] [cmd notify] [arg option] [opt [arg {arg ...}]]]
Many Tk widgets communicate with the outside world via [option -command]
callbacks and/or virtual events. For example, the Text widget
evaluates its [option -yscrollcommand] when the view in the widget changes,
and generates a <<Modified>> virtual event when text is inserted or deleted.
A treectrl widget replaces both methods of communication with its own event
mechanism accessed through the [cmd notify] subcommands.
[nl]

The exact behavior of the command depends on the [arg option] argument
that follows the [cmd notify] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {notify bind}] [opt [arg object]] \
     [opt [arg pattern]] [opt +][opt [arg script]]]
This command associates Tcl scripts with events generated by a
treectrl widget.

If all three arguments are specified, [cmd {notify bind}] will arrange for
[arg script] (a Tcl script) to be evaluated whenever the event(s) specified
by [arg pattern] are generated by this treectrl widget.

If [arg script] is prefixed with a "+", then it is appended to any existing
binding for [arg pattern];  otherwise [arg script] replaces any existing binding.

If [arg script] is an empty string then the current binding for [arg pattern]
is destroyed, leaving [arg pattern] unbound. In all of the cases where a script
argument is provided, [cmd {notify bind}] returns an empty string.
[nl]
If [arg pattern] is specified without a [arg script], then the script currently
bound to [arg pattern] is returned, or an empty string is returned if there is
no binding for [arg pattern]. If neither [arg pattern] nor [arg script] is
specified, then the return value is a list whose elements are all the patterns
for which there exist bindings for [arg object]. 
[nl]
The [arg object] argument determines which window(s) the binding applies to.
If [arg object] begins with a dot, as in .a.b.c, then it must be the path name
for a window; otherwise it may be an arbitrary string. Unlike the regular
[cmd bind] command, bindings on window names are not automatically removed if
that window is destroyed.

[call [arg pathName] [cmd {notify configure}] [arg object] \
     [arg pattern] [opt [arg option]] [opt [arg value]] \
     [opt [arg {option value ...}]]]
This command sets and retrieves options for bindings created by the
[cmd {notify bind}] command.
[nl]
If no [arg option] is specified, the command returns a list with
[arg option]-[arg value] pairs describing all
the available binding options for [arg pattern] on [arg object].
If [arg option] is specified with no [arg value],
then the command returns the current value of that option.
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given option(s) to have the given value(s) for the binding;
in this case the command returns an empty string.
[nl]

The following binding options are supported:
[list_begin opt]
[opt_def [option -active] [arg boolean]]
Specifies if the binding should be active.
As long as this option is specified as false,
a binding script will not be evaluated when the corresponding event is
generated.
[list_end]

[call [arg pathName] [cmd {notify detailnames}] [arg eventName]]
Returns a list containing the names of all details,
which are installed for the event with the name [arg eventName]
by means of the [cmd {notify install}] widget command
or by the treectrl widget itself.

[call [arg pathName] [cmd {notify eventnames}]]
Returns a list containing the names of all events,
which are installed by means of the [cmd {notify install}] widget command
or by the treectrl widget itself.

[call [arg pathName] [cmd {notify generate}] [arg pattern] \
	[opt [arg charMap]] [opt [arg percentsCommand]]]
This command causes the treectrl widget to generate an event. This command is
typically used to generate dynamic events created by the [cmd {notify install}]
command, but may be used to generate static events also.
The event specified by [arg pattern] is generated, and any active binding
scripts on the event are evaluated after undergoing %-substitution.
If there are details defined for the event,
[arg pattern] must describe an <[arg eventName]-[arg detail]> pair,
otherwise [arg pattern] should be <[arg eventName]>.
[nl]

The optional [arg charMap] is a list of [arg char]-[arg value] pairs
as in the form returned by [cmd {array get}].
Each [arg char] has to be exactly one character.
The [arg charMap] is used in %-substitution.
[nl]

If [arg percentsCommand] is specified, then it will be used to perform %-substitution
on any scripts bound to the event. If [arg percentsCommand] is not specified and
the event is dynamic, then the %-subtitution command passed to [cmd {notify install}]
will be used if it was provided. If the event is static or no %-substitution
command is available, then all %-substitution is done using [arg charMap] only .
See [cmd {notify install}] for a description of [arg percentsCommand].

[call [arg pathName] [cmd {notify install}] [arg pattern] [opt [arg percentsCommand]]]
This command installs a new event or detail specified by [arg pattern]. 
Events created by this command are called dynamic,
whereas events created by the treectrl widget itself are called static.
This command may be called to set or retrieve the [arg percentsCommand] for
an existing dynamic event.
[nl]

The optional [arg percentsCommand] is a list containing the name of a Tcl
command, plus any optional arguments, to which five additional arguments
will be appended. The command will be called to perform %-substitution on any
scripts bound to the event specified by [arg pattern] (see [sectref {EVENTS AND SCRIPT SUBSTITUTIONS}]).
[arg PercentsCommand] should be defined as follows:
[example_begin]
proc percentsCommand {?arg arg ...? char object event detail charMap} {
	switch -- $char {
		...
	}
	return $value
}
[example_end]

The optional [arg arg] arguments are part of the [arg percentsCommand] list.
[arg Char] is the %-character to be substituted. [arg Object] is the same
as the argument to [cmd {notify bind}]. [arg Event] and [arg detail] specify
the event. [arg CharMap] is the same as the argument to [cmd {notify generate}].
[arg PercentsCommand] should return the value to replace the %-character by.
If an error occurs evaluating [arg percentsCommand], the %-character is replaced
by itself.
[nl]
[cmd {notify install}] returns the current [arg percentsCommand] for the event,
or an error if the event is not dynamic.

[call [arg pathName] [cmd {notify install detail}] [arg eventName] \
     [arg detail] [opt [arg percentsCommand]]]
This command is for backward compatibility only.
Use [cmd {notify install}] with a [arg pattern] of <[arg eventName]-[arg detail]> instead.

[call [arg pathName] [cmd {notify install event}] [arg eventName] \
     [opt [arg percentsCommand]]]
This command is for backward compatibility only.
Use [cmd {notify install}] with a [arg pattern] of <[arg eventName]> instead.

[call [arg pathName] [cmd {notify linkage}] [arg pattern]]
Returns a string indicating
whether the specified event or detail is created
by means of the [cmd {notify install}] widget command ([const dynamic])
or by the treectrl widget itself ([const static]).

[call [arg pathName] [cmd {notify linkage}] [arg eventName] [opt [arg detail]]]
This form of this command is for backward compatibility only.
Use [cmd {notify linkage}] with a [arg pattern] of <[arg eventName]> or
<[arg eventName]-[arg detail]> instead.

[call [arg pathName] [cmd {notify uninstall}] [arg pattern]]
If the event or detail specified by [arg pattern] is static
(i.e. created by the treectrl widget itself), an error is generated.
Otherwise the dynamic event or detail is removed.

[call [arg pathName] [cmd {notify uninstall detail}] \
     [arg eventName] [arg detail]]
This command is for backward compatibility only.
Use [cmd {notify uninstall}] with a [arg pattern] of <[arg eventName]-[arg detail]> instead.

[call [arg pathName] [cmd {notify uninstall event}] [arg eventName]]
This command is for backward compatibility only.
Use [cmd {notify uninstall}] with a [arg pattern] of <[arg eventName]> instead.
[list_end]

[call [arg pathName] [cmd numcolumns]]
Returns a decimal string giving the number of
columns created by the [cmd "column create"] widget command which haven't been
deleted by the [cmd "column delete"] widget command. The [const tail] column
is not counted.

[call [arg pathName] [cmd numitems]]
Returns a decimal string giving the number of
items created by the [cmd "item create"] widget command which haven't been
deleted by the [cmd "item delete"] widget command.
This number is always positive,
since a newly created treectrl widget has already the root item,
which cannot be deleted.

[call [arg pathName] [cmd 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 [cmd {item remove}] widget command.

[call [arg pathName] [cmd range] [arg first] [arg last]]
[arg First] and [arg last] must be an [arg itemDesc].
Returns a list containing the numerical ids of all items
in the range between [arg first] and [arg last], inclusive.
The order between [arg first] and [arg last] doesn't matter,
and the result is always ordered by the increasing index of the items.

[call [arg pathName] [cmd state] [arg option] [opt [arg stateName]]]
This command is used to manipulate the list of user defined states,
see section [sectref STATES] below.
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd state] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {state define}] [arg stateName]]
Defines a new state with the name [arg stateName],
which must not be the name of a predefined or already user defined state.

[call [arg pathName] [cmd {state linkage}] [arg stateName]]
Returns a string indicating
whether the specified state is user defined
by means of the [cmd {state define}] widget command ([const dynamic])
or predefined by the treectrl widget itself ([const static]).

[call [arg pathName] [cmd {state names}]]
Returns a list containing the names of all user defined states.

[call [arg pathName] [cmd {state undefine}] [opt [arg {stateName ...}]]]
Every [arg stateName] must be the name of a user defined state.
Removes this state from the list of user defined states.
[list_end]

[call [arg pathName] [cmd see] [arg itemDesc]]
Adjust the view in the treectrl so that the item
described by [arg 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 [const <Scroll-x>] and/or [const <Scroll-y>]
events are generated.

[call [arg pathName] [cmd selection] [arg option] [arg arg]]
This command is used to adjust the selection within a treectrl.
It has several forms, depending on [arg option]:

[list_begin definitions]
[call [arg pathName] [cmd {selection add}] [arg first] [opt [arg last]]]
[arg First] and [arg last] (if specified)
must be the string [const all] or an [arg itemDesc].
Selects all of the items in the range between
[arg first] and [arg last], inclusive,
without affecting the selection state of items outside that range.
If one of the arguments is the string [const all],
all items of the treectrl widget are added to the selection instead.
A [const <Selection>] event is generated.

[call [arg pathName] [cmd {selection anchor}] [opt [arg itemDesc]]]
If [arg 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 selection with the mouse.
The item description [const 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.

[call [arg pathName] [cmd {selection clear}] \
     [opt [arg first]] [opt [arg last]]]
[arg First] and [arg last] (if specified)
must be the string [const all] or an [arg itemDesc].
If any of the items between [arg first] and [arg 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 [const all],
the selection is completely cleared instead.
A [const <Selection>] event is generated.

[call [arg pathName] [cmd {selection count}]]
Returns an integer indicating the number
of items in the treectrl that are currently selected.

[call [arg pathName] [cmd {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.

[call [arg pathName] [cmd {selection includes}] [arg itemDesc]]
Returns 1 if the item indicated by [arg itemDesc] is currently
selected, 0 if it isn't.

[call [arg pathName] [cmd {selection modify}] [arg select] [arg deselect]]
Both arguments [arg select] and [arg deselect] must be
the string [const all] or a possibly empty list of [arg itemDesc]s.
Selects all of the items described by [arg select],
then deselects all items described by [arg deselect],
without affecting the selection state of any item
not mentioned in both arguments.
If one item is described in both arguments [arg select] and [arg deselect],
it is added to the selection.
A [const <Selection>] event is generated.
[list_end]

[call [arg pathName] [cmd style] [arg option] [opt [arg element]] \
     [opt [arg {arg arg ...}]]]
This command is used to manipulate styles, which could be considered
as a geometry manager for the elements of one item.
The exact behavior of the command depends on the [arg option] argument
that follows the [cmd style] argument.
The following forms of the command are supported:

[list_begin definitions]
[call [arg pathName] [cmd {style cget}] [arg style] [arg option]]
This command returns the current value of the option named [arg option]
associated with the style given by [arg style].
[arg Option] may have any of the values accepted by the
[cmd {style configure}] widget command.

[call [arg pathName] [cmd {style configure}] [arg style] [opt [arg option]] \
     [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies options associated with the style given by [arg style]
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list describing
all of the available options for [arg style] (see [fun Tk_ConfigureInfo]
for information on the format of this list).
If [arg option] is specified with no [arg 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 [arg option]
is specified).
If one or more [arg option]-[arg value] pairs are specified, then the command
modifies the given option(s) to have the given value(s) in [arg style];
in this case the command returns an empty string.
[nl]

The options of a style have effect on all elements managed by the style.
The following options are supported:

[list_begin opt]
[opt_def [option -orient] [arg varName]]
This option specifies which orientation should be used
when laying out the elements associated with this style.
Must be either [const horizontal] (the default)
or [const vertical] or an abbreviation of one of these.
[list_end]

[call [arg pathName] [cmd {style create}] [arg style] \
     [opt [arg {option value ...}]]]
Create a new style in [arg pathName] with name [arg style].
After [arg style] there may be any number of [arg option]-[arg value]
pairs, each of which sets one of the configuration options
for the style.  These same [arg option]-[arg value] pairs may be
used in [cmd {style configure}] widget commands to change the style's
configuration.
Returns the name of the new style.

[call [arg pathName] [cmd {style delete}] [opt [arg {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.

[call [arg pathName] [cmd {style elements}] [arg style] \
     [opt [arg elementList]]]
Specifies the elements which should be layed out by this style.
Each element of [arg elementList] must be the name of an element
created by the widget command [cmd {element create}].
Duplicate names in [arg elementList] are ignored.
An element which was specified in a former call of this command
for [arg style] but is not included in [arg elementList],
will be deleted from the elements layed out by [arg style].
[nl]

If the [arg elementList] argument is not specified, a list is returned
containing the currently defined elements of [arg style].

[call [arg pathName] [cmd {style layout}] [arg style] [arg element] \
     [opt [arg option]] [opt [arg value]] [opt [arg {option value ...}]]]
This command is similar to the [cmd configure] widget command except
that it modifies options used by [arg style] for laying out [arg element]
instead of modifying options for the overall treectrl widget.
If no [arg option] is specified, the command returns a list with
[arg option]-[arg value] pairs describing
all of the available options for the layout.
If [arg option] is specified with no [arg value], then the command returns
the value of the named option.
If one or more [arg option]-[arg 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.
[nl]

The options of a layout have effect on exactly the one element [arg element]
managed by [arg style].
The following options are supported:

[list_begin opt]
[opt_def [option -padx] [arg amount]]
[opt_def [option -pady] [arg amount]]
[arg Amount] specifies how much external padding to
leave on the left and right (for [option -padx])
or top and bottom (for [option -pady]) side of the element.
[arg Amount] may be a list
of two values to specify padding for the two sides separately,
it defaults to 0.

[opt_def [option -ipadx] [arg amount]]
[opt_def [option -ipady] [arg amount]]
[arg Amount] specifies how much internal padding to
leave on the left and right (for [option -ipadx])
or top and bottom (for [option -ipady]) side of the element.
[arg Amount] may be a list
of two values to specify padding for the two sides separately,
it defaults to 0.

[opt_def [option -expand] [arg style]]
[opt_def [option -iexpand] [arg 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.
[arg Style]  is a string that contains zero or more of the characters
[const n], [const s], [const e] or [const w].
Each letter refers to a side (north, south,
east, or west) in which direction the element will grow in.

[opt_def [option -squeeze] [arg style]]
If an element's area is smaller than its requested dimensions, this
option may be used to allow shrinking of the element.
[arg Style] is a string that contains zero or more of the characters
[const x] or [const y].
[const x] shrinks the element horizontally,
[const y] shrinks it vertically.

[opt_def [option -union] [arg elementList]]
Specifies a list of other [arg element]s, which should be layed out
inside the space of this element.

[opt_def [option -detach] [arg boolean]]
Specifies whether the element should be positioned by themselves,
i.e. independent from the other elements.
[list_end]

[call [arg pathName] [cmd {style names}]]
Returns a list containing the names of all existing styles.
[list_end]

[call [arg pathName] [cmd toggle] [opt [option -recurse]] \
     [opt [arg {itemDesc ...}]]]
Use [cmd {item toggle}] instead.

[call [arg pathName] [cmd xview] [opt [arg 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:

[list_begin definitions]
[call [arg pathName] [cmd 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 element 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 [option -xscrollcommand]
option.

[call [arg pathName] [cmd {xview moveto}] [arg  fraction]]
Adjusts the view in the window so that [arg fraction] of the
total width of the tree is off-screen to the left.
[arg Fraction] must be a fraction between 0 and 1.
A [const <Scroll-x>] event is generated.

[call [arg pathName] [cmd {xview scroll}] [arg number] [arg what]]
This command shifts the view in the window left or right according to
[arg number] and [arg what].
[arg Number] must be an integer.
[arg What] must be either [const units] or [const pages] or an abbreviation
of one of these.
If [arg what] is [const units], the view adjusts left or right in units
of the [option -xscrollincrement] option, if it is greater than zero,
or in units of one-tenth the window's width otherwise.
If [arg what] is [const pages] then the view
adjusts in units of nine-tenths the window's width.
If [arg number] is negative then information farther to the left
becomes visible;  if it is positive then information farther to the right
becomes visible.
A [const <Scroll-x>] event is generated.
[list_end]

[call [arg pathName] [cmd yview] [opt [arg 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:

[list_begin definitions]
[call [arg pathName] [cmd 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 element 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 [option -yscrollcommand]
option.

[call [arg pathName] [cmd {yview moveto}] [arg fraction]]
Adjusts the view in the window so that [arg fraction] of the tree's
area is off-screen to the top.
[arg Fraction] is a fraction between 0 and 1.
A [const <Scroll-y>] event is generated.

[call [arg pathName] [cmd {yview scroll}] [arg number] [arg what]]
This command adjusts the view in the window up or down according to
[arg number] and [arg what].
[arg Number] must be an integer.
[arg What] must be either [const units] or [const pages].
If [arg what] is [const units], the view adjusts up or down in units
of the [option -yscrollincrement] option, if it is greater than zero,
or in units of one-tenth the window's height otherwise.
If [arg what] is [const pages] then
the view adjusts in units of nine-tenths the window's height.
If [arg number] is negative then higher information becomes
visible;  if it is positive then lower information
becomes visible.
A [const <Scroll-y>] event is generated.
[list_end]
[list_end]

[section 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.

[para]
Columns in a treectrl may be named in either of two ways: by number or by tag.
If a number is given it must be an integer from zero to [arg N], where [arg N]
is one less than the result of the [cmd numcolumns] widget command.
A column may also be named by the value of its [option -tag] configuration
option.

[para]
There is always one special column, the [const 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 [const tail], which cannot be modified.
It is explicitely mentioned for a widget command,
if its [arg column] argument can also specify the tail column.

[para]
The following options are supported for columns:

[list_begin opt]
[opt_def [option -arrow] [arg direction]]
Indicates whether or not an arrow should be drawn in the column header
to the right of the column title.
[arg Direction] must have one of the values
[const none] (the default), [const up], or [const down].

[opt_def [option -arrowside] [arg side]]
Indicates on which side an arrow should be drawn, if at all.
[arg Side] must be either [const left] or [const right] (the default).

[opt_def [option -arrowgravity] [arg side]]
Indicates onto which side an arrow should be packed,
if there is more space available for drawing the arrow then needed.
[arg Side] must be either [const left] (the default) or [const right].

[opt_def [option -arrowpad] [arg amount]]
[arg Amount] specifies how much padding to
leave on the left and right side of the arrow.
[arg Amount] may be a list
of two values to specify padding for left and right separately,
it defaults to 0.

[opt_def [option -bitmap] [arg bitmap]]
Specifies the bitmap to display in the element
to the left of the column title.

[opt_def [option -background] [arg color]]
Specifies the color to use for the background of the column header.

[opt_def [option -borderwidth] [arg 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 [option -relief] column option
determines this).
The value may have any of the forms acceptable to [fun Tk_GetPixels].

[opt_def [option -button] [arg boolean]]
Indicates whether or not a mouse click on the column header should
change the sorting order of the tree.

[opt_def [option -expand] [arg boolean]]
Indicates whether or not any extra horizontal space should be distributed
to this column.
This option will actually only work if the column has no fixed width defined
by means of the [option -width] column option.

[opt_def [option -font] [arg fontName]]
Specifies the font to use for the column title inside the column header.

[opt_def [option -image] [arg image]]
Specifies the image to display in the element
to the left of the column title.
This option overrides the [option -bitmap] column option.

[opt_def [option -imagepadx] [arg amount]]
[opt_def [option -imagepady] [arg amount]]
[arg Amount] specifies how much padding to
leave on the left and right (for [option -imagepadx])
or top and bottom (for [option -imagepady]) side of the image.
[arg Amount] may be a list
of two values to specify padding for the two sides separately,
it defaults to 0.

[opt_def [option -itembackground] [arg colorList]]
Specifies a list of colors, which should be used as
alternating background color for the items of this column.
See also the [option -backgroundmode] widget option for more on this.

[opt_def [option -justify] [arg justification]]
This option determines how the items (and the title) line up with each other.
Must be one of [const left] (the default), [const center], or [const right].

[opt_def [option -minwidth] [arg size]]
Specifies the minimum size, in screen units,
that will be permitted for this column.

[opt_def [option -relief] [arg relief]]
Specifies the 3-D effect desired for the column header containing the title.
Acceptable values are the typical relief values,
but the value seems to be ignored anyway;
better use the [option -sunken] column option instead.

[opt_def [option -squeeze] [arg boolean]]
Specifies a boolean value that indicates whether or not the column should
shrink when the content width of the treectrl is less than the total needed width
of all visible columns. Defaults to false, which means the column will not get
smaller than its needed width. The column will not get smaller than the value
of its [option -minwidth] option, if specified. This option has no effect if the
[option -width] option is set.

[opt_def [option -stepwidth] [arg 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 [arg size].

[opt_def [option -sunken] [arg boolean]]
Indicates whether or not the column header containing the column title
will be displayed with a sunken relief.

[opt_def [option -tag] [arg tag]]
Defines a unique name for the columns which can be used in subsequent calls
of the treectrl widget commands, wherever a column must be specified.

[opt_def [option -text] [arg text]]
Specifies a text to be displayed inside the column title.

[opt_def [option -textcolor] [arg color]]
Specifies a color, which should be used as foreground color
to display the column title.

[opt_def [option -textpadx] [arg amount]]
[opt_def [option -textpady] [arg amount]]
[arg Amount] specifies how much padding to
leave on the left and right (for [option -textpadx])
or top and bottom (for [option -textpady]) side of the text.
[arg Amount] may be a list
of two values to specify padding for the two sides separately,
it defaults to 0.

[opt_def [option -visible] [arg boolean]]
Indicates whether or not the column should be displayed.

[opt_def [option -width] [arg size]]
Specifies a fixed width for the column. If this value is zero, the column width
is calculated as the maximum of:
a) the width requested by items;
b) the width requested the column header;
c) and the column [option -minwidth].
This calculated width is also affected by the [option -expand] option of all
columns.

[opt_def [option -widthhack] [arg boolean]]
Indicates whether or not all items should have the same width. This option only
has effect when all of these conditions are met:
a) the tree [option -orientation] option is [const vertical];
b) only a single tree column is visible;
c) the single visible tree column [option -width] option is zero;
d) and the tree [option -wrap] option results in wrapping.

[list_end]

[section STATES]
A state consists basically of just a string: its [arg 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 predefined for every item:

[list_begin definitions]
[lst_item [const 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 [cmd activate].

[lst_item [const enabled]]
This state is set for every item, when it is created.
It cannot be modified.

[lst_item [const 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 <FocusOut> event.

[lst_item [const 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
[cmd expand], [cmd collapse], or [cmd toggle].

[lst_item [const selected]]
This state is set for every item, which is included in the selection.
It can be modified by means of the widget command [cmd selection].
[list_end]

[para]
By means of the [cmd {state define}] widget command
up to 27 additional [arg stateName]s can be defined.

[para]
Some widget commands expect a [arg stateDesc] argument,
which is a [arg stateName]
optionally preceded by an exclamation mark ([const !]).
If the [arg stateName] has no leading [const !]
it describes a currently switched on state,
if it has a leading [const !] it describes a currently switched off state.

[para]
Some widget commands expect a [arg statePattern] argument,
which should be a non empty list of [arg stateDesc]s.
The pattern matches, if for every element of the list
the [arg stateDesc] describes the same state as the item currently has.

[section ELEMENTS]
Elements are the smallest building block
which are handled by a treectrl 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 [cmd {item complex}] widget command.
An element can be of type [const bitmap], [const border], [const image],
[const rect], or [const text].
For each element type there is a section below describing all options
which can modify the behaviour of an element of this type.

[para]
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 ([arg value]-[arg statePattern] pairs)
specifies different values for different states.
For acceptable values of [arg statePattern]
see the section [sectref STATES] above.
The last [arg statePattern] can be empty,
implementing a sort of [emph {otherwise clause}].
The options with this behaviour are called [emph {per state options}].

[section {BITMAP ELEMENT}]
An element of type [const bitmap] can be used to display a bitmap in an item.
The following options are supported for bitmap elements:

[list_begin opt]
[opt_def [option -background] [arg color]]
Specifies as a per state option
the color to use for each of the bitmap's '0' valued pixels.

[opt_def [option -bitmap] [arg bitmap]]
Specifies as a per state option
the bitmap to display in the element.

[opt_def [option -foreground] [arg color]]
Specifies as a per state option
the color to use for each of the bitmap's '1' valued pixels.
[list_end]

[section {BORDER ELEMENT}]
An element of type [const border] can be used to add a border to an item.
The following options are supported for border elements:

[list_begin opt]
[opt_def [option -background] [arg color]]
Specifies as a per state option
the color to use for the background of the border.

[opt_def [option -filled] [arg 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.

[opt_def [option -height] [arg size]]
Specifies the height of the area of the border.

[opt_def [option -relief] [arg reliefList]]
Specifies as a per state option
relief of the border.
For acceptable values see the description of the
[option -relief] option in the [cmd options] manual page.

[opt_def [option -thickness] [arg thickness]]
Specifies the thickness of the border.

[opt_def [option -width] [arg size]]
Specifies the width of the area of the border.
[list_end]

[section {IMAGE ELEMENT}]
An element of type [const image] can be used to display an image in an item.
The following options are supported for image elements:

[list_begin opt]
[opt_def [option -height] [arg size]]
Specifies the height of the image.

[opt_def [option -image] [arg image]]
Specifies as a per state option
the image to display in the element.

[opt_def [option -width] [arg size]]
Specifies the width of the image.
[list_end]

[section {RECTANGLE ELEMENT}]
An element of type [const rect] can be used to display a rectangle in an item.
The following options are supported for rectangle elements:

[list_begin opt]
[opt_def [option -fill] [arg fillColor]]
Specifies as a per state option
the color to be used to fill rectangle's area.
[arg Color] may have any of the forms accepted by [fun Tk_GetColor].
If [arg color] is an empty string (the default), then
the rectangle will not be filled.

[opt_def [option -height] [arg size]]
Specifies the height of the rectangle.

[opt_def [option -open] [arg open]]
This option may be used to get an incomplete drawing of the outline.
[arg Open] is a string that contains zero or more of the characters
[const n], [const s], [const e] or [const w].
Each letter refers to a side (north, south, east, or west) that the outline
will not be drawn. 
The default is the empty string, which causes the outline to be drawn completely.

[opt_def [option -outline] [arg outlineColor]]
Specifies as a per state option
the color that should be used to draw the outline of the rectangle.
[arg Color] may have any of the forms accepted by [fun Tk_GetColor].
If [arg color] is specified as an empty string (the default),
then no outline is drawn for the rectangle.

[opt_def [option -outlinewidth] [arg outlineWidth]]
Specifies the width of the outline to be drawn around the rectangle's region.
[arg outlineWidth] may be in any of the forms acceptable to [fun Tk_GetPixels].
If the [option -outline] option has been specified as an empty string
(the default), then no outline is drawn.

[opt_def [option -showfocus] [arg 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 currently the focus.

[opt_def [option -width] [arg size]]
Specifies the width of the rectangle.
[list_end]

[section {TEXT ELEMENT}]
An element of type [const text] can be used to display a text in an item.
The following options are supported for text elements:

[list_begin opt]
[opt_def [option -data] [arg data]]
Specifies raw data to be printed as text.

[opt_def [option -datatype] [arg dataType]]
Specifies the datatype which should be used to convert the value of the
[option -data] option to the text to be printed. Acceptable values are
[const double], [const integer], [const long], [const string], or [const time].

[opt_def [option -fill] [arg color]]
Specifies as a per state option
the color to be used as foreground color of the text.
[arg Color] may have any of the forms accepted by [fun Tk_GetColor].
If [arg color] is an empty string (the default), then
the text will be displayed with the color specified as foreground color
of the treectrl widget.

[opt_def [option -format] [arg format]]
This option overwrites the default format choosen
by means of the [option -datatype] option.
For a datatype [const time] [arg format] should be
a valid format string for the [cmd clock] command,
for all other datatypes it should be
a valid format element of the [cmd format] command.

[opt_def [option -font] [arg fontName]]
Specifies as a per state option
the font to use for the text.
[arg FontName] may be any string acceptable to [fun Tk_GetFont].
If this option isn't specified, it defaults to the font configured for
the treectrl widget.

[opt_def [option -justify] [arg how]]
Specifies how to justify the text within its bounding region.
[arg How] must be one of the values [const left], [const right], or [const center].
This option will only matter if the text is displayed as multiple lines.
If the option is omitted, it defaults to [const left].

[opt_def [option -lines] [arg lineCount]]
Specifies the maximal number of lines the text should be printed.
If the doesn't fit into the area of [arg lineCount] lines with the
configured width, it will be truncated at the right end and filled up with
an ellipsis.

[opt_def [option -text] [arg string]]
[arg 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 [const \\n]).
If this option is specified, any values of [option -data], [option -datatype],
and [option -format] are ignored.

[opt_def [option -width] [arg size]]
Specifies the width of the area of the text.

[opt_def [option -wrap] [arg mode]]
[arg Mode] specifies how to handle lines that are wider than the
text's area.
Acceptable values are [const char] or [const word].
[list_end]

[section {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
indicators are called [arg itemDesc]s and may be specified in
any of the following forms:

[list_begin definitions]
[lst_item [arg number]]
Specifies the item numerically, where [arg number] should be
the return value of a prior call of the [cmd {item create}] widget command,
or [const 0] to specify the root item.

[lst_item [const active]]
Indicates the item that is currently active, i.e. normally
the item specified as argument of the last successful [cmd activate]
widget command, or the root item if no such call happened yet.

[lst_item [const anchor]]
Indicates the anchor item of the selection, i.e. normally
the item specified as argument of the last successful [cmd {selection anchor}]
widget command, or the root item if no such call happened yet.

[lst_item "[const first] [opt [const visible]]"]
Indicates the first item of the treectrl, i.e. the root item.
If [const visible] is specified and the widget is configured with
[option -showroot] [const no], the first visible child of the root node
is specified instead.

[lst_item "[const last] [opt [const visible]]"]
Indicates the last item of the treectrl.
If [const visible] is specified and the last item is currently not visible,
i.e. one of its father nodes is collapsed,
the last visible item is specified instead.

[lst_item "[const nearest] [arg {x y}]"]
Indicates the item nearest to the point given by [arg x] and [arg y].

[lst_item "[const rnc] [arg {row column}]"]
Indicates the item in the given [arg row] and [arg column].
You can memorize [const rnc] as abbreviation of "row 'n' column".

[lst_item [const root]]
Indicates the root item of the treectrl.
[list_end]

[para]
The [arg itemDesc] may be followed by one or more [arg modifier]s.
A modifier changes the item described by the [arg itemDesc] relative to
the description up to this point.
It may be specified in any of the following forms:

[list_begin definitions]
[lst_item [const above]]
Use the item one row above in this column.

[lst_item [const below]]
Use the item one row below in this column.

[lst_item [const bottom]]
Use the item in the last row of this column.

[lst_item "[const child] [arg n] [opt [const visible]]"]
Use the [arg n]th child of the item.

[lst_item "[const firstchild] [opt [const visible]]"]
Use the first child of the item.

[lst_item "[const lastchild] [opt [const visible]]"]
Use the last child of the item.

[lst_item [const left]]
Use the item one column to the left in the same row.

[lst_item [const leftmost]]
Use the item of the first column in the same row.

[lst_item "[const next] [opt [const visible]]"]
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.

[lst_item "[const nextsibling] [opt [const visible]]"]
Use the next sibling of the item.

[lst_item [const parent]]
Use the parent of the item.

[lst_item "[const prev] [opt [const visible]]"]
Use the last child of the previous sibling,
or the parent if there is no previos sibling.

[lst_item "[const prevsibling] [opt [const visible]]"]
Use the previous sibling of the item.

[lst_item [const right]]
Use the item one column to the right in the same row.

[lst_item [const rightmost]]
Use the item of the last column in the same row.

[lst_item "[const sibling] [arg n] [opt [const visible]]"]
Use the [arg n]th child of the item's parent.

[lst_item [const top]]
Use the item in the first row of this column.
[list_end]

[section {EVENTS AND SCRIPT SUBSTITUTIONS}]

The [arg script] argument to [cmd {notify bind}] is a Tcl script, which will be
evaluated whenever the given event is generated. [arg Script] will be executed
in the same interpreter that the [cmd {notify bind}] command was executed in,
and it will run at global level (only global variables will be accessible).
If [arg script] contains any [const %] characters, then the script will not be
evaluated directly.  Instead, a new script will be generated by replacing each
[const %], and the character following it, with information from the current
event. Unlike the regular Tk [cmd bind] mechanism, each event generated by
a treectrl widget has its own set of %-substitutions.
[para]
The following %-substitutions are valid for all static events:
[list_begin opt]
[opt_def %%] Replaced with a single %
[opt_def %d] The detail name
[opt_def %e] The event name
[opt_def %P] The pattern, either <event> or <event-detail>
[opt_def %W] The object argument to the [cmd "notify bind"] command
[opt_def %T] The treectrl widget which generated the event
[opt_def %?] A list of the format {char value char value ...} for each
%-substitution character and the value it is replaced by
[list_end]

[para]
The following events may be generated by a treectrl widget:

[list_begin definitions]
[lst_item [const <ActiveItem>]]
Generated whenever the active item changes.
[list_begin opt]
[opt_def %c] The current active item
[opt_def %p] The previous active item
[list_end]

[lst_item [const <Collapse-before>]]
Generated before an item is collapsed.
[list_begin opt]
[opt_def %I] The item id
[list_end]

[lst_item [const <Collapse-after>]]
Generated after an item is collapsed.
[list_begin opt]
[opt_def %I] The item id
[list_end]

[lst_item [const <Expand-before>]]
Generated before an item is expanded. This event is useful if you want to add
child items to the item just before the item is expanded.
[list_begin opt]
[opt_def %I] The item id
[list_end]

[lst_item [const <Expand-after>]]
Generated after an item is expanded.
[list_begin opt]
[opt_def %I] The item id
[list_end]

[lst_item [const <Scroll-x>]]
Generated whenever the view in the treectrl changes in such a way that a
horizontal scrollbar should be redisplayed.
[list_begin opt]
[opt_def %l] Same as the first fraction appended to [const -xscrollcommand]. Think [emph lower].
[opt_def %u] Same as the second fraction appended to [const -xscrollcommand]. Think [emph upper].
[list_end]

[lst_item [const <Scroll-y>]]
Generated whenever the view in the treectrl changes in such a way that a
vertical scrollbar should be redisplayed.
[list_begin opt]
[opt_def %l] Same as the first fraction appended to [const -yscrollcommand]. Think [emph lower].
[opt_def %u] Same as the second fraction appended to [const -yscrollcommand]. Think [emph upper].
[list_end]

[lst_item [const <Selection>]]
Generated whenever the selection changes. This event gives information about
how the selection changed.
[list_begin opt]
[opt_def %c] Same as the [cmd "selection count"] widget command
[opt_def %D] List of newly-deselected item ids
[opt_def %S] List of newly-selected item ids
[list_end]

[list_end]

[section {DYNAMIC EVENTS}]
In addition to the pre-defined static events such as <ActiveItem>
and <Selection>, new dynamic events can be created by using the
[cmd {notify install}] command. The default bindings provide an example
of using a dynamic event called <Header-invoke>, which is generated when
the mouse button is released over a column header.
[example_begin]
treectrl .t
.t notify install <Header-invoke>
.t notify bind ConsoleTag <Header-invoke> {
	puts "header %C clicked in treectrl %T"
}
proc ::TreeCtrl::Release1 {w x y} {
	...
	$w notify generate <Header-invoke> [lb]list C $Priv(column)[rb] \
		[lb]list ::TreeCtrl::PercentsCmd $w[rb]
	...
}
[example_end]
In the example a new treectrl widget is created and the <Header-invoke> event
is installed. For convenience there is no [arg percentsCommand] argument to
[cmd {notify install}]; instead the call to [cmd {notify generate}] specifies
the %-substitution command. A script is
bound to the event with [cmd {notify bind}] which will print out the column
number and widget
name to the console (in the demos, <Header-invoke> is used to sort the list
based on the column that was clicked). The [arg charMap] argument to
[cmd {notify generate}]
provides a list of %-substitution characters and values which is used by
::TreeCtrl::PercentsCmd. In this example any %C in any script bound to the
<Header-invoke> event will be replaced by the value of $Priv(column).

[section {DEFAULT BINDINGS}]
Tk automatically creates class bindings for treectrl widgets that give them
the following default behavior.
[list_begin enum]
[enum]
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.
[enum]
Clicking mouse button 1 with the Control key down will reposition the
active cursor and add the item to the selection
without ever removing any items from the selection.
[enum]
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).
[enum]
The Left and Right keys move the active cursor one item to the left or right;
for an hierarchical tree with vertical orientation 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.
[enum]
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.
[enum]
The Next and Prior keys move the active cursor forward or backwards
by one screenful, without affecting the selection.
[enum]
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.
[enum]
The Home and End keys scroll to the left or right end of the widget
without moving the active cursor or affecting the selection.
[enum]
The Control-Home and Control-End keys scroll to the top or bottom
of the widget, they also activate and select the first or last item.
If also the Shift key is down, then the active
cursor moves and the selection is extended to include the new item.
[enum]
The Space and Select keys set the selection to the active item.
[enum]
Control-/ selects the entire contents of the widget.
[enum]
Control-\\ clears any selection in the widget.
[enum]
The + and - keys expand or collapse the active item,
the Return key toggles the active item.
[enum]
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.
[list_end]

[see_also listbox(n) image(n) bitmap(n) bind(n) options(n)]
[keywords tree widget]
[manpage_end]