1treectrl(n)                       Tk Commands                      treectrl(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       treectrl - Create and manipulate hierarchical multicolumn widgets
9

SYNOPSIS

11       package require treectrl  2.4.1
12
13       treectrl pathName ?options?
14
15       pathName activate itemDesc
16
17       pathName bbox ?area?
18
19       pathName canvasx windowx
20
21       pathName canvasy windowy
22
23       pathName cget option
24
25       pathName collapse ?-recurse? ?itemDesc ...?
26
27       pathName column option column ?arg ...?
28
29       pathName column bbox columnDesc
30
31       pathName column cget columnDesc option
32
33       pathName  column  configure  columnDesc  ?option? ?value? ?option value
34       ...?
35
36       pathName column compare column1 op column2
37
38       pathName column count ?columnDesc?
39
40       pathName column create ?option value ...?
41
42       pathName column delete first ?last?
43
44       pathName column dragcget option
45
46       pathName column dragconfigure ?option? ?value? ?option value ...?
47
48       pathName column index columnDesc
49
50       pathName column id columnDesc
51
52       pathName column list ?-visible?
53
54       pathName column move columnDesc beforeDesc
55
56       pathName column neededwidth columnDesc
57
58       pathName column order columnDesc ?-visible?
59
60       pathName column tag option ?arg arg ...?
61
62       pathName column tag add columnDesc tagList
63
64       pathName column tag expr columnDesc tagExpr
65
66       pathName column tag names columnDesc
67
68       pathName column tag remove columnDesc tagList
69
70       pathName column width columnDesc
71
72       pathName compare itemDesc1 op itemDesc2
73
74       pathName configure ?option? ?value option value ...?
75
76       pathName contentbox
77
78       pathName debug option ?arg arg ...?
79
80       pathName debug alloc
81
82       pathName debug cget option
83
84       pathName debug configure ?option? ?value? ?option value ...?
85
86       pathName debug dinfo option
87
88       pathName debug expose x1 y1 x2 y2
89
90       pathName depth ?itemDesc?
91
92       pathName dragimage option ?arg ...?
93
94       pathName dragimage add itemDesc ?column? ?element?
95
96       pathName dragimage cget option
97
98       pathName dragimage clear
99
100       pathName dragimage configure ?option? ?value? ?option value ...?
101
102       pathName dragimage offset ?x y?
103
104       pathName element option ?element? ?arg arg ...?
105
106       pathName element cget element option
107
108       pathName element configure element ?option? ?value? ?option value ...?
109
110       pathName element create name type ?option value ...?
111
112       pathName element delete ?element ...?
113
114       pathName element names
115
116       pathName element perstate element option stateList
117
118       pathName element type element
119
120       pathName expand ?-recurse? ?itemDesc ...?
121
122       pathName gradient option ?arg ...?
123
124       pathName gradient cget gradient option
125
126       pathName gradient configure gradient ?option value ...?
127
128       pathName gradient create name ?option value ...?
129
130       pathName gradient delete ?name ...?
131
132       pathName gradient names
133
134       pathName gradient native ?preference?
135
136       pathName header option ?arg ...?
137
138       pathName header bbox headerDesc ?column? ?element?
139
140       pathName header compare headerDesc1 op headerDesc2
141
142       pathName header configure headerDesc ?arg ...?
143
144       pathName header count ?headerDesc?
145
146       pathName header create ?option value?
147
148       pathName header delete headerDesc
149
150       pathName header dragcget ?arg ...?
151
152       pathName header dragconfigure ?arg ...?
153
154       pathName header element ?arg ...?
155
156       pathName header id headerDesc
157
158       pathName header image headerDesc ?column? ?image? ?column image ...?
159
160       pathName header span  headerDesc  ?column?  ?numColumns?  ?column  num‐
161       Columns ...?
162
163       pathName header state command headerDesc ?arg ...?
164
165       pathName header style command headerDesc ?arg ...?
166
167       pathName header text headerDesc ?column? ?text? ?column text ...?
168
169       pathName header tag command headerDesc ?arg ...?
170
171       pathName identify ?-array varName? x y
172
173       pathName index itemDesc
174
175       pathName item option ?arg ...?
176
177       pathName item ancestors itemDesc
178
179       pathName item bbox itemDesc ?column? ?element?
180
181       pathName item buttonstate itemDesc ?state?
182
183       pathName item cget itemDesc option
184
185       pathName item children itemDesc
186
187       pathName item collapse itemDesc ?-animate? ?-recurse?
188
189       pathName item compare itemDesc1 op itemDesc2
190
191       pathName item complex itemDesc ?list...?
192
193       pathName item configure itemDesc ?option? ?value? ?option value ...?
194
195       pathName item count ?itemDesc?
196
197       pathName item create ?option value ...?
198
199       pathName item delete first ?last?
200
201       pathName item descendants itemDesc
202
203       pathName item dump itemDesc
204
205       pathName item element command itemDesc column element ?arg ...?
206
207       pathName item element actual itemDesc column element option
208
209       pathName item element cget itemDesc column element option
210
211       pathName  item  element  configure  itemDesc  column  element  ?option?
212       ?value? ?option value ...?
213
214       pathName  item  element  perstate  itemDesc   column   element   option
215       ?stateList?
216
217       pathName item enabled itemDesc ?boolean?
218
219       pathName item expand itemDesc ?-animate? ?-recurse?
220
221       pathName item firstchild parent ?child?
222
223       pathName item id itemDesc
224
225       pathName item image itemDesc ?column? ?image? ?column image ...?
226
227       pathName item isancestor itemDesc descendant
228
229       pathName item isopen itemDesc
230
231       pathName item lastchild parent ?child?
232
233       pathName item nextsibling sibling ?next?
234
235       pathName item numchildren itemDesc
236
237       pathName item order itemDesc ?-visible?
238
239       pathName item parent itemDesc
240
241       pathName item prevsibling sibling ?prev?
242
243       pathName item range first last
244
245       pathName item remove itemDesc
246
247       pathName item rnc itemDesc
248
249       pathName item sort itemDesc ?option ...?
250
251       pathName  item  span  itemDesc ?column? ?numColumns? ?column numColumns
252       ...?
253
254       pathName item state command itemDesc ?arg ...?
255
256       pathName item state define stateName
257
258       pathName item state forcolumn itemDesc column ?stateDescList?
259
260       pathName item state get itemDesc ?stateName?
261
262       pathName item state linkage stateName
263
264       pathName item state names
265
266       pathName item state set itemDesc ?lastItem? stateDescList
267
268       pathName item state undefine ?stateName ...?
269
270       pathName item style command itemDesc ?arg ...?
271
272       pathName item style elements itemDesc column
273
274       pathName item style map itemDesc column style map
275
276       pathName item style set itemDesc ?column? ?style? ?column style ...?
277
278       pathName item tag option ?arg arg ...?
279
280       pathName item tag add itemDesc tagList
281
282       pathName item tag expr itemDesc tagExpr
283
284       pathName item tag names itemDesc
285
286       pathName item tag remove itemDesc tagList
287
288       pathName item text itemDesc ?column? ?text? ?column text ...?
289
290       pathName item toggle itemDesc ?-animate? ?-recurse?
291
292       pathName marquee option ?arg ...?
293
294       pathName marquee anchor ?x y?
295
296       pathName marquee cget option
297
298       pathName marquee configure ?option? ?value? ?option value ...?
299
300       pathName marquee coords ?x1 y1 x2 y2?
301
302       pathName marquee corner ?x y?
303
304       pathName marquee identify
305
306       pathName notify option ?arg ...?
307
308       pathName notify bind ?object? ?pattern? ?+??script?
309
310       pathName notify configure object pattern ?option? ?value? ?option value
311       ...?
312
313       pathName notify detailnames eventName
314
315       pathName notify eventnames
316
317       pathName notify generate pattern ?charMap? ?percentsCommand?
318
319       pathName notify install pattern ?percentsCommand?
320
321       pathName notify install detail eventName detail ?percentsCommand?
322
323       pathName notify install event eventName ?percentsCommand?
324
325       pathName notify linkage pattern
326
327       pathName notify linkage eventName ?detail?
328
329       pathName notify unbind object ?pattern?
330
331       pathName notify uninstall pattern
332
333       pathName notify uninstall detail eventName detail
334
335       pathName notify uninstall event eventName
336
337       pathName numcolumns
338
339       pathName numitems
340
341       pathName orphans
342
343       pathName range first last
344
345       pathName scan option args
346
347       pathName scan mark x y
348
349       pathName scan dragto x y ?gain?
350
351       pathName see itemDesc ?columnDesc? ?option value ...?
352
353       pathName selection option args
354
355       pathName selection add first ?last?
356
357       pathName selection anchor ?itemDesc?
358
359       pathName selection clear ?first? ?last?
360
361       pathName selection count
362
363       pathName selection get ?first? ?last?
364
365       pathName selection includes itemDesc
366
367       pathName selection modify select deselect
368
369       pathName state option args
370
371       pathName state define stateName
372
373       pathName state linkage stateName
374
375       pathName state names
376
377       pathName state undefine ?stateName ...?
378
379       pathName style option ?element? ?arg arg ...?
380
381       pathName style cget style option
382
383       pathName style configure style ?option? ?value? ?option value ...?
384
385       pathName style create name ?option value ...?
386
387       pathName style delete ?style ...?
388
389       pathName style elements style ?elementList?
390
391       pathName style layout style element ?option? ?value? ?option value ...?
392
393       pathName style names
394
395       pathName theme option ?arg ...?
396
397       pathName theme platform
398
399       pathName theme setwindowtheme appname
400
401       pathName toggle ?-recurse? ?itemDesc ...?
402
403       pathName xview ?args?
404
405       pathName xview
406
407       pathName xview moveto fraction
408
409       pathName xview scroll number what
410
411       pathName yview ?args?
412
413       pathName yview
414
415       pathName yview moveto fraction
416
417       pathName yview scroll number what
418
419_________________________________________________________________
420

DESCRIPTION

422       treectrl pathName ?options?
423
424       The  treectrl command creates a new window (given by the pathName argu‐
425       ment) and  makes  it  into  a  treectrl  widget.   Additional  options,
426       described  above, may be specified on the command line or in the option
427       database to configure aspects of the treectrl such  as  its  background
428       color  and  relief.   The treectrl command returns the path name of the
429       new window.  At the time this command is invoked, there must not  exist
430       a window named pathName, but pathName's parent must exist.
431
432       A  treectrl  is a listbox widget which displays items in a one- or two-
433       dimensional arrangement.  Items have a parent-child  relationship  with
434       other items.  Items may be arranged from top-to-bottom or from left-to-
435       right.  Items may be spread about one or more columns.  Each  item-col‐
436       umn  may  be configured to span one or more adjacent item-columns.  The
437       visibility of items can be set individually.
438
439       Items have a set of states, which are  boolean  properties.   For  each
440       column  of an item there is a style associated, which determines how to
441       display the item's column taking into account the item's current  state
442       set.   New  states  may be defined to further control the appearance of
443       items; these custom states may be turned on or off in  individual  col‐
444       umns of items.
445
446       Multiple  rows  of  column  headers are supported.  Column headers have
447       platform-native appearance on Windows, Mac OS X, and Gtk+.  The appear‐
448       ance of column headers may be customized using styles.
449
450       Columns  may be rearranged by the user using drag-and-drop.  One column
451       can be specified to display the data in a hierarchical structure.   The
452       visibility of columns can be set individually.
453
454       A  treectrl can display a user-resizable selection rectangle called the
455       marquee. Another feature, the drag image, may be used to provide  feed‐
456       back  during  drag-and-drop operations. Both of these are features com‐
457       monly found in file browsers.
458
459       A treectrl can generate events when  various  things  happen,  such  as
460       changes  to  the  selection,  or  a  parent  item being toggled open or
461       closed.  Scripts may be bound to  these  events.   New  events  can  be
462       defined.
463
464       A treectrl can display a background image.  The background image can be
465       configured to be scrolled and tiled on each axis individually.
466

STANDARD OPTIONS

468       -background
469
470       -borderwidth
471
472       -cursor
473
474       -font
475
476       -highlightbackground
477
478       -highlightcolor
479
480       -highlightthickness
481
482       -orient
483
484       -relief
485
486       -takefocus
487
488       -xscrollcommand
489
490       -yscrollcommand
491
492       -foreground
493
494       See the option manual entry for details on the standard options.
495

WIDGET SPECIFIC OPTIONS

497       Command-Line Switch:    -backgroundimage
498       Database Name:          backgroundImage
499       Database Class:         BackgroundImage
500
501
502              Specifies the name of an image to draw as the  list  background.
503              Other options control whether the image is tiled and whether the
504              image scrolls. If the image is transparent it is drawn on top of
505              any column -itembackground colors.
506
507       Command-Line Switch:    -backgroundmode
508       Database Name:          backgroundMode
509       Database Class:         BackgroundMode
510
511
512              Specifies  how  the  background color of items is chosen in each
513              column.  The value should be  one  of  row,  column,  order,  or
514              ordervisible.  The  default  is  row.   This  option has only an
515              effect for columns which have -itembackground defined as list of
516              two or more colors (see section COLUMNS below for more on this).
517              If row or column is specified, the background  color  is  chosen
518              based  on  the  location  of the item in the 1- or 2-dimensional
519              grid of items as layed out on the screen; this layout  of  items
520              is  affected  by  the  -orient and -wrap options as well as item
521              visibility.  When order or ordervisible is specified, the  back‐
522              ground  color  is  chosen  based on the result of the item order
523              command, regardless of the layout of items.
524
525       Command-Line Switch:    -bgimage
526       Database Name:          bgImage
527       Database Class:         BgImage
528
529
530              Synonym for -backgroundimage.
531
532       Command-Line Switch:    -bgimageanchor
533       Database Name:          bgImageAnchor
534       Database Class:         BgImageAnchor
535
536
537              Specifies how the background image should be aligned in  any  of
538              the forms acceptable to Tk_GetAnchor.  Must be one of the values
539              n, ne, e, se, s, sw, w, nw, or center.  The default is nw.  When
540              the background image scrolls, the anchor position is relative to
541              the canvas, otherwise it is relative to the contentbox.
542
543       Command-Line Switch:    -bgimageopaque
544       Database Name:          bgImageOpaque
545       Database Class:         BgImageOpaque
546
547
548              Specifies a boolean indicating whether  or  not  the  background
549              image  is  fully opaque.  This is needed because there is no way
550              in Tk to determine whether an  image  contains  transparency  or
551              not.   The  default  value  is true, so if you use a transparent
552              -backgroundimage you must set this to false.
553
554       Command-Line Switch:    -bgimagescroll
555       Database Name:          bgImageScroll
556       Database Class:         BgImageScroll
557
558
559              Specifies whether the background image scrolls  along  with  the
560              items  or  whether  it  remains  locked in place relative to the
561              edges of the window.  The value must be a string  that  contains
562              zero or more of the characters x or y.  The default is xy.
563
564       Command-Line Switch:    -bgimagetile
565       Database Name:          bgImageTile
566       Database Class:         BgImageTile
567
568
569              Specifies  whether  the  background  image  is tiled along the x
570              and/or y axes.  The value must be a string that contains zero or
571              more of the characters x or y.  The default is xy.
572
573       Command-Line Switch:    -buttonbitmap
574       Database Name:          buttonBitmap
575       Database Class:         ButtonBitmap
576
577
578              Specifies   the  name  of  a  bitmap  be  used  to  display  the
579              expand/collapse button of an item.  This is a per-state  option.
580              If  a bitmap is specified for a certain item state, it overrides
581              the effects of -usetheme.
582
583       Command-Line Switch:    -buttoncolor
584       Database Name:          buttonColor
585       Database Class:         ButtonColor
586
587
588              Specifies the foreground color which should be used for  drawing
589              the  outline and the plus or minus sign of an item's expand/col‐
590              lapse button.
591
592       Command-Line Switch:    -buttonimage
593       Database Name:          buttonImage
594       Database Class:         ButtonImage
595
596
597              Specifies the name of  an  image  to  be  used  to  display  the
598              expand/collapse  button of an item.  This is a per-state option.
599              If an image is specified for a certain item state, it  overrides
600              the effects of -buttonbitmap and -usetheme.
601
602       Command-Line Switch:    -buttonsize
603       Database Name:          buttonSize
604       Database Class:         ButtonSize
605
606
607              Specifies  the width and height of the expand/collapse button of
608              an item in any of the forms acceptable to Tk_GetPixels.
609
610       Command-Line Switch:    -buttonthickness
611       Database Name:          buttonThickness
612       Database Class:         ButtonThickness
613
614
615              Specifies the width of the outline and the plus or minus sign of
616              the  expand/collapse  button  of  an  item  in  any of the forms
617              acceptable to Tk_GetPixels.
618
619       Command-Line Switch:    -buttonttracking
620       Database Name:          buttonTracking
621       Database Class:         ButtonTracking
622
623
624              Specifies a boolean that determines if the expand/collapse  but‐
625              tons  are  tracked  like  pushbuttons  when clicking them.  When
626              true, buttons are not toggled until  the  <ButtonRelease>  event
627              occurs  over  them.   When false, buttons are toggled as soon as
628              the <ButtonPress> event occurs over them.  This option  defaults
629              to true on Mac OS X and Gtk+, false on Win32 and X11.
630
631       Command-Line Switch:    -canvaspadx
632       Database Name:          canvasPadX
633       Database Class:         CanvasPadX
634
635
636              Specifies  the  width  of extra whitespace on the left and right
637              edges of the canvas in any of the forms acceptable to Tk_GetPix‐
638              els.   The  option value may be a list of one or two screen dis‐
639              tances to specify padding for the  two  edges  separately.   The
640              default is 0.
641
642       Command-Line Switch:    -canvaspady
643       Database Name:          canvasPadY
644       Database Class:         CanvasPadY
645
646
647              Specifies  the  height of extra whitespace on the top and bottom
648              edges of the canvas in any of the forms acceptable to Tk_GetPix‐
649              els.   The  option value may be a list of one or two screen dis‐
650              tances to specify padding for the  two  edges  separately.   The
651              default is 0.
652
653       Command-Line Switch:    -columnprefix
654       Database Name:          columnPrefix
655       Database Class:         ColumnPrefix
656
657
658              Specifies  an  ascii  string that changes the way column ids are
659              reported and processed. If this option is  a  non-empty  string,
660              the  usual  integer  value  of  a column id is prefixed with the
661              given string. This can aid debugging but it  is  important  your
662              code doesn't assume column ids are integers if you use it.
663
664       Command-Line Switch:    -columnproxy
665       Database Name:          columnProxy
666       Database Class:         ColumnProxy
667
668
669              If  this  option  specifies  a  non  empty value, it should be a
670              screen distance in any of the forms acceptable to  Tk_GetPixels.
671              Then  a  1 pixel thick vertical line will be drawn at the speci‐
672              fied screen distance from the left edge of the treectrl  widget,
673              which reaches from top to bottom of the treectrl widget and uses
674              an inverting color (i.e black on lighter  background,  white  on
675              darker  background).   This  line can be used to give the user a
676              visual feedback during column resizing.
677
678       Command-Line Switch:    -columnresizemode
679       Database Name:          columnResizeMode
680       Database Class:         ColumnResizeMode
681
682
683              Specifies the visual feedback used when  resizing  columns.  The
684              value  should  be one of proxy or realtime. For proxy, a 1-pixel
685              thick vertical line is drawn representing where the  right  edge
686              of the column will be after resizing. For realtime, the column's
687              size is changed while the user is dragging the right edge of the
688              column.  The default is realtime.
689
690       Command-Line Switch:    -columntagexpr
691       Database Name:          columnTagExpr
692       Database Class:         ColumnTagExpr
693
694
695              Specifies  a boolean that enables or disables tag expressions in
696              column descriptions. See ITEM AND COLUMN TAGS.
697
698       Command-Line Switch:    -defaultstyle
699       Database Name:          defaultStyle
700       Database Class:         DefaultStyle
701
702
703              This option is deprecated;  use  the  column  option  -itemstyle
704              instead.   Specifies  a list of styles, one per column, to apply
705              to each item created by the item create command. The  number  of
706              styles in the list can be different from the number of tree col‐
707              umns.  Each list element should be a  valid  style  name  or  an
708              empty  string  to  indicate no style should be applied to a spe‐
709              cific column. The list of  styles  is  updated  if  a  style  is
710              deleted or if a column is moved.
711
712       Command-Line Switch:    -doublebuffer
713       Database Name:          doubleBuffer
714       Database Class:         DoubleBuffer
715
716
717              This  option  no longer has any effect, but was left in for com‐
718              patibility.  It used to control the amount  of  double-buffering
719              that was used when displaying a treectrl.
720
721       Command-Line Switch:    -headerfont
722       Database Name:          headerFont
723       Database Class:         Font
724
725
726              Specifies  the  font  to  draw text in column headers with.  The
727              default value is TkHeadingFont where  available  (on  Tk  8.5+).
728              This  option  can  be overridden by setting the -font option for
729              individual column headers.
730
731       Command-Line Switch:    -headerfg
732       Database Name:          headerForeground
733       Database Class:         Foreground
734
735
736              Synonym for -headerforeground.
737
738       Command-Line Switch:    -headerforeground
739       Database Name:          headerForeground
740       Database Class:         Foreground
741
742
743              Specifies the color to draw text in column  headers  with.   The
744              default value is the Tk button foreground color (usually black).
745              On Gtk+, the system theme may override this color.  This  option
746              (and  the  Gtk+ system theme color) can be overridden by setting
747              the -textcolor option for individual column headers.
748
749       Command-Line Switch:    -height
750       Database Name:          height
751       Database Class:         Height
752
753
754              Specifies the desired height for the window in any of the  forms
755              acceptable to Tk_GetPixels.  The default is 200 pixels.  If this
756              option is less than or equal to zero then the  window  will  not
757              request any size at all.
758
759       Command-Line Switch:    -indent
760       Database Name:          indent
761       Database Class:         Indent
762
763
764              Specifies  the  screen  distance an item is indented relative to
765              its parent item in any of the forms acceptable to  Tk_GetPixels.
766              The default is 19 pixels.
767
768       Command-Line Switch:    -itemgapx
769       Database Name:          itemGapX
770       Database Class:         ItemGapX
771
772
773              Specifies  the  horizontal spacing between adjacent items in any
774              of the forms acceptable to Tk_GetPixels.  The default is 0.
775
776       Command-Line Switch:    -itemgapy
777       Database Name:          itemGapY
778       Database Class:         ItemGapY
779
780
781              Specifies the vertical spacing between adjacent items in any  of
782              the forms acceptable to Tk_GetPixels.  The default is 0.
783
784       Command-Line Switch:    -itemheight
785       Database Name:          itemHeight
786       Database Class:         ItemHeight
787
788
789              Specifies  a  fixed  height  for  every item in any of the forms
790              acceptable to Tk_GetPixels. If non-zero, this  option  overrides
791              the  requested  height of an item and the -minitemheight option.
792              If an item's own -height option is specified then  that  is  the
793              height  used  for the item. In any case, items are never shorter
794              than the maximum height of a button if they  display  one.   The
795              default is 0.
796
797       Command-Line Switch:    -itemprefix
798       Database Name:          itemPrefix
799       Database Class:         ItemPrefix
800
801
802              Specifies  an  ascii  string  that  changes the way item ids are
803              reported and processed. If this option is  a  non-empty  string,
804              the usual integer value of an item id is prefixed with the given
805              string. This can aid debugging but it  is  important  your  code
806              doesn't assume item ids are integers if you use it.
807
808       Command-Line Switch:    -itemtagexpr
809       Database Name:          itemTagExpr
810       Database Class:         ItemTagExpr
811
812
813              Specifies  a boolean that enables or disables tag expressions in
814              item descriptions. See ITEM AND COLUMN TAGS.
815
816       Command-Line Switch:    -itemwidth
817       Database Name:          itemWidth
818       Database Class:         ItemWidth
819
820
821              Specifies a fixed width for every  item  in  any  of  the  forms
822              acceptable to Tk_GetPixels.  If more than one column is visible,
823              then this option has no effect.  If the -orient option is verti‐
824              cal,  and  the -wrap option is unspecified, then this option has
825              no effect (in that case all items are as wide as the column).
826
827       Command-Line Switch:    -itemwidthequal
828       Database Name:          itemWidthEqual
829       Database Class:         ItemWidthEqual
830
831
832              Specifies a boolean that says whether all items should have  the
833              same  width.   If  more  than  one  column is visible, then this
834              option has no effect.  If the -orient option  is  vertical,  and
835              the  -wrap option is unspecified, then this option has no effect
836              (in that case all items are as wide  as  the  column).   If  the
837              -itemwidth option is specified, then this option has no effect.
838
839       Command-Line Switch:    -itemwidthmultiple
840       Database Name:          itemWidthMultiple
841       Database Class:         ItemWidthMultiple
842
843
844              Specifies  a  screen  distance  that  every item's width will be
845              evenly divisible by in any of the forms acceptable to Tk_GetPix‐
846              els.   If  more than one column is visible, then this option has
847              no effect.  If the -orient option is  vertical,  and  the  -wrap
848              option  is  unspecified, then this option has no effect (in that
849              case all items are as wide as the column).   If  the  -itemwidth
850              option is specified, then this option has no effect.
851
852       Command-Line Switch:    -linecolor
853       Database Name:          lineColor
854       Database Class:         LineColor
855
856
857              Specifies  the  color  which should be used for drawing the con‐
858              necting lines between related items.
859
860       Command-Line Switch:    -linestyle
861       Database Name:          lineStyle
862       Database Class:         LineStyle
863
864
865              Specifies the appearance of the connecting lines between related
866              items.  The value should be dot, which is the default, or solid.
867
868       Command-Line Switch:    -linethickness
869       Database Name:          lineThickness
870       Database Class:         LineThickness
871
872
873              Specifies  the thickness of the connecting lines between related
874              items in any of the forms acceptable to Tk_GetPixels.
875
876       Command-Line Switch:    -minitemheight
877       Database Name:          minItemHeight
878       Database Class:         MinItemHeight
879
880
881              Specifies a minimum height for every item in any  of  the  forms
882              acceptable  to Tk_GetPixels.  The default is 0, which means that
883              every item has the height requested by the arrangement  of  ele‐
884              ments  in  each column.  This option has no effect if either the
885              -itemheight widget option or -height item option  is  specified.
886              In  any case, items are never shorter than the maximum height of
887              an expand/collapse button.
888
889       Command-Line Switch:    -rowproxy
890       Database Name:          rowProxy
891       Database Class:         RowProxy
892
893
894              If this option specifies a non  empty  value,  it  should  be  a
895              screen  distance in any of the forms acceptable to Tk_GetPixels.
896              Then a 1 pixel thick horizontal line will be drawn at the speci‐
897              fied  screen  distance from the top edge of the treectrl widget,
898              which reaches from left to right of the treectrl widget and uses
899              an  inverting  color  (i.e black on lighter background, white on
900              darker background).  This line can be used to give  the  user  a
901              visual feedback during row resizing.
902
903       Command-Line Switch:    -scrollmargin
904       Database Name:          scrollMargin
905       Database Class:         ScrollMargin
906
907
908              Specifies a positive screen distance in any of the forms accept‐
909              able to Tk_GetPixels.  This option is used by the default  bind‐
910              ings  to  determine how close to the edges of the contentbox the
911              mouse pointer must be before  scrolling  occurs.   Specifying  a
912              positive  value  is  useful  when items may be drag-and-dropped.
913              Defaults to 0.
914
915       Command-Line Switch:    -selectmode
916       Database Name:          selectMode
917       Database Class:         SelectMode
918
919
920              Specifies one of several styles for manipulating the  selection.
921              The  value of the option may be arbitrary, but the default bind‐
922              ings expect  it  to  be  either  single,  browse,  multiple,  or
923              extended;  the default value is browse.
924
925       Command-Line Switch:    -showbuttons
926       Database Name:          showButtons
927       Database Class:         ShowButtons
928
929
930              Specifies  a  boolean  value that determines whether this widget
931              leaves indentation space to display the expand/collapse  buttons
932              next  to  items.   The  default  value is true.  The item option
933              -button determines whether an item has a button.  See  also  the
934              widget options -showrootbutton and -showrootchildbuttons.
935
936       Command-Line Switch:    -showheader
937       Database Name:          showHeader
938       Database Class:         ShowHeader
939
940
941              Specifies  a  boolean  value that determines whether this widget
942              should display the header line with the column names at the  top
943              of the widget.  The default value is true.
944
945       Command-Line Switch:    -showlines
946       Database Name:          showLines
947       Database Class:         ShowLines
948
949
950              Specifies  a  boolean  value that determines whether this widget
951              should draw the connecting lines  between  related  items.   The
952              default  value  is  true on Win32 and X11, false on Mac OS X and
953              Gtk+.
954
955       Command-Line Switch:    -showroot
956       Database Name:          showRoot
957       Database Class:         ShowRoot
958
959
960              Specifies a boolean value that determines  whether  this  widget
961              should  draw  the  root item.  By suppressing the drawing of the
962              root item the widget can have  multiple  items  that  appear  as
963              toplevel items.  The default value is true.
964
965       Command-Line Switch:    -showrootbutton
966       Database Name:          showRootButton
967       Database Class:         ShowRootButton
968
969
970              Specifies  a  boolean  value that determines whether this widget
971              leaves indentation space to display the  expand/collapse  button
972              next  to  the  root  item. The default value is false.  The item
973              option -button determines whether the root item has a button.
974
975       Command-Line Switch:    -showrootchildbuttons
976       Database Name:          showRootChildButtons
977       Database Class:         ShowRootChildButtons
978
979
980              Specifies a boolean value that determines  whether  this  widget
981              should  draw the expand/collapse buttons next to children of the
982              root item.  The default value is true.
983
984       Command-Line Switch:    -showrootlines
985       Database Name:          showRootLines
986       Database Class:         ShowRootLines
987
988
989              Specifies a boolean value that determines  whether  this  widget
990              should  draw  the  connecting lines between children of the root
991              item.  The default value is true.
992
993       Command-Line Switch:    -treecolumn
994       Database Name:          treeColumn
995       Database Class:         TreeColumn
996
997
998              Specifies a column description that determines which column dis‐
999              plays  the  expand/collapse buttons and connecting lines between
1000              items.  The default is unspecified.
1001
1002       Command-Line Switch:    -usetheme
1003       Database Name:          useTheme
1004       Database Class:         UseTheme
1005
1006
1007              Specifies a boolean value that determines  whether  this  widget
1008              should draw parts of itself using a platform-specific theme man‐
1009              ager.  The default is true.
1010
1011       Command-Line Switch:    -width
1012       Database Name:          width
1013       Database Class:         Width
1014
1015
1016              Specifies the desired width for the window in any of  the  forms
1017              acceptable  to Tk_GetPixels.  The default is 200 pixel.  If this
1018              option is less than or equal to zero then the  window  will  not
1019              request any size at all.
1020
1021       Command-Line Switch:    -wrap
1022       Database Name:          wrap
1023       Database Class:         Wrap
1024
1025
1026              Specifies  whether  items  are arranged in a 1- or 2-dimensional
1027              layout.
1028
1029              If the value is an empty string (the default),  then  items  are
1030              arranged  from  top to bottom (-orient=vertical) or from left to
1031              right (-orient=horizontal) in a 1-dimensional layout.
1032
1033              If the value is "N items", then no more than N items will appear
1034              in  a  vertical  group  (-orient=vertical)  or  horizontal group
1035              (-orient=horizontal).
1036
1037              If the value is "N pixels", then no vertical group of items will
1038              be  taller  than  N  pixels  (-orient=vertical) or no horizontal
1039              group of items will be wider than N pixels (-orient=horizontal).
1040
1041              If the value is window, then a no vertical group of  items  will
1042              be  taller  than  the window (-orient=vertical) or no horizontal
1043              group of items will be wider than the  window  (-orient=horizon‐
1044              tal).
1045
1046              It  is  also  possible  to cause wrapping to occur on a per-item
1047              basis by using the item option -wrap.  See the item create  com‐
1048              mand for that option.
1049
1050       Command-Line Switch:    -xscrolldelay
1051       Database Name:          xScrollDelay
1052       Database Class:         ScrollDelay
1053
1054
1055              This  option  controls  how  quickly horizontal scrolling occurs
1056              while dragging the mouse  with  button  1  pressed.   The  value
1057              should be a list of 1 or 2 integers interpreted as milliseconds.
1058              If 2 values are specified, then the first value  determines  the
1059              intial delay after the first scroll, and the second value deter‐
1060              mines the delay for all scrolling after the  first.  If  only  1
1061              value is specified, each scroll takes place after that delay.
1062
1063       Command-Line Switch:    -xscrollincrement
1064       Database Name:          xScrollIncrement
1065       Database Class:         ScrollIncrement
1066
1067
1068              Specifies  an  increment for horizontal scrolling, in any of the
1069              usual forms permitted for screen distances.   If  the  value  of
1070              this  option  is  greater  than zero, the horizontal view in the
1071              window will be constrained so that the canvas  x  coordinate  at
1072              the  left  edge  of  the  window  is  always an even multiple of
1073              -xscrollincrement;  furthermore, the units for scrolling  (e.g.,
1074              the change in view when the left and right arrows of a scrollbar
1075              are selected) will also be -xscrollincrement.  If the  value  of
1076              this  option  is  less  than  or  equal to zero, then horizontal
1077              scrolling snaps to the left of an item, or part of  an  item  if
1078              items are wider than the contentbox.
1079
1080       Command-Line Switch:    -xscrollsmoothing
1081       Database Name:          xScrollSmoothing
1082       Database Class:         ScrollSmoothing
1083
1084
1085              Specifies  whether scrolling should be done as if -xscrollincre‐
1086              ment=1 whenever scrolling  is  performed  by  non-unit  amounts.
1087              When  the  value of this option is true and the xview command is
1088              called to scroll by "units", scrolling occurs according  to  the
1089              -xscrollincrement  option, and all other scrolling is done as if
1090              the -xscrollincrement option was set to 1.  The effect  is  that
1091              when  dragging the scrollbar thumb scrolling is very smooth, but
1092              when clicking the scrollbar buttons scrolling is done in coarser
1093              increments.  The default value is false.
1094
1095       Command-Line Switch:    -yscrolldelay
1096       Database Name:          yScrollDelay
1097       Database Class:         ScrollDelay
1098
1099
1100              This option controls how quickly vertical scrolling occurs while
1101              dragging the mouse with button 1 pressed.  The value should be a
1102              list  of 1 or 2 integers interpreted as milliseconds.  If 2 val‐
1103              ues are specified, then the first value  determines  the  intial
1104              delay  after  the  first scroll, and the second value determines
1105              the delay for all scrolling after the first. If only 1 value  is
1106              specified, each scroll takes place after that delay.
1107
1108       Command-Line Switch:    -yscrollincrement
1109       Database Name:          yScrollIncrement
1110       Database Class:         ScrollIncrement
1111
1112
1113              Specifies  an  increment  for  vertical scrolling, in any of the
1114              usual forms permitted for screen distances.   If  the  value  of
1115              this  option is greater than zero, the vertical view in the win‐
1116              dow will be constrained so that the canvas y coordinate  at  the
1117              top   edge   of  the  window  is  always  an  even  multiple  of
1118              -yscrollincrement;  furthermore, the units for scrolling  (e.g.,
1119              the change in view when the top and bottom arrows of a scrollbar
1120              are selected) will also be -yscrollincrement.  If the  value  of
1121              this  option  is  less  than  or  equal  to  zero, then vertical
1122              scrolling snaps to the top of an item, or part  of  an  item  if
1123              items are taller than the contentbox.
1124
1125       Command-Line Switch:    -yscrollsmoothing
1126       Database Name:          yScrollSmoothing
1127       Database Class:         ScrollSmoothing
1128
1129
1130              Specifies  whether scrolling should be done as if -yscrollincre‐
1131              ment=1 whenever scrolling  is  performed  by  non-unit  amounts.
1132              When  the  value of this option is true and the yview command is
1133              called to scroll by "units", scrolling occurs according  to  the
1134              -yscrollincrement  option, and all other scrolling is done as if
1135              the -yscrollincrement option was set to 1.  The effect  is  that
1136              when  dragging the scrollbar thumb scrolling is very smooth, but
1137              when clicking the scrollbar buttons scrolling is done in coarser
1138              increments.  The default value is false.
1139

THE CANVAS

1141       Throughout  this  manual  page  the term canvas is sometimes used.  The
1142       canvas can be thought of as the virtual sheet of paper upon  which  all
1143       visible  items are drawn.  The treectrl window displays different areas
1144       of the canvas within its borders as the list is scrolled.
1145

ITEM AND COLUMN TAGS

1147       Columns and items may have any number of tags associated with them.   A
1148       tag is just a string of characters, and it may take any form, including
1149       that of an integer, although the characters '(', ')', '&', '|', '^' and
1150       '!' should be avoided.
1151
1152       The same tag may be associated with many columns or items. This is com‐
1153       monly done to group items in various interesting ways; for example,  in
1154       a file browser all directories might be given the tag "directory".
1155
1156       Tag  expressions  are used in column descriptions and item descriptions
1157       to specify which columns and items to operate on.  A tag expression can
1158       be  a  single  tag name or a logical expression of tags using operators
1159       '&&', '||', '^' and '!', and parenthesized subexpressions.   For  exam‐
1160       ple:
1161
1162
1163       or equivalently:
1164
1165
1166       will  return  the  unique ids of any items with either "a" or "b" tags,
1167       but not both.
1168
1169       Within a tag expression a tag name may be enclosed in double quotes  to
1170       avoid special processing of the operator characters. For example:
1171
1172
1173       will return the unique ids of any items with either "a&&b" or "c" tags;
1174       in this example the && is not treated as an  operator.  A  double-quote
1175       may be escaped within a quoted tag name using a backslash '\'.
1176
1177       Tag  operators may be bypassed completely by setting the -columntagexpr
1178       and -itemtagexpr options. This can be useful if  your  application  has
1179       column or item tags containing arbitrary text.
1180
1181
1182

WIDGET COMMAND

1184       The  treectrl  command creates a new Tcl command whose name is the same
1185       as the path name of the treectrl's window.  This command may be used to
1186       invoke  various operations on the widget.  It has the following general
1187       form:
1188
1189       pathName option ?arg arg ...?
1190
1191       PathName is the name of the command, which is the same as the  treectrl
1192       widget's  path  name.  Option and the args determine the exact behavior
1193       of the command.  The following commands are possible for treectrl  wid‐
1194       gets:
1195
1196       pathName activate itemDesc
1197              Sets  the  active  item  to  the  one described by itemDesc, and
1198              switches on the state active for that item.  The active item can
1199              be  referred to by the item description active.  If this command
1200              changes which item is active an <ActiveItem> event is generated.
1201              If  the  active  item  is  deleted the root item becomes the new
1202              active item.
1203
1204       pathName bbox ?area?
1205              Returns a list with four elements giving the bounding box (left,
1206              top,  right and bottom) of an area of the window. If area is not
1207              specified, then the result is the bounding  box  of  the  entire
1208              window.   If area is content, then the result is the part of the
1209              window not including borders, headers, or  locked  columns.   If
1210              area  is  header,  then the result is the part of the window not
1211              including borders where column titles are displayed.  If area is
1212              left,  then  the  result is the part of the window not including
1213              borders or headers where left-locked columns are displayed.   If
1214              area  is  right,  then  the result is the part of the window not
1215              including borders or headers where right-locked columns are dis‐
1216              played.
1217
1218              If  area is one of header.left, header.none or header.right then
1219              the  area  of  the  column  headers  occupied  by  columns  with
1220              -lock=left, -lock=none or -lock=right is returned.
1221
1222              An empty string is returned if the display area has no height or
1223              width, which can be true for various reasons such as the  window
1224              is  too  small,  or the header is not displayed, or there aren't
1225              any locked columns.
1226
1227       pathName canvasx windowx
1228              Translates the given window x-coordinate windowx in the treectrl
1229              to  canvas coordinate space.  The marquee command expects canvas
1230              coordinates.
1231
1232       pathName canvasy windowy
1233              Translates the given window y-coordinate windowy in the treectrl
1234              to  canvas coordinate space.  The marquee command expects canvas
1235              coordinates.
1236
1237       pathName cget option
1238              Returns the current value of the configuration option  given  by
1239              option.   Option may have any of the values accepted by the tree
1240              command.
1241
1242       pathName collapse ?-recurse? ?itemDesc ...?
1243              Deprecated. Use item collapse instead.
1244
1245       pathName column option column ?arg ...?
1246              This command is used to manipulate the columns of  the  treectrl
1247              widget  (see  section COLUMNS below).  The exact behavior of the
1248              command depends on the option argument that follows  the  column
1249              argument.  The following forms of the command are supported:
1250
1251              pathName column bbox columnDesc
1252                     Returns a list with four elements giving the bounding box
1253                     of the header of  the  column  specified  by  the  column
1254                     description  columnDesc.   The  returned  coordinates are
1255                     relative to the top-left corner of the  widget.   If  the
1256                     column  option  -visible=false  or  if  the widget option
1257                     -showheader=false, then an empty list is returned.
1258
1259              pathName column cget columnDesc option
1260                     This command returns the  current  value  of  the  option
1261                     named  option  for  the  column  specified  by the column
1262                     description columnDesc, ColumnDesc may also be the string
1263                     tail  to specify the tail column.  Option may have any of
1264                     the values accepted by the column configure  widget  com‐
1265                     mand.
1266
1267              pathName  column  configure  columnDesc ?option? ?value? ?option
1268              value ...?
1269                     This command is similar to the configure  widget  command
1270                     except  that it modifies options associated with the col‐
1271                     umns  specified  by  the  column  description  columnDesc
1272                     instead  of  modifying  options  for the overall treectrl
1273                     widget.  ColumnDesc may be the string tail to specify the
1274                     tail  column.  If columnDesc refers to more than one col‐
1275                     umn, then at least one option-value pair must  be  given.
1276                     If  no  option  is  specified, the command returns a list
1277                     describing all of the available  options  for  columnDesc
1278                     (see  Tk_ConfigureInfo  for  information on the format of
1279                     this list).  If option is specified with no  value,  then
1280                     the  command  returns  a  list  describing  the one named
1281                     option (this list will be identical to the  corresponding
1282                     sublist of the value returned if no option is specified).
1283                     If one or more option-value pairs are specified, then the
1284                     command  modifies  the  given option(s) to have the given
1285                     value(s) for columnDesc; in this case the command returns
1286                     an empty string.
1287
1288                     See  COLUMNS  below  for details on the options available
1289                     for columns.
1290
1291                     For compatibility with older versions of treectrl  (which
1292                     did  not support more than one row of column headers) any
1293                     of the configuration options  mentioned  in  the  HEADERS
1294                     section, such as -arrow, -text, etc, may be passed to the
1295                     top header-row through this command.
1296
1297              pathName column compare column1 op column2
1298                     For both column  descriptions  column1  and  column2  the
1299                     index  is  retrieved  (as  returned from the column order
1300                     widget command).  Then these indexes are  compared  using
1301                     the operator op, which must be either <,  <=,  ==, >=, >,
1302                     or !=.  The return value of this command is 1 if the com‐
1303                     parison evaluated to true, 0 otherwise.
1304
1305              pathName column count ?columnDesc?
1306                     If  no  additional  arguments  are given, the result is a
1307                     decimal string giving the number of  columns  created  by
1308                     the  column  create  widget  command  which  haven't been
1309                     deleted by the column delete widget command; in this case
1310                     the  tail column is not counted.  If columnDesc is given,
1311                     then the result is the number of columns that match  that
1312                     column description.
1313
1314              pathName column create ?option value ...?
1315                     This command creates a new column in the treectrl widget.
1316                     The new column is placed to the right of all  other  col‐
1317                     umns (except the tail column). Any option-value arguments
1318                     configure the new column according to the column  config‐
1319                     ure command. The return value is the unique identifier of
1320                     the new column.
1321
1322              pathName column delete first ?last?
1323                     Deletes the specified column(s). First and last  must  be
1324                     valid  column  descriptions.  If  both first and last are
1325                     specified, then they may refer to a single  column  only.
1326                     The  tail  column cannot be deleted and it is an error to
1327                     specify it.  The order of first and last doesn't  matter,
1328                     and first may be equal to last.
1329
1330              pathName column dragcget option
1331                     Deprecated. Use header dragcget instead.
1332
1333              pathName  column  dragconfigure  ?option?  ?value? ?option value
1334              ...?
1335                     Deprecated. Use header dragconfigure instead.
1336
1337              pathName column index columnDesc
1338                     Deprecated. Use column id instead.
1339
1340              pathName column id columnDesc
1341                     This command resolves the column  description  columnDesc
1342                     into  a  list  of  unique column identifiers. If the col‐
1343                     umn(s) described by columnDesc don't exist, this  command
1344                     returns an empty list.
1345
1346              pathName column list ?-visible?
1347                     This command returns a list of identifiers for every col‐
1348                     umn (except the tail) from left to right. If -visible  is
1349                     given,  only  columns  whose  -visible option is true are
1350                     returned.
1351
1352              pathName column move columnDesc beforeDesc
1353                     Moves the column specified by columnDesc to the  left  of
1354                     the  column  specified by beforeDesc. Both columnDesc and
1355                     beforeDesc must be valid column descriptions.  If before‐
1356                     Desc  is  the  string  tail,  the  column columnDesc will
1357                     become the last column.
1358
1359              pathName column neededwidth columnDesc
1360                     This command returns a decimal string giving  the  needed
1361                     width  of  the column specified by the column description
1362                     columnDesc.  The needed width is the maximum of the width
1363                     of the column header and the width of the widest style in
1364                     any visible item.
1365
1366                     When an item style or column header spans  multiple  col‐
1367                     umns,  the  needed  width  of a column is affected by the
1368                     widths of other columns in the span, in  which  case  the
1369                     result of this command isn't particularly useful.
1370
1371              pathName column order columnDesc ?-visible?
1372                     This command returns a decimal string giving the position
1373                     of the column specified by the column description column‐
1374                     Desc  in  the  list of columns starting from zero for the
1375                     leftmost column.  If  -visible  is  given,  only  columns
1376                     whose  -visible  option is true are considered, and -1 is
1377                     returned if columnDesc's -visible option is false.
1378
1379              pathName column tag option ?arg arg ...?
1380                     This command is used to manipulate tags on columns.   The
1381                     exact behavior of the command depends on the option argu‐
1382                     ment that follows the column tag argument.  The following
1383                     forms of the command are supported:
1384
1385                     pathName column tag add columnDesc tagList
1386                            Adds  each tag in tagList to the columns specified
1387                            by the column description  columnDesc.   Duplicate
1388                            tags  are  ignored.  The list of tags for a column
1389                            can also be changed via a column's -tags option.
1390
1391                     pathName column tag expr columnDesc tagExpr
1392                            Evaluates the tag expression tagExpr against every
1393                            column specified by the column description column‐
1394                            Desc. The result is 1 if the tag expression evalu‐
1395                            ates to true for every column, 0 otherwise.
1396
1397                     pathName column tag names columnDesc
1398                            Returns  a  list of tag names assigned to the col‐
1399                            umns specified by the column  description  column‐
1400                            Desc. The result is the union of any tags assigned
1401                            to the columns.
1402
1403                     pathName column tag remove columnDesc tagList
1404                            Removes each tag in tagList from the columns spec‐
1405                            ified by the column description columnDesc.  It is
1406                            not an error if any of the columns do not use  any
1407                            of  the  tags.   The list of tags for a column can
1408                            also be changed via a column's -tags option.
1409
1410              pathName column width columnDesc
1411                     This command returns a decimal string giving the width in
1412                     pixels  of the column specified by the column description
1413                     columnDesc, even if the treectrl  is  configured  to  not
1414                     display  the  column  headers by means of the -showheader
1415                     option.
1416
1417       pathName compare itemDesc1 op itemDesc2
1418              Deprecated. Use the item compare command instead.
1419
1420       pathName configure ?option? ?value option value ...?
1421              Query or modify the configuration options of the widget.  If  no
1422              option is specified, returns a list describing all of the avail‐
1423              able options for pathName (see Tk_ConfigureInfo for  information
1424              on  the  format  of  this list).  If option is specified with no
1425              value, then the command returns a list describing the one  named
1426              option (this list will be identical to the corresponding sublist
1427              of the value returned if no option is  specified).   If  one  or
1428              more option-value pairs are specified, then the command modifies
1429              the given widget option(s) to have the given value(s);  in  this
1430              case  the  command returns an empty string.  Option may have any
1431              of the values accepted by the treectrl command.
1432
1433       pathName contentbox
1434              Returns a list with four elements giving the bounding box of the
1435              screen area used to display items.  This is the area of the win‐
1436              dow not including borders, column headers, or locked columns. An
1437              empty  string  is  returned if the display area has no height or
1438              width, which can happen if the window is too small.  The  result
1439              of this command is the same as that of bbox content.
1440
1441       pathName debug option ?arg arg ...?
1442              This  command  is  used  to facilitate debugging of the treectrl
1443              widget.  The exact behavior of the command depends on the option
1444              argument  that  follows the debug argument.  The following forms
1445              of the command are supported:
1446
1447              pathName debug alloc
1448                     Returns a string  giving  partial  statistics  on  memory
1449                     allocations, if the package was built with TREECTRL_DEBUG
1450                     defined.
1451
1452              pathName debug cget option
1453                     This command returns the current value of  the  debugging
1454                     option  named  option.  Option may have any of the values
1455                     accepted by the debug configure widget command.
1456
1457              pathName debug configure ?option? ?value? ?option value ...?
1458                     This command is similar to the configure  widget  command
1459                     except that it modifies debugging options instead of mod‐
1460                     ifying options for the overall treectrl  widget.   If  no
1461                     option  is specified, the command returns a list describ‐
1462                     ing all of the available debugging options  (see  Tk_Con‐
1463                     figureInfo  for  information on the format of this list).
1464                     If option is specified with no value,  then  the  command
1465                     returns a list describing the one named option (this list
1466                     will be identical to the  corresponding  sublist  of  the
1467                     value  returned  if  no  option is specified).  If one or
1468                     more option-value pairs are specified, then  the  command
1469                     modifies  the given debugging option(s) to have the given
1470                     value(s); in this  case  the  command  returns  an  empty
1471                     string.
1472
1473                     The following debugging options are supported:
1474
1475                     -displaydelay millis
1476                            Specifies  a  time duration in milliseconds, which
1477                            should be waited after something has been drawn to
1478                            the  screen.   Setting  this  option  has  only an
1479                            effect, if the debugging options -enable and -dis‐
1480                            play are switched on.
1481
1482                     -data boolean
1483                            If  this  option is switched on (together with the
1484                            debugging option -enable),  at  various  places  a
1485                            consistence  check  on the internal data structure
1486                            is made (e.g. for every item is  checked,  if  the
1487                            registered number of children is equal to the num‐
1488                            ber of child  items).   If  an  inconsistency  was
1489                            found, a Tcl background error is raised.
1490
1491                     -display boolean
1492                            If  this  option is switched on (together with the
1493                            debugging option -enable), at varios places  addi‐
1494                            tional debugging output is printed to stdout.
1495
1496                     -drawcolor color
1497                            When  specified,  areas  of the window are painted
1498                            with this color when drawing  in  those  areas  is
1499                            about  to  occur.  Setting this option has only an
1500                            effect if the debugging options -enable and  -dis‐
1501                            play are switched on.
1502
1503                     -enable boolean
1504                            All  other  debugging  options only take effect if
1505                            this option is also switched on.
1506
1507                     -erasecolor color
1508                            When specified, areas of  the  window  which  have
1509                            been  marked  as "invalid" (for example, when part
1510                            of the window is exposed) are  painted  with  this
1511                            color.   If  you  use  an  unusual  color for this
1512                            option (like pink), superflous screen redraws  can
1513                            be  spotted  more easily.  Setting this option has
1514                            only an effect if the  debugging  options  -enable
1515                            and -display are switched on.
1516
1517                     -span boolean
1518                            Debugging related to column spanning.
1519
1520                     -textlayout boolean
1521                            Debugging related to text-element layout.
1522
1523              pathName debug dinfo option
1524                     Returns a string describing display-related stuff. Option
1525                     must be one of alloc, ditem, onscreen or range.
1526
1527              pathName debug expose x1 y1 x2 y2
1528                     Causes the area of the window bounded by the  given  win‐
1529                     dow-coords to be marked as invalid. This simulates uncov‐
1530                     ering part of the window.
1531
1532       pathName depth ?itemDesc?
1533              If the additional argument itemDesc is given, then the result is
1534              a  decimal  string  giving  the  depth  of the item described by
1535              itemDesc.  If no itemDesc is specified, then the  maximum  depth
1536              of  all items in the treectrl widget is returned instead.  Depth
1537              is defined as the number of ancestors an item has.
1538
1539       pathName dragimage option ?arg ...?
1540              This command is used to manipulate the drag image, which is used
1541              to  provide  feedback when items are drag-and-dropped within the
1542              window.  The drag image is displayed as the dotted  outlines  of
1543              one  or more items, columns and/or elements.  The exact behavior
1544              of the command depends on the option argument that  follows  the
1545              dragimage argument.  The following forms of the command are sup‐
1546              ported:
1547
1548              pathName dragimage add itemDesc ?column? ?element?
1549                     Adds the shapes of the item described by itemDesc to  the
1550                     shapes of the dragimage.  Specifying additional arguments
1551                     reduces the number of rectangles that are  added  to  the
1552                     dragimage.   If no additional arguments is specified, for
1553                     every element of the item in every column a  dotted  rec‐
1554                     tangles  is  added.  If column is specified, all elements
1555                     in other columns are ignored.  If also element is  speci‐
1556                     fied, only a rectangle for this one element of the speci‐
1557                     fied item in the given column is added.
1558
1559              pathName dragimage cget option
1560                     This command returns the current value of  the  dragimage
1561                     option  named  option.  Option may have any of the values
1562                     accepted by the dragimage configure widget command.
1563
1564              pathName dragimage clear
1565                     Removes all shapes (if there are any) from the dragimage.
1566                     This command does not modify the dragimage offset.
1567
1568              pathName dragimage configure ?option? ?value? ?option value ...?
1569                     This  command  is similar to the configure widget command
1570                     except that it modifies the dragimage options instead  of
1571                     modifying options for the overall treectrl widget.  If no
1572                     option is specified, the command returns a list  describ‐
1573                     ing  all  of the available dragimage options (see Tk_Con‐
1574                     figureInfo for information on the format of  this  list).
1575                     If  option  is  specified with no value, then the command
1576                     returns a list describing the one named dragimage  option
1577                     (this list will be identical to the corresponding sublist
1578                     of the value returned if no option is specified).  If one
1579                     or  more  option-value pairs are specified, then the com‐
1580                     mand modifies the given dragimage option(s) to  have  the
1581                     given value(s); in this case the command returns an empty
1582                     string.
1583
1584                     The following dragimage options are supported:
1585
1586                     -visible boolean
1587                            Specifies a boolean value which determines whether
1588                            the dragimage should currently be visible.
1589
1590              pathName dragimage offset ?x y?
1591                     Returns  a  list  containing  the  x and y offsets of the
1592                     dragimage, if no additional arguments are specified.  The
1593                     dragimage offset is the screen distance the image is dis‐
1594                     played at relative to the item(s) its  shape  is  derived
1595                     from.  If two coordinates are specified, sets the dragim‐
1596                     age offset to the given coordinates x and y.
1597
1598       pathName element option ?element? ?arg arg ...?
1599              This command is used to manipulate elements  (see  ELEMENTS  AND
1600              STYLES below).  The exact behavior of the command depends on the
1601              option argument that follows the element argument.  The  follow‐
1602              ing forms of the command are supported:
1603
1604              pathName element cget element option
1605                     This  command  returns  the  current  value of the option
1606                     named option associated with the element  given  by  ele‐
1607                     ment.   Option may have any of the values accepted by the
1608                     element configure widget command.
1609
1610                     This command also accepts the -statedomain option.
1611
1612              pathName element  configure  element  ?option?  ?value?  ?option
1613              value ...?
1614                     This  command  is similar to the configure widget command
1615                     except that it modifies options associated with the  ele‐
1616                     ment  given  by  element instead of modifying options for
1617                     the overall treectrl widget.  If no option is  specified,
1618                     the  command  returns a list describing all of the avail‐
1619                     able options for element (see Tk_ConfigureInfo for infor‐
1620                     mation  on the format of this list).  If option is speci‐
1621                     fied with no value,  then  the  command  returns  a  list
1622                     describing  the one named option (this list will be iden‐
1623                     tical to the corresponding sublist of the value  returned
1624                     if  no option is specified).  If one or more option-value
1625                     pairs are specified, then the command modifies the  given
1626                     option(s)  to have the given value(s) in element; in this
1627                     case the command returns an empty string.   See  ELEMENTS
1628                     AND STYLES below for details on the options available for
1629                     elements.
1630
1631              pathName element create name type ?option value ...?
1632                     Creates a new master element of type type with the unique
1633                     user-defined  name  name  and  configures it with zero or
1634                     more option/value pairs.  See the subsections on individ‐
1635                     ual  element types in ELEMENTS AND STYLES for the options
1636                     that are valid for each type of  element.   This  command
1637                     returns the name of the new element (the same as the name
1638                     argument).
1639
1640                     This command also accepts the -statedomain option with  a
1641                     value of either header or item to specify where this ele‐
1642                     ment will be displayed.
1643
1644              pathName element delete ?element ...?
1645                     Deletes each of the named elements and returns  an  empty
1646                     string.   If an element is deleted while it is still con‐
1647                     figured as an element of one or more styles by  means  of
1648                     the  style  elements  widget  command, it is also removed
1649                     from the element lists of these styles.
1650
1651              pathName element names
1652                     Returns a list containing the names of all existing  ele‐
1653                     ments.
1654
1655              pathName element perstate element option stateList
1656                     This  command  returns  the value of the per-state option
1657                     named option for element for a certain state.   StateList
1658                     is a list of state names (static and dynamic, see STATES)
1659                     which specifies the state to use.
1660
1661              pathName element type element
1662                     Returns the type of the element given by element, such as
1663                     rect or text.
1664
1665       pathName expand ?-recurse? ?itemDesc ...?
1666              Deprecated.  Use item expand instead.
1667
1668       pathName gradient option ?arg ...?
1669              This  command is used to manipulate color gradients.  See GRADI‐
1670              ENTS for more information  about  using  gradients.   The  exact
1671              behavior of the command depends on the option argument that fol‐
1672              lows the gradient argument.  The following forms of the  command
1673              are supported:
1674
1675              pathName gradient cget gradient option
1676                     Returns the current value of the configuration option for
1677                     the gradient specified by gradient whose name is  option.
1678                     Option  may have any of the values accepted by the gradi‐
1679                     ent configure command.
1680
1681              pathName gradient configure gradient ?option value ...?
1682                     If no option is specified, the  command  returns  a  list
1683                     describing  all  of  the  available gradient options (see
1684                     Tk_ConfigureInfo for information on the  format  of  this
1685                     list).   If  option  is specified with no value, then the
1686                     command returns a list describing the one named  gradient
1687                     option  (this list will be identical to the corresponding
1688                     sublist of the value returned if no option is specified).
1689                     If one or more option-value pairs are specified, then the
1690                     command modifies the given gradient option(s) to have the
1691                     given value(s); in this case the command returns an empty
1692                     string.
1693
1694                     The following options are supported (see gradient  create
1695                     for the meaning of each option):
1696
1697                     -bottom coordSpec
1698
1699                     -left coordSpec
1700
1701                     -orient direction
1702
1703                     -right coordSpec
1704
1705                     -steps stepCount
1706
1707                     -stops stopsList
1708
1709                     -top coordSpec
1710
1711              pathName gradient create name ?option value ...?
1712                     Creates  a new gradient with the name name, which must be
1713                     a unique name not used by  another  gradient  created  by
1714                     this treectrl widget.
1715
1716                     The following options are supported:
1717
1718                     -bottom coordSpec
1719
1720                     -left coordSpec
1721
1722                     -right coordSpec
1723
1724                     -top coordSpec
1725                            Each  of  these  options specifies one edge of the
1726                            gradient brush.  If the option is specified as  an
1727                            empty  string  (the default), the gradient brush's
1728                            edge is the same as that of whatever rectangle  is
1729                            being  painted  using  the gradient.  See GRADIENT
1730                            COORDINATES for details on gradient brush  coordi‐
1731                            nates.
1732
1733                            The format of each of these options is a list of 2
1734                            or more values {value coordType ?arg ...?},  where
1735                            value is a floating point number (usually from 0.0
1736                            to 1.0) and coordType is one of area, canvas, col‐
1737                            umn or item.  The area keyword must be followed by
1738                            one of the same area names that the  bbox  command
1739                            accepts.   The column keyword may be followed by a
1740                            column description specifying exactly one  column.
1741                            The  item  keyword  may  be  followed  by  an item
1742                            description specifying exactly one item.
1743
1744                     -orient direction
1745                            This option specifies the direction a linear  gra‐
1746                            dient changes color in.  Must be either horizontal
1747                            (the default) or vertical or  an  abbreviation  of
1748                            one of these.
1749
1750                     -steps stepCount
1751                            Specifies  the  number of bands of color drawn for
1752                            each color stop described by  the  -stops  option.
1753                            The  default  value is 1, the maximum is 25.  This
1754                            option has no effect if gradients are drawn  using
1755                            something better than Tk API calls.  See GRADIENTS
1756                            for more on this.
1757
1758                     -stops stopsList
1759                            Specifies the color stops along this gradient. The
1760                            argument stopsList has the following form:
1761
1762                            {{offset color ?opacity?} {offset color ?opacity?} ...}
1763
1764                            Each offset is a floating point number from 0.0 to
1765                            1.0 specifying the distance from the start of  the
1766                            gradient  where the color begins.  Each color is a
1767                            Tk color name or description.  Each optional opac‐
1768                            ity  is  a  floating  point number from 0.0 to 1.0
1769                            specifying how transparent the gradient is.
1770
1771                            If stopsList is non-empty there must be  at  least
1772                            two  stops specified, and the first offset must be
1773                            0.0 and the last offset must be  1.0.   Any  other
1774                            stop  offsets  must be listed in increasing order.
1775                            Specifying opacity has no effect if gradients  are
1776                            drawn  using Tk API calls.  See GRADIENTS for more
1777                            on this.
1778
1779              pathName gradient delete ?name ...?
1780                     Deletes each gradient specified by name.  If the gradient
1781                     is still being used then it is not actually deleted until
1782                     all elements etc using the gradient  have  stopped  using
1783                     it.   A  deleted-but-in-use gradient is not recognized by
1784                     the various gradient commands.  Creating a  new  gradient
1785                     with  the same name as a deleted-but-in-use gradient res‐
1786                     urrects the deleted gradient.
1787
1788              pathName gradient names
1789                     Returns a list of names of all the  gradients  that  have
1790                     been created by this treectrl widget.
1791
1792              pathName gradient native ?preference?
1793                     Without  any  arguments,  this  command returns a boolean
1794                     indicating whether or not the  platform  supports  native
1795                     transparent  gradients.   The  preference  argument  is a
1796                     boolean that indicates whether native gradients should be
1797                     used;  this  can  be  used  to test the appearance of the
1798                     application.
1799
1800       pathName header option ?arg ...?
1801              This command is used to manipulate column  headers.   The  exact
1802              behavior of the command depends on the option argument that fol‐
1803              lows the header argument.  The following forms  of  the  command
1804              are supported:
1805
1806              pathName header bbox headerDesc ?column? ?element?
1807                     See the item bbox command.
1808
1809              pathName header compare headerDesc1 op headerDesc2
1810                     See the item compare command.
1811
1812              pathName header configure headerDesc ?arg ...?
1813                     There  are  two  forms  of  this command distinguished by
1814                     whether or not a column  description  appears  after  the
1815                     headerDesc  argument.   If the first argument after head‐
1816                     erDesc begins with a '-' character it is assumed to be an
1817                     option  name, not a column description, in which case the
1818                     command applies to the header-row.  If the first argument
1819                     after  headerDesc does not being with a '-' it is assumed
1820                     to be a column description, in  which  case  the  command
1821                     applies to a header-column.
1822
1823                     pathName  header  configure  headerDesc  ?option? ?value?
1824                     ?option value ...?
1825                            If no option is specified, returns a list describ‐
1826                            ing  all  of  the available options for the header
1827                            given  by  headerDesc  (see  Tk_ConfigureInfo  for
1828                            information on the format of this list). If option
1829                            is specified  with  no  value,  then  the  command
1830                            returns  a  list  describing  the one named option
1831                            (this list will be identical to the  corresponding
1832                            sublist  of  the  value  returned  if no option is
1833                            specified).
1834
1835                            If one or more option-value pairs  are  specified,
1836                            then  the  command modifies the given option(s) to
1837                            have the given value(s); in this case the  command
1838                            returns  an  empty  string.  This is the only case
1839                            where headerDesc may  refer  to  multiple  header-
1840                            rows.
1841
1842                            The  following  options are supported by this com‐
1843                            mand (see header create for the  meaning  of  each
1844                            option):
1845
1846                            -height height
1847
1848                            -tags tagList
1849
1850                            -visible boolean
1851
1852                     pathName  header  configure  headerDesc  column  ?option?
1853                     ?value? ?option value ...?
1854                            If no option is specified, returns a list describ‐
1855                            ing  all  of  the available options for the single
1856                            column column of the  header-row  given  by  head‐
1857                            erDesc  (see  Tk_ConfigureInfo  for information on
1858                            the format of this list).  If option is  specified
1859                            with  no  value,  then  the command returns a list
1860                            describing the one named option (this list will be
1861                            identical  to  the  corresponding  sublist  of the
1862                            value returned if no option is specified).
1863
1864                            If one or more option-value pairs  are  specified,
1865                            then  the  command modifies the given option(s) to
1866                            have the given value(s); in this case the  command
1867                            returns  an  empty  string.  This is the only case
1868                            where  both  headerDesc  may  refer  to   multiple
1869                            header-rows  and  column  may  refer  to  multiple
1870                            header-columns.
1871
1872                            The following options are supported by  this  com‐
1873                            mand   (see  HEADERS)  for  the  meaning  of  each
1874                            option):
1875
1876                            -arrow direction
1877
1878                            -arrowbitmap bitmap
1879
1880                            -arrowgravity direction
1881
1882                            -arrowimage image
1883
1884                            -arrowpadx amount
1885
1886                            -arrowpady amount
1887
1888                            -arrowside side
1889
1890                            -background color
1891
1892                            -bitmap bitmap
1893
1894                            -borderwidth size
1895
1896                            -button boolean
1897
1898                            -font fontName
1899
1900                            -image image
1901
1902                            -imagepadx amount
1903
1904                            -imagepady amount
1905
1906                            -justify justification
1907
1908                            -state state
1909
1910                            -text text
1911
1912                            -textcolor color
1913
1914                            -textlines count
1915
1916                            -textpadx amount
1917
1918                            -textpady amount
1919
1920              pathName header count ?headerDesc?
1921                     If no additional arguments are given,  the  result  is  a
1922                     decimal  string  giving the number of header-rows created
1923                     by the header create widget command  which  haven't  been
1924                     deleted  by  the header delete widget command, plus 1 for
1925                     the ever-present top header-row created  along  with  the
1926                     widget.   If  the  optional argument headerDesc is given,
1927                     then the result is the number of header-rows  that  match
1928                     that header description.
1929
1930              pathName header create ?option value?
1931                     Creates  a  new header-row and returns its unique identi‐
1932                     fier.  The following configuration options are supported:
1933
1934                     -height height
1935                            Specifies a fixed height for the header-row in any
1936                            of  the  forms acceptable to Tk_GetPixels. Must be
1937                            >= 0.  If height is  zero  then  the  header-row's
1938                            height  is the maximum height of all of its column
1939                            headers.  Defaults to 0.
1940
1941                     -tags tagList
1942                            TagList is a list of tag names to be added to  the
1943                            new  header-row.   The header tag command can also
1944                            be used to manipulate this list of tags.
1945
1946                     -visible boolean
1947                            Boolean must have one of  the  forms  accepted  by
1948                            Tcl_GetBoolean.  It  indicates  whether or not the
1949                            header-row should be  displayed.   If  the  widget
1950                            option  -showheader  is  false then the header-row
1951                            will not be displayed regardless of the  value  of
1952                            this option.
1953
1954              pathName header delete headerDesc
1955                     Deletes  the  header-rows given by the header description
1956                     headerDesc.  Attempts  to  delete  the  ever-present  top
1957                     header-row are ignored without raising an error.
1958
1959              pathName header dragcget ?arg ...?
1960                     There  are  two  forms  of  this command distinguished by
1961                     whether or not a header description appears as the  first
1962                     argument.   If the first argument begins with a '-' char‐
1963                     acter it is assumed to be an option name,  not  a  header
1964                     description,  in  which  case  the command applies to the
1965                     header-drag-and-drop options  for  the  widget.   If  the
1966                     first argument does not being with a '-' it is assumed to
1967                     be a  header  description,  in  which  case  the  command
1968                     applies to a header-row.
1969
1970                     pathName header dragcget option
1971                            This  command  returns  the  current  value of the
1972                            header-drag-and-drop option named option  for  the
1973                            widget.   The  following configuration options are
1974                            supported (see header dragconfigure for the  mean‐
1975                            ing of each option):
1976
1977                            -enable boolean
1978
1979                            -imagealpha alpha
1980
1981                            -imagecolor background
1982
1983                            -imagecolumn column
1984
1985                            -imageoffset offset
1986
1987                            -imagespan count
1988
1989                            -indicatorcolor color
1990
1991                            -indicatorcolumn column
1992
1993                            -indicatorside side
1994
1995                            -indicatorspan count
1996
1997                     pathName header dragcget headerDesc option
1998                            This  command  returns  the  current  value of the
1999                            header-drag-and-drop option  named  option  for  a
2000                            header-row.   The  following configuration options
2001                            are supported (see header  dragconfigure  for  the
2002                            meaning of each option):
2003
2004                            -draw boolean
2005
2006                            -enable boolean
2007
2008              pathName header dragconfigure ?arg ...?
2009                     There  are  two  forms  of  this command distinguished by
2010                     whether or not a header description appears as the  first
2011                     argument.   If the first argument begins with a '-' char‐
2012                     acter it is assumed to be an option name,  not  a  header
2013                     description,  in  which  case  the command applies to the
2014                     header-drag-and-drop options  for  the  widget.   If  the
2015                     first argument does not being with a '-' it is assumed to
2016                     be a  header  description,  in  which  case  the  command
2017                     applies to a header-row.
2018
2019                     pathName  header  dragconfigure  ?option? ?value? ?option
2020                     value ...?
2021                            This command queries and sets header-drag-and-drop
2022                            options for the widget, not for individual header-
2023                            rows.  The  following  configuration  options  are
2024                            supported:
2025
2026                            -enable boolean
2027                                   Controls  whether  the  user  is allowed to
2028                                   rearrange columns  by  drag-and-drop.   The
2029                                   default is false.  Each header-row also has
2030                                   an -enable dragconfigure option.
2031
2032                            -imagealpha alpha
2033                                   Alpha is an integer from 0  (invisible)  to
2034                                   255  (opaque)  controlling the transparency
2035                                   of the drag image. Any value  outside  this
2036                                   range is clipped.  The default is 200.
2037
2038                            -imagecolor background
2039                                   Unused.
2040
2041                            -imagecolumn column
2042                                   Column  specifies  the column to create the
2043                                   drag image from.
2044
2045                            -imageoffset offset
2046                                   Offset is the  horizontal  screen  distance
2047                                   the  drag image is offset from its starting
2048                                   position.
2049
2050                            -imagespan count
2051                                   Count is the number  of  columns,  starting
2052                                   with  -imagecolumn, that will be dragged as
2053                                   a group.
2054
2055                            -indicatorcolor color
2056                                   Unused.
2057
2058                            -indicatorcolumn column
2059                                   The 2-pixel-thick line will be  drawn  over
2060                                   the left or right edge of column.
2061
2062                            -indicatorside side
2063                                   Unused.
2064
2065                            -indicatorspan count
2066                                   Count  is  the  number of columns, starting
2067                                   with -indicatorcolumn, that  will  be  dis‐
2068                                   placed as a group by the dragged column(s)
2069
2070                     pathName  header  dragconfigure  header  ?option? ?value?
2071                     ?option value ...?
2072                            This command queries and sets header-drag-and-drop
2073                            options  for  header-rows, not for the widget as a
2074                            whole.  The following  configuration  options  are
2075                            supported:
2076
2077                            -draw boolean
2078                                   Controls  whether a header-row displays any
2079                                   feedback during header drag-and-drop.   The
2080                                   default is true.
2081
2082                            -enable boolean
2083                                   Controls  whether  clicking and dragging in
2084                                   this  header-row  initiates  drag-and-drop.
2085                                   The default is true.  If the -enable option
2086                                   for the widget is false  (see  above)  then
2087                                   this option has no effect.
2088
2089              pathName header element ?arg ...?
2090                     See the item element command.
2091
2092              pathName header id headerDesc
2093                     This  command  resolves the header description headerDesc
2094                     into a list of unique header-row  identifiers.  If  head‐
2095                     erDesc  doesn't  refer  to any existing header-rows, then
2096                     this command returns an empty list.
2097
2098              pathName header image headerDesc ?column? ?image? ?column  image
2099              ...?
2100                     The  behavior of this command depends on whether or not a
2101                     column header was assigned a style  containing  an  image
2102                     element.   If  a  column  header has no style or no style
2103                     with an image element then this command operates  on  the
2104                     same  -image  option as header configure.  Otherwise this
2105                     command operates on the -image option of the first  image
2106                     element  in  a column header's style.  See the item image
2107                     command.
2108
2109              pathName header span headerDesc  ?column?  ?numColumns?  ?column
2110              numColumns ...?
2111                     See the item span command.
2112
2113              pathName header state command headerDesc ?arg ...?
2114                     See the item state command.
2115
2116              pathName header style command headerDesc ?arg ...?
2117                     See the item style command.
2118
2119              pathName  header  text  headerDesc  ?column? ?text? ?column text
2120              ...?
2121                     The behavior of this command depends on whether or not  a
2122                     column header was assigned a style containing a text ele‐
2123                     ment.  If a column header has no style or no style with a
2124                     text element then this command operates on the same -text
2125                     option as header configure.  Otherwise this command oper‐
2126                     ates  on  the -text option of the first text element in a
2127                     column header's style.  See item text.
2128
2129              pathName header tag command headerDesc ?arg ...?
2130                     See the item tag command.
2131
2132       pathName identify ?-array varName? x y
2133              This command returns information about the what is displayed  at
2134              the given window coordinates x and y.  When the -array option is
2135              used to specify the name of an array variable, elements  of  the
2136              array variable are set as follows:
2137
2138              [1]    If  the coordinates are outside the window, over the bor‐
2139                     ders, or over any whitespace in the window, then:
2140
2141                     $varName(where) is ""
2142
2143              [2]    If the coordinates are over a column header, then:
2144
2145                     $varName(where) is header
2146
2147                     $varName(header) is the unique id of the header-row
2148
2149                     $varName(column) is the unique id of the column
2150
2151                     $varName(element) is the name of an element, or ""
2152
2153                     $varName(side) is left or right if  the  coordinates  are
2154                     close to the edge of the column header, otherwise ""
2155
2156              [3]    If the coordinates are over an item, then:
2157
2158                     $varName(where) is item
2159
2160                     $varName(item) is the unique id of the item
2161
2162                     $varName(column) is the unique id of the column
2163
2164                     $varName(element) is the name of an element, or ""
2165
2166                     $varName(button)  is  a boolean indicating whether or not
2167                     the coordinates are over the item's expand/collapse  but‐
2168                     ton
2169
2170                     $varName(line)  is  the  unique  id of an ancestor of the
2171                     item (but not the parent of the item) if the  coordinates
2172                     are  over  a  line descending from that ancestor.  If the
2173                     coordinates are not over such a line then  $varName(line)
2174                     is  "".   This  is used to collapse the ancestor when the
2175                     line is clicked on.
2176       When the -array option  is  not  used,  this  command  returns  a  list
2177       describing what is displayed at the given window coordinates.  The for‐
2178       mat of this list can be like one of the following:
2179
2180              [1]    {}
2181
2182                     An empty list is returned if the coordinates are  outside
2183                     the  window,  over the borders, or over any whitespace in
2184                     the window.
2185
2186              [2]    header C ?left|right?
2187
2188                     header C elem E ?left|right?
2189
2190                     header H column C ?left|right?
2191
2192                     header H column C elem E ?left|right?
2193
2194                     Only when there is more than one header-row  is  there  a
2195                     unique  id of a header-row H followed by the keyword col‐
2196                     umn.  This is for compatibility with older versions  when
2197                     there was only one row of column headers allowed.
2198
2199              [3]    item I column C
2200
2201              [4]    item I column C elem E
2202
2203              [5]    item I button
2204
2205                     This  is  the  result  when  the coordinates are over the
2206                     expand/collapse button next to an item.
2207
2208              [6]    item I line I2
2209
2210                     This is the result when the coordinates are over  a  line
2211                     descending from an ancestor I2 of the item I (but not the
2212                     parent of that item). This is used to collapse the ances‐
2213                     tor when the line is clicked on.
2214
2215       pathName index itemDesc
2216              Deprecated. Use item id instead.
2217
2218       pathName item option ?arg ...?
2219              This command is used to manipulate items.  The exact behavior of
2220              the command depends on the option argument that follows the item
2221              argument.  The following forms of the command are supported:
2222
2223              pathName item ancestors itemDesc
2224                     Returns  a  list containing the item ids of the ancestors
2225                     of the item specified by itemDesc. The first  list  value
2226                     is  the  parent, the second is the parent's parent, an so
2227                     on. The last list value will be the root item if itemDesc
2228                     is a descendant of the root item.
2229
2230              pathName item bbox itemDesc ?column? ?element?
2231                     Returns a list with four elements giving the bounding box
2232                     of the item described by itemDesc. If no further argument
2233                     is  specified,  the  bbox spans the area of the item over
2234                     all non-locked columns. If a column  is  specified,  only
2235                     the  area of the item in this column is considered. If an
2236                     additional element is specified, the area of this element
2237                     in  column  of  the  specified  item  is  returned.   The
2238                     returned coordinates are relative to the top-left  corner
2239                     of  the  widget.  If the item is not visible for any rea‐
2240                     son, the result in an empty string.
2241
2242              pathName item buttonstate itemDesc ?state?
2243                     If state is specified, this command sets the state of the
2244                     expand/collapse  button  for the single item specified by
2245                     itemDesc.  The state argument may be one of active,  nor‐
2246                     mal  or pressed.  The current (or newly-set) state of the
2247                     button is returned.  The button state is used by the sys‐
2248                     tem  theme,  if any, to change the appearance of the but‐
2249                     ton.
2250
2251              pathName item cget itemDesc option
2252                     Returns the current value of the configuration option for
2253                     the  item  specified  by  itemDesc  whose name is option.
2254                     Option may have any of the values accepted  by  the  item
2255                     configure command.
2256
2257              pathName item children itemDesc
2258                     Returns a list containing the item ids of all children of
2259                     the item specified by itemDesc in the correct order  from
2260                     the first child to the last child.
2261
2262              pathName item collapse itemDesc ?-animate? ?-recurse?
2263                     Switches  off  the open state of the item(s) described by
2264                     itemDesc.  If an item has descendants, then they  are  no
2265                     longer  displayed.   If  an  item is already closed, then
2266                     this command has no effect on that item.  If -animate  is
2267                     specified,  then  the  item's  button  will animate as it
2268                     transitions between states if the theme supports  it;  in
2269                     this case only one item may be specified.  If -recurse is
2270                     specified, then all descendants of the items described by
2271                     itemDesc  will  also  be  collapsed.  For every item that
2272                     actually will be collapsed, two events are  generated:  a
2273                     <Collapse-before> event before the item state is changed,
2274                     and a <Collapse-after> event after  the  item  state  was
2275                     changed.
2276
2277              pathName item compare itemDesc1 op itemDesc2
2278                     From  both  items described by the itemDescs the index is
2279                     retrieved (as returned from the item  order  widget  com‐
2280                     mand).   Then these indexes are compared using the opera‐
2281                     tor op, which must be either <,  <=,  ==, >=, >,  or  !=.
2282                     The  return  value of this command is 1 if the comparison
2283                     evaluated to true, 0 otherwise.
2284
2285              pathName item complex itemDesc ?list...?
2286                     This horrible command is now deprecated. Use item element
2287                     configure instead. For every column of the treectrl there
2288                     may be specified one list.  Each list  should  look  like
2289                     this:
2290
2291                     { {element option value ...} {element option value ...} ...}
2292
2293                     Every  option  must  be  known by the element's type (see
2294                     ELEMENTS AND STYLES below).  Each option will be  set  to
2295                     value for the element in this one column in this item.
2296
2297              pathName  item configure itemDesc ?option? ?value? ?option value
2298              ...?
2299                     If no option is specified, returns a list describing  all
2300                     of  the  available options for the item given by itemDesc
2301                     (see Tk_ConfigureInfo for information on  the  format  of
2302                     this  list).  If  option is specified with no value, then
2303                     the command returns  a  list  describing  the  one  named
2304                     option  (this list will be identical to the corresponding
2305                     sublist of the value returned if no option is specified).
2306
2307                     If one or more option-value pairs are specified, then the
2308                     command  modifies  the  given  item option(s) to have the
2309                     given value(s); in this case the command returns an empty
2310                     string. This is the only case where itemDesc may refer to
2311                     multiple items.
2312
2313                     The following options are supported by this command  (see
2314                     item create for the meaning of each option):
2315
2316                     -button boolean|auto
2317
2318                     -height height
2319
2320                     -tags tagList
2321
2322                     -visible boolean
2323
2324                     -wrap boolean
2325
2326              pathName item count ?itemDesc?
2327                     If  no  additional  arguments  are given, the result is a
2328                     decimal string giving the number of items created by  the
2329                     item  create widget command which haven't been deleted by
2330                     the item delete widget command,  plus  1  for  the  ever-
2331                     present  root item.  If the optional argument itemDesc is
2332                     given, then the result is the number of items that  match
2333                     that item description.
2334
2335              pathName item create ?option value ...?
2336                     Creates  some  new items and optionally returns a list of
2337                     unique identifiers for those items.  The new  items  have
2338                     the  states  open  and  enabled  set  by default.  If the
2339                     treectrl widget currently has the focus, the state  focus
2340                     is also set.
2341
2342                     The following options are supported by this command:
2343
2344                     -button boolean|auto
2345                            The  value  of  this  option  must have one of the
2346                            forms accepted by Tcl_GetBoolean or  be  the  word
2347                            auto  (or  any  abbreviation  of it). It indicates
2348                            whether or not an expand/collapse button should be
2349                            drawn next to the item, typically to indicate that
2350                            the item has  children.   If  the  value  of  this
2351                            option is auto, then a button is displayed next to
2352                            the item whenever the item has any children  whose
2353                            item  option  -visible  is  true.  The button will
2354                            only be displayed if:
2355
2356                            [1]    the column specified by the treectrl option
2357                                   -treecolumn is visible, and
2358
2359                            [2]    the  treectrl  option -showbuttons is true,
2360                                   and
2361
2362                            [3]    for the  root  item,  the  treectrl  option
2363                                   -showrootbutton is true, and
2364
2365                            [4]    for  immediate  children  of the root item,
2366                                   the treectrl  option  -showrootchildbuttons
2367                                   is true.
2368
2369                     -count numItems
2370                            Specifies  the  number of items to create. Must be
2371                            >= 0. Defaults to 1.
2372
2373                     -enabled boolean
2374                            Specifies whether the  items  should  be  enabled.
2375                            Default is true.
2376
2377                     -height height
2378                            Specifies  a  fixed  height  in  any  of the forms
2379                            acceptable to Tk_GetPixels.   Must  be  >=  0.  If
2380                            height  is zero then the item's height is unspeci‐
2381                            fied.  Defaults to 0.  See also the widget options
2382                            -itemheight and -minitemheight.
2383
2384                     -nextsibling itemDesc
2385                            Specifies the item before which the new items will
2386                            be inserted. The new items will have the same par‐
2387                            ent as itemDesc.
2388
2389                     -open boolean
2390                            Specifies  whether  the  items  should  be open or
2391                            closed. Default is true.
2392
2393                     -parent itemDesc
2394                            Specifies the item which the new items will be the
2395                            children of. The new items will be appended to the
2396                            list of children of itemDesc.  When no  parent  is
2397                            specified, the new items are orphan items (see the
2398                            widget command orphans) and will not be  displayed
2399                            in the list.
2400
2401                     -prevsibling itemDesc
2402                            Specifies  the item after which the new items will
2403                            be inserted. The new items will have the same par‐
2404                            ent as itemDesc.
2405
2406                     -returnid boolean
2407                            Specifies  whether or not to return a list of item
2408                            identifiers for the newly created items.  Specify‐
2409                            ing  false  is useful when creating a large number
2410                            of items in the console or to improve performance.
2411                            Default is true.
2412
2413                     -tags tagList
2414                            TagList  is a list of tag names to be added to the
2415                            new items.  The item tag command can also be  used
2416                            to manipulate this list of tags.
2417
2418                     -visible boolean
2419                            Boolean  must  have  one  of the forms accepted by
2420                            Tcl_GetBoolean. It indicates that the item  should
2421                            be  displayed  in  the list. The item will only be
2422                            displayed if:
2423
2424                            [1]    each ancestor is a descendant of  the  root
2425                                   item (not an orphan), and
2426
2427                            [2]    each ancestor's -visible option is true
2428
2429                     -wrap boolean
2430                            Boolean  must  have  one  of the forms accepted by
2431                            Tcl_GetBoolean. It indicates that this item should
2432                            be the first one in a horizontal range or vertical
2433                            range of items. See also the widget option -wrap.
2434
2435              pathName item delete first ?last?
2436                     Deletes the specified item(s).  First and  last  must  be
2437                     valid  item  descriptions.  If last isn't specified, then
2438                     first may specify multiple items.  If both first and last
2439                     are  specified, they must each decribe a single item with
2440                     a common ancestor; then the range of items between  first
2441                     and last is deleted.  The order of first and last doesn't
2442                     matter.
2443
2444                     Deleting an item deletes any child items of  the  deleted
2445                     item recursively.  If the current active item is deleted,
2446                     the root item becomes the new active item.  If  the  cur‐
2447                     rent  selection  anchor  item  is  deleted, the root item
2448                     becomes the new anchor item.  There is no way  to  delete
2449                     the  root  item  of the treectrl widget; in all cases the
2450                     specification of the root item is ignored.
2451
2452                     For each call to this command, two events may  be  gener‐
2453                     ated.   If  any  of  the deleted items are selected, then
2454                     they are removed from the  selection  and  a  <Selection>
2455                     event is generated just before the items are deleted.  If
2456                     any items are going to be deleted, then  an  <ItemDelete>
2457                     event is generated just before the items are deleted.
2458
2459              pathName item descendants itemDesc
2460                     Returns a list containing the item ids of the descendants
2461                     of the item specified by  itemDesc,  i.e.  the  children,
2462                     grandchildren, great-grandchildren etc, of the item.
2463
2464              pathName item dump itemDesc
2465                     Debug  command.  Returns  a list with 4 words in the form
2466                     index index indexVis indexVis.
2467
2468              pathName item element command itemDesc column element ?arg ...?
2469                     This command is used to manipulate elements of the  item.
2470                     The  exact behavior of the command depends on the command
2471                     argument that follows the element argument.  The  follow‐
2472                     ing forms of the command are supported:
2473
2474                     pathName  item  element  actual  itemDesc  column element
2475                     option
2476                            Deprecated. Use item element perstate instead.
2477
2478                     pathName item element cget itemDesc column element option
2479                            This command returns the value of the option named
2480                            option  associated  with  element inside column of
2481                            the item described by itemDesc, if it was  already
2482                            configured  for  the actual item.  Option may have
2483                            any of the values accepted  by  the  type  of  the
2484                            specified element (see ELEMENTS AND STYLES below)
2485
2486                     pathName  item  element configure itemDesc column element
2487                     ?option? ?value? ?option value ...?
2488                            This command modifies configuration options for an
2489                            element  in  a column of an item.  If no option is
2490                            specified, the command returns a  list  describing
2491                            all  of the available options for the element (see
2492                            Tk_ConfigureInfo for information on the format  of
2493                            this list).  If option is specified with no value,
2494                            then the command returns a list describing the one
2495                            named  option  (this list will be identical to the
2496                            corresponding sublist of the value returned if  no
2497                            option is specified).
2498
2499                            If  one  or more option-value pairs are specified,
2500                            then the command modifies the given  option(s)  to
2501                            have the given value(s) in the element inside col‐
2502                            umn of the item(s) described by itemDesc; in  this
2503                            case  the command returns an empty string. This is
2504                            the only case where itemDesc may refer to multiple
2505                            items.
2506
2507                            It  is  possible to configure multiple elements in
2508                            multiple columns with a single call. To  configure
2509                            another  element  in the same column, append a ´+'
2510                            argument followed by the element name. To  config‐
2511                            ure elements in another column, append a ',' argu‐
2512                            ment followed by the column.  For example:
2513
2514                                                    $C1 $E1 -text "hello" + $E2 -text "world" , \
2515                                                    $C2 $E3 -fill Blue , \
2516                                                    $C3 $E1 -text "apples and oranges"
2517
2518                            Each of the column description arguments  to  this
2519                            command  may refer to multiple columns if at least
2520                            one option-value pair is given.
2521
2522                     pathName item element perstate  itemDesc  column  element
2523                     option ?stateList?
2524                            This command returns the current value of the per-
2525                            state option named option for element inside  col‐
2526                            umn   of   the  item  described  by  itemDesc.  If
2527                            stateList is specified, the list  of  state  names
2528                            (static  and dynamic, see STATES) is used in place
2529                            of the current state for item and column.
2530
2531              pathName item enabled itemDesc ?boolean?
2532                     Returns 1 if the item described by itemDesc has the state
2533                     enabled  switched  on,  0 otherwise. If boolean is speci‐
2534                     fied, then the enabled state of every item  described  by
2535                     the  item  description  itemDesc is set accordingly.  New
2536                     items are enabled by default when created. Disabled items
2537                     cannot  be  selected, and are ignored by the default key-
2538                     navigation and mouse bindings.
2539
2540              pathName item expand itemDesc ?-animate? ?-recurse?
2541                     Switches on the open state of the  item(s)  described  by
2542                     itemDesc.   If an item has descendants, then they are now
2543                     displayed.  If an item is already open, then this command
2544                     has  no  effect  on that item.  If -animate is specified,
2545                     then the item's button will  animate  as  it  transitions
2546                     between  states  if  the  theme supports it; in this case
2547                     only one item may be specified.  If  -recurse  is  speci‐
2548                     fied,  then  all  descendants  of  the items described by
2549                     itemDesc will also be  expanded.   For  every  item  that
2550                     actually  will  be expanded, two events are generated: an
2551                     <Expand-before> event before the item state  is  changed,
2552                     and  an  <Expand-after>  event  after  the item state was
2553                     changed.
2554
2555              pathName item firstchild parent ?child?
2556                     If child is not specified, returns the  item  id  of  the
2557                     first child of the item described by parent.  If child is
2558                     specified, it must describe an item that is  neither  the
2559                     root item nor an ancestor of parent.  Then it will become
2560                     the new first child of parent.
2561
2562              pathName item id itemDesc
2563                     This command resolves the item description itemDesc  into
2564                     a  list  of  unique item identifiers. If itemDesc doesn't
2565                     refer to any existing items, then this command returns an
2566                     empty list.
2567
2568              pathName item image itemDesc ?column? ?image? ?column image ...?
2569                     This command sets or retrieves the value of the per-state
2570                     -image option for the first image element in one or  more
2571                     columns.  If no column is specified, this command returns
2572                     a list of values, one per column.  If no image is  speci‐
2573                     fied, this command returns the value for column.
2574
2575                     If  one or more column-image pairs is specified, then the
2576                     value of the -image option  in  each  column  is  set  to
2577                     image.  In this case itemDesc may refer to multiple items
2578                     and each column may refer to multiple columns.
2579
2580                     Note that this command is provided as a convenience.  Use
2581                     the  item element configure or item element cget commands
2582                     if you want to set or retrieve the value  of  the  -image
2583                     option for a specific image element.
2584
2585              pathName item isancestor itemDesc descendant
2586                     Returns  1  if the item described by itemDesc is a direct
2587                     or indirect parent of the item decribed by descendant,  0
2588                     otherwise.
2589
2590              pathName item isopen itemDesc
2591                     Returns 1 if the item described by itemDesc has the state
2592                     open switched on, 0 otherwise.
2593
2594              pathName item lastchild parent ?child?
2595                     If child is not specified, returns the  item  id  of  the
2596                     last  child of the item described by parent.  If child is
2597                     specified, it must describe an item that is not an ances‐
2598                     tor of parent.  Then it will become the new last child of
2599                     parent.
2600
2601              pathName item nextsibling sibling ?next?
2602                     If next is not specified, returns the item id of the next
2603                     sibling  of  the  item  described by sibling.  If next is
2604                     specified, it must describe an item that is not an ances‐
2605                     tor of sibling.  Then it will become the new next sibling
2606                     of sibling.
2607
2608              pathName item numchildren itemDesc
2609                     Returns the number of children of the item  described  by
2610                     itemDesc.
2611
2612              pathName item order itemDesc ?-visible?
2613                     This  command  returns  the position of the item itemDesc
2614                     relative to its toplevel ancestor (usually the root item,
2615                     unless the ancestor is an orphan). If you imagine all the
2616                     items flattened into a vertical list, the result of  this
2617                     command  is  the  row  the item falls in. If the optional
2618                     argument -visible is given, only the items  whose  ances‐
2619                     tors are expanded, and whose -visible option is true, get
2620                     counted; in this case -1 is returned if the item  is  not
2621                     visible.
2622
2623              pathName item parent itemDesc
2624                     Returns  the  item id of the parent of the item described
2625                     by itemDesc.
2626
2627              pathName item prevsibling sibling ?prev?
2628                     If prev is not specified, returns the item id of the pre‐
2629                     vious  sibling of the item described by sibling.  If prev
2630                     is specified, it must describe an item  that  is  not  an
2631                     ancestor  of sibling.  Then it will become the new previ‐
2632                     ous sibling of sibling.
2633
2634              pathName item range first last
2635                     Returns a list containing the item ids of  all  items  in
2636                     the  range  between first and last, inclusive.  The order
2637                     between first and last doesn't matter, and the result  is
2638                     always  sorted  by  the increasing order of the items (as
2639                     returned by the item order command).  The items specified
2640                     by first and last must share a common ancestor.
2641
2642              pathName item remove itemDesc
2643                     Removes  the  item described by itemDesc from the list of
2644                     children of its parent, so that it will become an orphan.
2645
2646              pathName item rnc itemDesc
2647                     Returns a list of two integers, which corresponds to  the
2648                     row and column of the item described by itemDesc. The row
2649                     and column corresponds to the  on-screen  arrangement  of
2650                     items  as determined by the -orient and -wrap options. If
2651                     the item is not displayed, this command returns an  empty
2652                     string.
2653
2654              pathName item sort itemDesc ?option ...?
2655                     Sorts the children of the item described by itemDesc, and
2656                     redisplays the tree with the items in the new order.
2657
2658                     The  range  of  items  which  should  be  sorted  can  be
2659                     restricted  by  means of the -first and/or -last options,
2660                     which  should  be  children  of  the  item  described  by
2661                     itemDesc;  the  order  between  these  two limiting items
2662                     doesn't matter.
2663
2664                     The sort column can be specified by means of the  -column
2665                     option;  this  option  can be used repeatedly to define a
2666                     multicolumn sort.  The sorting is done by looking at  the
2667                     text  of  the  element  specified by the -element option,
2668                     which must be a text element defined in the style of  the
2669                     sorting  column,  by  default  the  first text element is
2670                     used.
2671
2672                     If the -notreally option is specified, no rearranging  of
2673                     the  items is done; instead the sorted items are returned
2674                     as result of the command.
2675
2676                     By default ASCII sorting is used with the result returned
2677                     in increasing order.  Any of the following options may be
2678                     specified to control the sorting process  of  the  previ‐
2679                     ously   specified   column   (unique   abbreviations  are
2680                     accepted):
2681
2682                     -ascii Use string comparison with ASCII collation  order.
2683                            This is the default.
2684
2685                     -command command
2686                            Use  command  as a comparison command.  To compare
2687                            two items, evaluate a  Tcl  script  consisting  of
2688                            command  with  the  numerical ids of the two items
2689                            appended  as  additional  arguments.   The  script
2690                            should  return  an integer less than, equal to, or
2691                            greater than zero if the first item is to be  con‐
2692                            sidered  less  than, equal to, or greater than the
2693                            second, respectively.
2694
2695                     -decreasing
2696                            Sort the  items  in  decreasing  order  ("largest"
2697                            items first).
2698
2699                     -dictionary
2700                            Use  dictionary-style comparison. This is the same
2701                            as -ascii except (a) case is ignored except  as  a
2702                            tie-breaker  and (b) if two strings contain embed‐
2703                            ded numbers, the numbers compare as integers,  not
2704                            characters.   For  example,  in  -dictionary mode,
2705                            bigBoy sorts between bigbang and bigboy, and  x10y
2706                            sorts between x9y and x11y.
2707
2708                     -increasing
2709                            Sort  the  items  in  increasing order ("smallest"
2710                            items first). This is the default.
2711
2712                     -integer
2713                            Convert to integers and use integer comparison.
2714
2715                     -real  Convert to floating-point values and use  floating
2716                            comparison.
2717
2718              pathName  item  span itemDesc ?column? ?numColumns? ?column num‐
2719              Columns ...?
2720                     This command sets or retrieves the number of columns that
2721                     a  style  covers.   If no column is specified, the return
2722                     value is a list of spans, one per  column.   If  no  num‐
2723                     Columns  is  specified,  the return value is the span for
2724                     column.
2725
2726                     If one or more column-numColumns pairs is specified,  the
2727                     span  for  each column is set to numColumns. In this case
2728                     itemDesc may refer to multiple items and each column  may
2729                     refer to multiple columns.
2730
2731              pathName item state command itemDesc ?arg ...?
2732                     This command is used to manipulate the states of an item.
2733                     The exact behavior of the command depends on the  command
2734                     argument  that follows the style argument.  The following
2735                     forms of the command are supported:
2736
2737                     pathName item state define stateName
2738                            Defines a new state with the name stateName, which
2739                            must not be the name of an existing state.
2740
2741                     pathName  item  state  forcolumn  itemDesc  column ?stat‐
2742                     eDescList?
2743                            Just like item state set but  manipulates  dynamic
2744                            states for a single item column, not the item as a
2745                            whole. If stateDescList is unspecified, this  com‐
2746                            mand  returns  a  list containing the names of all
2747                            the dynamic states which are switched on  in  col‐
2748                            umn.
2749
2750                            If  stateDescList  is specified, then itemDesc may
2751                            refer to multiple items and column  may  refer  to
2752                            multiple columns.
2753
2754                     pathName item state get itemDesc ?stateName?
2755                            If  no stateName is specified, returns a list con‐
2756                            taining the names  of  all  (static  and  dynamic)
2757                            states  which  are  currently  switched on for the
2758                            item described by itemDesc.   If  a  stateName  is
2759                            specified, 1 is returned if the specified state is
2760                            currently switched on for the item, 0 otherwise.
2761
2762                     pathName item state linkage stateName
2763                            Returns a string indicating whether the  specified
2764                            state  is  user-defined by means of the item state
2765                            define widget command (dynamic) or  predefined  by
2766                            the treectrl widget itself (static).
2767
2768                     pathName item state names
2769                            Returns  a  list containing the names of all user-
2770                            defined states.
2771
2772                     pathName item state set itemDesc ?lastItem? stateDescList
2773                            Every element of stateDescList must be the name of
2774                            a  dynamic  state  (see  STATES below), optionally
2775                            preceded by a ~ or ! character.  Every state  with
2776                            a  leading  !  will  be  switched off for the item
2777                            described by itemDesc, every state with a  leading
2778                            ~ will be toggled, and every state without leading
2779                            ! or ~ will be switched on.  If lastItem is speci‐
2780                            fied, the state changes will be made for all items
2781                            in the range between itemDesc  and  lastItem.   If
2782                            lastItem  unspecified,  then the state changes are
2783                            made for all items described by itemDesc.
2784
2785                     pathName item state undefine ?stateName ...?
2786                            Every stateName must be the name of a user-defined
2787                            state.   Removes this state from the list of user-
2788                            defined states.
2789
2790              pathName item style command itemDesc ?arg ...?
2791                     This command is used to manipulate the styles of an item.
2792                     The  exact behavior of the command depends on the command
2793                     argument that follows the style argument.  The  following
2794                     forms of the command are supported:
2795
2796                     pathName item style elements itemDesc column
2797                            This  command  returns a list containing the names
2798                            of elements which were configured by the item ele‐
2799                            ment  configure  command for the item described by
2800                            itemDesc in column. If there is no style  assigned
2801                            to column an error is returned.
2802
2803                     pathName item style map itemDesc column style map
2804                            Like  the item style set command, this command may
2805                            be used to assign a style to a specific column  of
2806                            an  item.  Unlike item style set, this command can
2807                            transfer configuration values of elements  in  the
2808                            current  style to elements in the new style speci‐
2809                            fied by style.  Map must be a list of  elementOld-
2810                            elementNew  pairs,  where elementOld is an element
2811                            in the current style, and elementNew is an element
2812                            in  the  style specified by style. Both elementOld
2813                            and elementNew must be of the same  type  (bitmap,
2814                            text  etc).   ItemDesc may refer to multiple items
2815                            and column may refer to multiple columns.
2816
2817                     pathName item style set itemDesc ?column? ?style? ?column
2818                     style ...?
2819                            This  command sets or retrieves the style assigned
2820                            to one or more columns.  If no  column  is  speci‐
2821                            fied,  this  command returns a list containing the
2822                            names of the styles set for  all  columns  of  the
2823                            item described by itemDesc.  If no style is speci‐
2824                            fied, this command returns the name of  the  style
2825                            set for the item described by itemDesc in column.
2826
2827                            If  one  or  more column-style pairs is specified,
2828                            then the style in each column is set to style.  In
2829                            this case itemDesc may refer to multiple items and
2830                            each column may refer to multiple columns.
2831
2832              pathName item tag option ?arg arg ...?
2833                     This command is used to manipulate tags  on  items.   The
2834                     exact behavior of the command depends on the option argu‐
2835                     ment that follows the item tag argument.   The  following
2836                     forms of the command are supported:
2837
2838                     pathName item tag add itemDesc tagList
2839                            Adds each tag in tagList to the items specified by
2840                            the item description itemDesc.  Duplicate tags are
2841                            ignored.  The list of tags for an item can also be
2842                            changed via an item's -tags option.
2843
2844                     pathName item tag expr itemDesc tagExpr
2845                            Evaluates the tag expression tagExpr against every
2846                            item  specified  by the item description itemDesc.
2847                            The result is 1 if the tag expression evaluates to
2848                            true for every item, 0 otherwise.
2849
2850                     pathName item tag names itemDesc
2851                            Returns  a list of tag names assigned to the items
2852                            specified by the item  description  itemDesc.  The
2853                            result  is  the  union of any tags assigned to the
2854                            items.
2855
2856                     pathName item tag remove itemDesc tagList
2857                            Removes each tag in tagList from the items  speci‐
2858                            fied  by the item description itemDesc.  It is not
2859                            an error if any of the items do not use any of the
2860                            tags.   The  list  of tags for an item can also be
2861                            changed via an item's -tags option.
2862
2863              pathName item text itemDesc ?column? ?text? ?column text ...?
2864                     This command sets or retrieves the  value  of  the  -text
2865                     option for the first text element in one or more columns.
2866                     If no column is specified, this command returns a list of
2867                     values,  one  per  column.  If no text is specified, this
2868                     command returns the value for column.
2869
2870                     If one or more column-text pairs is specified,  then  the
2871                     value  of the -text option in each column is set to text.
2872                     In this case itemDesc may refer  to  multiple  items  and
2873                     each column may refer to multiple columns.
2874
2875                     Note  that this command is provided as a convenience. Use
2876                     the item element configure or item element cget  commands
2877                     if  you  want  to  set or retrieve the value of the -text
2878                     option for a specific text element.
2879
2880              pathName item toggle itemDesc ?-animate? ?-recurse?
2881                     Changes the  open  state  of  the  item(s)  described  by
2882                     itemDesc.   If  the open state is currently switched off,
2883                     then this command does the same as the item expand widget
2884                     command;  otherwise  the same as the item collapse widget
2885                     command.  If -animate is specified, then the item's  but‐
2886                     ton  will animate as it transitions between states if the
2887                     theme supports it; in this case  only  one  item  may  be
2888                     specified.  If -recurse is specified, then the open state
2889                     of all descendants of the  items  described  by  itemDesc
2890                     will also be toggled.
2891
2892       pathName marquee option ?arg ...?
2893              This  command  is  used  to manipulate the marquee, which can be
2894              used to implement a resizable selection  rectangle,  in  a  file
2895              browser  for  example.  One corner point of the marquee is fixed
2896              as long as the marquee is visible and  called  the  anchor;  the
2897              diagonally  opposite  corner  is  dragged  with  the mouse while
2898              resizing the marquee and simply called the corner.
2899
2900              All coordinates handled by this widget command are canvas  coor‐
2901              dinates,  i.e.  the  canvasx or canvasy widget command should be
2902              used to translate window coordinates to canvas coordinates.
2903
2904              By default, the marquee is displayed as a 1-pixel  thick  dotted
2905              rectangle.  If either of the -fill or -outline options is speci‐
2906              fied, then the marquee is drawn as a filled and/or outlined rec‐
2907              tangle  of  the  specified  color(s).   The  -fill option should
2908              specify a transparent gradient to avoid hiding  what  is  inside
2909              the marquee.  See GRADIENTS for more info.
2910
2911              The exact behavior of the command depends on the option argument
2912              that follows the marquee argument.  The following forms  of  the
2913              command are supported:
2914
2915              pathName marquee anchor ?x y?
2916                     Returns  a list containing the x and y coordinates of the
2917                     anchor, if no additional arguments are specified.  If two
2918                     coordinates  are  specified, sets the anchor to the given
2919                     coordinates x and y.
2920
2921              pathName marquee cget option
2922                     This command returns the current  value  of  the  marquee
2923                     option  named  option.  Option may have any of the values
2924                     accepted by the marquee configure widget command.
2925
2926              pathName marquee configure ?option? ?value? ?option value ...?
2927                     This command is similar to the configure  widget  command
2928                     except  that  it  modifies the marquee options instead of
2929                     modifying options for the overall treectrl widget.  If no
2930                     option  is specified, the command returns a list describ‐
2931                     ing all of the available marquee options (see  Tk_Config‐
2932                     ureInfo  for information on the format of this list).  If
2933                     option is specified  with  no  value,  then  the  command
2934                     returns  a  list  describing the one named marquee option
2935                     (this list will be identical to the corresponding sublist
2936                     of the value returned if no option is specified).  If one
2937                     or more option-value pairs are specified, then  the  com‐
2938                     mand  modifies  the  given  marquee option(s) to have the
2939                     given value(s); in this case the command returns an empty
2940                     string.
2941
2942                     The following marquee options are supported:
2943
2944                     -fill color
2945                            Specifies  the color to fill the marquee rectangle
2946                            with.  See the comments above about using a trans‐
2947                            parent gradient here.
2948
2949                     -outline color
2950                            Specifies the color to outline the marquee rectan‐
2951                            gle with.
2952
2953                     -outlinewidth color
2954                            Specifies the width of the  outline  drawn  inside
2955                            the marquee's rectangle.  The outline is not drawn
2956                            if this value is less than 1.  This option has  no
2957                            effect  if  the  -outline  option  is unspecified,
2958                            i.e., the default dotted rectangle  is  unaffected
2959                            by this option.  outlineWidth may be in any of the
2960                            forms acceptable to Tk_GetPixels.  Defaults to 1.
2961
2962                     -visible boolean
2963                            Specifies a boolean value which determines whether
2964                            the marquee is displayed.
2965
2966              pathName marquee coords ?x1 y1 x2 y2?
2967                     Returns  a list containing the x and y coordinates of the
2968                     anchor followed by the x and y coordinates of the corner,
2969                     if  no additional arguments are specified.  If four coor‐
2970                     dinates are specified, sets the anchor to the given coor‐
2971                     dinates  x1  and  y1 and the corner to the coordinates x2
2972                     and y2.
2973
2974              pathName marquee corner ?x y?
2975                     Returns a list containing the x and y coordinates of  the
2976                     corner, if no additional arguments are specified.  If two
2977                     coordinates are specified, sets the corner to  the  given
2978                     coordinates x and y.
2979
2980              pathName marquee identify
2981                     Returns  a  list  with information about any items inter‐
2982                     secting the marquee.  The format of the returned list is:
2983
2984                     {
2985                         {item {column element element ...} {column element element ...} ...}
2986                         {item {column element element ...} {column element element ...} ...}
2987                         ...
2988                     }
2989
2990                     There may be zero sublists following an item  id  if  the
2991                     marquee  is in the button/line area of an item. There may
2992                     be zero element names following a column id if the  item-
2993                     column  has no style or if the marquee does not intersect
2994                     any elements in that column.
2995
2996       pathName notify option ?arg ...?
2997              Many Tk widgets communicate with the outside world via  -command
2998              callbacks  and/or  virtual  events. For example, the Text widget
2999              evaluates its  -yscrollcommand  when  the  view  in  the  widget
3000              changes, and generates a <<Modified>> virtual event when text is
3001              inserted or deleted.  A treectrl widget replaces both methods of
3002              communication  with its own event mechanism accessed through the
3003              notify subcommands.
3004
3005              The exact behavior of the command depends on the option argument
3006              that  follows  the  notify argument.  The following forms of the
3007              command are supported:
3008
3009              pathName notify bind ?object? ?pattern? ?+??script?
3010                     This command associates Tcl scripts with events generated
3011                     by  a treectrl widget.  If all three arguments are speci‐
3012                     fied, notify bind will arrange for script (a Tcl  script)
3013                     to  be  evaluated whenever the event(s) specified by pat‐
3014                     tern are generated by this treectrl widget.  If script is
3015                     prefixed  with a "+", then it is appended to any existing
3016                     binding  for  pattern;   otherwise  script  replaces  any
3017                     existing  binding.  If script is an empty string then the
3018                     current binding for pattern is destroyed, leaving pattern
3019                     unbound.  In  all of the cases where a script argument is
3020                     provided, notify bind returns an empty string.
3021
3022                     If pattern is specified without a script, then the script
3023                     currently  bound  to  pattern  is  returned,  or an empty
3024                     string is returned if there is no binding for pattern. If
3025                     neither  pattern nor script is specified, then the return
3026                     value is a list whose elements are all the  patterns  for
3027                     which there exist bindings for object.
3028
3029                     The  object argument determines which window(s) the bind‐
3030                     ing applies to.  If object  begins  with  a  dot,  as  in
3031                     .a.b.c,  then it must be the path name for a window; oth‐
3032                     erwise it may be an arbitrary string.  Like  the  regular
3033                     bind  command, bindings on window names are automatically
3034                     removed if that window is destroyed.
3035
3036              pathName  notify  configure  object  pattern  ?option?   ?value?
3037              ?option value ...?
3038                     This command sets and retrieves options for bindings cre‐
3039                     ated by the notify bind command.
3040
3041                     If no option is specified, the  command  returns  a  list
3042                     with  option-value  pairs  describing  all  the available
3043                     binding options for pattern  on  object.   If  option  is
3044                     specified  with  no  value,  then the command returns the
3045                     current value of that option.  If  one  or  more  option-
3046                     value  pairs are specified, then the command modifies the
3047                     given option(s) to have the given value(s) for the  bind‐
3048                     ing; in this case the command returns an empty string.
3049
3050                     The following binding options are supported:
3051
3052                     -active boolean
3053                            Specifies  if  the  binding  should be active.  As
3054                            long as this option is specified as false, a bind‐
3055                            ing  script  will not be evaluated when the corre‐
3056                            sponding event is generated.
3057
3058              pathName notify detailnames eventName
3059                     Returns a list containing the names of all details, which
3060                     are  installed  for  the event with the name eventName by
3061                     means of the notify install  widget  command  or  by  the
3062                     treectrl widget itself.
3063
3064              pathName notify eventnames
3065                     Returns  a list containing the names of all events, which
3066                     are installed by means of the notify install widget  com‐
3067                     mand or by the treectrl widget itself.
3068
3069              pathName notify generate pattern ?charMap? ?percentsCommand?
3070                     This  command  causes  the treectrl widget to generate an
3071                     event. This command is typically used to generate dynamic
3072                     events  created by the notify install command, but may be
3073                     used to generate static events also.  The event specified
3074                     by  pattern  is generated, and any active binding scripts
3075                     on the event are evaluated after  undergoing  %-substitu‐
3076                     tion.   If  there are details defined for the event, pat‐
3077                     tern must describe an <eventName-detail> pair,  otherwise
3078                     pattern should be <eventName>.
3079
3080                     The  optional charMap is a list of char-value pairs as in
3081                     the form returned by array get.   Each  char  has  to  be
3082                     exactly  one character.  The charMap is used in %-substi‐
3083                     tution.
3084
3085                     If percentsCommand is specified, then it will be used  to
3086                     perform %-substitution on any scripts bound to the event.
3087                     If percentsCommand is not  specified  and  the  event  is
3088                     dynamic,  then the %-subtitution command passed to notify
3089                     install will be used if it was provided. If the event  is
3090                     static  or  no  %-substitution command is available, then
3091                     all %-substitution is done  using  charMap  only  .   See
3092                     notify install for a description of percentsCommand.
3093
3094              pathName notify install pattern ?percentsCommand?
3095                     This  command installs a new event or detail specified by
3096                     pattern.  Events  created  by  this  command  are  called
3097                     dynamic,  whereas  events  created by the treectrl widget
3098                     itself are called static.  This command may be called  to
3099                     set  or  retrieve  the  percentsCommand  for  an existing
3100                     dynamic event.
3101
3102                     The optional percentsCommand is  a  list  containing  the
3103                     name  of  a  Tcl command, plus any optional arguments, to
3104                     which five additional arguments  will  be  appended.  The
3105                     command  will  be called to perform %-substitution on any
3106                     scripts bound to the  event  specified  by  pattern  (see
3107                     EVENTS AND SCRIPT SUBSTITUTIONS).  PercentsCommand should
3108                     be defined as follows:
3109
3110                     proc percentsCommand {?arg arg ...? char object event detail charMap} {
3111                                             switch -- $char {
3112                                             ...
3113                                             }
3114                                             return $value
3115                     }
3116
3117                     The optional arg arguments are part of  the  percentsCom‐
3118                     mand  list.   Char  is the %-character to be substituted.
3119                     Object is the same as the argument to notify bind.  Event
3120                     and  detail specify the event. CharMap is the same as the
3121                     argument  to  notify  generate.   PercentsCommand  should
3122                     return  the  value  to replace the %-character by.  If an
3123                     error occurs evaluating percentsCommand, the  %-character
3124                     is replaced by itself.
3125
3126                     notify  install  returns  the current percentsCommand for
3127                     the event, or an error if the event is not dynamic.
3128
3129              pathName notify install detail  eventName  detail  ?percentsCom‐
3130              mand?
3131                     Deprecated.  Use notify install with a pattern of <event‐
3132                     Name-detail> instead.
3133
3134              pathName notify install event eventName ?percentsCommand?
3135                     Deprecated.  Use notify install with a pattern of <event‐
3136                     Name> instead.
3137
3138              pathName notify linkage pattern
3139                     Returns  a  string indicating whether the specified event
3140                     or detail is created by means of the notify install  wid‐
3141                     get  command  (dynamic)  or by the treectrl widget itself
3142                     (static).
3143
3144              pathName notify linkage eventName ?detail?
3145                     Deprecated.  Use notify linkage with a pattern of <event‐
3146                     Name> or <eventName-detail> instead.
3147
3148              pathName notify unbind object ?pattern?
3149                     If  no  pattern  is specified, all bindings on object are
3150                     removed.  If pattern is specified, then the current bind‐
3151                     ing for pattern is destroyed, leaving pattern unbound.
3152
3153              pathName notify uninstall pattern
3154                     If  the  event  or  detail specified by pattern is static
3155                     (i.e. created by the treectrl widget itself), an error is
3156                     generated.   Otherwise  the  dynamic  event  or detail is
3157                     removed. If an event name is specified without a  detail,
3158                     all details for that event are also removed.
3159
3160              pathName notify uninstall detail eventName detail
3161                     Deprecated.   Use  notify  uninstall  with  a  pattern of
3162                     <eventName-detail> instead.
3163
3164              pathName notify uninstall event eventName
3165                     Deprecated.  Use  notify  uninstall  with  a  pattern  of
3166                     <eventName> instead.
3167
3168       pathName numcolumns
3169              Deprecated. Use the column count command instead.
3170
3171       pathName numitems
3172              Deprecated. Use the item count command instead.
3173
3174       pathName orphans
3175              Returns  a  list containing the item ids of all items which have
3176              no parent.  When an  item  is  created,  it  has  no  parent  by
3177              default,  and  can  later  become an orphan by means of the item
3178              remove widget command. The root item is not returned.
3179
3180       pathName range first last
3181              Deprecated. Use the item range command instead.
3182
3183       pathName scan option args
3184              This command is used to implement scanning on treectrls. It  has
3185              two forms, depending on option:
3186
3187              pathName scan mark x y
3188                     Records x and y and the treectrl's current view;  used in
3189                     conjunction with later scan  dragto  commands.  Typically
3190                     this  command  is associated with a mouse button press in
3191                     the widget and x and y are the coordinates of the  mouse.
3192                     It returns an empty string.
3193
3194              pathName scan dragto x y ?gain?
3195                     This  command computes the difference between its x and y
3196                     arguments (which are typically mouse coordinates) and the
3197                     x  and  y arguments to the last scan mark command for the
3198                     widget. It then adjusts the view by gain times  the  dif‐
3199                     ference  in  coordinates, where gain defaults to 10. This
3200                     command is typically associated with mouse motion  events
3201                     in  the  widget,  to  produce  the effect of dragging the
3202                     treectrl at high speed through its  window.   The  return
3203                     value is an empty string.
3204
3205       pathName see itemDesc ?columnDesc? ?option value ...?
3206              Adjust  the  view  in the treectrl so that the item described by
3207              itemDesc is visible.  If the item is already  visible  then  the
3208              command  has  no effect; otherwise the treectrl scrolls to bring
3209              the item into view,  and  the  corresponding  <Scroll-x>  and/or
3210              <Scroll-y> events are generated. If columnDesc is specified then
3211              a specific column of the item is scrolled into view  instead  of
3212              the entire item.
3213
3214              The following options are supported:
3215
3216              -center flags
3217                     Flags is a string that contains zero or more of the char‐
3218                     acters x or y. This option is used  to  center  the  item
3219                     horizontally  and/or  vertically in the window.  The item
3220                     will be centered regardless of whether it is already vis‐
3221                     ible.
3222
3223       pathName selection option args
3224              This  command is used to adjust the selection within a treectrl.
3225              It has several forms, depending on option:
3226
3227              pathName selection add first ?last?
3228                     First and last (if specified) must be valid item descrip‐
3229                     tions.  If  both  first and last are specified, then they
3230                     may refer to a single item only; in this case the command
3231                     adds every unselected item in the range between first and
3232                     last, inclusive, to the selection without  affecting  the
3233                     selected  state  of  items  outside  that range.  If only
3234                     first is specified, then every unselected item  specified
3235                     by  first is added to the selection.  A <Selection> event
3236                     is generated if any items were added to the selection.
3237
3238              pathName selection anchor ?itemDesc?
3239                     If itemDesc is specified, the selection anchor is set  to
3240                     the  described  item.  The selection anchor is the end of
3241                     the selection that is fixed while dragging out  a  selec‐
3242                     tion  with the mouse.  The item description anchor may be
3243                     used to refer to the anchor item.  This  command  doesn't
3244                     modify  the  selection  state  of  any item.  Returns the
3245                     unique id of the selection anchor item.
3246
3247              pathName selection clear ?first? ?last?
3248                     First and last (if specified) must be valid item descrip‐
3249                     tions.  If  both  first and last are specified, then they
3250                     may refer to  a  single  item  only;  in  this  case  any
3251                     selected  items  between  first  and last (inclusive) are
3252                     removed from the selection without affecting the selected
3253                     state  of  items  outside  that  range.  If only first is
3254                     specified, then every selected item specified by first is
3255                     removed  from  the  selection.  If neither first nor last
3256                     are specified, then all selected items are  removed  from
3257                     the  selection.   A <Selection> event is generated if any
3258                     items were removed from the selection.
3259
3260              pathName selection count
3261                     Returns an integer indicating the number of items in  the
3262                     treectrl that are currently selected.
3263
3264              pathName selection get ?first? ?last?
3265                     When  no additional arguments are given, the result is an
3266                     unsorted list containing the item ids of all of the items
3267                     in  the  treectrl  that are currently selected.  If there
3268                     are no items selected in  the  treectrl,  then  an  empty
3269                     string  is  returned.   The  optional arguments first and
3270                     last are treated as  indices  into  the  sorted  list  of
3271                     selected items; these arguments allow in-place lindex and
3272                     lrange operations on the selection. For example:
3273
3274
3275
3276              pathName selection includes itemDesc
3277                     Returns 1 if the item described by itemDesc is  currently
3278                     selected, 0 if it isn't.
3279
3280              pathName selection modify select deselect
3281                     Both  arguments  select and deselect are a possibly-empty
3282                     list of  item  descriptions.   Any  unselected  items  in
3283                     select are added to the selection, and any selected items
3284                     in deselect are removed from the  selection  (except  for
3285                     those  items  which  are  also in select).  A <Selection>
3286                     event is generated if any items were  selected  or  dese‐
3287                     lected.
3288
3289       pathName state option args
3290              This command is used to manipulate the list of user-defined item
3291              states, see section STATES below.  Item states can also be  man‐
3292              aged using the item state command.  To manage states for header-
3293              rows, use the header state widget command.  The  exact  behavior
3294              of  the  command depends on the option argument that follows the
3295              state argument.  The following forms of  the  command  are  sup‐
3296              ported:
3297
3298              pathName state define stateName
3299                     Defines  a  new state with the name stateName, which must
3300                     not be the name of an existing state.
3301
3302              pathName state linkage stateName
3303                     Returns a string indicating whether the  specified  state
3304                     is  user-defined by means of the state define widget com‐
3305                     mand (dynamic)  or  predefined  by  the  treectrl  widget
3306                     itself (static).
3307
3308              pathName state names
3309                     Returns  a  list containing the names of all user-defined
3310                     states.
3311
3312              pathName state undefine ?stateName ...?
3313                     Every stateName must be the name of a user-defined state.
3314                     Removes this state from the list of user-defined states.
3315
3316       pathName style option ?element? ?arg arg ...?
3317              This  command is used to manipulate styles, which can be thought
3318              of as a geometry manager for elements.  The  exact  behavior  of
3319              the  command  depends  on  the  option argument that follows the
3320              style argument.  The following forms of  the  command  are  sup‐
3321              ported:
3322
3323              pathName style cget style option
3324                     This  command  returns  the  current  value of the option
3325                     named option associated with the style  given  by  style.
3326                     Option  may  have any of the values accepted by the style
3327                     configure widget command.
3328
3329                     This command also accepts the -statedomain option.
3330
3331              pathName style configure style ?option?  ?value?  ?option  value
3332              ...?
3333                     This  command  is similar to the configure widget command
3334                     except that it modifies options associated with the style
3335                     given by style instead of modifying options for the over‐
3336                     all treectrl widget.  If no option is specified, the com‐
3337                     mand  returns  a  list  describing  all  of the available
3338                     options for style (see Tk_ConfigureInfo  for  information
3339                     on the format of this list).  If option is specified with
3340                     no value, then the command returns a list describing  the
3341                     one named option (this list will be identical to the cor‐
3342                     responding sublist of the value returned if no option  is
3343                     specified).  If one or more option-value pairs are speci‐
3344                     fied, then the command modifies the  given  option(s)  to
3345                     have  the  given value(s) in style; in this case the com‐
3346                     mand returns an empty string.
3347
3348                     The following options are supported:
3349
3350                     -buttony offset
3351                            Specifies the distance from the top  of  the  item
3352                            that  the  expand/collapse button should be drawn.
3353                            If offset is an empty string  (the  default)  then
3354                            the  button  is  centered  vertically in the item.
3355                            The value may have any of the forms acceptable  to
3356                            Tk_GetPixels.   This  option  only has effect when
3357                            the style is set in an item in the tree column.
3358
3359                     -orient varName
3360                            This option specifies which orientation should  be
3361                            used  when laying out the elements associated with
3362                            this  style.   Must  be  either  horizontal   (the
3363                            default)  or vertical or an abbreviation of one of
3364                            these.
3365
3366              pathName style create name ?option value ...?
3367                     Creates a new style with  the  unique  user-defined  name
3368                     name.  After name there may be any number of option-value
3369                     pairs, each  of  which  sets  one  of  the  configuration
3370                     options  for  the style.  See the style configure command
3371                     for the possible options.  The result of this command  is
3372                     the name of the new style (the same as the name option).
3373
3374                     This  command also accepts the -statedomain option with a
3375                     value of either header or  item  to  specify  where  this
3376                     style will be displayed.
3377
3378              pathName style delete ?style ...?
3379                     Deletes  each  of  the  named styles and returns an empty
3380                     string.  If a style is deleted while it is still used  to
3381                     display  one  or  more items, it is also removed from the
3382                     style list of these items.
3383
3384              pathName style elements style ?elementList?
3385                     Specifies the elements which should be layed out by  this
3386                     style.   Each  element of elementList must be the name of
3387                     an element created by the widget command element  create.
3388                     Duplicate  names  in elementList are ignored.  An element
3389                     which was specified in a former call of this command  for
3390                     style but is not included in elementList, will be deleted
3391                     from the elements layed out by style.
3392
3393                     Every element used by a style must have been created with
3394                     the same value for the -statedomain option.
3395
3396                     If  the  elementList argument is not specified, a list is
3397                     returned containing the  currently  defined  elements  of
3398                     style.
3399
3400              pathName  style  layout  style  element ?option? ?value? ?option
3401              value ...?
3402                     This command is similar to the configure  widget  command
3403                     except  that it modifies options used by style for laying
3404                     out element instead of modifying options for the  overall
3405                     treectrl  widget.  If no option is specified, the command
3406                     returns a list with option-value pairs describing all  of
3407                     the available options for the layout.  If option is spec‐
3408                     ified with no value, then the command returns  the  value
3409                     of  the  named option.  If one or more option-value pairs
3410                     are  specified,  then  the  command  modifies  the  given
3411                     option(s)  to  have the given value(s) for the layout; in
3412                     this case the command returns an empty string.
3413
3414                     The options of a layout have effect on  exactly  the  one
3415                     element  element managed by style.  The following options
3416                     are supported:
3417
3418                     -detach boolean
3419                            Specifies whether the element should be positioned
3420                            by  itself,  i.e.  independent from the other ele‐
3421                            ments.  The default is false.
3422
3423                     -center flags
3424                            Flags is a string that contains zero  or  more  of
3425                            the characters x or y.  x causes the element to be
3426                            centered horizontally, y causes the element to  be
3427                            centered  vertically.   When more than one element
3428                            has -center layout, all the elements  between  the
3429                            first  and last with -center layout in the style's
3430                            list of elements are centered as  a  group.   Con‐
3431                            sider  the following when there is another element
3432                            to the right of MyElement:
3433
3434
3435                            With the first call, MyElement  will  be  centered
3436                            only  within the space that is not occupied by the
3437                            other element, so MyElement will appear off-center
3438                            towards  the  left  of the style.  With the second
3439                            call, MyElement will be centered within the  style
3440                            so long as it doesn't overlap the other element.
3441
3442                     -draw boolean
3443                            This is a per-state option that determines whether
3444                            an element should be drawn. If the  value  of  the
3445                            option  evaluates to false for a given item state,
3446                            then the element is not drawn, although  it  still
3447                            consumes space in the layout.
3448
3449                     -expand flags
3450                            This option allows the external padding around the
3451                            element to increase when a style has  more  screen
3452                            space  than it needs.  Flags is a string that con‐
3453                            tains zero or more of the characters n, s, w or e.
3454                            Each letter refers to the padding on the top, bot‐
3455                            tom, left, or right  that  should  be  allowed  to
3456                            increase.   This  option is typically used to jus‐
3457                            tify an element.  The default is an empty string.
3458
3459                     -iexpand flags
3460                            This option allows the  internal  padding  of  the
3461                            element  and  the  display  area of the element to
3462                            increase when a style has more screen  space  than
3463                            it  needs.   Flags  is a string that contains zero
3464                            or more of the characters x, y, n, s, w or e.  For
3465                            n,  s,  w and e, each letter refers to the padding
3466                            on the top, bottom, left, or right that should  be
3467                            allowed  to  increase.   For  x and y, each letter
3468                            refers to the horizontal and vertical screen space
3469                            the element can display itself in (i.e., the space
3470                            between the padding).  Note  that  if  the  -union
3471                            option  is  specified for this element, then the x
3472                            and y flags have no effect, since the size  of  an
3473                            element  with  -union  layout is determined by the
3474                            elements it surrounds.  The default  is  an  empty
3475                            string.
3476
3477                     -indent boolean
3478                            For item styles, this option specifies whether the
3479                            element should be positioned to the right  of  the
3480                            button/line  area in the tree column.  When false,
3481                            the element is displayed beneath the  buttons  and
3482                            lines  in  the tree column. This option is ignored
3483                            unless the -detach option is true.
3484
3485                            For header styles, this option  specifies  whether
3486                            the  element  should be positioned to the right of
3487                            the -canvaspadx padding.  This option  is  ignored
3488                            unless  the  -detach  option is true or the -union
3489                            option is specified.
3490
3491                            The default is true.
3492
3493                     -ipadx amount
3494
3495                     -ipady amount
3496                            Amount specifies  how  much  internal  padding  to
3497                            leave  on  the  left and right (for -ipadx) or top
3498                            and bottom (for  -ipady)  sides  of  the  element.
3499                            Amount may be a list of two values to specify pad‐
3500                            ding for the two sides  separately.   The  default
3501                            value  is  0.   This option is typically used with
3502                            the -union layout option, to create  space  around
3503                            the enclosed elements.
3504
3505                     -minheight pixels
3506
3507                     -height pixels
3508
3509                     -maxheight pixels
3510                            Specifies  the  minimum, fixed, and maximum height
3511                            of the display area of the element.   The  default
3512                            is unspecified.
3513
3514                     -minwidth pixels
3515
3516                     -width pixels
3517
3518                     -maxwidth pixels
3519                            Specifies the minimum, fixed, and maximum width of
3520                            the display area of the element.  The  default  is
3521                            unspecified.
3522
3523                     -padx amount
3524
3525                     -pady amount
3526                            Amount  specifies  how  much  external  padding to
3527                            leave on the left and right (for -padx) or top and
3528                            bottom  (for  -pady)  sides of the element. Amount
3529                            may be a list of two values to specify padding for
3530                            the two sides separately.  The default value is 0.
3531
3532                     -squeeze flags
3533                            This  option allows the display area of an element
3534                            to decrease when a style has less  space  than  it
3535                            needs.   Flags  is  a string that contains zero or
3536                            more of the characters x or y.  x  allows  display
3537                            area  to  decrease  horizontally, y allows display
3538                            area to decrease vertically.  This option is typi‐
3539                            cally  used  for  text elements and will cause the
3540                            text element to display an ellipsis  (...)  and/or
3541                            wrap lines.  The default is an empty string.
3542
3543                     -sticky flags
3544                            This option controls how the actual display infor‐
3545                            mation (image, text, etc) of an element  is  posi‐
3546                            tioned  (or  stretched)  within  its display area.
3547                            Flags is a string that contains zero  or  more  of
3548                            the characters n, s, w or e. Each letter refers to
3549                            the top, bottom, left or right side of the display
3550                            area  that  the display information should "stick"
3551                            to.  The default is nswe.
3552
3553                     -union elementList
3554                            Specifies a list of other elements which this ele‐
3555                            ment  will  surround.  The size of an element with
3556                            -union layout is determined by the size and  posi‐
3557                            tion  of  the elements in elementList.  The -ipadx
3558                            and -ipady options in this case refer to the  dis‐
3559                            tance  of  the  edges  of the display area of this
3560                            element from those  elements  it  surrounds.  This
3561                            option  is  typically  used to display a selection
3562                            rectangle around a piece of text. If none  of  the
3563                            elements in elementList are visible, then the ele‐
3564                            ment is not displayed.
3565
3566                     -visible boolean
3567                            This is a per-state option that controls  visibil‐
3568                            ity  of  an  element.  If  the value of the option
3569                            evaluates to false for a given  item  state,  then
3570                            the element is not displayed and consumes no space
3571                            in the layout.
3572
3573              pathName style names
3574                     Returns a list  containing  the  names  of  all  existing
3575                     styles.
3576
3577       pathName theme option ?arg ...?
3578              This  command  is  used  to  interact with the platform-specific
3579              theme.  The exact behavior of the command depends on the  option
3580              argument  that  follows the theme argument.  The following forms
3581              of the command are supported:
3582
3583              pathName theme platform
3584                     Returns the API used to draw themed parts of  the  treec‐
3585                     trl.   On Mac OS X the result is always aqua.  On MS Win‐
3586                     dows the result is visualstyles if  the  uxtheme.dll  was
3587                     loaded  and  visual  themes  are in use, otherwise X11 is
3588                     returned to indicate the Tk Xlib calls  are  drawing  the
3589                     themed  parts.   On Unix systems the result is gtk if the
3590                     Gtk+ version of treectrl  was  built,  otherwise  X11  is
3591                     returned.
3592
3593              pathName theme setwindowtheme appname
3594                     The  command is available on MS Windows only.  If appname
3595                     is "Explorer" then the item buttons look  like  those  in
3596                     the  Explorer  file  browser  (disclosure triangles under
3597                     Windows Vista/7).  If appname is an empty string then the
3598                     buttons  revert  to their default appearance according to
3599                     the system's current visual style.
3600
3601       pathName toggle ?-recurse? ?itemDesc ...?
3602              Use item toggle instead.
3603
3604       pathName xview ?args?
3605              This command is used to query and change the horizontal position
3606              of  the  information displayed in the treectrl's window.  It can
3607              take any of the following forms:
3608
3609              pathName xview
3610                     Returns a list containing two elements.  Each element  is
3611                     a  real fraction between 0 and 1;  together they describe
3612                     the horizontal span that is visible in the  window.   For
3613                     example,  if  the first element is .2 and the second ele‐
3614                     ment is .6, 20% of the tree's area is off-screen  to  the
3615                     left, the middle 40% is visible in the window, and 40% of
3616                     the tree is off-screen to the right.  These are the  same
3617                     values  passed  to  scrollbars  via  the  -xscrollcommand
3618                     option.
3619
3620              pathName xview moveto fraction
3621                     Adjusts the view in the window so that  fraction  of  the
3622                     total width of the tree is off-screen to the left.  Frac‐
3623                     tion must be a fraction between 0 and  1.   A  <Scroll-x>
3624                     event is generated.
3625
3626              pathName xview scroll number what
3627                     This  command shifts the view in the window left or right
3628                     according to number and what.  Number must be an integer.
3629                     What  must be either units or pages or an abbreviation of
3630                     one of these.  If what is units, the view adjusts left or
3631                     right in units determined by the -xscrollincrement option
3632                     (which may be zero, see the description of that  option).
3633                     If  what is pages then the view adjusts in units of nine-
3634                     tenths the window's width.  If number  is  negative  then
3635                     information  farther  to the left becomes visible;  if it
3636                     is positive then information farther to the right becomes
3637                     visible.  A <Scroll-x> event is generated.
3638
3639       pathName yview ?args?
3640              This  command  is used to query and change the vertical position
3641              of the information displayed in the treectrl's window.   It  can
3642              take any of the following forms:
3643
3644              pathName yview
3645                     Returns  a list containing two elements.  Each element is
3646                     a real fraction between 0 and 1;  together they  describe
3647                     the  vertical  span  that  is visible in the window.  For
3648                     example, if the first element is .6 and the  second  ele‐
3649                     ment is 1.0, the lowest 40% of the tree's area is visible
3650                     in the window.  These  are  the  same  values  passed  to
3651                     scrollbars via the -yscrollcommand option.
3652
3653              pathName yview moveto fraction
3654                     Adjusts  the  view  in the window so that fraction of the
3655                     tree's area is off-screen to  the  top.   Fraction  is  a
3656                     fraction  between  0 and 1.  A <Scroll-y> event is gener‐
3657                     ated.
3658
3659              pathName yview scroll number what
3660                     This command adjusts the view in the window  up  or  down
3661                     according to number and what.  Number must be an integer.
3662                     What must be either units or pages.  If  what  is  units,
3663                     the   view   adjusts   up   or   down  in  units  of  the
3664                     -yscrollincrement option (which  may  be  zero,  see  the
3665                     description  of  that option).  If what is pages then the
3666                     view adjusts in units of nine-tenths the window's height.
3667                     If  number  is  negative  then higher information becomes
3668                     visible;   if  it  is  positive  then  lower  information
3669                     becomes visible.  A <Scroll-y> event is generated.
3670

