1treeview(n) Tile Widget Set treeview(n)
2
6 ttk::treeview - hierarchical multicolumn data display widget
7
9 ttk::treeview pathname ?options?
10
12 The treeview widget displays a hierarchical collection of items. Each
13 item has a textual label, an optional image, and an optional list of
14 data values. The data values are displayed in successive columns after
15 the tree label.
16 The order in which data values are displayed may be controlled by set‐
18 ting the -displaycolumns widget option. The tree widget can also dis‐
19 play column headings. Columns may be accessed by number or by symbolic
20 names listed in the -columns widget option; see COLUMN IDENTIFIERS.
21 Each item is identified by a unique name. The widget will generate
23 item IDs if they are not supplied by the caller. There is a distin‐
24 guished root item, named {}. The root item itself is not displayed;
25 its children appear at the top level of the hierarchy.
26 Each item also has a list of tags, which can be used to associate event
28 bindings with individual items and control the appearance of the item.
29 Treeview widgets support vertical scrolling with the standard -yscroll‐
31 command option and yview widget command. They probably ought to sup‐
32 port horizontal scrolling as well. -class -cursor -takefo‐
33 cus -style -yscrollcommand
34
36 [-columns columns] A list of column identifiers, specifying the number
37 of columns and their names. [-displaycolumns displayColumns] A list of
38 column identifiers (either symbolic names or integer indices) specify‐
39 ing which data columns are displayed and the order in which they
40 appear.
41 If empty (the default), all columns are shown in the order given.
42 [-height height] Specifies the number of rows which should be visible.
43 Note: the requested width is determined from the sum of the column
44 widths. [-padding padding] Specifies the internal padding for the wid‐
45 get. The padding is a list of up to four length specifications; see
46 Ttk_GetPaddingFromObj() for details. [-selectmode selectMode] Controls
47 how the built-in class bindings manage the selection. One of extended,
48 browse, or none.
49 If set to extended (the default), multiple items may be selected. If
50 browse, only a single item will be selected at a time. If none, the
51 selection will not be changed.
52 Note that application code and tag bindings can set the selection how‐
53 ever they wish, regardless of the value of -selectmode. [-show show] A
54 list containing zero or more of the following values, specifying which
55 elements of the tree to display.
56 tree Display tree labels in column #0.
58 headings
60 Display the heading row.
61 The default is tree headings, i.e., show all elements.
63 NOTE: Column #0 always refers to the tree column, even if -show
65 tree is not specified.
66
68 pathname bbox item ?column?
69 Returns the bounding box (relative to the treeview widget's win‐
70 dow) of the specified item in the form x y width height. If
71 column is specified, returns the bounding box of that cell. If
72 the item is not visible (i.e., if it is a descendant of a closed
73 item or is scrolled offscreen), returns the empty list.
74 pathname cget option
76 Returns the current value of the specified option; see wid‐
77 get(n).
78 pathname children item ?newchildren?
80 If newchildren is not specified, returns the list of children
81 belonging to item.
82 If newchildren is specified, replaces item's child list with
83 newchildren. Items in the old child list not present in the new
84 child list are detached from the tree. None of the items in
85 newchildren may be an ancestor of item.
86 pathname column column ?-option ?value -option value...?
88 Query or modify the options for the specified column. If no
89 -option is specified, returns a dictionary of option/value
90 pairs. If a single -option is specified, returns the value of
91 that option. Otherwise, the options are updated with the speci‐
92 fied values. The following options may be set on each column:
93 -id name
95 The column name. This is a read-only option. For exam‐
96 ple, [$pathname column #n -id] returns the data column
97 associated with data column #n.
98 -anchor
100 Specifies how the text in this column should be aligned
101 with respect to the cell. One of n, ne, e, se, s, sw, w,
102 nw, or center.
103 -width w
105 The width of the column in pixels. Default is something
106 reasonable, probably 200 or so.
107 Use pathname column #0 to configure the tree column.
109 pathname configure ?option? ?value option value ...?
111 Modify or query widget options; see widget(n).
112 pathname delete itemList
114 Deletes each of the items in itemList and all of their descen‐
115 dants. The root item may not be deleted. See also: detach.
116 pathname detach itemList
118 Unlinks all of the specified items in itemList from the tree.
119 The items and all of their descendants are still present and may
120 be reinserted at another point in the tree but will not be dis‐
121 played. The root item may not be detached. See also: delete.
122 pathname exists item
124 Returns 1 if the specified item is present in the tree, 0 other‐
125 wise.
126 pathname focus ?item?
128 If item is specified, sets the focus item to item. Otherwise,
129 returns the current focus item, or {} if there is none.
130 pathname heading column ?-option ?value -option value...?
132 Query or modify the heading options for the specified column.
133 Valid options are:
134 -text text
136 The text to display in the column heading.
137 -image imageName
139 Specifies an image to display to the right of the column
140 heading.
141 -anchor anchor
143 Specifies how the heading text should be aligned. One of
144 the standard Tk anchor values.
145 -command script
147 A script to evaluate when the heading label is pressed.
148 Use pathname heading #0 to configure the tree column heading.
150 pathname identify component x y
152 Returns a description of the specified component under the point
153 given by x and y, or the empty string if no such component is
154 present at that position. The following subcommands are sup‐
155 ported:
156 pathname identify row x y
158 Returns the item ID of the item at position y.
159 pathname identify column x y
161 Returns the data column identifier of the cell at posi‐
162 tion x. The tree column has ID #0.
163 See COLUMN IDENTIFIERS for a discussion of display columns and
165 data columns.
166 pathname index item
168 Returns the integer index of item within its parent's list of
169 children.
170 pathname insert parent index ?-id id? options...
172 Creates a new item. parent is the item ID of the parent item,
173 or the empty string {} to create a new top-level item. index is
174 an integer, or the value end, specifying where in the list of
175 parent's children to insert the new item. If index is less than
176 or equal to zero, the new node is inserted at the beginning; if
177 index is greater than or equal to the current number of chil‐
178 dren, it is inserted at the end. If -id is specified, it is
179 used as the item identifier; id must not already exist in the
180 tree. Otherwise, a new unique identifier is generated.
181 pathname insert returns the item identifier of the newly created
182 item. See ITEM OPTIONS for the list of available options.
183 pathname instate statespec ?script?
185 Test the widget state; see widget(n).
186 pathname item item ?-option ?value -option value...?
188 Query or modify the options for the specified item. If no
189 -option is specified, returns a dictionary of option/value
190 pairs. If a single -option is specified, returns the value of
191 that option. Otherwise, the item's options are updated with the
192 specified values. See ITEM OPTIONS for the list of available
193 options.
194 pathname move item parent index
196 Moves item to position index in parent's list of children. It
197 is illegal to move an item under one of its descendants.
198 If index is less than or equal to zero, item is moved to the
199 beginning; if greater than or equal to the number of children,
200 it's moved to the end.
201 pathname next item
203 Returns the identifier of item's next sibling, or {} if item is
204 the last child of its parent.
205 pathname parent item
207 Returns the ID of the parent of item, or {} if item is at the
208 top level of the hierarchy.
209 pathname prev item
211 Returns the identifier of item's previous sibling, or {} if item
212 is the first child of its parent.
213 pathname see item
215 Ensure that item is visible: sets all of item's ancestors to
216 -open true, and scrolls the widget if necessary so that item is
217 within the visible portion of the tree.
218 pathname selection ?selop itemList?
220 If selop is not specified, returns the list of selected items.
221 Otherwise, selop is one of the following:
222 pathname selection set itemList
224 itemList becomes the new selection.
225 pathname selection add itemList
227 Add itemList to the selection
228 pathname selection remove itemList
230 Remove itemList from the selection
231 pathname selection toggle itemList
233 Toggle the selection state of each item in itemList.
234 pathname set item ?column ?value??
236 With one argument, returns a dictionary of column/value pairs
237 for the specified item. With two arguments, returns the current
238 value of the specified column. With three arguments, sets the
239 value of column column in item item to the specified value. See
240 also COLUMN IDENTIFIERS.
241 pathname state ?stateSpec?
243 Modify or query the widget state; see widget(n).
244 pathName tag args...
246 pathName tag bind tagName ?sequence ?script??
248 Add a Tk binding script for the event sequence sequence
249 to the tag tagName. When an X event is delivered to an
250 item, binding scripts for each of the item's -tags are
251 evaluated in order as per bindtags(n).
252 <KeyPress>, <KeyRelease>, and virtual events are sent to
253 the focus item. <ButtonPress>, <ButtonRelease>, and
254 <Motion> events are sent to the item under the mouse
255 pointer. No other event types are supported.
256 The binding script undergoes %-substitutions before eval‐
257 uation; see bind(n) for details.
258 pathName tag configure ?option? ?value option value ...?
260 Query or modify the options for the specified tagName.
261 If one or more option/value pairs are specified, sets the
262 value of those options for the specified tag. If a sin‐
263 gle option is specified, returns the value of that option
264 (or the empty string if the option has not been specified
265 for tagName). With no additional arguments, returns a
266 dictionary of the option settings for tagName. See TAG
267 OPTIONS for the list of available options.
268 pathName yview args
270 Standard command for vertical scrolling; see widget(n).
271
274 The following item options may be specified for items in the insert and
275 item widget commands. [-text text] The textual label to display for
276 the item. [-image image] A Tk image, displayed to the left of the
277 label. [-values values] The list of values associated with the item.
278 Each item should have the same number of values as the -columns widget
279 option. If there are fewer values than columns, the remaining values
280 are assumed empty. If there are more values than columns, the extra
281 values are ignored. [-open open] A boolean value indicating whether
282 the items's children should be displayed (-open true) or hidden (-open
283 false). [-tags tags] A list of tags associated with this item.
284
286 The following options may be specified on tags:
287 -foreground
289 Specifies the text foreground color.
290 -background
292 Specifies the cell or item background color.
293 -font Specifies the font to use when drawing text.
295 -image Specifies the item image, in case the item's -image option is
297 empty.
298 (@@@ TODO: sort out order of precedence for options)
300
302 Column identifiers take any of the following forms:
303 · A symbolic name from the list of -columns.
305 · An integer n, specifying the nth data column.
307 · A string of the form #n, where n is an integer, specifying the
309 nth display column.
310 NOTE: Item -values may be displayed in a different order than the order
312 in which they are stored.
313 NOTE: Column #0 always refers to the tree column, even if -show tree is
315 not specified.
316 A data column number is an index into an item's -values list; a display
318 column number is the column number in the tree where the values are
319 displayed. Tree labels are displayed in column #0. If -displaycolumns
320 is not set, then data column n is displayed in display column #n+1.
321 Again, column #0 always refers to the tree column.
322
324 The treeview widget generates the following virtual events.
325 <<TreeviewSelect>>
327 Generated whenever the selection changes.
328 <<TreeviewOpen>>
330 Generated just before setting the focus item to -open true.
331 <<TreeviewClose>>
333 Generated just after setting the focus item to -open false.
334 The focus and selection widget commands can be used to determine the
336 affected item or items. In Tk 8.5, the affected item is also passed as
337 the -detail field of the virtual event.
338
340 widget(n), listbox(n), image(n), bind(n)
341tile 0.5 treeview(n)