treectrl - Create and manipulate hierarchical multicolumn widgets
The treectrl command creates a new window (given by the 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 treectrl command returns the path name of the new window. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.
A treectrl is a listbox widget which displays items in a one- or two-dimensional arrangement. Items have a parent-child relationship with other items. Items may be arranged from top-to-bottom or from left-to-right. Items may be spread about one or more columns. Each item-column may be configured to span one or more adjacent item-columns. The visibility of items can be set individually.
Items have a set of states, which are boolean properties. For each column of an item there is a style associated, which determines how to display the item's column taking into account the item's current state set. New states may be defined to further control the appearance of items; these custom states may be turned on or off in individual columns of items.
Multiple rows of column headers are supported. Column headers have platform-native appearance on Windows, Mac OS X, and Gtk+. The appearance of column headers may be customized using styles.
Columns may be rearranged by the user using drag-and-drop. One column can be specified to display the data in a hierarchical structure. The visibility of columns can be set individually.
A treectrl can display a user-resizable selection rectangle called the marquee. Another feature, the drag image, may be used to provide feedback during drag-and-drop operations. Both of these are features commonly found in file browsers.
A treectrl can generate events when various things happen, such as changes to the selection, or a parent item being toggled open or closed. Scripts may be bound to these events. New events can be defined.
A treectrl can display a background image. The background image can be configured to be scrolled and tiled on each axis individually.
See the option manual entry for details on the standard options.
Throughout this manual page the term canvas is sometimes used. The canvas can be thought of as the virtual sheet of paper upon which all visible items are drawn. The treectrl window displays different areas of the canvas within its borders as the list is scrolled.
Columns and items may have any number of tags associated with them. A tag is just a string of characters, and it may take any form, including that of an integer, although the characters '(', ')', '&', '|', '^' and '!' should be avoided.
The same tag may be associated with many columns or items. This is commonly done to group items in various interesting ways; for example, in a file browser all directories might be given the tag "directory".
Tag expressions are used in column descriptions and item descriptions to specify which columns and items to operate on. A tag expression can be a single tag name or a logical expression of tags using operators '&&', '||', '^' and '!', and parenthesized subexpressions. For example:
.t item id "tag {(a && !b) || (!a && b)}"
or equivalently:
.t item id "tag {a ^ b}"
will return the unique ids of any items with either "a" or "b" tags, but not both.
Within a tag expression a tag name may be enclosed in double quotes to avoid special processing of the operator characters. For example:
.t item id {tag {"a&&b"||c}}
will return the unique ids of any items with either "a&&b" or "c" tags; in this example the && is not treated as an operator. A double-quote may be escaped within a quoted tag name using a backslash '\'.
Tag operators may be bypassed completely by setting the -columntagexpr and -itemtagexpr options. This can be useful if your application has column or item tags containing arbitrary text.
.t configure -itemtagexpr false .t item delete "tag a&&b"
The treectrl command creates a new Tcl command whose name is the same as the path name of the treectrl's window. This command may be used to invoke various operations on the widget. It has the following general form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as the treectrl widget's path name. Option and the args determine the exact behavior of the command. The following commands are possible for treectrl widgets:
Sets the active item to the one described by itemDesc, and switches on the state active for that item. The active item can be referred to by the item description active. If this command changes which item is active an <ActiveItem> event is generated. If the active item is deleted the root item becomes the new active item.
Returns a list with four elements giving the bounding box (left, top, right and bottom) of an area of the window. If area is not specified, then the result is the bounding box of the entire window. If area is content, then the result is the part of the window not including borders, headers, or locked columns. If area is header, then the result is the part of the window not including borders where column titles are displayed. If area is left, then the result is the part of the window not including borders or headers where left-locked columns are displayed. If area is right, then the result is the part of the window not including borders or headers where right-locked columns are displayed.
If area is one of header.left, header.none or header.right then the area of the column headers occupied by columns with -lock=left, -lock=none or -lock=right is returned.
An empty string is returned if the display area has no height or width, which can be true for various reasons such as the window is too small, or the header is not displayed, or there aren't any locked columns.
Translates the given window x-coordinate windowx in the treectrl to canvas coordinate space. The marquee command expects canvas coordinates.
Translates the given window y-coordinate windowy in the treectrl to canvas coordinate space. The marquee command expects canvas coordinates.
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the tree command.
Deprecated. Use item collapse instead.
This command is used to manipulate the columns of the treectrl widget (see section COLUMNS below). The exact behavior of the command depends on the option argument that follows the column argument. The following forms of the command are supported:
Returns a list with four elements giving the bounding box of the header of the column specified by the column description columnDesc. The returned coordinates are relative to the top-left corner of the widget. If the column option -visible=false or if the widget option -showheader=false, then an empty list is returned.
This command returns the current value of the option named option for the column specified by the column description columnDesc, ColumnDesc may also be the string tail to specify the tail column. Option may have any of the values accepted by the column configure widget command.
This command is similar to the configure widget command except that it modifies options associated with the columns specified by the column description columnDesc instead of modifying options for the overall treectrl widget. ColumnDesc may be the string tail to specify the tail column. If columnDesc refers to more than one column, then at least one option-value pair must be given. If no option is specified, the command returns a list describing all of the available options for columnDesc (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s) for columnDesc; in this case the command returns an empty string.
See COLUMNS below for details on the options available for columns.
For compatibility with older versions of treectrl (which did not support more than one row of column headers) any of the configuration options mentioned in the HEADERS section, such as -arrow, -text, etc, may be passed to the top header-row through this command.
For both column descriptions column1 and column2 the index is retrieved (as returned from the column order widget command). Then these indexes are compared using the operator op, which must be either <, <=, ==, >=, >, or !=. The return value of this command is 1 if the comparison evaluated to true, 0 otherwise.
If no additional arguments are given, the result is a decimal string giving the number of columns created by the column create widget command which haven't been deleted by the column delete widget command; in this case the tail column is not counted. If columnDesc is given, then the result is the number of columns that match that column description.
This command creates a new column in the treectrl widget. The new column is placed to the right of all other columns (except the tail column). Any option-value arguments configure the new column according to the column configure command. The return value is the unique identifier of the new column.
Deletes the specified column(s). First and last must be valid column descriptions. If both first and last are specified, then they may refer to a single column only. The tail column cannot be deleted and it is an error to specify it. The order of first and last doesn't matter, and first may be equal to last.
Deprecated. Use header dragcget instead.
Deprecated. Use header dragconfigure instead.
Deprecated. Use column id instead.
This command resolves the column description columnDesc into a list of unique column identifiers. If the column(s) described by columnDesc don't exist, this command returns an empty list.
This command returns a list of identifiers for every column (except the tail) from left to right. If -visible is given, only columns whose -visible option is true are returned.
Moves the column specified by columnDesc to the left of the column specified by beforeDesc. Both columnDesc and beforeDesc must be valid column descriptions. If beforeDesc is the string tail, the column columnDesc will become the last column.
This command returns a decimal string giving the needed width of the column specified by the column description columnDesc. The needed width is the maximum of the width of the column header and the width of the widest style in any visible item.
When an item style or column header spans multiple columns, the needed width of a column is affected by the widths of other columns in the span, in which case the result of this command isn't particularly useful.
This command returns a decimal string giving the position of the column specified by the column description columnDesc in the list of columns starting from zero for the leftmost column. If -visible is given, only columns whose -visible option is true are considered, and -1 is returned if columnDesc's -visible option is false.
This command is used to manipulate tags on columns. The exact behavior of the command depends on the option argument that follows the column tag argument. The following forms of the command are supported:
Adds each tag in tagList to the columns specified by the column description columnDesc. Duplicate tags are ignored. The list of tags for a column can also be changed via a column's -tags option.
Evaluates the tag expression tagExpr against every column specified by the column description columnDesc. The result is 1 if the tag expression evaluates to true for every column, 0 otherwise.
Returns a list of tag names assigned to the columns specified by the column description columnDesc. The result is the union of any tags assigned to the columns.
Removes each tag in tagList from the columns specified by the column description columnDesc. It is not an error if any of the columns do not use any of the tags. The list of tags for a column can also be changed via a column's -tags option.
This command returns a decimal string giving the width in pixels of the column specified by the column description columnDesc, even if the treectrl is configured to not display the column headers by means of the -showheader option.
Deprecated. Use the item compare command instead.
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the treectrl command.
Returns a list with four elements giving the bounding box of the screen area used to display items. This is the area of the window not including borders, column headers, or locked columns. An empty string is returned if the display area has no height or width, which can happen if the window is too small. The result of this command is the same as that of bbox content.
This command is used to facilitate debugging of the treectrl widget. The exact behavior of the command depends on the option argument that follows the debug argument. The following forms of the command are supported:
Returns a string giving partial statistics on memory allocations, if the package was built with TREECTRL_DEBUG defined.
This command returns the current value of the debugging option named option. Option may have any of the values accepted by the debug configure widget command.
This command is similar to the configure widget command except that it modifies debugging options instead of modifying options for the overall treectrl widget. If no option is specified, the command returns a list describing all of the available debugging options (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given debugging option(s) to have the given value(s); in this case the command returns an empty string.
The following debugging options are supported:
Returns a string describing display-related stuff. Option must be one of alloc, ditem, onscreen or range.
Causes the area of the window bounded by the given window-coords to be marked as invalid. This simulates uncovering part of the window.
If the additional argument itemDesc is given, then the result is a decimal string giving the depth of the item described by itemDesc. If no itemDesc is specified, then the maximum depth of all items in the treectrl widget is returned instead. Depth is defined as the number of ancestors an item has.
This command is used to manipulate the drag image, which is used to provide feedback when items are drag-and-dropped within the window. The drag image is displayed as the dotted outlines of one or more items, columns and/or elements. The exact behavior of the command depends on the option argument that follows the dragimage argument. The following forms of the command are supported:
Adds the shapes of the item described by itemDesc to the shapes of the dragimage. Specifying additional arguments reduces the number of rectangles that are added to the dragimage. If no additional arguments is specified, for every element of the item in every column a dotted rectangles is added. If column is specified, all elements in other columns are ignored. If also element is specified, only a rectangle for this one element of the specified item in the given column is added.
This command returns the current value of the dragimage option named option. Option may have any of the values accepted by the dragimage configure widget command.
Removes all shapes (if there are any) from the dragimage. This command does not modify the dragimage offset.
This command is similar to the configure widget command except that it modifies the dragimage options instead of modifying options for the overall treectrl widget. If no option is specified, the command returns a list describing all of the available dragimage options (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named dragimage option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given dragimage option(s) to have the given value(s); in this case the command returns an empty string.
The following dragimage options are supported:
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 at relative to the item(s) its shape is derived from. If two coordinates are specified, sets the dragimage offset to the given coordinates x and y.
This command is used to manipulate elements (see ELEMENTS AND STYLES below). The exact behavior of the command depends on the option argument that follows the element argument. The following forms of the command are supported:
This command returns the current value of the option named option associated with the element given by element. Option may have any of the values accepted by the element configure widget command.
This command also accepts the -statedomain option.
This command is similar to the configure widget command except that it modifies options associated with the element given by element instead of modifying options for the overall treectrl widget. If no option is specified, the command returns a list describing all of the available options for element (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s) in element; in this case the command returns an empty string. See ELEMENTS AND STYLES below for details on the options available for elements.
Creates a new master element of type type with the unique user-defined name name and configures it with zero or more option/value pairs. See the subsections on individual element types in ELEMENTS AND STYLES for the options that are valid for each type of element. This command returns the name of the new element (the same as the name argument).
This command also accepts the -statedomain option with a value of either header or item to specify where this element will be displayed.
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 style elements widget command, it is also removed from the element lists of these styles.
Returns a list containing the names of all existing elements.
This command returns the value of the per-state option named option for element for a certain state. StateList is a list of state names (static and dynamic, see STATES) which specifies the state to use.
Returns the type of the element given by element, such as rect or text.
Deprecated. Use item expand instead.
This command is used to manipulate color gradients. See GRADIENTS for more information about using gradients. The exact behavior of the command depends on the option argument that follows the gradient argument. The following forms of the command are supported:
Returns the current value of the configuration option for the gradient specified by gradient whose name is option. Option may have any of the values accepted by the gradient configure command.
If no option is specified, the command returns a list describing all of the available gradient options (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named gradient option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given gradient option(s) to have the given value(s); in this case the command returns an empty string.
The following options are supported (see gradient create for the meaning of each option):
Creates a new gradient with the name name, which must be a unique name not used by another gradient created by this treectrl widget.
The following options are supported:
Deletes each gradient specified by name. If the gradient is still being used then it is not actually deleted until all elements etc using the gradient have stopped using it. A deleted-but-in-use gradient is not recognized by the various gradient commands. Creating a new gradient with the same name as a deleted-but-in-use gradient resurrects the deleted gradient.
Returns a list of names of all the gradients that have been created by this treectrl widget.
Without any arguments, this command returns a boolean indicating whether or not the platform supports native transparent gradients. The preference argument is a boolean that indicates whether native gradients should be used; this can be used to test the appearance of the application.
This command is used to manipulate column headers. The exact behavior of the command depends on the option argument that follows the header argument. The following forms of the command are supported:
See the item bbox command.
See the item compare command.
There are two forms of this command distinguished by whether or not a column description appears after the headerDesc argument. If the first argument after headerDesc begins with a '-' character it is assumed to be an option name, not a column description, in which case the command applies to the header-row. If the first argument after headerDesc does not being with a '-' it is assumed to be a column description, in which case the command applies to a header-column.
If no option is specified, returns a list describing all of the available options for the header given by headerDesc (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).
If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. This is the only case where headerDesc may refer to multiple header-rows.
The following options are supported by this command (see header create for the meaning of each option):
If no option is specified, returns a list describing all of the available options for the single column column of the header-row given by headerDesc (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).
If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. This is the only case where both headerDesc may refer to multiple header-rows and column may refer to multiple header-columns.
The following options are supported by this command (see HEADERS) for the meaning of each option):
If no additional arguments are given, the result is a decimal string giving the number of header-rows created by the header create widget command which haven't been deleted by the header delete widget command, plus 1 for the ever-present top header-row created along with the widget. If the optional argument headerDesc is given, then the result is the number of header-rows that match that header description.
Creates a new header-row and returns its unique identifier. The following configuration options are supported:
Deletes the header-rows given by the header description headerDesc. Attempts to delete the ever-present top header-row are ignored without raising an error.
There are two forms of this command distinguished by whether or not a header description appears as the first argument. If the first argument begins with a '-' character it is assumed to be an option name, not a header description, in which case the command applies to the header-drag-and-drop options for the widget. If the first argument does not being with a '-' it is assumed to be a header description, in which case the command applies to a header-row.
This command returns the current value of the header-drag-and-drop option named option for the widget. The following configuration options are supported (see header dragconfigure for the meaning of each option):
This command returns the current value of the header-drag-and-drop option named option for a header-row. The following configuration options are supported (see header dragconfigure for the meaning of each option):
There are two forms of this command distinguished by whether or not a header description appears as the first argument. If the first argument begins with a '-' character it is assumed to be an option name, not a header description, in which case the command applies to the header-drag-and-drop options for the widget. If the first argument does not being with a '-' it is assumed to be a header description, in which case the command applies to a header-row.
This command queries and sets header-drag-and-drop options for the widget, not for individual header-rows. The following configuration options are supported:
This command queries and sets header-drag-and-drop options for header-rows, not for the widget as a whole. The following configuration options are supported:
See the item element command.
This command resolves the header description headerDesc into a list of unique header-row identifiers. If headerDesc doesn't refer to any existing header-rows, then this command returns an empty list.
The behavior of this command depends on whether or not a column header was assigned a style containing an image element. If a column header has no style or no style with an image element then this command operates on the same -image option as header configure. Otherwise this command operates on the -image option of the first image element in a column header's style. See the item image command.
See the item span command.
See the item state command.
See the item style command.
The behavior of this command depends on whether or not a column header was assigned a style containing a text element. If a column header has no style or no style with a text element then this command operates on the same -text option as header configure. Otherwise this command operates on the -text option of the first text element in a column header's style. See item text.
See the item tag command.
This command returns information about the what is displayed at the given window coordinates x and y. When the -array option is used to specify the name of an array variable, elements of the array variable are set as follows:
If the coordinates are outside the window, over the borders, or over any whitespace in the window, then:
$varName(where) is ""
If the coordinates are over a column header, then:
$varName(where) is header
$varName(header) is the unique id of the header-row
$varName(column) is the unique id of the column
$varName(element) is the name of an element, or ""
$varName(side) is left or right if the coordinates are close to the edge of the column header, otherwise ""
If the coordinates are over an item, then:
$varName(where) is item
$varName(item) is the unique id of the item
$varName(column) is the unique id of the column
$varName(element) is the name of an element, or ""
$varName(button) is a boolean indicating whether or not the coordinates are over the item's expand/collapse button
$varName(line) is the unique id of an ancestor of the item (but not the parent of the item) if the coordinates are over a line descending from that ancestor. If the coordinates are not over such a line then $varName(line) is "". This is used to collapse the ancestor when the line is clicked on.
When the -array option is not used, this command returns a list describing what is displayed at the given window coordinates. The format of this list can be like one of the following:
{}
An empty list is returned if the coordinates are outside the window, over the borders, or over any whitespace in the window.
header C ?left|right?
header C elem E ?left|right?
header H column C ?left|right?
header H column C elem E ?left|right?
Only when there is more than one header-row is there a unique id of a header-row H followed by the keyword column. This is for compatibility with older versions when there was only one row of column headers allowed.
item I column C
item I column C elem E
item I button
This is the result when the coordinates are over the expand/collapse button next to an item.
item I line I2
This is the result when the coordinates are over a line descending from an ancestor I2 of the item I (but not the parent of that item). This is used to collapse the ancestor when the line is clicked on.
Deprecated. Use item id instead.
This command is used to manipulate items. The exact behavior of the command depends on the option argument that follows the item argument. The following forms of the command are supported:
Returns a list containing the item ids of the ancestors of the item specified by itemDesc. The first list value is the parent, the second is the parent's parent, an so on. The last list value will be the root item if itemDesc is a descendant of the root item.
Returns a list with four elements giving the bounding box of the item described by itemDesc. If no further argument is specified, the bbox spans the area of the item over all non-locked columns. If a column is specified, only the area of the item in this column is considered. If an additional element is specified, the area of this element in column of the specified item is returned. The returned coordinates are relative to the top-left corner of the widget. If the item is not visible for any reason, the result in an empty string.
If state is specified, this command sets the state of the expand/collapse button for the single item specified by itemDesc. The state argument may be one of active, normal or pressed. The current (or newly-set) state of the button is returned. The button state is used by the system theme, if any, to change the appearance of the button.
Returns the current value of the configuration option for the item specified by itemDesc whose name is option. Option may have any of the values accepted by the item configure command.
Returns a list containing the item ids of all children of the item specified by itemDesc in the correct order from the first child to the last child.
Switches off the open state of the item(s) described by itemDesc. If an item has descendants, then they are no longer displayed. If an item is already closed, then this command has no effect on that item. If -animate is specified, then the item's button will animate as it transitions between states if the theme supports it; in this case only one item may be specified. If -recurse is specified, then all descendants of the items described by itemDesc will also be collapsed. For every item that actually will be collapsed, two events are generated: a <Collapse-before> event before the item state is changed, and a <Collapse-after> event after the item state was changed.
From both items described by the itemDescs the index is retrieved (as returned from the item order widget command). Then these indexes are compared using the operator op, which must be either <, <=, ==, >=, >, or !=. The return value of this command is 1 if the comparison evaluated to true, 0 otherwise.
This horrible command is now deprecated. Use item element configure instead. For every column of the treectrl there may be specified one list. Each list should look like this:
{ {element option value ...} {element option value ...} ...}
Every option must be known by the element's type (see ELEMENTS AND STYLES below). Each option will be set to value for the element in this one column in this item.
If no option is specified, returns a list describing all of the available options for the item given by itemDesc (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).
If one or more option-value pairs are specified, then the command modifies the given item option(s) to have the given value(s); in this case the command returns an empty string. This is the only case where itemDesc may refer to multiple items.
The following options are supported by this command (see item create for the meaning of each option):
If no additional arguments are given, the result is a decimal string giving the number of items created by the item create widget command which haven't been deleted by the item delete widget command, plus 1 for the ever-present root item. If the optional argument itemDesc is given, then the result is the number of items that match that item description.
Creates some new items and optionally returns a list of unique identifiers for those items. The new items have the states open and enabled set by default. If the treectrl widget currently has the focus, the state focus is also set.
The following options are supported by this command:
Deletes the specified item(s). First and last must be valid item descriptions. If last isn't specified, then first may specify multiple items. If both first and last are specified, they must each decribe a single item with a common ancestor; then the range of items between first and last is deleted. The order of first and last doesn't matter.
Deleting an item deletes any child items of the deleted item recursively. If the current active item is deleted, the root item becomes the new active item. If the current selection 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.
For each call to this command, two events may be generated. If any of the deleted items are selected, then they are removed from the selection and a <Selection> event is generated just before the items are deleted. If any items are going to be deleted, then an <ItemDelete> event is generated just before the items are deleted.
Returns a list containing the item ids of the descendants of the item specified by itemDesc, i.e. the children, grandchildren, great-grandchildren etc, of the item.
Debug command. Returns a list with 4 words in the form index index indexVis indexVis.
This command is used to manipulate elements of the item. The exact behavior of the command depends on the command argument that follows the element argument. The following forms of the command are supported:
Deprecated. Use item element perstate instead.
This command returns the value of the option named option associated with element inside column of the item described by itemDesc, if it was already configured for the actual item. Option may have any of the values accepted by the type of the specified element (see ELEMENTS AND STYLES below)
This command modifies configuration options for an element in a column of an item. If no option is specified, the command returns a list describing all of the available options for the element (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified).
If one or more option-value pairs are specified, then the command modifies the given option(s) to have the given value(s) in the element inside column of the item(s) described by itemDesc; in this case the command returns an empty string. This is the only case where itemDesc may refer to multiple items.
It is possible to configure multiple elements in multiple columns with a single call. To configure another element in the same column, append a '+' argument followed by the element name. To configure elements in another column, append a ',' argument followed by the column. For example:
.t item element configure $I \ $C1 $E1 -text "hello" + $E2 -text "world" , \ $C2 $E3 -fill Blue , \ $C3 $E1 -text "apples and oranges"
Each of the column description arguments to this command may refer to multiple columns if at least one option-value pair is given.
This command returns the current value of the per-state option named option for element inside column of the item described by itemDesc. If stateList is specified, the list of state names (static and dynamic, see STATES) is used in place of the current state for item and column.
Returns 1 if the item described by itemDesc has the state enabled switched on, 0 otherwise. If boolean is specified, then the enabled state of every item described by the item description itemDesc is set accordingly. New items are enabled by default when created. Disabled items cannot be selected, and are ignored by the default key-navigation and mouse bindings.
Switches on the open state of the item(s) described by itemDesc. If an item has descendants, then they are now displayed. If an item is already open, then this command has no effect on that item. If -animate is specified, then the item's button will animate as it transitions between states if the theme supports it; in this case only one item may be specified. If -recurse is specified, then all descendants of the items described by itemDesc will also be expanded. For every item that actually will be expanded, two events are generated: an <Expand-before> event before the item state is changed, and an <Expand-after> event after the item state was changed.
If child is not specified, returns the item id of the first child of the item described by parent. If child is specified, it must describe an item that is neither the root item nor an ancestor of parent. Then it will become the new first child of parent.
This command resolves the item description itemDesc into a list of unique item identifiers. If itemDesc doesn't refer to any existing items, then this command returns an empty list.
This command sets or retrieves the value of the per-state -image option for the first image element in one or more columns. If no column is specified, this command returns a list of values, one per column. If no image is specified, this command returns the value for column.
If one or more column-image pairs is specified, then the value of the -image option in each column is set to image. In this case itemDesc may refer to multiple items and each column may refer to multiple columns.
Note that this command is provided as a convenience. Use the item element configure or item element cget commands if you want to set or retrieve the value of the -image option for a specific image element.
Returns 1 if the item described by itemDesc is a direct or indirect parent of the item decribed by descendant, 0 otherwise.
Returns 1 if the item described by itemDesc has the state open switched on, 0 otherwise.
If child is not specified, returns the item id of the last child of the item described by parent. If child is specified, it must describe an item that is not an ancestor of parent. Then it will become the new last child of parent.
If next is not specified, returns the item id of the next sibling of the item described by sibling. If next is specified, it must describe an item that is not an ancestor of sibling. Then it will become the new next sibling of sibling.
Returns the number of children of the item described by itemDesc.
This command returns the position of the item itemDesc relative to its toplevel ancestor (usually the root item, unless the ancestor is an orphan). If you imagine all the items flattened into a vertical list, the result of this command is the row the item falls in. If the optional argument -visible is given, only the items whose ancestors are expanded, and whose -visible option is true, get counted; in this case -1 is returned if the item is not visible.
Returns the item id of the parent of the item described by itemDesc.
If prev is not specified, returns the item id of the previous sibling of the item described by sibling. If prev is specified, it must describe an item that is not an ancestor of sibling. Then it will become the new previous sibling of sibling.
Returns a list containing the item ids of all items in the range between first and last, inclusive. The order between first and last doesn't matter, and the result is always sorted by the increasing order of the items (as returned by the item order command). The items specified by first and last must share a common ancestor.
Removes the item described by itemDesc from the list of children of its parent, so that it will become an orphan.
Returns a list of two integers, which corresponds to the row and column of the item described by itemDesc. The row and column corresponds to the on-screen arrangement of items as determined by the -orient and -wrap options. If the item is not displayed, this command returns an empty string.
Sorts the children of the item described by itemDesc, and redisplays the tree with the items in the new order.
The range of items which should be sorted can be restricted by means of the -first and/or -last options, which should be children of the item described by itemDesc; the order between these two limiting items doesn't matter.
The sort column can be specified by means of the -column option; this option can be used repeatedly to define a multicolumn sort. The sorting is done by looking at the text of the element specified by the -element option, which must be a text element defined in the style of the sorting column, by default the first text element is used.
If the -notreally option is specified, no rearranging of the items is done; instead the sorted items are returned as result of the command.
By default ASCII sorting is used with the result returned in increasing order. Any of the following options may be specified to control the sorting process of the previously specified column (unique abbreviations are accepted):