HEADERS

3672       A  treectrl  widget  can  display  zero or more rows of column headers.
3673       When a treectrl widget is created, a single row of column headers  (aka
3674       a  header-row)  is  created  as  well;  this  top  header-row cannot be
3675       deleted.  Additional header-rows can be created with the header  create
3676       command and deleted with header delete.
3677
3678       There  are no commands for changing the order of header-rows;  they are
3679       displayed from top to bottom in the order they were created.
3680
3681       Drag-and-drop reordering of column headers is supported within  a  wid‐
3682       get.   To  control column header drag-and-drop, use the header dragcon‐
3683       figure command.
3684
3685       Header-rows in a treectrl may be specified in a number  of  ways.   See
3686       HEADER DESCRIPTION below.
3687
3688       The  appearance of individual column headers within a header-row may be
3689       customized in two different ways:
3690
3691       [1]    By configuring various column header  options  with  the  header
3692              configure command
3693
3694       [2]    By  assigning  a  style to a column header with the header style
3695              command.
3696
3697       When one of the options below is  specified  as  per-state,  the  state
3698       names  are  those described in STATES for headers only, i.e. do not use
3699       item state names.
3700
3701       The following options are supported for each individual column header:
3702
3703       -arrow direction
3704              Indicates whether or not a sort arrow should  be  drawn  in  the
3705              column  header.  Direction must have one of the values none (the
3706              default), up, or down.
3707
3708       -arrowbitmap bitmap
3709              Specifies as a per-state option the name of a bitmap to  use  to
3710              draw the arrow if this column's -arrow option is not none.
3711
3712       -arrowgravity direction
3713              Indicates  onto  which  side the sort arrow should be packed, if
3714              there is more space available for drawing the arrow then needed.
3715              direction must be either left (the default) or right.
3716
3717       -arrowimage image
3718              Specifies  as  a per-state option the name of an image to use to
3719              draw the sort arrow if this column's -arrow option is not  none.
3720              If  an  image is specified for a certain state, it overrides the
3721              -arrowbitmap option.
3722
3723       -arrowpadx amount
3724              Amount specifies how much padding to leave on the left and right
3725              of  the sort arrow.  Amount may be a list of two values to spec‐
3726              ify padding for left and right separately; it defaults to 6.
3727
3728       -arrowpady amount
3729              Amount specifies how much padding to leave on the top and bottom
3730              of  the sort arrow.  Amount may be a list of two values to spec‐
3731              ify padding for top and bottom separately; it defaults to 0.
3732
3733       -arrowside side
3734              Indicates on which side of the bitmap/image/text the sort  arrow
3735              should  be  drawn.   Side  must  be  either  left  or right (the
3736              default).
3737
3738       -bitmap bitmap
3739              Specifies the name of a bitmap to display to  the  left  of  the
3740              column title.
3741
3742       -background color
3743              Specifies  as  a per-state option the color to use for the back‐
3744              ground of the column header.
3745
3746       -borderwidth size
3747              Specifies a non-negative value indicating the width of  the  3-D
3748              border  to draw around the outside of the column header (if such
3749              a border is being drawn;  the -relief column  option  determines
3750              this).   The  value  may  have  any  of  the forms acceptable to
3751              Tk_GetPixels.
3752
3753       -button boolean
3754              Indicates whether or not the column  header  should  be  treated
3755              like  a pushbutton.  When this option is true, the default bind‐
3756              ings track <Button-1>  events  in  the  header  and  generate  a
3757              <Header-invoke>  event  when a <ButtonRelease-1> event occurs in
3758              the header. See DYNAMIC EVENTS.
3759
3760       -font fontName
3761              Specifies the font to use for displaying the column title inside
3762              the  column  header.   When the value of this option is unspeci‐
3763              fied, the font specified by the  widget  option  -headerfont  is
3764              used.
3765
3766       -image image
3767              Specifies  the  name  of  an image to display to the left of the
3768              column title.  This option overrides the -bitmap column option.
3769
3770       -imagepadx amount
3771              Amount specifies how much padding to leave on the left and right
3772              of the image (or bitmap).  Amount may be a list of two values to
3773              specify padding for left and right separately; it defaults to 6.
3774
3775       -imagepady amount
3776              Amount specifies how much padding to leave on the top and bottom
3777              of the image (or bitmap).  Amount may be a list of two values to
3778              specify padding for top and bottom separately; it defaults to 0.
3779
3780       -justify justification
3781              This option determines how the image  and  text  in  the  column
3782              header  are positioned.  Must be one of left (the default), cen‐
3783              ter, or right.
3784
3785       -state state
3786              Specifies one of three states for  the  column  header:  normal,
3787              active,  or  pressed. The active state is used when the mouse is
3788              over the header.  The pressed state is used when the mouse  but‐
3789              ton is pressed in the header.
3790
3791              Changing  the  value of this option also affects the current set
3792              of header states for the column header, which  may  affect  both
3793              the  per-state  options  mentioned here (such as -arrowimage) as
3794              well as the elements in any style that may be  assigned  to  the
3795              column header.
3796
3797       -text text
3798              Specifies a text string to be displayed as the column title.
3799
3800       -textcolor color
3801              Specifies  as a per-state option the color to display the column
3802              title with.  When the value of this option is  unspecified,  the
3803              title will be drawn according to the system theme color, if any,
3804              otherwise the widget  option  -headerforeground  is  used.   The
3805              default is unspecified.
3806
3807       -textlines count
3808              Specifies  the maximum number of lines of text to display in the
3809              column title.  If this value is zero, the number of  lines  dis‐
3810              played  is  determined by any newline characters and the effects
3811              of wrapping when the column  width  is  less  than  needed.  The
3812              default is 1. Note: Under OSX/Aqua this value is always set to 1
3813              when the  treectrl's  -usetheme  option  is  true,  because  the
3814              Appearance  Manager  uses  a fixed height for the column header;
3815              there is only room for a single line of text.
3816
3817       -textpadx amount
3818              Amount specifies how much padding to leave on the left and right
3819              of the text.  Amount may be a list of two values to specify pad‐
3820              ding for left and right separately; it defaults to 6.
3821
3822       -textpady amount
3823              Amount specifies how much padding to leave on the top and bottom
3824              of the text.  Amount may be a list of two values to specify pad‐
3825              ding for top and bottom separately; it defaults to 0.
3826

