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 See the ttk_widget manual entry for details on the standard options.
41
43 [-columns columns] A list of column identifiers, specifying the number
44 of columns and their names. [-displaycolumns displayColumns] A list of
45 column identifiers (either symbolic names or integer indices) specify‐
46 ing which data columns are displayed and the order in which they
47 appear, or the string #all. If set to #all (the default), all columns
48 are shown in the order given. [-height height] Specifies the number of
49 rows which should be visible. Note: the requested width is determined
50 from the sum of the column widths. [-padding padding] Specifies the
51 internal padding for the widget. The padding is a list of up to four
52 length specifications; see Ttk_GetPaddingFromObj() for details.
53 [-selectmode selectMode] Controls how the built-in class bindings man‐
54 age the selection. One of extended, browse, or none.
55 If set to extended (the default), multiple items may be
57 selected. If browse, only a single item will be selected at a
58 time. If none, the selection will not be changed.
59 Note that application code and tag bindings can set the selec‐
61 tion however they wish, regardless of the value of -selectmode.
62 [-show show] A list containing zero or more of the following values,
63 specifying which elements of the tree to display.
64 tree Display tree labels in column #0.
66 headings
68 Display the heading row.
69 The default is tree headings, i.e., show all elements.
71 NOTE: Column #0 always refers to the tree column, even if -show
73 tree is not specified.
74
76 pathname bbox item ?column?
77 Returns the bounding box (relative to the treeview widget's win‐
78 dow) of the specified item in the form x y width height. If
79 column is specified, returns the bounding box of that cell. If
80 the item is not visible (i.e., if it is a descendant of a closed
81 item or is scrolled offscreen), returns the empty list.
82 pathname cget option
84 Returns the current value of the specified option; see ttk::wid‐
85 get(n).
86 pathname children item ?newchildren?
88 If newchildren is not specified, returns the list of children
89 belonging to item.
90 If newchildren is specified, replaces item's child list with
92 newchildren. Items in the old child list not present in the new
93 child list are detached from the tree. None of the items in
94 newchildren may be an ancestor of item.
95 pathname column column ?-option ?value -option value...?
97 Query or modify the options for the specified column. If no
98 -option is specified, returns a dictionary of option/value
99 pairs. If a single -option is specified, returns the value of
100 that option. Otherwise, the options are updated with the speci‐
101 fied values. The following options may be set on each column:
102 -id name
104 The column name. This is a read-only option. For exam‐
105 ple, [$pathname column #n -id] returns the data column
106 associated with display column #n.
107 -anchor
109 Specifies how the text in this column should be aligned
110 with respect to the cell. One of n, ne, e, se, s, sw, w,
111 nw, or center.
112 -minwidth
114 The minimum width of the column in pixels. The treeview
115 widget will not make the column any smaller than -min‐
116 width when the widget is resized or the user drags a col‐
117 umn separator.
118 -stretch
120 Specifies whether or not the column's width should be
121 adjusted when the widget is resized.
122 -width w
124 The width of the column in pixels. Default is something
125 reasonable, probably 200 or so.
126 Use pathname column #0 to configure the tree column.
128 pathname configure ?option? ?value option value ...?
130 Modify or query widget options; see ttk::widget(n).
131 pathname delete itemList
133 Deletes each of the items in itemList and all of their descen‐
134 dants. The root item may not be deleted. See also: detach.
135 pathname detach itemList
137 Unlinks all of the specified items in itemList from the tree.
138 The items and all of their descendants are still present and may
139 be reinserted at another point in the tree with the move opera‐
140 tion, but will not be displayed until that is done. The root
141 item may not be detached. See also: delete.
142 pathname exists item
144 Returns 1 if the specified item is present in the tree, 0 other‐
145 wise.
146 pathname focus ?item?
148 If item is specified, sets the focus item to item. Otherwise,
149 returns the current focus item, or {} if there is none.
150 pathname heading column ?-option ?value -option value...?
152 Query or modify the heading options for the specified column.
153 Valid options are:
154 -text text
156 The text to display in the column heading.
157 -image imageName
159 Specifies an image to display to the right of the column
160 heading.
161 -anchor anchor
163 Specifies how the heading text should be aligned. One of
164 the standard Tk anchor values.
165 -command script
167 A script to evaluate when the heading label is pressed.
168 Use pathname heading #0 to configure the tree column heading.
170 pathname identify component x y
172 Returns a description of the specified component under the point
173 given by x and y, or the empty string if no such component is
174 present at that position. The following subcommands are sup‐
175 ported:
176 pathname identify region x y
178 Returns one of:
179 heading
181 Tree heading area; use [pathname identify column x
182 y] to determine the heading number.
183 separator
185 Space between two column headings; [pathname iden‐
186 tify column x y] will return the display column
187 identifier of the heading to left of the separa‐
188 tor.
189 tree The tree area.
191 cell A data cell.
193 pathname identify item x y Returns the item ID of the item at
194 position y.
195 pathname identify column x y
197 Returns the data column identifier of the cell at posi‐
198 tion x. The tree column has ID #0.
199 pathname identify element x y
201 The element at position x,y.
202 pathname identify row x y
204 Obsolescent synonym for pathname identify item.
205 See COLUMN IDENTIFIERS for a discussion of display columns and
207 data columns.
208 pathname index item
210 Returns the integer index of item within its parent's list of
211 children.
212 pathname insert parent index ?-id id? options...
214 Creates a new item. parent is the item ID of the parent item,
215 or the empty string {} to create a new top-level item. index is
216 an integer, or the value end, specifying where in the list of
217 parent's children to insert the new item. If index is less than
218 or equal to zero, the new node is inserted at the beginning; if
219 index is greater than or equal to the current number of chil‐
220 dren, it is inserted at the end. If -id is specified, it is
221 used as the item identifier; id must not already exist in the
222 tree. Otherwise, a new unique identifier is generated.
223 pathname insert returns the item identifier of the newly created
225 item. See ITEM OPTIONS for the list of available options.
226 pathname instate statespec ?script?
228 Test the widget state; see ttk::widget(n).
229 pathname item item ?-option ?value -option value...?
231 Query or modify the options for the specified item. If no
232 -option is specified, returns a dictionary of option/value
233 pairs. If a single -option is specified, returns the value of
234 that option. Otherwise, the item's options are updated with the
235 specified values. See ITEM OPTIONS for the list of available
236 options.
237 pathname move item parent index
239 Moves item to position index in parent's list of children. It
240 is illegal to move an item under one of its descendants.
241 If index is less than or equal to zero, item is moved to the
243 beginning; if greater than or equal to the number of children,
244 it is moved to the end.
245 pathname next item
247 Returns the identifier of item's next sibling, or {} if item is
248 the last child of its parent.
249 pathname parent item
251 Returns the ID of the parent of item, or {} if item is at the
252 top level of the hierarchy.
253 pathname prev item
255 Returns the identifier of item's previous sibling, or {} if item
256 is the first child of its parent.
257 pathname see item
259 Ensure that item is visible: sets all of item's ancestors to
260 -open true, and scrolls the widget if necessary so that item is
261 within the visible portion of the tree.
262 pathname selection ?selop itemList?
264 If selop is not specified, returns the list of selected items.
265 Otherwise, selop is one of the following:
266 pathname selection set itemList
268 itemList becomes the new selection.
269 pathname selection add itemList
271 Add itemList to the selection
272 pathname selection remove itemList
274 Remove itemList from the selection
275 pathname selection toggle itemList
277 Toggle the selection state of each item in itemList.
278 pathname set item ?column? ?value?
280 With one argument, returns a dictionary of column/value pairs
281 for the specified item. With two arguments, returns the current
282 value of the specified column. With three arguments, sets the
283 value of column column in item item to the specified value. See
284 also COLUMN IDENTIFIERS.
285 pathname state ?stateSpec?
287 Modify or query the widget state; see ttk::widget(n).
288 pathName tag args...
290 pathName tag bind tagName ?sequence? ?script?
292 Add a Tk binding script for the event sequence sequence
293 to the tag tagName. When an X event is delivered to an
294 item, binding scripts for each of the item's -tags are
295 evaluated in order as per bindtags(n).
296 <KeyPress>, <KeyRelease>, and virtual events are sent to
298 the focus item. <ButtonPress>, <ButtonRelease>, and
299 <Motion> events are sent to the item under the mouse
300 pointer. No other event types are supported.
301 The binding script undergoes %-substitutions before eval‐
303 uation; see bind(n) for details.
304 pathName tag configure tagName ?option? ?value option value...?
306 Query or modify the options for the specified tagName.
307 If one or more option/value pairs are specified, sets the
308 value of those options for the specified tag. If a sin‐
309 gle option is specified, returns the value of that option
310 (or the empty string if the option has not been specified
311 for tagName). With no additional arguments, returns a
312 dictionary of the option settings for tagName. See TAG
313 OPTIONS for the list of available options.
314 pathName tag has tagName ?item?
316 If item is specified, returns 1 or 0 depending on whether
317 the specified item has the named tag. Otherwise, returns
318 a list of all items which have the specified tag.
319 pathName tag names
321 Returns a list of all tags used by the widget.
322 pathName tag add tag items
324 Adds the specified tag to each of the listed items. If
325 tag is already present for a particular item, then the
326 -tags for that item are unchanged.
327 pathName tag remove tag ?items?
329 Removes the specified tag from each of the listed items.
330 If items is omitted, removes tag from each item in the
331 tree. If tag is not present for a particular item, then
332 the -tags for that item are unchanged.
333 pathName xview args
335 Standard command for horizontal scrolling; see widget(n).
336 pathName yview args
338 Standard command for vertical scrolling; see ttk::widget(n).
339
341 The following item options may be specified for items in the insert and
342 item widget commands. [-text text] The textual label to display for
343 the item. [-image image] A Tk image, displayed to the left of the
344 label. [-values values] The list of values associated with the item.
345 Each item should have the same number of values as the -columns
347 widget option. If there are fewer values than columns, the
348 remaining values are assumed empty. If there are more values
349 than columns, the extra values are ignored.
350 [-open open] A boolean value indicating whether the item's children
351 should be displayed (-open true) or hidden (-open false). [-tags tags]
352 A list of tags associated with this item.
353
355 The following options may be specified on tags:
356 -foreground
358 Specifies the text foreground color.
359 -background
361 Specifies the cell or item background color.
362 -font Specifies the font to use when drawing text.
364 -image Specifies the item image, in case the item's -image option is
366 empty.
367
369 Column identifiers take any of the following forms:
370 · A symbolic name from the list of -columns.
372 · An integer n, specifying the nth data column.
374 · A string of the form #n, where n is an integer, specifying the
376 nth display column.
377 NOTE: Item -values may be displayed in a different order than the order
379 in which they are stored.
380 NOTE: Column #0 always refers to the tree column, even if -show tree is
382 not specified.
383 A data column number is an index into an item's -values list; a display
385 column number is the column number in the tree where the values are
386 displayed. Tree labels are displayed in column #0. If -displaycolumns
387 is not set, then data column n is displayed in display column #n+1.
388 Again, column #0 always refers to the tree column.
389
391 The treeview widget generates the following virtual events.
392 <<TreeviewSelect>>
394 Generated whenever the selection changes.
395 <<TreeviewOpen>>
397 Generated just before setting the focus item to -open true.
398 <<TreeviewClose>>
400 Generated just after setting the focus item to -open false.
401 The focus and selection widget commands can be used to determine the
403 affected item or items.
404
406 ttk::widget(n), listbox(n), image(n), bind(n)
407Tk 8.5.9 ttk::treeview(n)