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
132 Specifies how the text in this column should be aligned
133 with respect to the cell. One of n, ne, e, se, s, sw, w,
134 nw, or center.
135 -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.
141 -stretch
143 Specifies whether or not the column's width should be
144 adjusted when the widget is resized.
145 -width w
147 The width of the column in pixels. Default is something
148 reasonable, probably 200 or so.
149 Use pathname column #0 to configure the tree column.
151 pathname configure ?option? ?value option value ...?
153 Modify or query widget options; see ttk::widget(n).
154 pathname delete itemList
156 Deletes each of the items in itemList and all of their descen‐
157 dants. The root item may not be deleted. See also: detach.
158 pathname detach itemList
160 Unlinks all of the specified items in itemList from the tree.
161 The items and all of their descendants are still present and may
162 be reinserted at another point in the tree with the move opera‐
163 tion, but will not be displayed until that is done. The root
164 item may not be detached. See also: delete.
165 pathname exists item
167 Returns 1 if the specified item is present in the tree, 0 other‐
168 wise.
169 pathname focus ?item?
171 If item is specified, sets the focus item to item. Otherwise,
172 returns the current focus item, or {} if there is none.
173 pathname heading column ?-option ?value -option value...?
175 Query or modify the heading options for the specified column.
176 Valid options are:
177 -text text
179 The text to display in the column heading.
180 -image imageName
182 Specifies an image to display to the right of the column
183 heading.
184 -anchor anchor
186 Specifies how the heading text should be aligned. One of
187 the standard Tk anchor values.
188 -command script
190 A script to evaluate when the heading label is pressed.
191 Use pathname heading #0 to configure the tree column heading.
193 pathname identify component x y
195 Returns a description of the specified component under the point
196 given by x and y, or the empty string if no such component is
197 present at that position. The following subcommands are sup‐
198 ported:
199 pathname identify region x y
201 Returns one of:
202 heading
204 Tree heading area; use [pathname identify column x
205 y] to determine the heading number.
206 separator
208 Space between two column headings; [pathname iden‐
209 tify column x y] will return the display column
210 identifier of the heading to left of the separa‐
211 tor.
212 tree The tree area.
214 cell A data cell.
216 pathname identify item x y Returns the item ID of the item at
217 position y.
218 pathname identify column x y
220 Returns the data column identifier of the cell at posi‐
221 tion x. The tree column has ID #0.
222 pathname identify element x y
224 The element at position x,y.
225 pathname identify row x y
227 Obsolescent synonym for pathname identify item.
228 See COLUMN IDENTIFIERS for a discussion of display columns and
230 data columns.
231 pathname index item
233 Returns the integer index of item within its parent's list of
234 children.
235 pathname insert parent index ?-id id? options...
237 Creates a new item. parent is the item ID of the parent item,
238 or the empty string {} to create a new top-level item. index is
239 an integer, or the value end, specifying where in the list of
240 parent's children to insert the new item. If index is less than
241 or equal to zero, the new node is inserted at the beginning; if
242 index is greater than or equal to the current number of chil‐
243 dren, it is inserted at the end. If -id is specified, it is
244 used as the item identifier; id must not already exist in the
245 tree. Otherwise, a new unique identifier is generated.
246 pathname insert returns the item identifier of the newly created
248 item. See ITEM OPTIONS for the list of available options.
249 pathname instate statespec ?script?
251 Test the widget state; see ttk::widget(n).
252 pathname item item ?-option ?value -option value...?
254 Query or modify the options for the specified item. If no
255 -option is specified, returns a dictionary of option/value
256 pairs. If a single -option is specified, returns the value of
257 that option. Otherwise, the item's options are updated with the
258 specified values. See ITEM OPTIONS for the list of available
259 options.
260 pathname move item parent index
262 Moves item to position index in parent's list of children. It
263 is illegal to move an item under one of its descendants.
264 If index is less than or equal to zero, item is moved to the
266 beginning; if greater than or equal to the number of children,
267 it is moved to the end.
268 pathname next item
270 Returns the identifier of item's next sibling, or {} if item is
271 the last child of its parent.
272 pathname parent item
274 Returns the ID of the parent of item, or {} if item is at the
275 top level of the hierarchy.
276 pathname prev item
278 Returns the identifier of item's previous sibling, or {} if item
279 is the first child of its parent.
280 pathname see item
282 Ensure that item is visible: sets all of item's ancestors to
283 -open true, and scrolls the widget if necessary so that item is
284 within the visible portion of the tree.
285 pathname selection ?selop itemList?
287 If selop is not specified, returns the list of selected items.
288 Otherwise, selop is one of the following:
289 pathname selection set itemList
291 itemList becomes the new selection.
292 pathname selection add itemList
294 Add itemList to the selection
295 pathname selection remove itemList
297 Remove itemList from the selection
298 pathname selection toggle itemList
300 Toggle the selection state of each item in itemList.
301 pathname set item ?column? ?value?
303 With one argument, returns a dictionary of column/value pairs
304 for the specified item. With two arguments, returns the current
305 value of the specified column. With three arguments, sets the
306 value of column column in item item to the specified value. See
307 also COLUMN IDENTIFIERS.
308 pathname state ?stateSpec?
310 Modify or query the widget state; see ttk::widget(n).
311 pathName tag args...
313 pathName tag bind tagName ?sequence? ?script?
315 Add a Tk binding script for the event sequence sequence
316 to the tag tagName. When an X event is delivered to an
317 item, binding scripts for each of the item's -tags are
318 evaluated in order as per bindtags(n).
319 <KeyPress>, <KeyRelease>, and virtual events are sent to
321 the focus item. <ButtonPress>, <ButtonRelease>, and
322 <Motion> events are sent to the item under the mouse
323 pointer. No other event types are supported.
324 The binding script undergoes %-substitutions before eval‐
326 uation; see bind(n) for details.
327 pathName tag configure tagName ?option? ?value option value...?
329 Query or modify the options for the specified tagName.
330 If one or more option/value pairs are specified, sets the
331 value of those options for the specified tag. If a sin‐
332 gle option is specified, returns the value of that option
333 (or the empty string if the option has not been specified
334 for tagName). With no additional arguments, returns a
335 dictionary of the option settings for tagName. See TAG
336 OPTIONS for the list of available options.
337 pathName tag has tagName ?item?
339 If item is specified, returns 1 or 0 depending on whether
340 the specified item has the named tag. Otherwise, returns
341 a list of all items which have the specified tag.
342 pathName tag names
344 Returns a list of all tags used by the widget.
345 pathName tag add tag items
347 Adds the specified tag to each of the listed items. If
348 tag is already present for a particular item, then the
349 -tags for that item are unchanged.
350 pathName tag remove tag ?items?
352 Removes the specified tag from each of the listed items.
353 If items is omitted, removes tag from each item in the
354 tree. If tag is not present for a particular item, then
355 the -tags for that item are unchanged.
356 pathName xview args
358 Standard command for horizontal scrolling; see widget(n).
359 pathName yview args
361 Standard command for vertical scrolling; see ttk::widget(n).
362
364 The following item options may be specified for items in the insert and
365 item widget commands.
366 Command-Line Name:-text
368 Database Name: text
369 Database Class: Text
370 The textual label to display for the item.
372 Command-Line Name:-image
374 Database Name: image
375 Database Class: Image
376 A Tk image, displayed to the left of the label.
378 Command-Line Name:-values
380 Database Name: values
381 Database Class: Values
382 The list of values associated with the item.
384 Each item should have the same number of values as the -columns
386 widget option. If there are fewer values than columns, the
387 remaining values are assumed empty. If there are more values
388 than columns, the extra values are ignored.
389 Command-Line Name:-open
391 Database Name: open
392 Database Class: Open
393 A boolean value indicating whether the item's children should be
395 displayed (-open true) or hidden (-open false).
396 Command-Line Name:-tags
398 Database Name: tags
399 Database Class: Tags
400 A list of tags associated with this item.
402
404 The following options may be specified on tags:
405 -foreground
407 Specifies the text foreground color.
408 -background
410 Specifies the cell or item background color.
411 -font Specifies the font to use when drawing text.
413 -image Specifies the item image, in case the item's -image option is
415 empty.
416
418 Column identifiers take any of the following forms:
419 · A symbolic name from the list of -columns.
421 · An integer n, specifying the nth data column.
423 · A string of the form #n, where n is an integer, specifying the
425 nth display column.
426 NOTE: Item -values may be displayed in a different order than the order
428 in which they are stored.
429 NOTE: Column #0 always refers to the tree column, even if -show tree is
431 not specified.
432 A data column number is an index into an item's -values list; a display
434 column number is the column number in the tree where the values are
435 displayed. Tree labels are displayed in column #0. If -displaycolumns
436 is not set, then data column n is displayed in display column #n+1.
437 Again, column #0 always refers to the tree column.
438
440 The treeview widget generates the following virtual events.
441 <<TreeviewSelect>>
443 Generated whenever the selection changes.
444 <<TreeviewOpen>>
446 Generated just before setting the focus item to -open true.
447 <<TreeviewClose>>
449 Generated just after setting the focus item to -open false.
450 The focus and selection widget commands can be used to determine the
452 affected item or items.
453
455 ttk::widget(n), listbox(n), image(n), bind(n)
456Tk 8.5 ttk::treeview(n)