HEADER DESCRIPTION

3828       Many of the commands for a treectrl take as an argument  a  description
3829       of  which  header-rows  to operate on.  A header description is a prop‐
3830       erly-formed tcl list of keywords and arguments. The  first  word  of  a
3831       header description must be one of the following:
3832
3833       id     Specifies a unique header-row identifier, where id should be the
3834              return value of a prior call of the header  create  widget  com‐
3835              mand, or 0 to specify the ever-present top header-row.
3836
3837       QUALIFIERS
3838              Specifies  a  list  of qualifiers. This gives the same result as
3839              all followed by QUALIFIERS; i.e., every header-row is tested for
3840              a match.
3841
3842       tagExpr QUALIFIERS
3843              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
3844              which every header-row's tags are tested for a match.   You  may
3845              run  into trouble if tagExpr looks like a header-row id or other
3846              keyword; also, tagExpr must look  like  a  single  list  element
3847              since  header-row  descriptions are properly-formed lists. To be
3848              safe you may want to use the tag qualifier followed by tagExpr.
3849
3850
3851
3852       all QUALIFIERS
3853              Matches every header-row which satisfies QUALIFIERS.
3854
3855       first QUALIFIERS
3856              Indicates the top header-row  of  the  treectrl,  or  the  first
3857              header-row starting from the top that satisfies QUALIFIERS.
3858
3859       end QUALIFIERS
3860
3861       last QUALIFIERS
3862              Indicates the last header-row which satisfies QUALIFIERS.
3863
3864       The  word  QUALIFIERS  above represents a series of zero or more of the
3865       following terms that changes which header-row is chosen:
3866
3867       tag tagExpr
3868              TagExpr is a tag expression (see ITEM AND COLUMN  TAGS)  against
3869              which a header-row's tags are tested for a match.
3870
3871       visible
3872              When  this  qualifier  is  given, only header-rows that are dis‐
3873              played are matched.  A header-row is displayed only if both  the
3874              -showheader  widget  option  and  -visible header-row option are
3875              true.  Also, if only the tail column is  visible,  then  header-
3876              rows are not displayed.
3877
3878       !visible
3879              When  this  qualifier  is given, only header-rows that are *not*
3880              displayed are matched.
3881

