'\" '\" Copyright (c) 2004 Joe English '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" .TH ttk::treeview n 9.1 Tk "Tk Themed Widget" .\" The -*- nroff -*- definitions below are for supplemental macros used .\" in Tcl/Tk manual entries. .\" .\" .AP type name in/out ?indent? .\" Start paragraph describing an argument to a library procedure. .\" type is type of argument (int, etc.), in/out is either "in", "out", .\" or "in/out" to describe whether procedure reads or modifies arg, .\" and indent is equivalent to second arg of .IP (shouldn't ever be .\" needed; use .AS below instead) .\" .\" .AS ?type? ?name? .\" Give maximum sizes of arguments for setting tab stops. Type and .\" name are examples of largest possible arguments that will be passed .\" to .AP later. If args are omitted, default tab stops are used. .\" .\" .BS .\" Start box enclosure. From here until next .BE, everything will be .\" enclosed in one large box. .\" .\" .BE .\" End of box enclosure. .\" .\" .CS .\" Begin code excerpt. .\" .\" .CE .\" End code excerpt. .\" .\" .VS ?version? ?br? .\" Begin vertical sidebar, for use in marking newly-changed parts .\" of man pages. The first argument is ignored and used for recording .\" the version when the .VS was added, so that the sidebars can be .\" found and removed when they reach a certain age. If another argument .\" is present, then a line break is forced before starting the sidebar. .\" .\" .VE .\" End of vertical sidebar. .\" .\" .DS .\" Begin an indented unfilled display. .\" .\" .DE .\" End of indented unfilled display. .\" .\" .SO ?manpage? .\" Start of list of standard options for a Tk widget. The manpage .\" argument defines where to look up the standard options; if .\" omitted, defaults to "options". The options follow on successive .\" lines, in three columns separated by tabs. .\" .\" .SE .\" End of list of standard options for a Tk widget. .\" .\" .OP cmdName dbName dbClass .\" Start of description of a specific option. cmdName gives the .\" option's name as specified in the class command, dbName gives .\" the option's name in the option database, and dbClass gives .\" the option's class in the option database. .\" .\" .UL arg1 arg2 .\" Print arg1 underlined, then print arg2 normally. .\" .\" .QW arg1 ?arg2? .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). .\" .\" .PQ arg1 ?arg2? .\" Print an open parenthesis, arg1 in quotes, then arg2 normally .\" (for trailing punctuation) and then a closing parenthesis. .\" .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l \n(.l .ad b .\" # Start an argument description .de AP .ie !"\\$4"" .TP \\$4 .el \{\ . ie !"\\$2"" .TP \\n()Cu . el .TP 15 .\} .ta \\n()Au \\n()Bu .ie !"\\$3"" \{\ \&\\$1 \\fI\\$2\\fP (\\$3) .\".b .\} .el \{\ .br .ie !"\\$2"" \{\ \&\\$1 \\fI\\$2\\fP .\} .el \{\ \&\\fI\\$1\\fP .\} .\} .. .\" # define tabbing values for .AP .de AS .nr )A 10n .if !"\\$1"" .nr )A \\w'\\$1'u+3n .nr )B \\n()Au+15n .\" .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n .nr )C \\n()Bu+\\w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out .\" # BS - start boxed text .\" # ^y = starting y location .\" # ^b = 1 .de BS .br .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n \l'\\n(.lu\(ul' .if n .fi .. .\" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n \l'\\n(^lu\(ul' .el \{\ .\" Draw four-sided box normally, but don't draw top of .\" box if the box started on an earlier page. .ie !\\n(^b-1 \{\ \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .el \}\ \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' .\} .\} .fi .br .nr ^b 0 .. .\" # VS - start vertical sidebar .\" # ^Y = starting y location .\" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"\\$2"" .br .mk ^Y .ie n 'mc \s12\(br\s0 .el .nr ^v 1u .. .\" # VE - end of vertical sidebar .de VE .ie n 'mc .el \{\ .ev 2 .nf .ti 0 .mk ^t \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' .sp -1 .fi .ev .\} .nr ^v 0 .. .\" # Special macro to handle page bottom: finish off current .\" # box/sidebar if in box/sidebar mode, then invoked standard .\" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if \\n(^b \{\ .\" Draw three-sided box if this is the box's first page, .\" draw two sides but no top otherwise. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c .\} .if \\n(^v \{\ .nr ^x \\n(^tu+1v-\\n(^Yu \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c .\} .bp 'fi .ev .if \\n(^b \{\ .mk ^y .nr ^b 2 .\} .if \\n(^v \{\ .mk ^Y .\} .. .\" # DS - begin display .de DS .RS .nf .sp .. .\" # DE - end display .de DE .fi .RE .sp .. .\" # SO - start of list of standard options .de SO 'ie '\\$1'' .ds So \\fBoptions\\fR 'el .ds So \\fB\\$1\\fR .SH "STANDARD OPTIONS" .LP .nf .ta 5.5c 11c .ft B .. .\" # SE - end of list of standard options .de SE .fi .ft R .LP See the \\*(So manual entry for details on the standard options. .. .\" # OP - start of full description for a single option .de OP .LP .nf .ta 4c Command-Line Name: \\fB\\$1\\fR Database Name: \\fB\\$2\\fR Database Class: \\fB\\$3\\fR .fi .IP .. .\" # CS - begin code excerpt .de CS .RS .nf .ta .25i .5i .75i 1i .. .\" # CE - end code excerpt .de CE .fi .RE .. .\" # UL - underline word .de UL \\$1\l'|0\(ul'\\$2 .. .\" # QW - apply quotation marks to word .de QW .ie '\\*(lq'"' ``\\$1''\\$2 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\$2 .. .\" # PQ - apply parens and quotation marks to word .de PQ .ie '\\*(lq'"' (``\\$1''\\$2)\\$3 .\"" fix emacs highlighting .el (\\*(lq\\$1\\*(rq\\$2)\\$3 .. .\" # QR - quoted range .de QR .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 .\"" fix emacs highlighting .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 .. .\" # MT - "empty" string .de MT .QW "" .. .BS .SH NAME ttk::treeview \- hierarchical multicolumn data display widget .SH SYNOPSIS \fBttk::treeview \fIpathname \fR?\fIoptions\fR? .BE .SH DESCRIPTION .PP The \fBttk::treeview\fR widget displays a hierarchical collection of items. Each item has a textual label, an optional image, and an optional list of data values. The data values are displayed in successive columns after the tree label as cells. The order in which data values are displayed may be controlled by setting the \fB\-displaycolumns\fR widget option. The tree widget can also display column headings. Columns may be accessed by number or by symbolic names listed in the \fB\-columns\fR widget option; see \fBCOLUMN IDENTIFIERS\fR. Treeview widgets support horizontal and vertical scrolling with the standard \fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options and [\fBxy\fR]\fBview\fR widget commands. .PP Each item is identified by a unique name. The widget will generate item IDs if they are not supplied by the caller. There is a distinguished root item, named \fB{}\fR. The root item itself is not displayed; only its children appear at the top level of the hierarchy. Cell ids are a 2-value list consisting of the item id and column id. Items and cells may also be associated with 0 or more tags. Tags are used to associate event bindings with individual items/cells and to control their appearance. Items and cells can be selected depending on the \fB-selectmode\fR and \fB-selecttype\fR widget options. The item and cell focus determines which item or cell receives the keyboard focus for navigation between items and cells and for selection changes. .PP .SO ttk_widget \-class \-cursor \-takefocus \-style \-xscrollcommand \-yscrollcommand \-padding .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-columns columns Columns A list of column identifiers, specifying the number of columns and their names. .\"X: This is a read-only option; it may only be set when the widget is created. .OP \-displaycolumns displayColumns DisplayColumns A list of column identifiers (either symbolic names or integer indices) specifying which columns are to be displayed and the order in which they appear, or the string \fB#all\fR to display all columns in \fB-columns\fR order. The default is \fB#all\fR. .OP \-headingheight headingHeight Height Specifies the heading height in pixels. The default value is auto calculated based on the theme and font. It can be overridden by this option until the next theme or font change. It can be permanently overridden via ttk::style option: \fBttk::style configure Treeview -headingheight \fIpixels\fR. .OP \-height height Height Specifies the number of rows which should be visible. Note that the requested width is determined from the sum of the column widths. .OP \-rowheight rowHeight Height Specifies the row height in pixels. The default value is auto calculated based on the theme and font. It can be overridden by this option until the next theme or font change. It can be permanently overridden via ttk::style option: \fBttk::style configure Treeview -rowheight \fIpixels\fR. .OP \-selectmode selectMode SelectMode Controls how the built-in class bindings manage the selection. Options are: .RS .PP .IP \fBnone\fR The selection cannot be changed. Focus and item/cell navigation is still allowed. .IP \fBbrowse\fR Only one item or cell will be selected at a time. Items and cells are selected via Button-1 press. Selecting an item/cell deselects all other items/cells. The selection follows the mouse when Button 1 is kept pressed. The selection follows the focus during keyboard traversal. In this mode, the selection cannot be removed via the keyboard bindings. .IP \fBsingle\fR Only a single item or cell can be selected at a time. Items and cells are selected via Button-1 press. Selecting an item/cell deselects all other items/cells. The selection follows the focus during keyboard traversal. The selection can be cleared via the keyboard bindings. .IP \fBmultiple\fR Multiple items or cells can be selected. The selection state of items and cells is toggled via a Button-1 press. Selecting an item/cell does not change the selection state of other items/cells. In this mode, the focus and selection are independent which allows for keyboard traversal to change the focus without changing the selection. The selection can be cleared via the keyboard bindings. .IP \fBextended\fR Multiple items or cells can be selected, but the default is for only one item/cell to be selected at a time. More items can be selected by extending the selection using the Shift and Control/Command keys in combination with Button 1 press or keyboard traversal. The selection follows the focus during keyboard traversal. The selection can be cleared via the keyboard bindings. This is the default. .PP Note that application code and tag bindings can set the selection however they wish, regardless of the value of \fB\-selectmode\fR. .RE .OP \-selecttype selectType SelectType Controls how the built-in class bindings manage the selection. Options are \fBitem\fR or \fBcell\fR. The selection should be cleared before switching modes. The \fBCheckTreeview\fR style works best with \fBitem\fR select type. .OP \-show show Show Controls which elements of the tree to display. May be a list containing zero or more of the following values. The default is \fBtree headings\fR. .RS .IP \fBtree\fR Display tree labels in column #0. .IP \fBheadings\fR Display the heading row. .PP \fBNOTE:\fR Column #0 always refers to the tree column, even if \fB\-show tree\fR is not specified. .RE .OP \-striped striped Striped Boolean specifying zebra striped item coloring. Note that striped items uses the \fB\-stripedbackground\fR option if set by the theme or a tag. If not supported by the current theme, it will not show. .OP \-titlecolumns titleColumns TitleColumns Number of display columns at the left that should not be scrolled. The tree column counts, even if \fB\-show tree\fR is not specified. Thus for value N of this option, column #N is the first one that is scrollable. The default is 0. .OP \-titleitems titleItems TitleItems Number of items at the top that should not be vertically scrolled. The default is 0. .SH "INDICES" .PP Several of the widget subcommands use an index as their argument. An index specifies a particular child item within it's parent, using any of the following forms: .IP \fInumber\fR 12 Specifies the numerical index of a child within its parent, where 0 corresponds to the first item. .IP \fBend\fR 12 Indicates the end of the list of children. For most subcommands this refers to the last child, but for a few such as \fBindex\fR, \fBinsert\fR, and \fBmove\fR it refers to the item just after the last one. .IP \fBfirst\fR 12 Indicates the first child in the list of children. .IP \fBlast\fR 12 Indicates the last child in the list of children. .IP \fBend-\fIn\fR 12 Indicates the item at position \fIn\fR relative to the end where \fBend-1\fR is the last item in the list of children. .IP \fIm\fB-\fIn\fR or \fIm\fB+\fIn\fR 12 Indicates the item at position \fIn\fR relative to index \fIm\fR. See \fBstring index\fR for valid forms. .SH "COLUMN IDENTIFIERS" Column identifiers take any of the following forms: .IP \(bu A symbolic name from the list defined by \fB\-columns\fR option. .IP \(bu An integer \fIn\fR, specifying the \fIn\fRth data column. This is an index corresponding to the columns in the \fB\-columns\fR option and the value is taken from the item's \fB-values\fR option. .IP \(bu A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, specifying the \fIn\fRth display column. Column \fB#0\fR is always the tree column even if not shown. The subsequent columns are defined by the \fB\-displaycolumns\fR option. For example, \fB#1\fR is the first column in \fB\-displaycolumns\fR. .IP \(bu In the form of \fBend-\fIn\fR, specifying the \fIn\fRth display column from the end, where \fBend-1\fR is the last displayed column. .IP \(bu In the form of \fIm\fB-\fIn\fR or \fIm\fB+\fIn\fR for the \fIn\fRth data column relative to column \fIm\fR. See \fBstring index\fR for valid forms. .PP .SH "WIDGET COMMAND" In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBinstate\fR, \fBstate\fR, \fBstyle\fR, \fBxview\fR and \fByview\fR subcommands (see \fBttk::widget\fR), treeview widgets support the following additional subcommands: .\" METHOD: after .TP \fIpathname \fBafter\fR ?\fB-hidden\fR? ?\fB-norecurse\fR? \fIitem\fR . Returns the identifier of the item after \fIitem\fR in the current view. It can be the first child, next sibling, next sibling of an ancestor, or {} for none. Use \fB-hidden\fR to include hidden items and \fB-nohidden\fR (default) to exclude them. Use \fB-recurse\fR to include descendants/ancestors of \fIitem\fR (default) and \fB-norecurse\fR to exclude them. If both \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. The \fBnext\fR method is equivalent to "\fBafter -hidden -norecurse\fR" .\" METHOD: bbox .TP \fIpathname \fBbbox\fR \fIitem\fR ?\fIcolumn\fR? . Returns the bounding box (relative to the treeview widget's window) of the specified \fIitem\fR in the form \fIx y width height\fR. If the \fIitem\fR is not visible (i.e., if it is a descendant of a closed item or is vertically scrolled offscreen), returns the empty list. If \fIcolumn\fR is specified and is not hidden (by the \fB\-displaycolumns\fR option), returns the bounding box of that cell within \fIitem\fR (even if the cell is horizontally scrolled offscreen). .TP \fIpathname \fBbbox {*}\fIcell\fR . Same as previous subcommand, but uses the expand operator to convert \fIcell\fR into item and column components. .\" METHOD: before .TP \fIpathname \fBbefore\fR ?\fB-hidden\fR? ?\fB-norecurse\fR? \fIitem\fR . Returns the identifier of the item before \fIitem\fR in the current view. It can be the previous sibling, parent of \fIitem\fR, or {} for none. Use \fB-hidden\fR to include hidden items and \fB-nohidden\fR (default) to exclude them. Use \fB-recurse\fR to include descendants/ancestors of \fIitem\fR (default) and \fB-norecurse\fR to exclude them. If both \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. The \fBprev\fR method is equivalent to "\fBbefore -hidden -norecurse\fR" .\" METHOD: cellfocus .TP \fIpathname \fBcellfocus\fR ?\fIcell\fR? . Sets the cell focus to \fIcell\fR. Use \fB{}\fR to clear the focus cell. Without \fIcell\fR, returns the current focus cell id or \fB{}\fR if none. .\" METHOD: cellselection .TP \fIpathname \fBcellselection\fR ?\fIselop arg ...\fR? . Manages cell selection. The cell selection is independent from the item selection handled by the \fBselection\fR subcommand. A cell is specified by a list of two elements, the item and the column. For the rectangle versions of these subcommands, the cells must be in displayed columns. Any change to \fB\-columns\fR clears the cell selection. A \fIcellList\fR argument may be a single cell or a list of cells. If \fIselop\fR is not specified, returns a list of selected cells. Otherwise, \fIselop\fR is one of the following: .RS .TP \fIpathname \fBcellselection add \fIcellList\fR . Adds cells \fIcellList\fR to the cell selection. .TP \fIpathname \fBcellselection add\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIcellFirst cellLast\fR . Add the cells within the rectangle defined by \fIcellFirst\fR and \fIcellLlast\fR to the cell selection. With \fB-nohidden\fR, hidden cells will be excluded and with \fB-norecurse\fR, cell in descendant items will be excluded. .TP \fIpathname \fBcellselection anchor\fR ?\fIcell\fR? . Sets the cell selection anchor to \fIcell\fR. The anchor is used as the cellFirst for the selection extend bindings. Without \fIcell\fR, the current cell selection anchor is returned. Use empty string \fB{}\fR to unset the anchor. .TP \fIpathname \fBcellselection has \fIcellList\fR . Returns 1 if cell selection includes all of the cells in \fIcellList\fR or 0 if any are not selected. .TP \fIpathname \fBcellselection includes \fIcellList\fR . Returns 1 if cell selection includes all of the cells in \fIcellList\fR or 0 if any are not selected. .TP \fIpathname \fBcellselection present\fR . Returns 1 if there are selected cells or 0 if none. .TP \fIpathname \fBcellselection remove \fIcellList\fR . Remove each cell in \fIcellList\fR from the cell selection. .TP \fIpathname \fBcellselection remove\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIcellFirst cellLast\fR . Remove the cells within the rectangle defined by \fIcellFirst\fR and \fIcellLast\fR from the cell selection. With \fB-nohidden\fR, hidden cells will be excluded and with \fB-norecurse\fR, cell in descendant items will be excluded. .TP \fIpathname \fBcellselection set \fIcellList\fR . Sets the selection to the cells in \fIcellList\fR. All other cells are unselected. Use an empty set \fB{}\fR to clear the selection. .TP \fIpathname \fBcellselection set\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIcellFirst cellLast\fR . Set the selection to the cells within the rectangle defined by \fIcellFirst\fR and \fIcellLast\fR. All other cells are unselected. With \fB-nohidden\fR, hidden cells will be excluded and with \fB-norecurse\fR, cell in descendant items will be excluded. .TP \fIpathname \fBcellselection size\fR . Returns the count of selected cells. .TP \fIpathname \fBcellselection toggle \fIcellList\fR . Toggle the cell selection state of each cell in \fIcellList\fR. If the element is partially visible, the result gives the full area of the element, including any parts that are not visible. .TP \fIpathname \fBcellselection toggle\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIcellFirst cellLast\fR . Toggle the selection state of the cells within the rectangle defined by \fIcellFirst\fR and \fIcellLast\fR. With \fB-nohidden\fR, hidden cells will be excluded and with \fB-norecurse\fR, cell in descendant items will be excluded. .RE .\" METHOD: children .TP \fIpathname \fBchildren \fIitem\fR ?\fInewchildren\fR? . If \fInewchildren\fR is not specified, returns the list of children belonging to \fIitem\fR. If \fInewchildren\fR is specified, replaces \fIitem\fR's child list with \fInewchildren\fR. Items in the old child list not present in the new child list are detached from the tree. None of the items in \fInewchildren\fR may be an ancestor of \fIitem\fR. .\" METHOD: collapse .TP \fIpathname \fBcollapse\fR ?\fI\-recurse\fR? \fIitemList\fR . Sets all of the items in \fIitemList\fR to closed state. Same as "\fIpathname \fBitem \fIitem \fB\-open 0\fR" for each item in \fIitemList\fR. With the \fI\-recurse\fR option, will also close all of their descendants. Use \fB{}\fR for root item. .\" METHOD: column .TP \fIpathname \fBcolumn \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? . Query or modify the options for the specified \fIcolumn\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the options are updated with the specified values. The following options may be set on each column: .RS .\" OPTION: -id .TP \fB\-id \fIname\fR . The column name. This is a read-only option. For example, [\fI$pathname \fBcolumn #\fIn \fB\-id\fR] returns the data column associated with display column \fIn\fR. The tree column has \fB\-id #0\fR. .\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR . Specifies how the text in this column should be aligned with respect to the cell. \fIAnchor\fR is one of \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. See \fBTk_GetAnchor\fR for more information. .\" OPTION: -minwidth .TP \fB\-minwidth \fIminwidth\fR . The minimum width of the column in pixels. The treeview widget will not make the column any smaller than \fB\-minwidth\fR when the widget is resized or the user drags a heading column separator. The default is 20 pixels. .\" OPTION: -separator .TP \fB\-separator \fIboolean\fR . Specifies whether or not a column separator should be drawn to the right of the column. The default is false. .\" OPTION: -stretch .TP \fB\-stretch \fIboolean\fR . Specifies whether or not the column width should be adjusted when the widget is resized or the user drags a heading column separator. \fIBoolean\fR may have any of the forms accepted by \fBTcl_GetBoolean\fR. By default columns are stretchable. .\" OPTION: -width .TP \fB\-width \fIwidth\fR . The width of the column in pixels. The default is 200 pixels. The specified column width may be changed by Tk in order to honor \fB\-stretch\fR and/or \fB\-minwidth\fR, or when the widget is resized or the user drags a heading column separator. .PP Use \fIpathname \fBcolumn #0\fR to configure the tree column. .RE .\" METHOD: current .TP \fIpathname \fBcurrent\fR . Returns the current item id and column id, if any, or {} if none. The current item is the item under the mouse pointer. It can be used in the \fB\fR and \fB\fR event handlers to get the item and column for the event. .\" METHOD: delete .TP \fIpathname \fBdelete \fIitemList\fR . Deletes each of the items in \fIitemList\fR and all of their descendants. The root item may not be deleted. See also: \fBdetach\fR. .\" METHOD: depth .TP \fIpathname \fBdepth \fIitem\fR . Returns the number of levels between \fIitem\fR and the root item. .\" METHOD: detach .TP \fIpathname \fBdetach \fIitemList\fR . Unlinks all of the specified items in \fIitemList\fR from the tree. The items and all of their descendants are still present and may be reinserted at another point in the tree with the \fBchildren\fR or \fBmove\fR operations, but will not be displayed until that is done. The root item may not be detached. See also: \fBdelete\fR. .\" METHOD: detached .TP \fIpathname \fBdetached\fR ?\fB\-all\fR|\fIitem\fR? . Without any arguments, returns a list of all detached items, but not their descendants, in an arbitrary order. If \fIitem\fR is provided, returns a Boolean value indicating whether \fIitem\fR or an ancestor is detached or not. If \fB\-all\fR is specified, returns a list of all the detached items and their descendants in an arbitrary order. The root item is never detached. .\" METHOD: exists .TP \fIpathname \fBexists \fIitem\fR . Returns 1 if the specified \fIitem\fR is present in the tree, 0 if not. .\" METHOD: expand .TP \fIpathname \fBexpand\fR ?\fI\-recurse\fR? \fIitemList\fR . Set all of the items in \fIitemList\fR to open state. Same as "\fIpathname \fBitem \fIitem \fB\-open 1\fR" for each item in \fIitemList\fR. With the \fI\-recurse\fR option, will also open all of their descendants. Use \fB{}\fR for root item. .\" METHOD: focus .TP \fIpathname \fBfocus \fR?\fIitem\fR? . Sets the focus item to \fIitem\fR. Use \fB{}\fR to clear focus item. Without \fIitem\fR, returns the current focus item id or \fB{}\fR if none. .\" METHOD: haschildren .TP \fIpathname \fBhaschildren \fIitem\fR . Returns 1 if \fIitem\fR has children, 0 if not. .\" METHOD: heading .TP \fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? . Query or modify the heading options for the specified \fIcolumn\fR. Valid options are: .RS .\" OPTION: -anchor .TP \fB\-anchor \fIanchor\fR . Specifies how the heading text should be aligned. See \fBTk_GetAnchor\fR for valid values. .\" OPTION: -command .TP \fB\-command \fIscript\fR . A script to evaluate when the heading label is pressed. .PP Use \fIpathname heading #0\fR to configure the tree column heading. .\" OPTION: -image .TP \fB\-image \fIimageName\fR . Specifies an image to display to the right of the column heading. Ignored by Mac Aqua theme. .\" OPTION: -text .TP \fB\-text \fItext\fR . The text to display in the column heading. .\" OPTION: state .TP \fBstate \fIstateSpec\fR . Modify or inquire about heading state. If \fIstateSpec\fR is present, sets the widget state: for each flag in stateSpec, sets the corresponding flag or clears it if prefixed by an exclamation point. To use the default sort direction indicator, set the heading to \fBuser1\fR state plus either \fBselected\fR for descending sorts or \fBalternate\fR for ascending sorts. Remember to clear the states when a new heading is to be used as the sort column. Themes may set and use other states as needed for visual effects. .RE .\" METHOD: hide .TP \fIpathname \fBhide\fR ?\fI\-recurse\fR? \fIitemList\fR . Hide all of the items in \fIitemList\fR and all child items. Same as "\fIpathname \fBitem \fIitem \fB\-hidden 1\fR" for each item in \fIitemList\fR. With the \fI\-recurse\fR option, will also hide all of their descendants. Use \fB{}\fR for root item. .\" METHOD: identifier .TP \fIpathname \fBidentifier \fIitem index\fR . Returns the identifier of the item at \fIindex\fR within \fIitem\fR's list of children. See \fBINDICES\fR for valid forms of \fIindex\fR. .\" METHOD: identify .TP \fIpathname \fBidentify \fIcomponent x y\fR . Returns a description of the specified \fIcomponent\fR under the point given by \fIx\fR and \fIy\fR, or the empty string if no such \fIcomponent\fR is present at that position. The values \fIx\fR and \fIy\fR may have any of the forms acceptable to \fBTk_GetPixels\fR. The following subcommands are supported: .RS .TP \fIpathname \fBidentify region \fIx y\fR .RS Returns one of: .IP heading Tree heading area; use [\fBpathname identify column \fIx y\fR] to determine the heading number. .IP separator Space between two column headings; [\fBpathname identify column \fIx y\fR] will return the display column identifier of the heading to left of the separator. .IP tree The tree area. .IP cell A data cell. .RE .TP \fIpathname \fBidentify item \fIx y\fR . Returns the identifier of the item at position \fIx,y\fR. .TP \fIpathname \fBidentify column \fIx y\fR . Returns the display column identifier of the cell at position \fIx,y\fR. The tree column has ID \fB#0\fR. .TP \fIpathname \fBidentify cell \fIx y\fR . Returns the cell identifier of the cell at position \fIx,y\fR. A cell identifier is a list of item ID and column ID. .TP \fIpathname \fBidentify element \fIx y\fR . The element at position \fIx,y\fR. .TP \fIpathname \fBidentify row \fIx y\fR . Obsolescent synonym for \fIpathname \fBidentify item\fR. .PP See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns and data columns. .RE .\" METHOD: index .TP \fIpathname \fBindex \fIitem ?index?\fR . Returns the numeric index of \fIitem\fR within its parent's list of children or if \fIindex\fR is specified, the index of the item at \fIindex\fR in \fIitem\fR's list of children. See \fBINDICES\fR for valid forms of \fIindex\fR. .\" METHOD: insert .TP \fIpathname \fBinsert \fIparent index\fR ?\fB\-id \fIid\fR? \fIoptions...\fR . Creates a new item, inserts it in \fIparent\fR's children at position \fIindex\fR, and returns its identifier. See \fBITEM OPTIONS\fR for the list of available options. Use the empty string \fB{}\fR for \fIparent\fR to create a new top-level item. See \fBINDICES\fR for valid forms of \fIindex\fR. If \fIindex\fR is negative or zero, the new item is inserted at the beginning; if \fIindex\fR is greater than or equal to the current number of children, it is inserted at the end. If \fB\-id\fR is specified, then \fIid\fR is used as the identifier of the item; \fIid\fR must not already exist in the tree. Otherwise, a new unique identifier is generated. .TP \fIpathname \fBinsert before\fR|\fBafter\fR \fIitem\fR ?\fB\-id \fIid\fR? \fIoptions...\fR . Creates a new item, inserts it in \fIitem\fR's parent before or after \fIitem\fR, and returns its identifier. See \fBITEM OPTIONS\fR for the list of available options. If \fB\-id\fR is specified, it is used as the identifier of the item; \fIid\fR must not already exist in the tree. Otherwise, a new unique identifier is generated. .\" METHOD: item .TP \fIpathname \fBitem \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? . Query or modify the options for the specified \fIitem\fR. If no \fI\-option\fR is specified, returns a dictionary of option/value pairs. If a single \fI\-option\fR is specified, returns the value of that option. Otherwise, the item's options are updated with the specified values. See \fBITEM OPTIONS\fR for the list of available options. .\" METHOD: move .TP \fIpathname \fBmove \fIitem parent index\fR . Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children. If \fIindex\fR is negative or zero, \fIitem\fR is moved to the beginning; if greater than or equal to the number of children, it is moved to the end. See \fBINDICES\fR for valid forms of \fIindex\fR. It is illegal to move an item under one of its descendants. .TP \fIpathname \fBmove \fIitem\fR \fBbefore\fR|\fBafter\fR \fIotherItem\fR . Moves \fIitem\fR to before or after \fIotherItem\fR in \fIotherItem\fR's parent's children. It is illegal to move an item under one of its descendants. .\" METHOD: next .TP \fIpathname \fBnext \fIitem\fR . Returns the identifier of \fIitem\fR's next sibling, or \fB{}\fR if \fIitem\fR is the last child of its parent. .\" METHOD: parent .TP \fIpathname \fBparent \fIitem\fR . Returns the ID of the parent of \fIitem\fR, or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. .\" METHOD: prev .TP \fIpathname \fBprev \fIitem\fR . Returns the identifier of \fIitem\fR's previous sibling, or \fB{}\fR if \fIitem\fR is the first child of its parent. .\" METHOD: range .TP \fIpathname \fBrange\fR ?\fB-hidden\fR? ?\fB-norecurse\fR? \fIfirst last\fR . Returns a list of items from \fIfirst\fR through \fIlast\fR, inclusive. Use \fB-hidden\fR to include hidden items and \fB-nohidden\fR (default) to exclude them. Use \fB-recurse\fR to include descendants/ancestors of \fIitem\fR (default) and \fB-norecurse\fR to exclude them. If both \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. .\" METHOD: search .TP \fIpathname \fBsearch \fIparent\fR ?\fI\-option ...\fR? \fIpattern\fR . Searches within \fIparent\fR's children for \fIpattern\fR and returns the identifier of the first match. Valid options are: .RS Comparisons .RS .\" OPTION: -ascii .TP \fB\-ascii\fR . The values are to be compared to \fIpattern\fR as Unicode strings (the name is for backward-compatibility reasons.) This is the default. .\" OPTION: -dictionary .TP \fB\-dictionary\fR . The values are to be compared to \fIpattern\fR using dictionary-style comparisons. For search, this is the same as \fB-ascii\fR but also sets \fB-nocase\fR. NOTE: This means I18n and I018N are not the same. .\" OPTION: -integer .TP \fB\-integer\fR . The values are to be compared to \fIpattern\fR as integers. Empty values will be ignored, but non-numeric values will generate an error. .\" OPTION: -nocase .TP \fB\-nocase\fR . Comparisons are to be performed in a case-insensitive manner. Only used with \fB\-ascii\fR and \fB-dictionary\fR options for the \fB-exact\fR, \fB-glob\fR, and \fB-regexp\fR matching. .\" OPTION: -real .TP \fB\-real\fR . The values are to be compared to \fIpattern\fR as floating-point values. Empty values will be ignored, but non-numeric values will generate an error. .\" OPTION: -unicode .TP \fB\-unicode\fR . Alias for \fB-ascii\fR. .RE Direction .RS .\" OPTION: -backwards .TP \fB\-backwards\fR . The search is to be performed backwards starting from \fB\-start\fR item or cell. .\" OPTION: -forwards .TP \fB\-forwards\fR . The search is to be performed forwards starting from \fB\-start\fR item or cell. This is the default. .RE Pattern Matching .RS .\" OPTION: -exact .TP \fB\-exact\fR . \fIPattern\fR is a literal string that is compared for exact equality against each cell value. Used with \fB-ascii\fR and \fB-dictionary\fR options. This is the default. .\" OPTION: -glob .TP \fB\-glob\fR . \fIPattern\fR is a glob-style pattern which is matched against each cell value using the same rules as the \fBstring match\fR command. Used with \fB-ascii\fR and \fB-dictionary\fR options. .\" OPTION: -regexp .TP \fB\-regexp\fR . \fIPattern\fR is an advanced regular expression that is matched against each cell value using the rules described in the \fBre_syntax\fR reference page. Used with \fB-ascii\fR and \fB-dictionary\fR options. .RE Search Modifiers .RS .\" OPTION: -column .TP \fB\-columns \fIcolumns\fR . Limit search to only the columns specified in \fIcolumns\fR list. The default is to search in all displayed columns. See \fBCOLUMN IDENTIFIERS\fR for valid forms of \fIcolumn\fR. .\" OPTION: -hidden .TP \fB\-hidden\fR . Search within hidden and closed items too. The default is to exclude hidden and descendants of closed items from the search. .\" OPTION: -recurse .TP \fB\-recurse\fR . Search within all descendants of \fIparent\fR. The default is to only search within the children of \fIparent\fR. .\" OPTION: -start .TP \fB\-start \fIitem\fR|\fIcell\fR . Start the search at \fIitem\fR or if the \fB-cell\fR option is also specified, then start the search at \fIcell\fR. The default start item and cell when used with the \fB-forwards\fR option is the first child of \fIparent\fR and the first display column. For the \fB-backwards\fR option, the default is the last child of \fIparent\fR (or descendant when used with \fB-recurse\fR) and the last display column. The \fIitem\fR or \fIcell\fR must be a descendant of \fIparent\fR. When resuming a search, use the \fBbefore\fR or \fBafter\fR subcommands to get the previous or next item to start the search at. All other options should be the same as the initial search including \fIparent\fR. .\" OPTION: -stop .TP \fB\-stop \fIitem\fR|\fIcell\fR . Stop the search at \fIitem\fR or if the \fB-cell\fR option is also specified, then stop the search at \fIcell\fR. The default stop item and cell when used with the \fB-forwards\fR option is the last child of \fIparent\fR (or descendant when used with \fB-recurse\fR) and the last display column. For the \fB-backwards\fR option, the default is the first child of \fIparent\fR and the first display column. When used with the \fB-wraparound\fR option, the default is just before the start item or cell (in other words, the start item or cell won't be searched again). This means, to wrap-around and stop at the start item, only use the \fB-start\fR and \fB-wraparound\fR options. If the \fB-start\fR and \fB-stop\fR options both use the same item, then only that item will be searched. The \fIitem\fR or \fIcell\fR must be a descendant of \fIparent\fR. .\" OPTION: -wraparound .TP \fB\-wraparound\fR . When used with the \fB-start\fR option, enables the search to wrap-round to the first/last item in \fIparent\fR to continue to the \fB-stop\fR item or cell. .RE Result Modifiers .RS .\" OPTION: -all .TP \fB\-all\fR . Return the identifiers of all of the items that match \fIpattern\fR rather than only the first one. .\" OPTION: -cell .TP \fB\-cell\fR . Return cell ids instead of item ids. The default is to return item ids. Also switches the \fB-start\fR and \fB-stop\fR options to use cell values. .\" OPTION: -not .TP \fB\-not\fR . Negates the match, so only the items that do not match \fIpattern\fR, will be returned. .RE .RE .\" METHOD: see .TP \fIpathname \fBsee \fIitem\fR ?\fIcolumn\fR? . Ensure that \fIitem\fR is visible by setting all of \fIitem\fR's ancestors to \fB\-open true\fR, and scroll the widget in the vertical direction, if necessary, so that \fIitem\fR is within the visible portion of the tree. If \fIcolumn\fR is specified, then the widget is scrolled in the horizontal direction, if necessary, so that \fIcolumn\fR is within the visible portion of the tree. Only non-title columns and rows will be scrolled. .TP \fIpathname \fBsee {*}\fIcell\fR . Same as previous subcommand, but uses the expand operator to convert \fIcell\fR into item and column components. .\" METHOD: selection .TP \fIpathname \fBselection\fR ?\fIselop itemList|first last\fR? . Manages item selection. The item selection is independent from the cell selection handled by the \fBcellselection\fR subcommand. If \fIselop\fR is not specified, returns a list of selected items. Otherwise, \fIselop\fR is one of the following: .RS .TP \fIpathname \fBselection add \fIitemList\fR . Add items in \fIitemList\fR to the selection. .TP \fIpathname \fBselection add\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIfirst last\fR . Add the items from \fIfirst\fR to \fIlast\fR (inclusive) to the selection. Use \fB-hidden\fR to include hidden items (default) and \fB-nohidden\fR to exclude them. Use \fB-recurse\fR to include descendants and ancestors (default) and \fB-norecurse\fR to exclude them. If \fB-hidden\fR and \fB-recurse\fR are used, all descendants of closed items will be included. .TP \fIpathname \fBselection anchor ?\fIitem\fR? . Sets the selection anchor to \fIitem\fR. The anchor is used as the from item for the selection extend bindings. Without \fIitem\fR, the current selection anchor is returned. Use empty string {} to unset the anchor. .TP \fIpathname \fBselection has \fIitemList\fR . Returns 1 if selection includes all items in \fIitemList\fR or 0 if any are not selected. .TP \fIpathname \fBselection includes \fIitemList\fR . Returns 1 if selection includes all items in \fIitemList\fR or 0 if any are not selected. .TP \fIpathname \fBselection present\fR . Returns 1 if there are selected items or 0 if none. .TP \fIpathname \fBselection remove \fIitemList\fR . Remove each item in \fIitemList\fR from the selection. .TP \fIpathname \fBselection remove\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIfirst last\fR . Remove the items from \fIfirst\fR to \fIlast\fR (inclusive) from the selection. Use \fB-hidden\fR to include hidden items (default) and \fB-nohidden\fR to exclude them. Use \fB-recurse\fR to include descendants and ancestors (default) and \fB-norecurse\fR to exclude them. If \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. .TP \fIpathname \fBselection set \fIitemList\fR . Sets selection to the items in \fIitemList\fR. All other items are unselected. Use an empty set \fB{}\fR to clear the selection. .TP \fIpathname \fBselection set\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIfirst last\fR . Sets selection to the items from \fIfirst\fR to \fIlast\fR (inclusive). Use \fB-hidden\fR to include hidden items (default) and \fB-nohidden\fR to exclude them. Use \fB-recurse\fR to include descendants and ancestors (default) and \fB-norecurse\fR to exclude them. If \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. .TP \fIpathname \fBselection size\fR . Returns the count of selected items. .TP \fIpathname \fBselection toggle \fIitemList\fR . Toggle the selection state of each item in \fIitemList\fR. .TP \fIpathname \fBselection toggle\fR ?\fB\-nohidden\fR? ?\fB\-norecurse\fR? \fIfirst last\fR . Toggle the selection state of the items from \fIfirst\fR to \fIlast\fR (inclusive). Use \fB-hidden\fR to include hidden items (default) and \fB-nohidden\fR to exclude them. Use \fB-recurse\fR to include descendants and ancestors (default) and \fB-norecurse\fR to exclude them. If \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. .RE .\" METHOD: set .TP \fIpathname \fBset \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? ?\fIcolumn value ...\fR? . Set or get \fIitem\fR column values. With no \fIcolumn\fR or \fIvalue\fR arguments, returns a dictionary of all column/value pairs. With only the \fIcolumn\fR argument, returns the current value for \fIcolumn\fR. With one or more \fIcolumn\fR and \fIvalue\fR pair arguments, sets the value of each \fIcolumn\fR to the associated \fIvalue\fR. Use column \fB#0\fR for the tree column. See \fBCOLUMN IDENTIFIERS\fR for valid forms of \fIcolumn\fR. .\" METHOD: size .TP \fIpathname \fBsize\fR ?\fB\-hidden\fR? ?\fB\-recurse\fR? \fIitem\fR . Returns the count of children belonging to \fIitem\fR. Use \fB-hidden\fR to include hidden items and \fB-nohidden\fR (default) to exclude them. Use \fB-recurse\fR to include descendants of \fIitem\fR and \fB-norecurse\fR (default) to exclude them. If both \fB-hidden\fR and \fB-recurse\fR are used, descendants of closed items will be included. .\" METHOD: sort .TP \fIpathname \fBsort \fIparent\fR ?\fI\-option ...\fR? . Sort the children of \fIparent\fR. Valid options are: .RS .\" OPTION: -ascii .TP \fB\-ascii\fR . The values are to be sorted in Unicode character code order (the name is for backward-compatibility reasons.) This is the default. .\" OPTION: -dictionary .TP \fB\-dictionary\fR . The values are to be sorted using dictionary-style comparisons. This is the same as \fB-ascii\fR 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 \fB-dictionary\fR mode, "bigBoy" sorts between "bigbang" and "bigboy", and "x10y" sorts between "x9y" and "x11y". Overrides the \fB-nocase\fR option. .\" OPTION: -integer .TP \fB\-integer\fR . The values are to be sorted as integers. Non-integer values will generate an error. .\" OPTION: -nocase .TP \fB\-nocase\fR . Comparisons are to be performed in a case-insensitive manner. Only used with \fB\-ascii\fR option. .\" OPTION: -real .TP \fB\-real\fR . The values are to be sorted as floating-point values. Non-numeric values will generate an error. .\" OPTION: -unicode .TP \fB\-unicode\fR . Alias for \fB-ascii\fR. .\" OPTION: -command .TP \fB\-command \fIcommand\fR . Use \fIcommand\fR as a comparison command. To compare two elements, evaluate a Tcl script consisting of command with the two elements appended as additional arguments. The script should return an integer less than, equal to, or greater than zero if the first element is to be considered less than, equal to, or greater than the second, respectively. .\" OPTION: -increasing .TP \fB\-increasing\fR . Sort the list in increasing order (“smallest” items first). This is the default. .\" OPTION: -decreasing .TP \fB\-decreasing\fR . Sort the list in decreasing order (“largest” items first). .\" OPTION: -column .TP \fB\-column \fIcolumn\fR . Sort based on values in column \fIcolumn\fR. See \fBCOLUMN IDENTIFIERS\fR for valid forms of \fIcolumn\fR. The default is the first display column (\fB#0\fR if tree in -show or \fB#1\fR if not). .\" OPTION: -ignoreempty .TP \fB\-ignoreempty\fR . Used with \fB-integer\fR or \fB-real\fR to ignore empty entries. Normally these would trigger an error and abort the sort. Empty entries will be sorted first for \fB-increasing\fR and last for \fB-decreasing\fR. .\" OPTION: -recurse .TP \fB\-recurse\fR . Sort all descendants of \fIparent\fR. The default is to only sort the children of \fIparent\fR. .RE .\" METHOD: tag .TP \fIpathName \fBtag \fIargs...\fR . Manages tags. Tags can be set on items as well as on cells. The set of tags is shared between items and cells. However item tagging is independent from cell tagging (for instance adding a tag on an item does not also add this tag on the cells in that item). Cell tags take precedence over item tags when drawing. The following subcommands are supported: .RS .TP \fIpathName \fBtag add \fItagName itemList\fR . Adds tag \fItagName\fR to each of the items in \fIitemList\fR. If \fItagName\fR is already present for a particular item, then the \fB\-tags\fR for that item are unchanged. .TP \fIpathName \fBtag bind \fItagName\fR ?\fIsequence\fR? ?\fIscript\fR? . Add a Tk binding script for the event sequence \fIsequence\fR to the tag \fItagName\fR. When an X event is delivered to an item, binding scripts for each of the item's \fB\-tags\fR are evaluated in order as per \fIbindtags(n)\fR. If the event can be associated with a cell (i.e. mouse events) any bindings for the cell's \fB\-tags\fR are evaluated as well. .RS .PP \fB\fR, \fB\fR, and virtual events are sent to the focus item. The \fB