1ttk::treeview(n)               Tk Themed Widget               ttk::treeview(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       ttk::treeview - hierarchical multicolumn data display widget
9

SYNOPSIS

11       ttk::treeview pathname ?options?
12______________________________________________________________________________
13

DESCRIPTION

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
20       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
25       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
30       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
33       Treeview  widgets  support  horizontal  and vertical scrolling with the
34       standard -[xy]scrollcommand options and [xy]view widget commands.
35

STANDARD OPTIONS

37       -class                -cursor              -takefocus
38       -style                -xscrollcommand      -yscrollcommand
39       -padding
40
41       See the ttk_widget manual entry for details on the standard options.
42

WIDGET-SPECIFIC OPTIONS

44       Command-Line Name:-columns
45       Database Name:  columns
46       Database Class: Columns
47
48              A list of column identifiers, specifying the number  of  columns
49              and their names.
50
51       Command-Line Name:-displaycolumns
52       Database Name:  displayColumns
53       Database Class: DisplayColumns
54
55              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
60       Command-Line Name:-height
61       Database Name:  height
62       Database Class: Height
63
64              Specifies the number of rows which should be visible.  Note: the
65              requested width is determined from the sum of the column widths.
66
67       Command-Line Name:-selectmode
68       Database Name:  selectMode
69       Database Class: SelectMode
70
71              Controls  how  the built-in class bindings manage the selection.
72              One of extended, browse, or none.
73
74              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
78              Note that application code and tag bindings can set  the  selec‐
79              tion however they wish, regardless of the value of -selectmode.
80
81       Command-Line Name:-show
82       Database Name:  show
83       Database Class: Show
84
85              A list containing zero or more of the following values, specify‐
86              ing which elements of the tree to display.
87
88              tree   Display tree labels in column #0.
89
90              headings
91                     Display the heading row.
92
93              The default is tree headings, i.e., show all elements.
94
95              NOTE: Column #0 always refers to the tree column, even if  -show
96              tree is not specified.
97

WIDGET COMMAND

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
106       pathname cget option
107              Returns the current value of the specified option; see ttk::wid‐
108              get(n).
109
110       pathname children item ?newchildren?
111              If newchildren is not specified, returns the  list  of  children
112              belonging to item.
113
114              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
119       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
126              -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
131              -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
136              -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
142              -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
149              -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
155              Use pathname column #0 to configure the tree column.
156
157       pathname configure ?option? ?value option value ...?
158              Modify or query widget options; see ttk::widget(n).
159
160       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
164       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
171       pathname exists item
172              Returns 1 if the specified item is present in the tree, 0 other‐
173              wise.
174
175       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
179       pathname heading column ?-option ?value -option value...?
180              Query  or  modify  the heading options for the specified column.
181              Valid options are:
182
183              -text text
184                     The text to display in the column heading.
185
186              -image imageName
187                     Specifies an image to display to the right of the  column
188                     heading.
189
190              -anchor anchor
191                     Specifies how the heading text should be aligned.  One of
192                     the standard Tk anchor values.
193
194              -command script
195                     A script to evaluate when the heading label is pressed.
196
197              Use pathname heading #0 to configure the tree column heading.
198
199       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
205              pathname identify region x y
206                     Returns one of:
207
208                     heading
209                            Tree heading area; use [pathname identify column x
210                            y] to determine the heading number.
211
212                     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
218                     tree   The tree area.
219
220                     cell   A data cell.
221              pathname  identify  item  x y Returns the item ID of the item at
222              position y.
223
224              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
228              pathname identify element x y
229                     The element at position x,y.
230
231              pathname identify row x y
232                     Obsolescent synonym for pathname identify item.
233
234              See  COLUMN  IDENTIFIERS for a discussion of display columns and
235              data columns.
236
237       pathname index item
238              Returns the integer index of item within its  parent's  list  of
239              children.
240
241       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
252              pathname insert returns the item identifier of the newly created
253              item.  See ITEM OPTIONS for the list of available options.
254
255       pathname instate statespec ?script?
256              Test the widget state; see ttk::widget(n).
257
258       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
266       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
270              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
274       pathname next item
275              Returns the identifier of item's next sibling, or {} if item  is
276              the last child of its parent.
277
278       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
282       pathname prev item
283              Returns the identifier of item's previous sibling, or {} if item
284              is the first child of its parent.
285
286       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
291       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
295              pathname selection set itemList
296                     itemList becomes the new selection.
297
298              pathname selection add itemList
299                     Add itemList to the selection
300
301              pathname selection remove itemList
302                     Remove itemList from the selection
303
304              pathname selection toggle itemList
305                     Toggle the selection state of each item in itemList.
306
307       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
314       pathname state ?stateSpec?
315              Modify or query the widget state; see ttk::widget(n).
316
317       pathName tag args...
318
319              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
325                     <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
330                     The binding script undergoes %-substitutions before eval‐
331                     uation; see bind(n) for details.
332
333              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
343              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
348              pathName tag names
349                     Returns a list of all tags used by the widget.
350
351              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
356              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
362       The  treeview  widget  also  supports the following generic ttk::widget
363       widget subcommands (see ttk::widget(n) for details):
364
365              xview                 yview
366
367

ITEM OPTIONS

369       The following item options may be specified for items in the insert and
370       item widget commands.
371
372       Command-Line Name:-text
373       Database Name:  text
374       Database Class: Text
375
376              The textual label to display for the item.
377
378       Command-Line Name:-image
379       Database Name:  image
380       Database Class: Image
381
382              A Tk image, displayed to the left of the label.
383
384       Command-Line Name:-values
385       Database Name:  values
386       Database Class: Values
387
388              The list of values associated with the item.
389
390              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
395       Command-Line Name:-open
396       Database Name:  open
397       Database Class: Open
398
399              A boolean value indicating whether the item's children should be
400              displayed (-open true) or hidden (-open false).
401
402       Command-Line Name:-tags
403       Database Name:  tags
404       Database Class: Tags
405
406              A list of tags associated with this item.
407

TAG OPTIONS

409       The following options may be specified on tags:
410
411       -foreground
412              Specifies the text foreground color.
413
414       -background
415              Specifies the cell or item background color.
416
417       -font  Specifies the font to use when drawing text.
418
419       -image Specifies  the  item  image, in case the item's -image option is
420              empty.
421
422       Tag priority is decided by  the  creation  order:  tags  created  first
423       receive higher priority.
424

COLUMN IDENTIFIERS

426       Column identifiers take any of the following forms:
427
428       ·      A symbolic name from the list of -columns.
429
430       ·      An integer n, specifying the nth data column.
431
432       ·      A  string  of the form #n, where n is an integer, specifying the
433              nth display column.
434
435       NOTE: Item -values may be displayed in a different order than the order
436       in which they are stored.
437
438       NOTE: Column #0 always refers to the tree column, even if -show tree is
439       not specified.
440
441       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

VIRTUAL EVENTS

448       The treeview widget generates the following virtual events.
449
450       <<TreeviewSelect>>
451              Generated whenever the selection changes.
452
453       <<TreeviewOpen>>
454              Generated just before setting the focus item to -open true.
455
456       <<TreeviewClose>>
457              Generated just after setting the focus item to -open false.
458
459       The focus and selection widget commands can be used  to  determine  the
460       affected item or items.
461

STYLING OPTIONS

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
467       Dynamic states: disabled, selected.
468
469       Treeview styling options configurable with ttk::style are:
470
471       -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
480              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
485              ttk::style configure Treeview \
486                   -rowheight [expr {[font metrics font -linespace] + 2}]
487
488       Heading styling options configurable with ttk::style are:
489
490       -background color
491       -font font
492       -relief relief
493
494       Item styling options configurable with ttk::style are:
495
496       -foreground color
497       -indicatormargins padding
498       -indicatorsize amount
499       -padding padding
500
501       Cell styling options configurable with ttk::style are:
502
503       -padding padding
504
505       Some options are only available for specific themes.
506
507       See the ttk::style manual page for information on how to configure  ttk
508       styles.
509

SEE ALSO

511       ttk::widget(n), listbox(n), image(n), bind(n)
512
513
514
515Tk                                    8.5                     ttk::treeview(n)
Impressum