COLUMNS

3883       A treectrl widget is capable of displaying  multiple  columns  next  to
3884       each other.  An item can be considered as a row, which reaches over all
3885       columns.
3886
3887       Columns in a treectrl may be specified in a number of ways.  See COLUMN
3888       DESCRIPTION below.
3889
3890       There  is  always  one special column, the tail column, which fills all
3891       space to the right of the last ordinary column.   This  column  has  no
3892       unique ID; it can only be specified by the keyword tail.
3893
3894       For  compatibility  with older versions of treectrl (which did not sup‐
3895       port more than one row of column  headers)  any  of  the  configuration
3896       options  mentioned  in the HEADERS section, such as -arrow, -text, etc,
3897       may be passed to the top header-row through the column  configure  com‐
3898       mand and queried with the column cget command.
3899
3900       The following options are supported for columns:
3901
3902       -expand boolean
3903              Indicates  whether  or  not any extra horizontal space should be
3904              distributed to this column.  This option has no  effect  if  the
3905              -width option is set.
3906
3907       -gridleftcolor color
3908
3909       -gridrightcolor color
3910              Specifies  the  color of the lines drawn down the left and right
3911              edges of the column.  These so-called  "grid  lines"  are  drawn
3912              over the elements of each item style in the column and down into
3913              the whitespace region below any items.  The  default  value  for
3914              each option is an empty string meaning no lines are drawn.
3915
3916       -itembackground colorList
3917              Specifies  a  list  of  zero  or  more colors, which are used as
3918              alternating background colors for items  in  this  column.   See
3919              also the -backgroundmode widget option for more on this.
3920
3921       -itemjustify justification
3922              This  option  determines  how the item styles in this column are
3923              aligned horizontally.  Must be one of left,  center,  or  right.
3924              The  default  value  is  an empty string (for compatibility with
3925              older versions), in which case the  column  option  -justify  is
3926              used to align item styles in this column.
3927
3928       -itemstyle style
3929              Style  is  the name of a style that should be set in this column
3930              for newly-created items.
3931
3932       -justify justification
3933              This option determines  how  item  styles  in  this  column  are
3934              aligned horizontally unless overriden by the -itemjustify option
3935              for this column.  Must be one of left (the default), center,  or
3936              right.
3937
3938              For compatibility with older versions of treectrl (which did not
3939              allow multiple rows of column headers), changing  the  value  of
3940              this  option  also  changes  the  -justify  option of the column
3941              header in the top header-row.
3942
3943       -lock lock
3944              This option allows a column to stick to the left or  right  edge
3945              of the window.  A locked column scrolls vertically but not hori‐
3946              zontally.  Must be one of none (the default), left, or right.
3947
3948       -maxwidth size
3949              Specifies the maximum size, in screen units, that will  be  per‐
3950              mitted  for this column.  If size is an empty string, then there
3951              is no limit on the maximum size of the column.  This option  has
3952              no effect if the -width option is set.
3953
3954       -minwidth size
3955              Specifies  the  minimum size, in screen units, that will be per‐
3956              mitted for this column.  If size is an empty  string,  then  the
3957              minimum  size  of the column is zero.  This option has no effect
3958              if the -width option is set.
3959
3960       -resize boolean
3961              Specifies a boolean value that indicates whether the user should
3962              be allowed to resize the column by dragging the edge of the col‐
3963              umn's header. Default is true.
3964
3965       -squeeze boolean
3966              Specifies a boolean value that indicates whether or not the col‐
3967              umn should shrink when the content width of the treectrl is less
3968              than the total needed width of all visible columns. Defaults  to
3969              false,  which  means  the  column  will not get smaller than its
3970              needed width. The column will not get smaller than the value  of
3971              its -minwidth option, if specified. This option has no effect if
3972              the -width option is set.
3973
3974       -stepwidth size
3975              Deprecated.  Use  the   treectrl's   -itemwidthmultiple   option
3976              instead.
3977
3978       -tags tagList
3979              TagList  is a list of tag names that can be used to identify the
3980              column.  See also the column tag command.
3981
3982       -uniform group
3983              When a non-empty value is supplied, this option places the  col‐
3984              umn  in  a  uniform  group with other columns that have the same
3985              value for -uniform. The space for columns belonging to a uniform
3986              group is allocated so that their sizes are always in strict pro‐
3987              portion to their -weight values.  This option is  based  on  the
3988              grid geometry manager.
3989
3990       -visible boolean
3991              Indicates whether or not the column should be displayed.
3992
3993       -weight integer
3994              Sets  the relative weight for apportioning any extra space among
3995              columns.  A weight of zero (0) indicates  the  column  will  not
3996              deviate  from  its requested size.  A column whose weight is two
3997              will grow at twice the rate as a column of weight one when extra
3998              space is allocated to columns.  This option is based on the grid
3999              geometry manager.
4000
4001       -width size
4002              Specifies a fixed width for the column.  If  this  value  is  an
4003              empty string, then the column width is calculated as the maximum
4004              of: a) the width requested by items; b) the width  requested  by
4005              the column's header; and c) the column's -minwidth option.  This
4006              calculated width is also  affected  by  the  -expand,  -squeeze,
4007              -uniform  and -weight options. In any case, the calculated width
4008              will not be greater than the -maxwidth option, if specified.
4009
4010       -widthhack boolean
4011              Deprecated. Use the treectrl's -itemwidthequal option instead.
4012

