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.
48 If set to #all (the default), all columns are shown in the order
50 given.
51 [-height height] Specifies the number of rows which should be visible.
52 Note: the requested width is determined from the sum of the column
53 widths. [-padding padding] Specifies the internal padding for the wid‐
54 get. The padding is a list of up to four length specifications; see
55 Ttk_GetPaddingFromObj() for details. [-selectmode selectMode] Controls
56 how the built-in class bindings manage the selection. One of extended,
57 browse, or none.
58 If set to extended (the default), multiple items may be
60 selected. If browse, only a single item will be selected at a
61 time. If none, the selection will not be changed.
62 Note that application code and tag bindings can set the selec‐
64 tion however they wish, regardless of the value of -selectmode.
65 [-show show] A list containing zero or more of the following values,
66 specifying which elements of the tree to display.
67 tree Display tree labels in column #0.
69 headings
71 Display the heading row.
72 The default is tree headings, i.e., show all elements.
74 NOTE: Column #0 always refers to the tree column, even if -show
76 tree is not specified.
77
79 pathname bbox item ?column?
80 Returns the bounding box (relative to the treeview widget's win‐
81 dow) of the specified item in the form x y width height. If
82 column is specified, returns the bounding box of that cell. If
83 the item is not visible (i.e., if it is a descendant of a closed
84 item or is scrolled offscreen), returns the empty list.
85 pathname cget option
87 Returns the current value of the specified option; see ttk::wid‐
88 get(n).
89 pathname children item ?newchildren?
91 If newchildren is not specified, returns the list of children
92 belonging to item.
93 If newchildren is specified, replaces item's child list with
95 newchildren. Items in the old child list not present in the new
96 child list are detached from the tree. None of the items in
97 newchildren may be an ancestor of item.
98 pathname column column ?-option ?value -option value...?
100 Query or modify the options for the specified column. If no
101 -option is specified, returns a dictionary of option/value
102 pairs. If a single -option is specified, returns the value of
103 that option. Otherwise, the options are updated with the speci‐
104 fied values. The following options may be set on each column:
105 -id name
107 The column name. This is a read-only option. For exam‐
108 ple, [$pathname column #n -id] returns the data column
109 associated with display column #n.
110 -anchor
112 Specifies how the text in this column should be aligned
113 with respect to the cell. One of n, ne, e, se, s, sw, w,
114 nw, or center.
115 -minwidth
117 The minimum width of the column in pixels. The treeview
118 widget will not make the column any smaller than -min‐
119 width when the widget is resized or the user drags a col‐
120 umn separator.
121 -stretch
123 Specifies whether or not the column's width should be
124 adjusted when the widget is resized.
125 -width w
127 The width of the column in pixels. Default is something
128 reasonable, probably 200 or so.
129 Use pathname column #0 to configure the tree column.
131 pathname configure ?option? ?value option value ...?
133 Modify or query widget options; see ttk::widget(n).
134 pathname delete itemList
136 Deletes each of the items in itemList and all of their descen‐
137 dants. The root item may not be deleted. See also: detach.
138 pathname detach itemList
140 Unlinks all of the specified items in itemList from the tree.
141 The items and all of their descendants are still present and may
142 be reinserted at another point in the tree but will not be dis‐
143 played. The root item may not be detached. See also: delete.
144 pathname exists item
146 Returns 1 if the specified item is present in the tree, 0 other‐
147 wise.
148 pathname focus ?item?
150 If item is specified, sets the focus item to item. Otherwise,
151 returns the current focus item, or {} if there is none.
152 pathname heading column ?-option ?value -option value...?
154 Query or modify the heading options for the specified column.
155 Valid options are:
156 -text text
158 The text to display in the column heading.
159 -image imageName
161 Specifies an image to display to the right of the column
162 heading.
163 -anchor anchor
165 Specifies how the heading text should be aligned. One of
166 the standard Tk anchor values.
167 -command script
169 A script to evaluate when the heading label is pressed.
170 Use pathname heading #0 to configure the tree column heading.
172 pathname identify component x y
174 Returns a description of the specified component under the point
175 given by x and y, or the empty string if no such component is
176 present at that position. The following subcommands are sup‐
177 ported:
178 pathname identify row x y
180 Returns the item ID of the item at position y.
181 pathname identify column x y
183 Returns the data column identifier of the cell at posi‐
184 tion x. The tree column has ID #0.
185 See COLUMN IDENTIFIERS for a discussion of display columns and
187 data columns.
188 pathname index item
190 Returns the integer index of item within its parent's list of
191 children.
192 pathname insert parent index ?-id id? options...
194 Creates a new item. parent is the item ID of the parent item,
195 or the empty string {} to create a new top-level item. index is
196 an integer, or the value end, specifying where in the list of
197 parent's children to insert the new item. If index is less than
198 or equal to zero, the new node is inserted at the beginning; if
199 index is greater than or equal to the current number of chil‐
200 dren, it is inserted at the end. If -id is specified, it is
201 used as the item identifier; id must not already exist in the
202 tree. Otherwise, a new unique identifier is generated.
203 pathname insert returns the item identifier of the newly created
205 item. See ITEM OPTIONS for the list of available options.
206 pathname instate statespec ?script?
208 Test the widget state; see ttk::widget(n).
209 pathname item item ?-option ?value -option value...?
211 Query or modify the options for the specified item. If no
212 -option is specified, returns a dictionary of option/value
213 pairs. If a single -option is specified, returns the value of
214 that option. Otherwise, the item's options are updated with the
215 specified values. See ITEM OPTIONS for the list of available
216 options.
217 pathname move item parent index
219 Moves item to position index in parent's list of children. It
220 is illegal to move an item under one of its descendants.
221 If index is less than or equal to zero, item is moved to the
223 beginning; if greater than or equal to the number of children,
224 it is moved to the end.
225 pathname next item
227 Returns the identifier of item's next sibling, or {} if item is
228 the last child of its parent.
229 pathname parent item
231 Returns the ID of the parent of item, or {} if item is at the
232 top level of the hierarchy.
233 pathname prev item
235 Returns the identifier of item's previous sibling, or {} if item
236 is the first child of its parent.
237 pathname see item
239 Ensure that item is visible: sets all of item's ancestors to
240 -open true, and scrolls the widget if necessary so that item is
241 within the visible portion of the tree.
242 pathname selection ?selop itemList?
244 If selop is not specified, returns the list of selected items.
245 Otherwise, selop is one of the following:
246 pathname selection set itemList
248 itemList becomes the new selection.
249 pathname selection add itemList
251 Add itemList to the selection
252 pathname selection remove itemList
254 Remove itemList from the selection
255 pathname selection toggle itemList
257 Toggle the selection state of each item in itemList.
258 pathname set item ?column? ?value?
260 With one argument, returns a dictionary of column/value pairs
261 for the specified item. With two arguments, returns the current
262 value of the specified column. With three arguments, sets the
263 value of column column in item item to the specified value. See
264 also COLUMN IDENTIFIERS.
265 pathname state ?stateSpec?
267 Modify or query the widget state; see ttk::widget(n).
268 pathName tag args...
270 pathName tag bind tagName ?sequence? ?script?
272 Add a Tk binding script for the event sequence sequence
273 to the tag tagName. When an X event is delivered to an
274 item, binding scripts for each of the item's -tags are
275 evaluated in order as per bindtags(n).
276 <KeyPress>, <KeyRelease>, and virtual events are sent to
278 the focus item. <ButtonPress>, <ButtonRelease>, and
279 <Motion> events are sent to the item under the mouse
280 pointer. No other event types are supported.
281 The binding script undergoes %-substitutions before eval‐
283 uation; see bind(n) for details.
284 pathName tag configure tagName ?option? ?value option value...?
286 Query or modify the options for the specified tagName.
287 If one or more option/value pairs are specified, sets the
288 value of those options for the specified tag. If a sin‐
289 gle option is specified, returns the value of that option
290 (or the empty string if the option has not been specified
291 for tagName). With no additional arguments, returns a
292 dictionary of the option settings for tagName. See TAG
293 OPTIONS for the list of available options.
294 pathName xview args
296 Standard command for horizontal scrolling; see widget(n).
297 pathName yview args
299 Standard command for vertical scrolling; see ttk::widget(n).
300
302 The following item options may be specified for items in the insert and
303 item widget commands. [-text text] The textual label to display for
304 the item. [-image image] A Tk image, displayed to the left of the
305 label. [-values values] The list of values associated with the item.
306 Each item should have the same number of values as the -columns
308 widget option. If there are fewer values than columns, the
309 remaining values are assumed empty. If there are more values
310 than columns, the extra values are ignored.
311 [-open open] A boolean value indicating whether the item's children
312 should be displayed (-open true) or hidden (-open false). [-tags tags]
313 A list of tags associated with this item.
314
316 The following options may be specified on tags:
317 -foreground
319 Specifies the text foreground color.
320 -background
322 Specifies the cell or item background color.
323 -font Specifies the font to use when drawing text.
325 -image Specifies the item image, in case the item's -image option is
327 empty.
328 (@@@ TODO: sort out order of precedence for options)
330
332 Column identifiers take any of the following forms:
333 · A symbolic name from the list of -columns.
335 · An integer n, specifying the nth data column.
337 · A string of the form #n, where n is an integer, specifying the
339 nth display column.
340 NOTE: Item -values may be displayed in a different order than the order
342 in which they are stored.
343 NOTE: Column #0 always refers to the tree column, even if -show tree is
345 not specified.
346 A data column number is an index into an item's -values list; a display
348 column number is the column number in the tree where the values are
349 displayed. Tree labels are displayed in column #0. If -displaycolumns
350 is not set, then data column n is displayed in display column #n+1.
351 Again, column #0 always refers to the tree column.
352
354 The treeview widget generates the following virtual events.
355 <<TreeviewSelect>>
357 Generated whenever the selection changes.
358 <<TreeviewOpen>>
360 Generated just before setting the focus item to -open true.
361 <<TreeviewClose>>
363 Generated just after setting the focus item to -open false.
364 The focus and selection widget commands can be used to determine the
366 affected item or items.
367
369 ttk::widget(n), listbox(n), image(n), bind(n)
370Tk 8.5 ttk::treeview(n)