1ttk::treeview(n) Tk Themed Widget ttk::treeview(n)
2______________________________________________________________________________
6
8 ttk::treeview - hierarchical multicolumn data display widget
9
11 ttk::treeview pathname ?options?
12______________________________________________________________________________
13
15 The ttk::treeview widget displays a hierarchical collection of items.
16 Each item has a textual label, an optional image, and an optional list
17 of data values. The data values are displayed in successive columns
18 after the tree label.
19 The order in which data values are displayed may be controlled by set‐
21 ting the -displaycolumns widget option. The tree widget can also dis‐
22 play column headings. Columns may be accessed by number or by symbolic
23 names listed in the -columns widget option; see COLUMN IDENTIFIERS.
24 Each item is identified by a unique name. The widget will generate
26 item IDs if they are not supplied by the caller. There is a distin‐
27 guished root item, named {}. The root item itself is not displayed;
28 its children appear at the top level of the hierarchy.
29 Each item also has a list of tags, which can be used to associate event
31 bindings with individual items and control the appearance of the item.
32 Treeview widgets support horizontal and vertical scrolling with the
34 standard -[xy]scrollcommand options and [xy]view widget commands.
35
37 -class -cursor -takefocus
38 -style -xscrollcommand -yscrollcommand
39 -padding
40 See the ttk_widget manual entry for details on the standard options.
42
44 Command-Line Name:-columns
45 Database Name: columns
46 Database Class: Columns
47 A list of column identifiers, specifying the number of columns
49 and their names.
50 Command-Line Name:-displaycolumns
52 Database Name: displayColumns
53 Database Class: DisplayColumns
54 A list of column identifiers (either symbolic names or integer
56 indices) specifying which data columns are displayed and the
57 order in which they appear, or the string #all. If set to #all
58 (the default), all columns are shown in the order given.
59 Command-Line Name:-height
61 Database Name: height
62 Database Class: Height
63 Specifies the number of rows which should be visible. Note: the
65 requested width is determined from the sum of the column widths.
66 Command-Line Name:-selectmode
68 Database Name: selectMode
69 Database Class: SelectMode
70 Controls how the built-in class bindings manage the selection.
72 One of extended, browse, or none.
73 If set to extended (the default), multiple items may be
75 selected. If browse, only a single item will be selected at a
76 time. If none, the selection will not be changed.
77 Note that application code and tag bindings can set the selec‐
79 tion however they wish, regardless of the value of -selectmode.
80 Command-Line Name:-show
82 Database Name: show
83 Database Class: Show
84 A list containing zero or more of the following values, specify‐
86 ing which elements of the tree to display.
87 tree Display tree labels in column #0.
89 headings
91 Display the heading row.
92 The default is tree headings, i.e., show all elements.
94 NOTE: Column #0 always refers to the tree column, even if -show
96 tree is not specified.
97
99 pathname bbox item ?column?
100 Returns the bounding box (relative to the treeview widget's win‐
101 dow) of the specified item in the form x y width height. If
102 column is specified, returns the bounding box of that cell. If
103 the item is not visible (i.e., if it is a descendant of a closed
104 item or is scrolled offscreen), returns the empty list.
105 pathname cget option
107 Returns the current value of the specified option; see ttk::wid‐
108 get(n).
109 pathname children item ?newchildren?
111 If newchildren is not specified, returns the list of children
112 belonging to item.
113 If newchildren is specified, replaces item's child list with
115 newchildren. Items in the old child list not present in the new
116 child list are detached from the tree. None of the items in
117 newchildren may be an ancestor of item.
118 pathname column column ?-option ?value -option value...?
120 Query or modify the options for the specified column. If no
121 -option is specified, returns a dictionary of option/value
122 pairs. If a single -option is specified, returns the value of
123 that option. Otherwise, the options are updated with the speci‐
124 fied values. The following options may be set on each column:
125 -id name
127 The column name. This is a read-only option. For exam‐
128 ple, [$pathname column #n -id] returns the data column
129 associated with display column #n.
130 -anchor anchor
132 Specifies how the text in this column should be aligned
133 with respect to the cell. Anchor is one of n, ne, e, se,
134 s, sw, w, nw, or center.
135 -minwidth minwidth
137 The minimum width of the column in pixels. The treeview
138 widget will not make the column any smaller than -min‐
139 width when the widget is resized or the user drags a col‐
140 umn separator. Default is 20 pixels.
141 -stretch boolean
143 Specifies whether or not the column width should be
144 adjusted when the widget is resized or the user drags a
145 column separator. Boolean may have any of the forms
146 accepted by Tcl_GetBoolean. By default columns are
147 stretchable.
148 -width width
150 The width of the column in pixels. Default is 200 pix‐
151 els. The specified column width may be changed by Tk in
152 order to honor -stretch and/or -minwidth, or when the
153 widget is resized or the user drags a column separator.
154 Use pathname column #0 to configure the tree column.
156 pathname configure ?option? ?value option value ...?
158 Modify or query widget options; see ttk::widget(n).
159 pathname delete itemList
161 Deletes each of the items in itemList and all of their descen‐
162 dants. The root item may not be deleted. See also: detach.
163 pathname detach itemList
165 Unlinks all of the specified items in itemList from the tree.
166 The items and all of their descendants are still present and may
167 be reinserted at another point in the tree with the move opera‐
168 tion, but will not be displayed until that is done. The root
169 item may not be detached. See also: delete.
170 pathname exists item
172 Returns 1 if the specified item is present in the tree, 0 other‐
173 wise.
174 pathname focus ?item?
176 If item is specified, sets the focus item to item. Otherwise,
177 returns the current focus item, or {} if there is none.
178 pathname heading column ?-option ?value -option value...?
180 Query or modify the heading options for the specified column.
181 Valid options are:
182 -text text
184 The text to display in the column heading.
185 -image imageName
187 Specifies an image to display to the right of the column
188 heading.
189 -anchor anchor
191 Specifies how the heading text should be aligned. One of
192 the standard Tk anchor values.
193 -command script
195 A script to evaluate when the heading label is pressed.
196 Use pathname heading #0 to configure the tree column heading.
198 pathname identify component x y
200 Returns a description of the specified component under the point
201 given by x and y, or the empty string if no such component is
202 present at that position. The following subcommands are sup‐
203 ported:
204 pathname identify region x y
206 Returns one of:
207 heading
209 Tree heading area; use [pathname identify column x
210 y] to determine the heading number.
211 separator
213 Space between two column headings; [pathname iden‐
214 tify column x y] will return the display column
215 identifier of the heading to left of the separa‐
216 tor.
217 tree The tree area.
219 cell A data cell.
221 pathname identify item x y Returns the item ID of the item at
222 position y.
223 pathname identify column x y
225 Returns the display column identifier of the cell at
226 position x. The tree column has ID #0.
227 pathname identify element x y
229 The element at position x,y.
230 pathname identify row x y
232 Obsolescent synonym for pathname identify item.
233 See COLUMN IDENTIFIERS for a discussion of display columns and
235 data columns.
236 pathname index item
238 Returns the integer index of item within its parent's list of
239 children.
240 pathname insert parent index ?-id id? options...
242 Creates a new item. parent is the item ID of the parent item,
243 or the empty string {} to create a new top-level item. index is
244 an integer, or the value end, specifying where in the list of
245 parent's children to insert the new item. If index is less than
246 or equal to zero, the new node is inserted at the beginning; if
247 index is greater than or equal to the current number of chil‐
248 dren, it is inserted at the end. If -id is specified, it is
249 used as the item identifier; id must not already exist in the
250 tree. Otherwise, a new unique identifier is generated.
251 pathname insert returns the item identifier of the newly created
253 item. See ITEM OPTIONS for the list of available options.
254 pathname instate statespec ?script?
256 Test the widget state; see ttk::widget(n).
257 pathname item item ?-option ?value -option value...?
259 Query or modify the options for the specified item. If no
260 -option is specified, returns a dictionary of option/value
261 pairs. If a single -option is specified, returns the value of
262 that option. Otherwise, the item's options are updated with the
263 specified values. See ITEM OPTIONS for the list of available
264 options.
265 pathname move item parent index
267 Moves item to position index in parent's list of children. It
268 is illegal to move an item under one of its descendants.
269 If index is less than or equal to zero, item is moved to the
271 beginning; if greater than or equal to the number of children,
272 it is moved to the end.
273 pathname next item
275 Returns the identifier of item's next sibling, or {} if item is
276 the last child of its parent.
277 pathname parent item
279 Returns the ID of the parent of item, or {} if item is at the
280 top level of the hierarchy.
281 pathname prev item
283 Returns the identifier of item's previous sibling, or {} if item
284 is the first child of its parent.
285 pathname see item
287 Ensure that item is visible: sets all of item's ancestors to
288 -open true, and scrolls the widget if necessary so that item is
289 within the visible portion of the tree.
290 pathname selection ?selop itemList?
292 If selop is not specified, returns the list of selected items.
293 Otherwise, selop is one of the following:
294 pathname selection set itemList
296 itemList becomes the new selection.
297 pathname selection add itemList
299 Add itemList to the selection
300 pathname selection remove itemList
302 Remove itemList from the selection
303 pathname selection toggle itemList
305 Toggle the selection state of each item in itemList.
306 pathname set item ?column? ?value?
308 With one argument, returns a dictionary of column/value pairs
309 for the specified item. With two arguments, returns the current
310 value of the specified column. With three arguments, sets the
311 value of column column in item item to the specified value. See
312 also COLUMN IDENTIFIERS.
313 pathname state ?stateSpec?
315 Modify or query the widget state; see ttk::widget(n).
316 pathName tag args...
318 pathName tag bind tagName ?sequence? ?script?
320 Add a Tk binding script for the event sequence sequence
321 to the tag tagName. When an X event is delivered to an
322 item, binding scripts for each of the item's -tags are
323 evaluated in order as per bindtags(n).
324 <KeyPress>, <KeyRelease>, and virtual events are sent to
326 the focus item. <ButtonPress>, <ButtonRelease>, and
327 <Motion> events are sent to the item under the mouse
328 pointer. No other event types are supported.
329 The binding script undergoes %-substitutions before eval‐
331 uation; see bind(n) for details.
332 pathName tag configure tagName ?option? ?value option value...?
334 Query or modify the options for the specified tagName.
335 If one or more option/value pairs are specified, sets the
336 value of those options for the specified tag. If a sin‐
337 gle option is specified, returns the value of that option
338 (or the empty string if the option has not been specified
339 for tagName). With no additional arguments, returns a
340 dictionary of the option settings for tagName. See TAG
341 OPTIONS for the list of available options.
342 pathName tag has tagName ?item?
344 If item is specified, returns 1 or 0 depending on whether
345 the specified item has the named tag. Otherwise, returns
346 a list of all items which have the specified tag.
347 pathName tag names
349 Returns a list of all tags used by the widget.
350 pathName tag add tag items
352 Adds the specified tag to each of the listed items. If
353 tag is already present for a particular item, then the
354 -tags for that item are unchanged.
355 pathName tag remove tag ?items?
357 Removes the specified tag from each of the listed items.
358 If items is omitted, removes tag from each item in the
359 tree. If tag is not present for a particular item, then
360 the -tags for that item are unchanged.
361 The treeview widget also supports the following generic ttk::widget
363 widget subcommands (see ttk::widget(n) for details):
364 xview yview
366
369 The following item options may be specified for items in the insert and
370 item widget commands.
371 Command-Line Name:-text
373 Database Name: text
374 Database Class: Text
375 The textual label to display for the item.
377 Command-Line Name:-image
379 Database Name: image
380 Database Class: Image
381 A Tk image, displayed to the left of the label.
383 Command-Line Name:-values
385 Database Name: values
386 Database Class: Values
387 The list of values associated with the item.
389 Each item should have the same number of values as the -columns
391 widget option. If there are fewer values than columns, the
392 remaining values are assumed empty. If there are more values
393 than columns, the extra values are ignored.
394 Command-Line Name:-open
396 Database Name: open
397 Database Class: Open
398 A boolean value indicating whether the item's children should be
400 displayed (-open true) or hidden (-open false).
401 Command-Line Name:-tags
403 Database Name: tags
404 Database Class: Tags
405 A list of tags associated with this item.
407
409 The following options may be specified on tags:
410 -foreground
412 Specifies the text foreground color.
413 -background
415 Specifies the cell or item background color.
416 -font Specifies the font to use when drawing text.
418 -image Specifies the item image, in case the item's -image option is
420 empty.
421 Tag priority is decided by the creation order: tags created first
423 receive higher priority.
424
426 Column identifiers take any of the following forms:
427 · A symbolic name from the list of -columns.
429 · An integer n, specifying the nth data column.
431 · A string of the form #n, where n is an integer, specifying the
433 nth display column.
434 NOTE: Item -values may be displayed in a different order than the order
436 in which they are stored.
437 NOTE: Column #0 always refers to the tree column, even if -show tree is
439 not specified.
440 A data column number is an index into an item's -values list; a display
442 column number is the column number in the tree where the values are
443 displayed. Tree labels are displayed in column #0. If -displaycolumns
444 is not set, then data column n is displayed in display column #n+1.
445 Again, column #0 always refers to the tree column.
446
448 The treeview widget generates the following virtual events.
449 <<TreeviewSelect>>
451 Generated whenever the selection changes.
452 <<TreeviewOpen>>
454 Generated just before setting the focus item to -open true.
455 <<TreeviewClose>>
457 Generated just after setting the focus item to -open false.
458 The focus and selection widget commands can be used to determine the
460 affected item or items.
461
463 The class name for a ttk::treeview is Treeview. The treeview header
464 class name is Heading. The treeview item class name is Item. The
465 treeview cell class name is Cell.
466 Dynamic states: disabled, selected.
468 Treeview styling options configurable with ttk::style are:
470 -background color
472 -fieldbackground color
473 -font font
474 -foreground color
475 -rowheight amount
476 The -rowheight value is not corrected by the tk scaling value or
477 by the configured font size and must always be set. Also make
478 sure that the -rowheight is large enough to contain any images.
479 To adjust the -rowheight for the Treeview style, use the follow‐
481 ing code after tk scaling has been applied. Note that even if
482 you do not support or change tk scaling in your program, your
483 users may have it set in their .wishrc.
484 ttk::style configure Treeview \
486 -rowheight [expr {[font metrics font -linespace] + 2}]
487 Heading styling options configurable with ttk::style are:
489 -background color
491 -font font
492 -relief relief
493 Item styling options configurable with ttk::style are:
495 -foreground color
497 -indicatormargins padding
498 -indicatorsize amount
499 -padding padding
500 Cell styling options configurable with ttk::style are:
502 -padding padding
504 Some options are only available for specific themes.
506 See the ttk::style manual page for information on how to configure ttk
508 styles.
509
511 ttk::widget(n), listbox(n), image(n), bind(n)
512Tk 8.5 ttk::treeview(n)