COLUMN DESCRIPTION

4014       Many of the commands and options for a treectrl take as an  argument  a
4015       description  of  which  column to operate on.  See the EXAMPLES section
4016       for examples.  The initial part of a column description must begin with
4017       one of the following terms:
4018
4019       id     Specifies  the  unique column identifier, where id should be the
4020              return value of a prior call of the column  create  widget  com‐
4021              mand.  See also the -columnprefix option.
4022
4023       QUALIFIERS
4024              Specifies  a  list  of qualifiers. This gives the same result as
4025              all followed by QUALIFIERS; i.e., every column is tested  for  a
4026              match.
4027
4028       tagExpr QUALIFIERS
4029              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
4030              which every column's tags are tested for a match.  This  keyword
4031              cannot  be  followed  by any modifiers unless a single column is
4032              matched. You may run into trouble if tagExpr looks like a column
4033              id  or other keyword; also, tagExpr must look like a single list
4034              element since column descriptions are properly-formed lists.  To
4035              be  safe  you may want to use the tag qualifier followed by tag‐
4036              Expr.
4037
4038       all QUALIFIERS
4039              Indicates every column, including the tail column if the command
4040              allows it, which match QUALIFIERS.
4041
4042       first QUALIFIERS
4043              Indicates  the  leftmost  column  of  the treectrl which matches
4044              QUALIFIERS.
4045
4046       end QUALIFIERS
4047
4048       last QUALIFIERS
4049              Indicates the rightmost column of the treectrl (but not the tail
4050              column) which matches QUALIFIERS.
4051
4052       list columnDescs
4053              ColumnDescs  is  a  list (a single argument, i.e. "list {a b c}"
4054              not "list a b c") of other column  descriptions.   This  keyword
4055              cannot  be  followed  by any modifiers unless a single column is
4056              matched.
4057
4058       order n QUALIFIERS
4059              Indicates the nth column in the list of columns as  returned  by
4060              the column order command.
4061
4062       range first last QUALIFIERS
4063              First  and last specify a range of columns.  This keyword cannot
4064              be followed by any modifiers unless a single  column  is  speci‐
4065              fied.
4066
4067       tail   Indicates the ever-present tail column of the treectrl.
4068
4069       tree   Indicates  the column specified by the -treecolumn option of the
4070              treectrl.
4071
4072       The initial part of the column description (matching any of the  values
4073       above)  may  be  followed by one or more modifiers.  A modifier changes
4074       the column used relative to the description up to this point.   It  may
4075       be specified in any of the following forms:
4076
4077       next QUALIFIERS
4078              Use the column to the right matching QUALIFIERS.
4079
4080       prev QUALIFIERS
4081              Use the column to the left matching QUALIFIERS.
4082
4083       span N QUALIFIERS
4084              Starting  with (and counting) the single column specified by the
4085              column description so far, walk at most  N  columns  rightwards,
4086              stopping if any of the following conditions is met:
4087
4088              [1]    A column does not match QUALIFIERS.
4089
4090              [2]    A column's -lock option does not match the first column's
4091                     -lock option.
4092
4093       The word QUALIFIERS above represents a sequence of zero or more of  the
4094       following terms that changes which column is chosen:
4095
4096       tag tagExpr
4097              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
4098              which a column's tags are tested for a match.
4099
4100       !tail  When this qualifier is given, the tail column is not matched.
4101
4102       visible
4103              When this qualifier is given, only columns whose -visible option
4104              is TRUE are considered.
4105
4106       !visible
4107              When this qualifier is given, only columns whose -visible option
4108              is FALSE are considered.
4109

STATES

4111       For every column header and every item a set of boolean states is  man‐
4112       aged.   These states play an integral role in the appearance of headers
4113       and items; that role is described in detail in PER-STATE OPTIONS.   The
4114       set  of  states available to headers is separate from the set of states
4115       available to items.
4116
4117       HEADER STATES
4118              The following states are predefined for every column header:
4119
4120              active
4121
4122              normal
4123
4124              pressed
4125                     These states mirror the value of a column  header's  con‐
4126                     figuration option -state.  Exactly one of these states is
4127                     set at any time in each column header.
4128
4129              down
4130
4131              up     These states mirror the value of a column  header's  con‐
4132                     figuration  option -arrow.  If the -arrow option is none,
4133                     then neither of these states is set.
4134
4135              background
4136                     This state is set for every header-row  if  the  toplevel
4137                     window  containing  the  treectrl  is  not the foreground
4138                     active window.  This state cannot be modified by means of
4139                     a  widget  command,  but is maintained in reaction to the
4140                     <Activate> and <Deactivate> windowing system events.
4141
4142              focus  This state is set for every header-row  if  the  treectrl
4143                     widget  currently has the focus. It cannot be modified by
4144                     means of a widget command, but is maintained in  reaction
4145                     to the <FocusIn> and <FocusOut> windowing system events.
4146
4147       ITEM STATES
4148              The following states are predefined for every item:
4149
4150              active At  all times this state is set for exactly one item. The
4151                     active item is used with keyboard navigation.   When  the
4152                     treectrl  widget  is  created  or when the active item is
4153                     deleted, the root item will become the active item.  This
4154                     state  can  be  modified  by  means of the widget command
4155                     activate.
4156
4157              enabled
4158                     This state is set for every  item  when  it  is  created.
4159                     Disabled  items cannot be selected and are ignored by the
4160                     default bindings when navigating via the keyboard.   This
4161                     state can be modified by means of the widget command item
4162                     enabled.
4163
4164              focus  This state is set for every item if the  treectrl  widget
4165                     currently  has the focus.  It cannot be modified by means
4166                     of a widget command, but is maintained in reaction to the
4167                     <FocusIn> and <FocusOut> events.
4168
4169              open   If this state is switched on, the descendants of the item
4170                     are displayed - the item is expanded.  If this  state  is
4171                     switched  off,  the  descendants of the item are not dis‐
4172                     played - the item is collapsed.   For  a  new  item  this
4173                     state is switched on by default.  This state can be modi‐
4174                     fied by means of the widget commands  item  expand,  item
4175                     collapse, or item toggle.
4176
4177              selected
4178                     This  state  is set for every item included in the selec‐
4179                     tion.  It can be modified by means of the widget  command
4180                     selection.
4181
4182       By means of the state define widget command, up to 27 additional states
4183       can be defined.
4184

PER-STATE OPTIONS

4186       The visual appearance of an item can change depending on the state  the
4187       item is in, such as being the active item, being included in the selec‐
4188       tion, being collapsed, or some combination of those  or  other  states.
4189       When  a  configuration  option  is described as per-state, it means the
4190       option describes a value which varies depending on  the  state  of  the
4191       item.  If  a per-state option is specified as a single value, the value
4192       is used for all states. Otherwise the per-state option must  be  speci‐
4193       fied  as  an even-numbered list. For example, to use the font "Times 12
4194       bold" in a text element regardless of the item state you can write:
4195
4196       $T element configure MyTextElement -font {{Times 12 bold}}
4197
4198       However, to use a different font when the item is  selected  you  could
4199       write:
4200
4201       $T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}
4202
4203       In  the  example  above,  the -font option reads "value stateList value
4204       stateList".  If stateList is an empty list, the preceding value is used
4205       regardless of the item state. A non-empty stateList specifies a list of
4206       states which must be set for the item in order  to  use  the  preceding
4207       value.  Each  stateList  can  also  include state names preceded by a !
4208       sign, indicating the state must *not* be set for the item. For example:
4209
4210       $T element configure MyRectElement -fill {blue {selected focus} gray {selected !focus}}
4211
4212       In the example above, the rect element is filled  with  blue  when  the
4213       treectrl  has  the focus and the item is selected. If the treectrl does
4214       not have the focus, the example specifies that gray should be used  for
4215       selected items. Also note that if the item is not selected, no color is
4216       specified for the -fill option.
4217
4218       Each value-stateList pair is checked in order from left to  right.  The
4219       value associated with the first stateList that matches the current item
4220       state is used. So stateLists should be  listed  from  most-specific  to
4221       least-specific.
4222
4223       $T element configure MyRectElement -fill {gray {selected} blue {selected focus}}
4224
4225       Written  this way, gray will always be used for selected items since it
4226       appears first, and blue will never be used for selected  items  regard‐
4227       less of the focus.
4228
4229       A  value  followed by an empty stateList should always be last since it
4230       will be chosen regardless of the item's state.
4231

ELEMENTS AND STYLES

4233       Elements and styles are the core visual building blocks that  determine
4234       the  appearance  of  items (and optionally column headers).  An element
4235       can be of type bitmap, border, header, image,  rect,  text  or  window.
4236       One  or more elements can be assigned to a style which manages the lay‐
4237       out of those elements.  It may be helpful to think of an element  as  a
4238       Tk  widget  and  a style as a Tk geometry manager such as grid, pack or
4239       place.
4240
4241       When an element is created by the element create command, that  element
4242       is referred to as a master element.  Similarly, a style that is created
4243       by style create is called a master  style.   When  a  master  style  is
4244       assigned  to  a  column of an item by the item style set command, a new
4245       instance style is allocated which refers back to the master  style  and
4246       its  master elements.  In this way, a single master style may be shared
4247       by multiple columns of multiple items.  If a master element  or  master
4248       style  is  modified,  those changes affect all the items whose instance
4249       styles and elements refer to those masters.
4250
4251       Although you probably want the font and selection-rectangle  colors  to
4252       be  shared  by all items, you most likely don't want the text to be the
4253       same for every column of every item.  The item element  configure  com‐
4254       mand  can  be used to override a master element's configuration options
4255       for a specific column of an item.  When you call item element configure
4256       (or  item  text or item image), a new instance element is allocated, if
4257       one wasn't already, and that instance element's options  will  override
4258       the master element's.
4259
4260       All  of  the element configuration options described below are unspeci‐
4261       fied by default, meaning that no value whatsoever has been given to the
4262       option.   It  may  seem  strange  to you that a boolean option would be
4263       unspecified instead of simply "true" or "false". The reason for this is
4264       that  when  an  instance element used by an item has no value specified
4265       for an option, that instance element refers to the master  element  for
4266       the  value  of  that  option.  This allows items which are displaying a
4267       certain element to be redisplayed when  the  master  element's  options
4268       change.   The benefits of this are that you don't need to configure the
4269       font or text color for every item in a  treectrl  individually,  saving
4270       CPU cycles and memory.
4271
4272       You  may  be thinking that to change the color of a selection rectangle
4273       you would call item element configure when an item  was  selected,  but
4274       that  is  not usually the case.  It would be wasteful to allocate a new
4275       instance element for a selection rectangle just because an item  became
4276       selected.   The  solution  is  to allow the appearance of the selection
4277       rectangle master element to change based on the selected state  of  the
4278       item.  This is described in PER-STATE OPTIONS.
4279
4280       For  each  element type there is a section below describing the options
4281       which can modify an element of that type.
4282

BITMAP ELEMENT

4284       An element of type bitmap can be used to display a bitmap in  an  item.
4285       The following options are supported for bitmap elements:
4286
4287       -background color
4288              Specifies as a per-state option the color to use for each of the
4289              bitmap's '0' valued pixels.  If the value for a certain state is
4290              an empty string (the default), the bitmap is drawn transparent.
4291
4292       -bitmap bitmap
4293              Specifies  as  a  per-state  option the bitmap to display in the
4294              element.
4295
4296       -draw boolean
4297              Deprecated; use the style layout option -draw  instead.   Speci‐
4298              fies  as  a per-state option whether to draw the element. If the
4299              value for a certain state is an empty string (the  default),  it
4300              is treated as true and the element will be drawn.
4301
4302       -foreground color
4303              Specifies as a per-state option the color to use for each of the
4304              bitmap's '1' valued pixels.  If the value for a certain state is
4305              an  empty string (the default), the bitmap's foreground color is
4306              black.
4307

BORDER ELEMENT

4309       An element of type border can be used to display  a  3D  border  in  an
4310       item.  The following options are supported for border elements:
4311
4312       -background color
4313              Specifies  as  a per-state option the color to use for the back‐
4314              ground of the border.  If the value for a certain  state  is  an
4315              empty string (the default), the element will not be drawn.
4316
4317       -draw boolean
4318              Deprecated;  use  the style layout option -draw instead.  Speci‐
4319              fies as a per-state option whether to draw the element.  If  the
4320              value  for  a certain state is an empty string (the default), it
4321              is treated as true and the element will be drawn.
4322
4323       -filled boolean
4324              Specifies whether the interior of the border  should  be  filled
4325              with  the  background  color. If this option is unspecified (the
4326              default), it it treated as false which means that only the edges
4327              of the border will be drawn.
4328
4329       -height size
4330              Specifies the height of the border. If this value is unspecified
4331              (the default), the border will be exactly as tall as its display
4332              area as determined by the style layout options.
4333
4334       -relief relief
4335              Specifies as a per-state option the relief of the border. If the
4336              value for a certain state is an empty string (the  default),  it
4337              is  treated  as flat.  For acceptable values see the description
4338              of the -relief option in the options manual page.
4339
4340       -thickness thickness
4341              Specifies the thickness of the edges of the border.
4342
4343       -width size
4344              Specifies the width of the border. If this value is  unspecified
4345              (the default), the border will be exactly as wide as its display
4346              area as determined by the style layout options.
4347

HEADER ELEMENT

4349       An element of type header can be used to  display  a  themed  (or  non-
4350       themed)  column  header background and sort arrow.  Header elements are
4351       best used surrounding  other  elements  via  the  style  layout  option
4352       -union, so that the sort arrow can be displayed correctly.
4353
4354       Some  of  the options for this type of element get their default values
4355       from the header state flags that are set in the column header in  which
4356       the  element  is  displayed.  In particular, the -arrow option gets its
4357       default value by checking the up and down state flags, and  the  -state
4358       option  gets  its  default  value  by  checking the active, normal, and
4359       pressed state flags.  If elements of this type are displayed in an item
4360       instead  of  a column header, then this behavior isn't used since those
4361       state flags aren't meaningful for items.
4362
4363       The following options are supported for header elements:
4364
4365       -arrow direction
4366              Indicates whether or not a sort arrow should be drawn. Direction
4367              must  have one of the values none, up, or down.  If unspecified,
4368              the value defaults to none (but see  the  note  above  regarding
4369              header states).
4370
4371       -arrowbitmap bitmap
4372              Specifies  as  a per-state option the name of a bitmap to use to
4373              draw the sort arrow if this element's -arrow option is not none.
4374              This option is ignored when drawing themed headers on Mac OS X.
4375
4376       -arrowgravity direction
4377              Indicates  onto  which  side the sort arrow should be packed, if
4378              there is more space available for drawing the arrow than needed.
4379              Direction  must  be  either  left  or right. If unspecified, the
4380              value defaults to left.  This option  is  ignored  when  drawing
4381              themed headers on Mac OS X.
4382
4383       -arrowimage image
4384              Specifies  as  a per-state option the name of an image to use to
4385              draw the sort arrow if this element's -arrow option is not none.
4386              If  an  image is specified for a certain state, it overrides the
4387              -arrowbitmap option.  This option is ignored when drawing themed
4388              headers on Mac OS X.
4389
4390       -arrowpadx amount
4391              Amount specifies how much padding to leave on the left and right
4392              of the sort arrow. Amount may be a list of two values to specify
4393              padding  for  the left and right separately. If unspecified, the
4394              value defaults to 6.  Padding to the right of the sort arrow  is
4395              ignored when drawing themed headers on Mac OS X.
4396
4397       -arrowpady amount
4398              Amount specifies how much padding to leave on the top and bottom
4399              of the sort arrow.  Amount may be a list of two values to  spec‐
4400              ify  padding  for the top and bottom separately. If unspecified,
4401              the value defaults to 0.  This option is  ignored  when  drawing
4402              themed headers on Mac OS X.
4403
4404       -arrowside side
4405              Indicates  on which side of the element the sort arrow should be
4406              drawn.  Side must be either left or right. If  unspecified,  the
4407              value defaults to right.
4408
4409       -background color
4410              Specifies  as  a  per-state option the color to use for the non-
4411              themed background and 3D  border.   If  unspecified,  the  value
4412              defaults  to  either  the  Tk  button  widget's  -background  or
4413              -activebackground color.
4414
4415       -borderwidth size
4416              Specifies a non-negative value indicating the width of the  non-
4417              themed  3D  border to draw around the inner edges of the element
4418              (if such a border is being drawn; the -relief option  determines
4419              this).   The  value  may  have  any  of  the forms acceptable to
4420              Tk_GetPixels.  If unspecified, the value defaults to 2.
4421
4422       -state state
4423              Specifies one of three states for the element:  normal,  active,
4424              or  pressed. The active state is used when the mouse is over the
4425              header.  The pressed state is used  when  the  mouse  button  is
4426              pressed  in  the  header.  If unspecified, the value defaults to
4427              normal (but see the note above regarding header states).
4428

IMAGE ELEMENT

4430       An element of type image can be used to display an image  in  an  item.
4431       The following options are supported for image elements:
4432
4433       -draw boolean
4434              Deprecated;  use  the style layout option -draw instead.  Speci‐
4435              fies as a per-state option whether to draw the element.  If  the
4436              value  for  a certain state is an empty string (the default), it
4437              is treated as true and the element will be drawn.
4438
4439       -height size
4440              Specifies the requested height of the display area for this ele‐
4441              ment.   If  unspecified  (the  default),  the element requests a
4442              height equal to the height of the image, or zero if there is  no
4443              image.
4444
4445       -image image
4446              Specifies as a per-state option the image to display in the ele‐
4447              ment.
4448
4449       -tiled boolean
4450              Specifies a boolean indicating whether or not the  image  should
4451              be tiled horizontally and vertically within the display area for
4452              the element.  The default is false.
4453
4454       -width size
4455              Specifies the requested width of the display area for this  ele‐
4456              ment.   If  unspecified  (the  default),  the element requests a
4457              width equal to the width of the image, or zero if  there  is  no
4458              image.
4459

RECTANGLE ELEMENT

4461       An  element of type rect can be used to display a rectangle in an item.
4462       The following options are supported for rectangle elements:
4463
4464       -draw boolean
4465              Deprecated; use the style layout option -draw  instead.   Speci‐
4466              fies  as  a per-state option whether to draw the element. If the
4467              value for a certain state is an empty string (the  default),  it
4468              is treated as true and the element will be drawn.
4469
4470       -fill color
4471              Specifies as a per-state option the color to be used to fill the
4472              rectangle's area.  If the color for a certain state is an  empty
4473              string (the default), then the rectangle will not be filled (but
4474              the outline may still be drawn).
4475
4476       -height size
4477              Specifies the height of the rectangle. If this value is unspeci‐
4478              fied (the default), the rectangle will be exactly as tall as its
4479              display area as determined by the style layout options.
4480
4481       -open open
4482              Specifies as a per-state option which  edges  of  the  rectangle
4483              should  be  left open.  This option may be used to get an incom‐
4484              plete drawing of the outline and rounded corners, often to  give
4485              the  appearance of the rectangle extending over adjacent columns
4486              or items.  Open is a string that contains zero or  more  of  the
4487              characters  n, s, e or w.  Each letter refers to an edge (north,
4488              south, east, or west) on which the outline and  rounded  corners
4489              will  not  be  drawn.   The  default  is the empty string, which
4490              causes all rounded corners and the outline to be drawn.
4491
4492       -outline color
4493              Specifies as a per-state option the color to be used to draw the
4494              outline  of  the rectangle.  If the color for a certain state is
4495              an empty string (the default), then no outline is drawn for  the
4496              rectangle.
4497
4498       -outlinewidth outlineWidth
4499              Specifies  the  width of the outline to be drawn around the rec‐
4500              tangle's region.  outlineWidth  may  be  in  any  of  the  forms
4501              acceptable  to  Tk_GetPixels.  If this option is specified as an
4502              empty string (the default), then no outline is drawn.
4503
4504       -rx radius
4505
4506       -ry radius
4507              Specifies the x and y radius of each corner of a rounded rectan‐
4508              gle in any of the forms acceptable to Tk_GetPixels.
4509
4510       -showfocus boolean
4511              Specifies  a  boolean  value  indicating  whether a "focus ring"
4512              should be drawn around the rectangle, if the item containing the
4513              rectangle  is  the active item and the treectrl widget currently
4514              has the focus.  If this option is specified as an  empty  string
4515              (the default), then a focus rectangle is not drawn.
4516
4517       -width size
4518              Specifies  the width of the rectangle. If this value is unspeci‐
4519              fied (the default), the rectangle will be exactly as wide as its
4520              display area as determined by the style layout options.
4521

TEXT ELEMENT

4523       An  element of type text can be used to display a text in an item.  The
4524       following options are supported for text elements:
4525
4526       -draw boolean
4527              Deprecated; use the style layout option -draw  instead.   Speci‐
4528              fies  as  a per-state option whether to draw the element. If the
4529              value for a certain state is an empty string (the  default),  it
4530              is treated as true and the element will be drawn.
4531
4532       -data data
4533              Specifies  a  value that together with the -datatype and -format
4534              options will be displayed as text.
4535
4536       -datatype dataType
4537              Specifies the type of information in the -data option.   Accept‐
4538              able values are double, integer, long, string, or time.
4539
4540       -fill color
4541              Specifies as a per-state option the foreground color to use when
4542              displaying text.
4543
4544              In items, if the color for a certain state is  an  empty  string
4545              (the  default),  then the text will be displayed using the color
4546              specified by the treectrl's -foreground option.
4547
4548              In headers, if the color for a certain state is an empty string,
4549              then  the text will be displayed using the system theme color on
4550              Gtk+; if that color is not specified then the  -headerforeground
4551              option is used.
4552
4553       -font font
4554              Specifies  as a per-state option the font to use when displaying
4555              the text.  If the font for a certain state is an  empty  string,
4556              the text is displayed using the font specified by the treectrl's
4557              -font option in items or the -headerfont option in headers.
4558
4559       -format formatString
4560              This option specifies the format  string  used  to  display  the
4561              value  of  the -data option.  If -datatype is time, formatString
4562              should be a valid format string for the Tcl clock command.   For
4563              all other -datatype values formatString should be a valid format
4564              string for the Tcl format command.  If this value is unspecified
4565              the  following defaults are used: for -datatype double "%g", for
4566              -datatype integer "%d", for -datatype long "%ld", for  -datatype
4567              string "%s", and for -datatype time the default format string of
4568              the Tcl clock command.
4569
4570       -justify how
4571              Specifies how to justify the text when multiple lines  are  dis‐
4572              played.   How  must be one of the values left, right, or center.
4573              If this option is specified as an empty  string  (the  default),
4574              left is used.
4575
4576       -lines lineCount
4577              Specifies  the maximum number of lines to display.  If more than
4578              lineCount lines would be displayed, the last line will be  trun‐
4579              cated  with  an ellipsis at the right.  If this option is speci‐
4580              fied as zero or an empty string (the default), there is no limit
4581              to the number of lines displayed.
4582
4583       -lmargin1 pixels
4584              Pixels  is  a  screen distance that specifies how much a line of
4585              text should be indented.  If a line of text wraps,  this  option
4586              only  applies  to  the  first line on the display; the -lmargin2
4587              option controls the indentation for subsequent lines.   If  this
4588              option  is  specified  as zero or an empty string (the default),
4589              then the line is not indented.  This option was based on the  Tk
4590              Text widget tag option of the same name.
4591
4592       -lmargin2 pixels
4593              Pixels  is  a  screen distance that specifies how much a line of
4594              text should be indented.  If a line of text wraps,  this  option
4595              only applies to the second and later display lines for a line of
4596              text.  If this option is specified as zero or  an  empty  string
4597              (the  default),  then the line is not indented.  This option was
4598              based on the Tk Text widget tag option of the same name.
4599
4600       -text string
4601              String specifies a  string  to  be  displayed  by  the  element.
4602              String  may  contain  newline  characters in which case multiple
4603              lines of text will be displayed.  If this option  is  specified,
4604              the  -data,  -datatype,  -format,  and -textvariable options are
4605              ignored.
4606
4607       -textvariable varName
4608              Specifies the name of a variable.  The value of the variable  is
4609              a  string to be displayed by the element;  if the variable value
4610              changes then the element will  automatically  update  itself  to
4611              display  the new value.  If this option is specified, the -data,
4612              -datatype, and -format options are ignored.
4613
4614       -underline charIndex
4615              Specifies the integer index of a character to underline.  0 cor‐
4616              responds  to  the  first character.  If charIndex is unspecified
4617              (the default), less than zero or greater than the index  of  the
4618              last displayed character, the underline is not drawn.
4619
4620       -width size
4621              Specifies the maximum line length in any of the forms acceptable
4622              to Tk_GetPixels.  For text to wrap lines the value of the -width
4623              option  must  be  less than the needed width of the text, or the
4624              display area for this element must be less than the needed width
4625              of  the  text.   For the display area to be less than the needed
4626              width of the text, one of the style  layout  options  -maxwidth,
4627              -width or -squeeze must be used.
4628
4629       -wrap mode
4630              Mode  specifies  how to handle lines in the text that are longer
4631              than the maximum line length.  Acceptable values are none,  char
4632              or  word.   If this option is unspecified (the default), word is
4633              used.  See the -width option for a description of how the  maxi‐
4634              mum line length is determined.
4635

WINDOW ELEMENT

4637       An  element  of  type  window  can be used to display a Tk window in an
4638       item.  The following options are supported for window elements:
4639
4640       -clip boolean
4641              Specifies whether the associated Tk window is a borderless frame
4642              which  should  be  used  to  clip its child window so it doesn't
4643              overlap the header, borders, or other  items  or  columns.  When
4644              this  option  is true, the treectrl manages the geometry of both
4645              the -window widget and its first child widget; in this case  the
4646              -window  widget  (which  should  be  a borderless frame) is kept
4647              sized and positioned so that it is never out-of-bounds.
4648
4649       -destroy boolean
4650              Specifies whether the associated Tk window should  be  destroyed
4651              when  the  element  is  deleted. The element is deleted when the
4652              item containing the element is deleted, when the column contain‐
4653              ing  the  element  is deleted, or when the style assigned to the
4654              item's column is changed. If this  option  is  unspecified  (the
4655              default),  it  is treated as false and the Tk window will not be
4656              destroyed.
4657
4658       -draw boolean
4659              Deprecated; use the style layout option -draw  instead.   Speci‐
4660              fies  as  a per-state option whether to draw the element. If the
4661              value for a certain state is an empty string (the  default),  it
4662              is treated as true and the element will be drawn.
4663
4664       -window pathName
4665              Specifies  the window to associate with this element. The window
4666              specified by pathName must either be a  child  of  the  treectrl
4667              widget or a child of some ancestor of the treectrl widget. Path‐
4668              Name may not refer to a top-level window. This option cannot  be
4669              specified  by  the element create or element configure commands,
4670              only by the item element configure command;  i.e.,  the  element
4671              must be associated with a particular item.
4672

ITEM DESCRIPTION

4674       Many  of  the commands for a treectrl take as an argument a description
4675       of which items to operate on. An item description is a  properly-formed
4676       tcl list of keywords and arguments.  The first word of an item descrip‐
4677       tion must be one of the following:
4678
4679       id     Specifies the unique item identifier, where  id  should  be  the
4680              return  value of a prior call of the item create widget command,
4681              or 0 to specify the ever-present root item. See also the  -item‐
4682              prefix option.
4683
4684       QUALIFIERS
4685              Specifies  a  list  of qualifiers. This gives the same result as
4686              all followed by QUALIFIERS; i.e., every item  is  tested  for  a
4687              match.
4688
4689       tagExpr QUALIFIERS
4690              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
4691              which every item's tags are tested for a  match.   This  keyword
4692              cannot  be  followed  by  any  modifiers unless a single item is
4693              matched. You may run into trouble if tagExpr looks like an  item
4694              id  or other keyword; also, tagExpr must look like a single list
4695              element since item descriptions are properly-formed lists. To be
4696              safe you may want to use the tag qualifier followed by tagExpr.
4697
4698       active Indicates  the  item that is currently active, i.e. normally the
4699              item specified as argument of the last successful activate  wid‐
4700              get command, or the root item if no such call happened yet.
4701
4702       anchor Indicates  the  anchor  item of the selection, i.e. normally the
4703              item specified as argument  of  the  last  successful  selection
4704              anchor widget command, or the root item if no such call happened
4705              yet.
4706
4707       all QUALIFIERS
4708              Indicates every item including orphans which  match  QUALIFIERS.
4709              This keyword cannot be followed by any modifiers unless a single
4710              item is matched.
4711
4712       first QUALIFIERS
4713              Indicates the first item of the treectrl (the root item), or the
4714              first item matching QUALIFIERS.
4715
4716       end QUALIFIERS
4717
4718       last QUALIFIERS
4719              Indicates the last item which matches QUALIFIERS.
4720
4721       list itemDescs
4722              ItemDescs  is a list (a single argument, i.e. "list {a b c}" not
4723              "list a b c") of other item descriptions.  This  keyword  cannot
4724              be followed by any modifiers unless a single item is matched.
4725
4726       nearest x y
4727              Indicates the item nearest to the point given by x and y.
4728
4729       rnc row column
4730              Indicates  the  item  in  the given row and column.  The row and
4731              column corresponds to the  on-screen  arrangement  of  items  as
4732              determined  by  the -orient and -wrap options.  You can memorize
4733              rnc as an abbreviation of "row 'n' column".
4734
4735       range first last QUALIFIERS
4736              First and last specify a range of items.  This keyword cannot be
4737              followed by any modifiers unless a single item is matched.
4738
4739       root   Indicates the root item of the treectrl.
4740
4741       The  initial  part  of the item description (matching any of the values
4742       above) may be followed by one or more modifiers.   A  modifier  changes
4743       the  item used relative to the description up to this point.  It may be
4744       specified in any of the following forms:
4745
4746       above  Use the item one row above in this column.
4747
4748       ancestors QUALIFIERS
4749              Use the ancestors of the item (like item  ancestors  but  QUALI‐
4750              FIERS may change which ancestors match).  This keyword cannot be
4751              followed by any modifiers.
4752
4753       below  Use the item one row below in this column.
4754
4755       bottom Use the item in the last row of this column.
4756
4757       child n QUALIFIERS
4758              Use the nth child of the item.
4759
4760       children QUALIFIERS
4761              Use the children of the item (like item children but  QUALIFIERS
4762              may  change  which children match).  This keyword cannot be fol‐
4763              lowed by any modifiers.
4764
4765       descendants QUALIFIERS
4766              Use the descendants of the item (like item descendants but QUAL‐
4767              IFIERS may change which descendants match).  This keyword cannot
4768              be followed by any modifiers.
4769
4770       firstchild QUALIFIERS
4771              Use the first child of the item.
4772
4773       lastchild QUALIFIERS
4774              Use the last child of the item.
4775
4776       left   Use the item one column to the left in the same row.
4777
4778       leftmost
4779              Use the item of the first column in the same row.
4780
4781       next QUALIFIERS
4782              Use the next item, which is the first item  from  the  following
4783              list:  the  first child, the next sibling or the next sibling of
4784              the nearest ancestor which has one.
4785
4786       nextsibling QUALIFIERS
4787              Use the next sibling of the item.
4788
4789       parent Use the parent of the item.
4790
4791       prev QUALIFIERS
4792              Use the last child of the previous sibling,  or  the  parent  if
4793              there is no previous sibling.
4794
4795       prevsibling QUALIFIERS
4796              Use the previous sibling of the item.
4797
4798       right  Use the item one column to the right in the same row.
4799
4800       rightmost
4801              Use the item of the last column in the same row.
4802
4803       sibling n QUALIFIERS
4804              Use the nth child of the item's parent.
4805
4806       top    Use the item in the first row of this column.
4807
4808       The  word  QUALIFIERS  above represents a series of zero or more of the
4809       following terms that changes which item is chosen:
4810
4811       depth depth
4812              Matches items whose depth (as returned by the depth command)  is
4813              equal to depth.
4814
4815       state stateList
4816              StateList is a list of item state names (static and dynamic, see
4817              STATES).  Only items that have the given states set (or unset if
4818              the '!' prefix is used) are considered.
4819
4820       tag tagExpr
4821              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
4822              which an item's tags are tested for a match.
4823
4824       visible
4825              When this qualifier is given, only items that are displayed  are
4826              considered.
4827
4828       !visible
4829              When  this  qualifier  is  given, only items that are *not* dis‐
4830              played are considered.
4831
4832       To get the first item in the list that is enabled:
4833
4834       $T item id "first state enabled"
4835
4836       To get the ancestors that are not open of the last item in the list:
4837
4838       $T item id "last ancestors state !open"
4839
4840       To get the visible descendants of the root item:
4841
4842       $T item id "root descendants visible"
4843
4844       To get the every hidden item with tag "a" or "b":
4845
4846       $T item id "all !visible tag a||b"
4847       $T item id "!visible tag a||b"
4848       $T item id "tag a||b !visible"
4849       $T item id "a||b !visible"
4850
4851

EVENTS AND SCRIPT SUBSTITUTIONS

4853       The script argument to notify bind is a Tcl script, which will be eval‐
4854       uated whenever the given event is generated. Script will be executed in
4855       the same interpreter that the notify bind command was executed in,  and
4856       it will run at global level (only global variables will be accessible).
4857       If script contains any % characters, then the script will not be evalu‐
4858       ated  directly.   Instead,  a new script will be generated by replacing
4859       each %, and the character following it, with information from the  cur‐
4860       rent  event. Unlike the regular Tk bind mechanism, each event generated
4861       by a treectrl widget has its own set of %-substitutions.
4862
4863       The following %-substitutions are valid for all static events:
4864
4865       %%     Replaced with a single %
4866
4867       %d     The detail name
4868
4869       %e     The event name
4870
4871       %P     The pattern, either <event> or <event-detail>
4872
4873       %W     The object argument to the notify bind command
4874
4875       %T     The treectrl widget which generated the event
4876
4877       %?     A list of the format {char value char value ...} for each %-sub‐
4878              stitution character and the value it is replaced by
4879
4880       The following events may be generated by a treectrl widget:
4881
4882       <ActiveItem>
4883              Generated whenever the active item changes.
4884
4885              %c     The current active item
4886
4887              %p     The previous active item
4888
4889       <Collapse-before>
4890              Generated before an item is collapsed.
4891
4892              %I     The item id
4893
4894       <Collapse-after>
4895              Generated after an item is collapsed.
4896
4897              %I     The item id
4898
4899       <Expand-before>
4900              Generated  before  an  item is expanded. This event is useful if
4901              you want to add child items to the item just before the item  is
4902              expanded.
4903
4904              %I     The item id
4905
4906       <Expand-after>
4907              Generated after an item is expanded.
4908
4909              %I     The item id
4910
4911       <ItemDelete>
4912              Generated  when items are about to be deleted by the item delete
4913              command.
4914
4915              %i     List of items ids being deleted.
4916
4917       <ItemVisibility>
4918              Generated when items become visible on screen and when items are
4919              no longer visible on screen.  This event is useful if you have a
4920              very large number of items and want to assign styles  only  when
4921              items are actually going to be displayed.
4922
4923              %h     List of items ids which are no longer visible.
4924
4925              %v     List of items ids which are now visible.
4926
4927       <Scroll-x>
4928              Generated  whenever  the  view in the treectrl changes in such a
4929              way that a horizontal scrollbar should be redisplayed.
4930
4931              %l     Same as the first fraction appended  to  -xscrollcommand.
4932                     Think lower.
4933
4934              %u     Same  as the second fraction appended to -xscrollcommand.
4935                     Think upper.
4936
4937       <Scroll-y>
4938              Generated whenever the view in the treectrl changes  in  such  a
4939              way that a vertical scrollbar should be redisplayed.
4940
4941              %l     Same  as  the first fraction appended to -yscrollcommand.
4942                     Think lower.
4943
4944              %u     Same as the second fraction appended to  -yscrollcommand.
4945                     Think upper.
4946
4947       <Selection>
4948              Generated  whenever  the  selection  changes.  This  event gives
4949              information about how the selection changed.
4950
4951              %c     Same as the selection count widget command
4952
4953              %D     List of newly-deselected item ids
4954
4955              %S     List of newly-selected item ids
4956

DYNAMIC EVENTS

4958       In addition to the pre-defined static events such as  <ActiveItem>  and
4959       <Selection>,  new  dynamic  events  can  be created by using the notify
4960       install command.
4961
4962       The library scripts provide an example of using a dynamic event  called
4963       <Header-invoke>,  which  is  generated when the mouse button is clicked
4964       and released over a column header.
4965
4966       # Example application code
4967       treectrl .t
4968                               puts "column header %C clicked in header-row %H in treectrl %T"
4969       }
4970       # Library code in treectrl.tcl
4971       proc ::TreeCtrl::Release1 {w x y} {
4972                               ...
4973                               $w notify generate <Header-invoke> [list H $Priv(header) C $Priv(column)] \
4974                               [list ::TreeCtrl::PercentsCmd $w]
4975                               ...
4976       }
4977
4978       In the example above, a new treectrl widget is created and the <Header-
4979       invoke>  event is installed. A script is bound to the event with notify
4980       bind which will print out the column ID, header ID and widget  name  to
4981       the  console.   In  a  real  application,  any script bound to <Header-
4982       invoke> would be used to sort the list based on the column header  that
4983       was clicked.
4984
4985       Note  there  is no percentsCommand argument to notify install; instead,
4986       the call to notify generate specifies the %-substitution command.   The
4987       charMap  argument  to notify generate provides a list of %-substitution
4988       characters and values which is used by ::TreeCtrl::PercentsCmd. In  the
4989       example,  any %C in any script bound to the <Header-invoke> event would
4990       be replaced by the value of $Priv(column), and %H would be replaced  by
4991       $Priv(header).  The library procedure ::TreeCtrl::PercentsCmd also sup‐
4992       ports the same common %-substitution characters as the built-in  static
4993       events, such as %T, %P, %? etc.
4994
4995       The following dynamic events may be generated by the library scripts:
4996
4997       <ColumnDrag-begin>
4998              This  event  is  generated just after the user begins dragging a
4999              column header.  At the time this event is generated, the  header
5000              dragconfigure option -imagecolumn is set to the unique ID of the
5001              column being dragged, the -imageoffset option is set to the hor‐
5002              izontal distance the mouse pointer has moved, and the -imagespan
5003              option is set to the span of the column  header  that  was  ini‐
5004              tially clicked.
5005
5006       <ColumnDrag-indicator>
5007              This  event  is  generated  each  time  a  new place to drop the
5008              dragged column header is found. At the time this event is gener‐
5009              ated, the header dragconfigure option -indicatorcolumn is set to
5010              the unique ID of the column before or after  which  the  dragged
5011              column  will be dropped, and the -indicatorspan option is set to
5012              the span of the column header for  this  newly-chosen  indicator
5013              column.
5014
5015       <ColumnDrag-receive>
5016              This  event  is generated when the user has successfully dragged
5017              and dropped a column header to  a  new  position.   The  library
5018              scripts do not actually move the dragged column. You must bind a
5019              script to this event to move the column.  See EXAMPLES.
5020
5021       <ColumnDrag-end>
5022              This event is generated after the user finally releases the left
5023              mouse button while dragging a column header.  This event is gen‐
5024              erated after all the other <ColumnDrag>  events  even  when  the
5025              column  wasn't  dragged  to  a  new location (i.e., even when no
5026              <ColumnDrag-receive> event was generated).
5027
5028              %H     The header-row that contains the column header.
5029
5030              %C     The column whose header is dragged within the header-row.
5031
5032              %b     The column to move the dragged column(s)  before.   Valid
5033                     for <ColumnDrag-receive> only.
5034
5035       <Drag-begin>
5036
5037       <Drag-receive>
5038
5039       <Drag-end>
5040              Generated  whenever the user drag-and-drops a file into a direc‐
5041              tory. This  event  is  generated  by  the  filelist-bindings.tcl
5042              library  code,  which is not used by default. See the "Explorer"
5043              demos.
5044
5045              %I     The item that the user dropped the dragged items on.
5046
5047              %l     (lowercase L) The list of dragged items.
5048
5049       <Edit-begin>
5050
5051       <Edit-accept>
5052
5053       <Edit-end>
5054              The filelist-bindings.tcl code will display a text-editing  win‐
5055              dow  if  the user clicks on a selected file/folder name. See the
5056              "Explorer" demos.
5057
5058              %I     The item containing the edited text element.
5059
5060              %C     The column containing the edited text element.
5061
5062              %E     The name of the edited text element.
5063
5064              %t     The edited text.
5065
5066       <Header-invoke>
5067              Generated whenever the user clicks and releases the  left  mouse
5068              button  in a column header if the column header's -button option
5069              is true. You can bind a script to this event to sort the list.
5070
5071              %H     The header-row that contains the column header.
5072
5073              %C     The column whose header was clicked.
5074
5075       <Header-state>
5076              Generated when the column header option -state is changed by the
5077              library scripts during Motion and Button events.
5078
5079              %H     The header-row that displays the column header.
5080
5081              %C     The  column  within  the  header-row  whose header option
5082                     -state changed.
5083
5084              %s     The new value of the column header option -state.
5085

DEFAULT BINDINGS

5087       Tk automatically creates class bindings for treectrl widgets that  give
5088       them the following default behavior.
5089
5090       [1]    Clicking mouse button 1 over an item positions the active cursor
5091              on the item, sets the input focus to this widget, and resets the
5092              selection  of  the  widget to this item, if it is not already in
5093              the selection.
5094
5095       [2]    Clicking mouse button 1 with the Control key down  will  reposi‐
5096              tion the active cursor and add the item to the selection without
5097              ever removing any items from the selection.
5098
5099       [3]    If the mouse is dragged out of the  widget  while  button  1  is
5100              pressed,  the  treectrl  will  automatically scroll to make more
5101              items visible (if there are more items off-screen  on  the  side
5102              where the mouse left the window).
5103
5104       [4]    The  Left  and Right keys move the active cursor one item to the
5105              left or right; for an hierarchical tree with  vertical  orienta‐
5106              tion  nothing will happen, since it has no two items in the same
5107              row.  The selection is set to include only the active item.   If
5108              Left  or Right is typed with the Shift key down, then the active
5109              cursor moves and the selection is extended to  include  the  new
5110              item.
5111
5112       [5]    The Up and Down keys move the active cursor one item up or down.
5113              The selection is set to include only the active item.  If Up  or
5114              Down  is  typed  with the Shift key down, then the active cursor
5115              moves and the selection is extended to include the new item.
5116
5117       [6]    The Next and Prior keys move the active cursor forward or  back‐
5118              wards by one screenful, without affecting the selection.
5119
5120       [7]    Control-Next  and Control-Prior scroll the view right or left by
5121              one page without moving  the  active  cursor  or  affecting  the
5122              selection.  Control-Left and Control-Right behave the same.
5123
5124       [8]    The  Home  and  End  keys scroll to the left or right end of the
5125              widget without moving the active cursor or affecting the  selec‐
5126              tion.
5127
5128       [9]    The  Control-Home and Control-End keys scroll to the top or bot‐
5129              tom of the widget, they also activate and select  the  first  or
5130              last  item.  If also the Shift key is down, then the active cur‐
5131              sor moves and the selection is extended to include the new item.
5132
5133       [10]   The Space and Select keys set the selection to the active item.
5134
5135       [11]   Control-/ selects the entire contents of the widget.
5136
5137       [12]   Control-\\ clears any selection in the widget.
5138
5139       [13]   The + and - keys expand or collapse the active item, the  Return
5140              key toggles the active item.
5141
5142       [14]   The  mousewheel  scrolls the view of the widget four lines up or
5143              down depending on the direction,  the  wheel  was  turned.   The
5144              active cursor or the selection is not affected.
5145

GRADIENTS

5147       Color  gradients  are  an  easy  way  to  give your lists a more modern
5148       appearance.  Since Tk provides no support for  drawing  gradients,  the
5149       TkPath  extension  was  used  as a guide when implementing gradients in
5150       TkTreeCtrl.  The current implementation has some limitations, however:
5151
5152       [1]    Only linear gradients are supported.
5153
5154       [2]    Gradients can only be painted  left-to-right  or  top-to-bottom,
5155              not at arbitrary angles.
5156
5157       [3]    Gradients  look  bad  on low-color displays. Before using gradi‐
5158              ents, you should check that the  display's  color  depth  is  at
5159              least 15 or 16 by calling the winfo depth command.
5160
5161       [4]    Gradients are fully opaque when XFillRectangle() is used to draw
5162              them (see below).  This means the opacity value  of  each  color
5163              stop  is  ignored.   Keep  that  in  mind if your application is
5164              cross-platform.
5165
5166       [5]    Rounded rectangles cannot be filled or outlined with a  gradient
5167              when  XFillRectangle()  is  used  to draw gradients (see below).
5168              Instead, the rounded rectangle is painted  with  the  gradient's
5169              first -stops color.
5170
5171       Gradients may be used in the following places:
5172
5173       [1]    The -gridleftcolor and -gridrightcolor options of columns.
5174
5175       [2]    The -itembackground option of columns.
5176
5177       [3]    The -fill and -outline options of rect elements.
5178
5179       [4]    The -fill and -outline options of the marquee configure command.
5180
5181       On  Microsoft  Windows, GDI+ is used where it is available (gdiplus.dll
5182       is dynamically loaded at run-time).  On Mac OS X, CoreGraphics is  used
5183       to  draw  gradients.  With the Gtk+ build of treectrl, libcairo is used
5184       to draw gradients.  When native gradient support is available, all  the
5185       talk below about -steps can safely be ignored.
5186
5187       When  no native support for gradients is available, gradients are drawn
5188       simply by filling sub-rectangles using XFillRectangle().  The number of
5189       sub-rectangles  drawn  and  number of colors that make up the displayed
5190       gradient are controlled by the gradient's -steps  and  -stops  options.
5191       The  number  of  sub-rectangles  is  equal  to the length of the -stops
5192       option multiplied by the value of the -steps option. For example:
5193
5194       $T gradient create myGradient -stops {{0 white} {1 gray}} -steps 8
5195
5196       This gradient will be drawn with 2x8=16 sub-rectangles of  color.   The
5197       higher  the  -steps  value, the smoother the color transitions will be,
5198       and the slower the gradient will be to draw.  For the best  appearance,
5199       make  the  number  of  sub-rectangles  drawn  less than or equal to the
5200       height or width of the gradient being drawn.  So if  you  have  a  rect
5201       element  18  pixels  tall,  use  a  vertical  gradient that has steps X
5202       stops=18.  Avoid using gradients with steps X stops  greater  than  the
5203       height  or width of the rectangle being drawn, because then colors will
5204       overlap.
5205

GRADIENT COORDINATES

5207       By default, a gradient brush is exactly the same size as whatever  rec‐
5208       tangle  is  being  painted.  For example, if a column's -itembackground
5209       option specifies a gradient name, then the background  of  an  item  is
5210       painted  with  all  the colors of the gradient.  So a vertical gradient
5211       from blue to green will start blue at the top and end with green at the
5212       bottom of every item.
5213
5214       By  specifying  any  of  the  -bottom,  -left,  -right or -top gradient
5215       options the size of the gradient brush does not need to match  that  of
5216       the  rectangle being painted.  These options can be used to make a gra‐
5217       dient appear to span across the entire width or height of the  treectrl
5218       window, or across the entire canvas, for example.
5219
5220       There  is no point specifying -left or -right if the gradient is verti‐
5221       cal, since the gradient's colors are constant horizontally, so changing
5222       the  horizontal  size  of  the brush won't change the appearance of the
5223       gradient.  The same reasoning applies for the -top and -bottom  options
5224       for a horizontal gradient.
5225
5226       package require treectrl
5227       set T [treectrl .t -itemheight 20 -showheader no]
5228       $T gradient create G1 -orient vertical -top {0.0 canvas} -bottom {1.0 canvas} \
5229                               -stops {{0.0 blue} {0.5 green} {1.0 red}} -steps 25
5230       $T column create -expand yes -itembackground G1
5231       pack $T -expand yes -fill both
5232
5233

EXAMPLES

5235       Get the unique identifier for the leftmost visible column:
5236
5237       set id [$T column index "first visible"]
5238
5239       Delete the leftmost column:
5240
5241       $T column delete "order 0"
5242
5243       Take  the  visible  column  that is to the left of the last column, and
5244       move that column in front of the tail column:
5245
5246       $T column move "last prev visible" tail
5247
5248       Get the unique identifier for the first visible item:
5249
5250       set id [$T item index "first visible"]
5251
5252       Delete the parent of the item that is under the point x,y:
5253
5254       $T item delete "nearest $x $y parent"
5255
5256       Add the 10th child of the second child of the root item to  the  selec‐
5257       tion:
5258
5259       $T selection add "root firstchild nextsibling child 10"
5260
5261       Move a column that the user drag-and-dropped:
5262
5263       $T header dragconfigure -enable yes
5264       $T notify install <ColumnDrag-receive>
5265       $T notify bind MyTag <ColumnDrag-receive> {
5266                               %T column move %C %b
5267       }
5268
5269

SEE ALSO

5271       bind(n), bitmap(n), image(n), listbox(n), options(n)
5272

KEYWORDS

5274       tree, widget
5275
5276
5277
5278treectrl                             2.4.1                         treectrl(n)
Impressum