1treectrl(n) Tk Commands treectrl(n)
2______________________________________________________________________________
6
8 treectrl - Create and manipulate hierarchical multicolumn widgets
9
11 package require treectrl 2.4.1
12 treectrl pathName ?options?
14 pathName activate itemDesc
16 pathName bbox ?area?
18 pathName canvasx windowx
20 pathName canvasy windowy
22 pathName cget option
24 pathName collapse ?-recurse? ?itemDesc ...?
26 pathName column option column ?arg ...?
28 pathName column bbox columnDesc
30 pathName column cget columnDesc option
32 pathName column configure columnDesc ?option? ?value? ?option value
34 ...?
35 pathName column compare column1 op column2
37 pathName column count ?columnDesc?
39 pathName column create ?option value ...?
41 pathName column delete first ?last?
43 pathName column dragcget option
45 pathName column dragconfigure ?option? ?value? ?option value ...?
47 pathName column index columnDesc
49 pathName column id columnDesc
51 pathName column list ?-visible?
53 pathName column move columnDesc beforeDesc
55 pathName column neededwidth columnDesc
57 pathName column order columnDesc ?-visible?
59 pathName column tag option ?arg arg ...?
61 pathName column tag add columnDesc tagList
63 pathName column tag expr columnDesc tagExpr
65 pathName column tag names columnDesc
67 pathName column tag remove columnDesc tagList
69 pathName column width columnDesc
71 pathName compare itemDesc1 op itemDesc2
73 pathName configure ?option? ?value option value ...?
75 pathName contentbox
77 pathName debug option ?arg arg ...?
79 pathName debug alloc
81 pathName debug cget option
83 pathName debug configure ?option? ?value? ?option value ...?
85 pathName debug dinfo option
87 pathName debug expose x1 y1 x2 y2
89 pathName depth ?itemDesc?
91 pathName dragimage option ?arg ...?
93 pathName dragimage add itemDesc ?column? ?element?
95 pathName dragimage cget option
97 pathName dragimage clear
99 pathName dragimage configure ?option? ?value? ?option value ...?
101 pathName dragimage offset ?x y?
103 pathName element option ?element? ?arg arg ...?
105 pathName element cget element option
107 pathName element configure element ?option? ?value? ?option value ...?
109 pathName element create name type ?option value ...?
111 pathName element delete ?element ...?
113 pathName element names
115 pathName element perstate element option stateList
117 pathName element type element
119 pathName expand ?-recurse? ?itemDesc ...?
121 pathName gradient option ?arg ...?
123 pathName gradient cget gradient option
125 pathName gradient configure gradient ?option value ...?
127 pathName gradient create name ?option value ...?
129 pathName gradient delete ?name ...?
131 pathName gradient names
133 pathName gradient native ?preference?
135 pathName header option ?arg ...?
137 pathName header bbox headerDesc ?column? ?element?
139 pathName header compare headerDesc1 op headerDesc2
141 pathName header configure headerDesc ?arg ...?
143 pathName header count ?headerDesc?
145 pathName header create ?option value?
147 pathName header delete headerDesc
149 pathName header dragcget ?arg ...?
151 pathName header dragconfigure ?arg ...?
153 pathName header element ?arg ...?
155 pathName header id headerDesc
157 pathName header image headerDesc ?column? ?image? ?column image ...?
159 pathName header span headerDesc ?column? ?numColumns? ?column num‐
161 Columns ...?
162 pathName header state command headerDesc ?arg ...?
164 pathName header style command headerDesc ?arg ...?
166 pathName header text headerDesc ?column? ?text? ?column text ...?
168 pathName header tag command headerDesc ?arg ...?
170 pathName identify ?-array varName? x y
172 pathName index itemDesc
174 pathName item option ?arg ...?
176 pathName item ancestors itemDesc
178 pathName item bbox itemDesc ?column? ?element?
180 pathName item buttonstate itemDesc ?state?
182 pathName item cget itemDesc option
184 pathName item children itemDesc
186 pathName item collapse itemDesc ?-animate? ?-recurse?
188 pathName item compare itemDesc1 op itemDesc2
190 pathName item complex itemDesc ?list...?
192 pathName item configure itemDesc ?option? ?value? ?option value ...?
194 pathName item count ?itemDesc?
196 pathName item create ?option value ...?
198 pathName item delete first ?last?
200 pathName item descendants itemDesc
202 pathName item dump itemDesc
204 pathName item element command itemDesc column element ?arg ...?
206 pathName item element actual itemDesc column element option
208 pathName item element cget itemDesc column element option
210 pathName item element configure itemDesc column element ?option?
212 ?value? ?option value ...?
213 pathName item element perstate itemDesc column element option
215 ?stateList?
216 pathName item enabled itemDesc ?boolean?
218 pathName item expand itemDesc ?-animate? ?-recurse?
220 pathName item firstchild parent ?child?
222 pathName item id itemDesc
224 pathName item image itemDesc ?column? ?image? ?column image ...?
226 pathName item isancestor itemDesc descendant
228 pathName item isopen itemDesc
230 pathName item lastchild parent ?child?
232 pathName item nextsibling sibling ?next?
234 pathName item numchildren itemDesc
236 pathName item order itemDesc ?-visible?
238 pathName item parent itemDesc
240 pathName item prevsibling sibling ?prev?
242 pathName item range first last
244 pathName item remove itemDesc
246 pathName item rnc itemDesc
248 pathName item sort itemDesc ?option ...?
250 pathName item span itemDesc ?column? ?numColumns? ?column numColumns
252 ...?
253 pathName item state command itemDesc ?arg ...?
255 pathName item state define stateName
257 pathName item state forcolumn itemDesc column ?stateDescList?
259 pathName item state get itemDesc ?stateName?
261 pathName item state linkage stateName
263 pathName item state names
265 pathName item state set itemDesc ?lastItem? stateDescList
267 pathName item state undefine ?stateName ...?
269 pathName item style command itemDesc ?arg ...?
271 pathName item style elements itemDesc column
273 pathName item style map itemDesc column style map
275 pathName item style set itemDesc ?column? ?style? ?column style ...?
277 pathName item tag option ?arg arg ...?
279 pathName item tag add itemDesc tagList
281 pathName item tag expr itemDesc tagExpr
283 pathName item tag names itemDesc
285 pathName item tag remove itemDesc tagList
287 pathName item text itemDesc ?column? ?text? ?column text ...?
289 pathName item toggle itemDesc ?-animate? ?-recurse?
291 pathName marquee option ?arg ...?
293 pathName marquee anchor ?x y?
295 pathName marquee cget option
297 pathName marquee configure ?option? ?value? ?option value ...?
299 pathName marquee coords ?x1 y1 x2 y2?
301 pathName marquee corner ?x y?
303 pathName marquee identify
305 pathName notify option ?arg ...?
307 pathName notify bind ?object? ?pattern? ?+??script?
309 pathName notify configure object pattern ?option? ?value? ?option value
311 ...?
312 pathName notify detailnames eventName
314 pathName notify eventnames
316 pathName notify generate pattern ?charMap? ?percentsCommand?
318 pathName notify install pattern ?percentsCommand?
320 pathName notify install detail eventName detail ?percentsCommand?
322 pathName notify install event eventName ?percentsCommand?
324 pathName notify linkage pattern
326 pathName notify linkage eventName ?detail?
328 pathName notify unbind object ?pattern?
330 pathName notify uninstall pattern
332 pathName notify uninstall detail eventName detail
334 pathName notify uninstall event eventName
336 pathName numcolumns
338 pathName numitems
340 pathName orphans
342 pathName range first last
344 pathName scan option args
346 pathName scan mark x y
348 pathName scan dragto x y ?gain?
350 pathName see itemDesc ?columnDesc? ?option value ...?
352 pathName selection option args
354 pathName selection add first ?last?
356 pathName selection anchor ?itemDesc?
358 pathName selection clear ?first? ?last?
360 pathName selection count
362 pathName selection get ?first? ?last?
364 pathName selection includes itemDesc
366 pathName selection modify select deselect
368 pathName state option args
370 pathName state define stateName
372 pathName state linkage stateName
374 pathName state names
376 pathName state undefine ?stateName ...?
378 pathName style option ?element? ?arg arg ...?
380 pathName style cget style option
382 pathName style configure style ?option? ?value? ?option value ...?
384 pathName style create name ?option value ...?
386 pathName style delete ?style ...?
388 pathName style elements style ?elementList?
390 pathName style layout style element ?option? ?value? ?option value ...?
392 pathName style names
394 pathName theme option ?arg ...?
396 pathName theme platform
398 pathName theme setwindowtheme appname
400 pathName toggle ?-recurse? ?itemDesc ...?
402 pathName xview ?args?
404 pathName xview
406 pathName xview moveto fraction
408 pathName xview scroll number what
410 pathName yview ?args?
412 pathName yview
414 pathName yview moveto fraction
416 pathName yview scroll number what
418_________________________________________________________________
420
422 treectrl pathName ?options?
423 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 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 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 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 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 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 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 A treectrl can display a background image. The background image can be
465 configured to be scrolled and tiled on each axis individually.
466
468 -background
469 -borderwidth
471 -cursor
473 -font
475 -highlightbackground
477 -highlightcolor
479 -highlightthickness
481 -orient
483 -relief
485 -takefocus
487 -xscrollcommand
489 -yscrollcommand
491 -foreground
493 See the option manual entry for details on the standard options.
495
497 Command-Line Switch: -backgroundimage
498 Database Name: backgroundImage
499 Database Class: BackgroundImage
500 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 Command-Line Switch: -backgroundmode
508 Database Name: backgroundMode
509 Database Class: BackgroundMode
510 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 Command-Line Switch: -bgimage
526 Database Name: bgImage
527 Database Class: BgImage
528 Synonym for -backgroundimage.
531 Command-Line Switch: -bgimageanchor
533 Database Name: bgImageAnchor
534 Database Class: BgImageAnchor
535 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 Command-Line Switch: -bgimageopaque
544 Database Name: bgImageOpaque
545 Database Class: BgImageOpaque
546 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 Command-Line Switch: -bgimagescroll
555 Database Name: bgImageScroll
556 Database Class: BgImageScroll
557 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 Command-Line Switch: -bgimagetile
565 Database Name: bgImageTile
566 Database Class: BgImageTile
567 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 Command-Line Switch: -buttonbitmap
574 Database Name: buttonBitmap
575 Database Class: ButtonBitmap
576 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 Command-Line Switch: -buttoncolor
584 Database Name: buttonColor
585 Database Class: ButtonColor
586 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 Command-Line Switch: -buttonimage
593 Database Name: buttonImage
594 Database Class: ButtonImage
595 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 Command-Line Switch: -buttonsize
603 Database Name: buttonSize
604 Database Class: ButtonSize
605 Specifies the width and height of the expand/collapse button of
608 an item in any of the forms acceptable to Tk_GetPixels.
609 Command-Line Switch: -buttonthickness
611 Database Name: buttonThickness
612 Database Class: ButtonThickness
613 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 Command-Line Switch: -buttonttracking
620 Database Name: buttonTracking
621 Database Class: ButtonTracking
622 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 Command-Line Switch: -canvaspadx
632 Database Name: canvasPadX
633 Database Class: CanvasPadX
634 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 Command-Line Switch: -canvaspady
643 Database Name: canvasPadY
644 Database Class: CanvasPadY
645 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 Command-Line Switch: -columnprefix
654 Database Name: columnPrefix
655 Database Class: ColumnPrefix
656 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 Command-Line Switch: -columnproxy
665 Database Name: columnProxy
666 Database Class: ColumnProxy
667 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 Command-Line Switch: -columnresizemode
679 Database Name: columnResizeMode
680 Database Class: ColumnResizeMode
681 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 Command-Line Switch: -columntagexpr
691 Database Name: columnTagExpr
692 Database Class: ColumnTagExpr
693 Specifies a boolean that enables or disables tag expressions in
696 column descriptions. See ITEM AND COLUMN TAGS.
697 Command-Line Switch: -defaultstyle
699 Database Name: defaultStyle
700 Database Class: DefaultStyle
701 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 Command-Line Switch: -doublebuffer
713 Database Name: doubleBuffer
714 Database Class: DoubleBuffer
715 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 Command-Line Switch: -headerfont
722 Database Name: headerFont
723 Database Class: Font
724 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 Command-Line Switch: -headerfg
732 Database Name: headerForeground
733 Database Class: Foreground
734 Synonym for -headerforeground.
737 Command-Line Switch: -headerforeground
739 Database Name: headerForeground
740 Database Class: Foreground
741 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 Command-Line Switch: -height
750 Database Name: height
751 Database Class: Height
752 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 Command-Line Switch: -indent
760 Database Name: indent
761 Database Class: Indent
762 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 Command-Line Switch: -itemgapx
769 Database Name: itemGapX
770 Database Class: ItemGapX
771 Specifies the horizontal spacing between adjacent items in any
774 of the forms acceptable to Tk_GetPixels. The default is 0.
775 Command-Line Switch: -itemgapy
777 Database Name: itemGapY
778 Database Class: ItemGapY
779 Specifies the vertical spacing between adjacent items in any of
782 the forms acceptable to Tk_GetPixels. The default is 0.
783 Command-Line Switch: -itemheight
785 Database Name: itemHeight
786 Database Class: ItemHeight
787 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 Command-Line Switch: -itemprefix
798 Database Name: itemPrefix
799 Database Class: ItemPrefix
800 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 Command-Line Switch: -itemtagexpr
809 Database Name: itemTagExpr
810 Database Class: ItemTagExpr
811 Specifies a boolean that enables or disables tag expressions in
814 item descriptions. See ITEM AND COLUMN TAGS.
815 Command-Line Switch: -itemwidth
817 Database Name: itemWidth
818 Database Class: ItemWidth
819 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 Command-Line Switch: -itemwidthequal
828 Database Name: itemWidthEqual
829 Database Class: ItemWidthEqual
830 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 Command-Line Switch: -itemwidthmultiple
840 Database Name: itemWidthMultiple
841 Database Class: ItemWidthMultiple
842 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 Command-Line Switch: -linecolor
853 Database Name: lineColor
854 Database Class: LineColor
855 Specifies the color which should be used for drawing the con‐
858 necting lines between related items.
859 Command-Line Switch: -linestyle
861 Database Name: lineStyle
862 Database Class: LineStyle
863 Specifies the appearance of the connecting lines between related
866 items. The value should be dot, which is the default, or solid.
867 Command-Line Switch: -linethickness
869 Database Name: lineThickness
870 Database Class: LineThickness
871 Specifies the thickness of the connecting lines between related
874 items in any of the forms acceptable to Tk_GetPixels.
875 Command-Line Switch: -minitemheight
877 Database Name: minItemHeight
878 Database Class: MinItemHeight
879 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 Command-Line Switch: -rowproxy
890 Database Name: rowProxy
891 Database Class: RowProxy
892 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 Command-Line Switch: -scrollmargin
904 Database Name: scrollMargin
905 Database Class: ScrollMargin
906 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 Command-Line Switch: -selectmode
916 Database Name: selectMode
917 Database Class: SelectMode
918 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 Command-Line Switch: -showbuttons
926 Database Name: showButtons
927 Database Class: ShowButtons
928 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 Command-Line Switch: -showheader
937 Database Name: showHeader
938 Database Class: ShowHeader
939 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 Command-Line Switch: -showlines
946 Database Name: showLines
947 Database Class: ShowLines
948 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 Command-Line Switch: -showroot
956 Database Name: showRoot
957 Database Class: ShowRoot
958 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 Command-Line Switch: -showrootbutton
966 Database Name: showRootButton
967 Database Class: ShowRootButton
968 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 Command-Line Switch: -showrootchildbuttons
976 Database Name: showRootChildButtons
977 Database Class: ShowRootChildButtons
978 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 Command-Line Switch: -showrootlines
985 Database Name: showRootLines
986 Database Class: ShowRootLines
987 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 Command-Line Switch: -treecolumn
994 Database Name: treeColumn
995 Database Class: TreeColumn
996 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 Command-Line Switch: -usetheme
1003 Database Name: useTheme
1004 Database Class: UseTheme
1005 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 Command-Line Switch: -width
1012 Database Name: width
1013 Database Class: Width
1014 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 Command-Line Switch: -wrap
1022 Database Name: wrap
1023 Database Class: Wrap
1024 Specifies whether items are arranged in a 1- or 2-dimensional
1027 layout.
1028 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 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 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 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 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 Command-Line Switch: -xscrolldelay
1051 Database Name: xScrollDelay
1052 Database Class: ScrollDelay
1053 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 Command-Line Switch: -xscrollincrement
1064 Database Name: xScrollIncrement
1065 Database Class: ScrollIncrement
1066 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 Command-Line Switch: -xscrollsmoothing
1081 Database Name: xScrollSmoothing
1082 Database Class: ScrollSmoothing
1083 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 Command-Line Switch: -yscrolldelay
1096 Database Name: yScrollDelay
1097 Database Class: ScrollDelay
1098 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 Command-Line Switch: -yscrollincrement
1109 Database Name: yScrollIncrement
1110 Database Class: ScrollIncrement
1111 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 Command-Line Switch: -yscrollsmoothing
1126 Database Name: yScrollSmoothing
1127 Database Class: ScrollSmoothing
1128 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
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
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 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 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 or equivalently:
1164 will return the unique ids of any items with either "a" or "b" tags,
1167 but not both.
1168 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 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 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
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 pathName option ?arg arg ...?
1190 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 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 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 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 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 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 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 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 pathName collapse ?-recurse? ?itemDesc ...?
1243 Deprecated. Use item collapse instead.
1244 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 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 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 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 See COLUMNS below for details on the options available
1289 for columns.
1290 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 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 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 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 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 pathName column dragcget option
1331 Deprecated. Use header dragcget instead.
1332 pathName column dragconfigure ?option? ?value? ?option value
1334 ...?
1335 Deprecated. Use header dragconfigure instead.
1336 pathName column index columnDesc
1338 Deprecated. Use column id instead.
1339 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 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 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 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 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 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 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 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 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 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 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 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 pathName compare itemDesc1 op itemDesc2
1418 Deprecated. Use the item compare command instead.
1419 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 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 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 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 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 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 The following debugging options are supported:
1474 -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 -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 -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 -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 -enable boolean
1504 All other debugging options only take effect if
1505 this option is also switched on.
1506 -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 -span boolean
1518 Debugging related to column spanning.
1519 -textlayout boolean
1521 Debugging related to text-element layout.
1522 pathName debug dinfo option
1524 Returns a string describing display-related stuff. Option
1525 must be one of alloc, ditem, onscreen or range.
1526 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 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 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 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 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 pathName dragimage clear
1565 Removes all shapes (if there are any) from the dragimage.
1566 This command does not modify the dragimage offset.
1567 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 The following dragimage options are supported:
1585 -visible boolean
1587 Specifies a boolean value which determines whether
1588 the dragimage should currently be visible.
1589 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 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 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 This command also accepts the -statedomain option.
1611 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 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 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 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 pathName element names
1652 Returns a list containing the names of all existing ele‐
1653 ments.
1654 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 pathName element type element
1662 Returns the type of the element given by element, such as
1663 rect or text.
1664 pathName expand ?-recurse? ?itemDesc ...?
1666 Deprecated. Use item expand instead.
1667 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 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 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 The following options are supported (see gradient create
1695 for the meaning of each option):
1696 -bottom coordSpec
1698 -left coordSpec
1700 -orient direction
1702 -right coordSpec
1704 -steps stepCount
1706 -stops stopsList
1708 -top coordSpec
1710 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 The following options are supported:
1717 -bottom coordSpec
1719 -left coordSpec
1721 -right coordSpec
1723 -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 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 -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 -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 -stops stopsList
1759 Specifies the color stops along this gradient. The
1760 argument stopsList has the following form:
1761 {{offset color ?opacity?} {offset color ?opacity?} ...}
1763 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 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 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 pathName gradient names
1789 Returns a list of names of all the gradients that have
1790 been created by this treectrl widget.
1791 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 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 pathName header bbox headerDesc ?column? ?element?
1807 See the item bbox command.
1808 pathName header compare headerDesc1 op headerDesc2
1810 See the item compare command.
1811 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 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 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 The following options are supported by this com‐
1843 mand (see header create for the meaning of each
1844 option):
1845 -height height
1847 -tags tagList
1849 -visible boolean
1851 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 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 The following options are supported by this com‐
1873 mand (see HEADERS) for the meaning of each
1874 option):
1875 -arrow direction
1877 -arrowbitmap bitmap
1879 -arrowgravity direction
1881 -arrowimage image
1883 -arrowpadx amount
1885 -arrowpady amount
1887 -arrowside side
1889 -background color
1891 -bitmap bitmap
1893 -borderwidth size
1895 -button boolean
1897 -font fontName
1899 -image image
1901 -imagepadx amount
1903 -imagepady amount
1905 -justify justification
1907 -state state
1909 -text text
1911 -textcolor color
1913 -textlines count
1915 -textpadx amount
1917 -textpady amount
1919 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 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 -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 -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 -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 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 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 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 -enable boolean
1978 -imagealpha alpha
1980 -imagecolor background
1982 -imagecolumn column
1984 -imageoffset offset
1986 -imagespan count
1988 -indicatorcolor color
1990 -indicatorcolumn column
1992 -indicatorside side
1994 -indicatorspan count
1996 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 -draw boolean
2005 -enable boolean
2007 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 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 -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 -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 -imagecolor background
2039 Unused.
2040 -imagecolumn column
2042 Column specifies the column to create the
2043 drag image from.
2044 -imageoffset offset
2046 Offset is the horizontal screen distance
2047 the drag image is offset from its starting
2048 position.
2049 -imagespan count
2051 Count is the number of columns, starting
2052 with -imagecolumn, that will be dragged as
2053 a group.
2054 -indicatorcolor color
2056 Unused.
2057 -indicatorcolumn column
2059 The 2-pixel-thick line will be drawn over
2060 the left or right edge of column.
2061 -indicatorside side
2063 Unused.
2064 -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 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 -draw boolean
2078 Controls whether a header-row displays any
2079 feedback during header drag-and-drop. The
2080 default is true.
2081 -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 pathName header element ?arg ...?
2090 See the item element command.
2091 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 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 pathName header span headerDesc ?column? ?numColumns? ?column
2110 numColumns ...?
2111 See the item span command.
2112 pathName header state command headerDesc ?arg ...?
2114 See the item state command.
2115 pathName header style command headerDesc ?arg ...?
2117 See the item style command.
2118 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 pathName header tag command headerDesc ?arg ...?
2130 See the item tag command.
2131 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 [1] If the coordinates are outside the window, over the bor‐
2139 ders, or over any whitespace in the window, then:
2140 $varName(where) is ""
2142 [2] If the coordinates are over a column header, then:
2144 $varName(where) is header
2146 $varName(header) is the unique id of the header-row
2148 $varName(column) is the unique id of the column
2150 $varName(element) is the name of an element, or ""
2152 $varName(side) is left or right if the coordinates are
2154 close to the edge of the column header, otherwise ""
2155 [3] If the coordinates are over an item, then:
2157 $varName(where) is item
2159 $varName(item) is the unique id of the item
2161 $varName(column) is the unique id of the column
2163 $varName(element) is the name of an element, or ""
2165 $varName(button) is a boolean indicating whether or not
2167 the coordinates are over the item's expand/collapse but‐
2168 ton
2169 $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 [1] {}
2181 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 [2] header C ?left|right?
2187 header C elem E ?left|right?
2189 header H column C ?left|right?
2191 header H column C elem E ?left|right?
2193 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 [3] item I column C
2200 [4] item I column C elem E
2202 [5] item I button
2204 This is the result when the coordinates are over the
2206 expand/collapse button next to an item.
2207 [6] item I line I2
2209 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 pathName index itemDesc
2216 Deprecated. Use item id instead.
2217 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 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 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 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 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 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 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 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 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 { {element option value ...} {element option value ...} ...}
2292 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 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 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 The following options are supported by this command (see
2314 item create for the meaning of each option):
2315 -button boolean|auto
2317 -height height
2319 -tags tagList
2321 -visible boolean
2323 -wrap boolean
2325 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 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 The following options are supported by this command:
2343 -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 [1] the column specified by the treectrl option
2357 -treecolumn is visible, and
2358 [2] the treectrl option -showbuttons is true,
2360 and
2361 [3] for the root item, the treectrl option
2363 -showrootbutton is true, and
2364 [4] for immediate children of the root item,
2366 the treectrl option -showrootchildbuttons
2367 is true.
2368 -count numItems
2370 Specifies the number of items to create. Must be
2371 >= 0. Defaults to 1.
2372 -enabled boolean
2374 Specifies whether the items should be enabled.
2375 Default is true.
2376 -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 -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 -open boolean
2390 Specifies whether the items should be open or
2391 closed. Default is true.
2392 -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 -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 -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 -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 -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 [1] each ancestor is a descendant of the root
2425 item (not an orphan), and
2426 [2] each ancestor's -visible option is true
2428 -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 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 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 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 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 pathName item dump itemDesc
2465 Debug command. Returns a list with 4 words in the form
2466 index index indexVis indexVis.
2467 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 pathName item element actual itemDesc column element
2475 option
2476 Deprecated. Use item element perstate instead.
2477 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 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 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 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 $C1 $E1 -text "hello" + $E2 -text "world" , \
2515 $C2 $E3 -fill Blue , \
2516 $C3 $E1 -text "apples and oranges"
2517 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 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 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 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 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 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 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 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 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 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 pathName item isopen itemDesc
2591 Returns 1 if the item described by itemDesc has the state
2592 open switched on, 0 otherwise.
2593 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 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 pathName item numchildren itemDesc
2609 Returns the number of children of the item described by
2610 itemDesc.
2611 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 pathName item parent itemDesc
2624 Returns the item id of the parent of the item described
2625 by itemDesc.
2626 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 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 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 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 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 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 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 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 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 -ascii Use string comparison with ASCII collation order.
2683 This is the default.
2684 -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 -decreasing
2696 Sort the items in decreasing order ("largest"
2697 items first).
2698 -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 -increasing
2709 Sort the items in increasing order ("smallest"
2710 items first). This is the default.
2711 -integer
2713 Convert to integers and use integer comparison.
2714 -real Convert to floating-point values and use floating
2716 comparison.
2717 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 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 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 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 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 If stateDescList is specified, then itemDesc may
2751 refer to multiple items and column may refer to
2752 multiple columns.
2753 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 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 pathName item state names
2769 Returns a list containing the names of all user-
2770 defined states.
2771 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 The following marquee options are supported:
2943 -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 -outline color
2950 Specifies the color to outline the marquee rectan‐
2951 gle with.
2952 -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 -visible boolean
2963 Specifies a boolean value which determines whether
2964 the marquee is displayed.
2965 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 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 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 {
2985 {item {column element element ...} {column element element ...} ...}
2986 {item {column element element ...} {column element element ...} ...}
2987 ...
2988 }
2989 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 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 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 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 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 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 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 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 The following binding options are supported:
3051 -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 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 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 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 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 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 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 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 proc percentsCommand {?arg arg ...? char object event detail charMap} {
3111 switch -- $char {
3112 ...
3113 }
3114 return $value
3115 }
3116 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 notify install returns the current percentsCommand for
3127 the event, or an error if the event is not dynamic.
3128 pathName notify install detail eventName detail ?percentsCom‐
3130 mand?
3131 Deprecated. Use notify install with a pattern of <event‐
3132 Name-detail> instead.
3133 pathName notify install event eventName ?percentsCommand?
3135 Deprecated. Use notify install with a pattern of <event‐
3136 Name> instead.
3137 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 pathName notify linkage eventName ?detail?
3145 Deprecated. Use notify linkage with a pattern of <event‐
3146 Name> or <eventName-detail> instead.
3147 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 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 pathName notify uninstall detail eventName detail
3161 Deprecated. Use notify uninstall with a pattern of
3162 <eventName-detail> instead.
3163 pathName notify uninstall event eventName
3165 Deprecated. Use notify uninstall with a pattern of
3166 <eventName> instead.
3167 pathName numcolumns
3169 Deprecated. Use the column count command instead.
3170 pathName numitems
3172 Deprecated. Use the item count command instead.
3173 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 pathName range first last
3181 Deprecated. Use the item range command instead.
3182 pathName scan option args
3184 This command is used to implement scanning on treectrls. It has
3185 two forms, depending on option:
3186 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 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 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 The following options are supported:
3215 -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 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 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 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 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 pathName selection count
3261 Returns an integer indicating the number of items in the
3262 treectrl that are currently selected.
3263 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 pathName selection includes itemDesc
3277 Returns 1 if the item described by itemDesc is currently
3278 selected, 0 if it isn't.
3279 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 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 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 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 pathName state names
3309 Returns a list containing the names of all user-defined
3310 states.
3311 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 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 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 This command also accepts the -statedomain option.
3330 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 The following options are supported:
3349 -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 -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 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 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 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 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 Every element used by a style must have been created with
3394 the same value for the -statedomain option.
3395 If the elementList argument is not specified, a list is
3397 returned containing the currently defined elements of
3398 style.
3399 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 The options of a layout have effect on exactly the one
3415 element element managed by style. The following options
3416 are supported:
3417 -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 -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 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 -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 -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 -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 -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 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 The default is true.
3492 -ipadx amount
3494 -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 -minheight pixels
3506 -height pixels
3508 -maxheight pixels
3510 Specifies the minimum, fixed, and maximum height
3511 of the display area of the element. The default
3512 is unspecified.
3513 -minwidth pixels
3515 -width pixels
3517 -maxwidth pixels
3519 Specifies the minimum, fixed, and maximum width of
3520 the display area of the element. The default is
3521 unspecified.
3522 -padx amount
3524 -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 -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 -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 -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 -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 pathName style names
3574 Returns a list containing the names of all existing
3575 styles.
3576 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 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 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 pathName toggle ?-recurse? ?itemDesc ...?
3602 Use item toggle instead.
3603 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 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 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 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 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 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 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 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
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 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 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 Header-rows in a treectrl may be specified in a number of ways. See
3686 HEADER DESCRIPTION below.
3687 The appearance of individual column headers within a header-row may be
3689 customized in two different ways:
3690 [1] By configuring various column header options with the header
3692 configure command
3693 [2] By assigning a style to a column header with the header style
3695 command.
3696 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 The following options are supported for each individual column header:
3702 -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 -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 -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 -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 -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 -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 -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 -bitmap bitmap
3739 Specifies the name of a bitmap to display to the left of the
3740 column title.
3741 -background color
3743 Specifies as a per-state option the color to use for the back‐
3744 ground of the column header.
3745 -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 -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 -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 -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 -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 -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 -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 -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 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 -text text
3798 Specifies a text string to be displayed as the column title.
3799 -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 -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 -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 -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
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 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 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 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 all QUALIFIERS
3853 Matches every header-row which satisfies QUALIFIERS.
3854 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 end QUALIFIERS
3860 last QUALIFIERS
3862 Indicates the last header-row which satisfies QUALIFIERS.
3863 The word QUALIFIERS above represents a series of zero or more of the
3865 following terms that changes which header-row is chosen:
3866 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 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 !visible
3879 When this qualifier is given, only header-rows that are *not*
3880 displayed are matched.
3881
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 Columns in a treectrl may be specified in a number of ways. See COLUMN
3888 DESCRIPTION below.
3889 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 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 The following options are supported for columns:
3901 -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 -gridleftcolor color
3908 -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 -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 -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 -itemstyle style
3929 Style is the name of a style that should be set in this column
3930 for newly-created items.
3931 -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 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 -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 -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 -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 -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 -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 -stepwidth size
3975 Deprecated. Use the treectrl's -itemwidthmultiple option
3976 instead.
3977 -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 -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 -visible boolean
3991 Indicates whether or not the column should be displayed.
3992 -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 -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 -widthhack boolean
4011 Deprecated. Use the treectrl's -itemwidthequal option instead.
4012
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 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 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 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 all QUALIFIERS
4039 Indicates every column, including the tail column if the command
4040 allows it, which match QUALIFIERS.
4041 first QUALIFIERS
4043 Indicates the leftmost column of the treectrl which matches
4044 QUALIFIERS.
4045 end QUALIFIERS
4047 last QUALIFIERS
4049 Indicates the rightmost column of the treectrl (but not the tail
4050 column) which matches QUALIFIERS.
4051 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 order n QUALIFIERS
4059 Indicates the nth column in the list of columns as returned by
4060 the column order command.
4061 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 tail Indicates the ever-present tail column of the treectrl.
4068 tree Indicates the column specified by the -treecolumn option of the
4070 treectrl.
4071 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 next QUALIFIERS
4078 Use the column to the right matching QUALIFIERS.
4079 prev QUALIFIERS
4081 Use the column to the left matching QUALIFIERS.
4082 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 [1] A column does not match QUALIFIERS.
4089 [2] A column's -lock option does not match the first column's
4091 -lock option.
4092 The word QUALIFIERS above represents a sequence of zero or more of the
4094 following terms that changes which column is chosen:
4095 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 !tail When this qualifier is given, the tail column is not matched.
4101 visible
4103 When this qualifier is given, only columns whose -visible option
4104 is TRUE are considered.
4105 !visible
4107 When this qualifier is given, only columns whose -visible option
4108 is FALSE are considered.
4109
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 HEADER STATES
4118 The following states are predefined for every column header:
4119 active
4121 normal
4123 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 down
4130 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 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 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 ITEM STATES
4148 The following states are predefined for every item:
4149 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 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 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 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 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 By means of the state define widget command, up to 27 additional states
4183 can be defined.
4184
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 $T element configure MyTextElement -font {{Times 12 bold}}
4197 However, to use a different font when the item is selected you could
4199 write:
4200 $T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}
4202 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 $T element configure MyRectElement -fill {blue {selected focus} gray {selected !focus}}
4211 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 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 $T element configure MyRectElement -fill {gray {selected} blue {selected focus}}
4224 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 A value followed by an empty stateList should always be last since it
4230 will be chosen regardless of the item's state.
4231
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 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 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 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 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 For each element type there is a section below describing the options
4281 which can modify an element of that type.
4282
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 -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 -bitmap bitmap
4293 Specifies as a per-state option the bitmap to display in the
4294 element.
4295 -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 -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
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 -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 -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 -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 -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 -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 -thickness thickness
4341 Specifies the thickness of the edges of the border.
4342 -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
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 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 The following options are supported for header elements:
4364 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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
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 -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 -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 -image image
4446 Specifies as a per-state option the image to display in the ele‐
4447 ment.
4448 -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 -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
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 -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 -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 -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 -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 -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 -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 -rx radius
4505 -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 -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 -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
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 -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 -data data
4533 Specifies a value that together with the -datatype and -format
4534 options will be displayed as text.
4535 -datatype dataType
4537 Specifies the type of information in the -data option. Accept‐
4538 able values are double, integer, long, string, or time.
4539 -fill color
4541 Specifies as a per-state option the foreground color to use when
4542 displaying text.
4543 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 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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -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
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 -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 -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 -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 -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
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 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 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 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 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 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 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 first QUALIFIERS
4713 Indicates the first item of the treectrl (the root item), or the
4714 first item matching QUALIFIERS.
4715 end QUALIFIERS
4717 last QUALIFIERS
4719 Indicates the last item which matches QUALIFIERS.
4720 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 nearest x y
4727 Indicates the item nearest to the point given by x and y.
4728 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 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 root Indicates the root item of the treectrl.
4740 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 above Use the item one row above in this column.
4747 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 below Use the item one row below in this column.
4754 bottom Use the item in the last row of this column.
4756 child n QUALIFIERS
4758 Use the nth child of the item.
4759 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 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 firstchild QUALIFIERS
4771 Use the first child of the item.
4772 lastchild QUALIFIERS
4774 Use the last child of the item.
4775 left Use the item one column to the left in the same row.
4777 leftmost
4779 Use the item of the first column in the same row.
4780 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 nextsibling QUALIFIERS
4787 Use the next sibling of the item.
4788 parent Use the parent of the item.
4790 prev QUALIFIERS
4792 Use the last child of the previous sibling, or the parent if
4793 there is no previous sibling.
4794 prevsibling QUALIFIERS
4796 Use the previous sibling of the item.
4797 right Use the item one column to the right in the same row.
4799 rightmost
4801 Use the item of the last column in the same row.
4802 sibling n QUALIFIERS
4804 Use the nth child of the item's parent.
4805 top Use the item in the first row of this column.
4807 The word QUALIFIERS above represents a series of zero or more of the
4809 following terms that changes which item is chosen:
4810 depth depth
4812 Matches items whose depth (as returned by the depth command) is
4813 equal to depth.
4814 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 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 visible
4825 When this qualifier is given, only items that are displayed are
4826 considered.
4827 !visible
4829 When this qualifier is given, only items that are *not* dis‐
4830 played are considered.
4831 To get the first item in the list that is enabled:
4833 $T item id "first state enabled"
4835 To get the ancestors that are not open of the last item in the list:
4837 $T item id "last ancestors state !open"
4839 To get the visible descendants of the root item:
4841 $T item id "root descendants visible"
4843 To get the every hidden item with tag "a" or "b":
4845 $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
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 The following %-substitutions are valid for all static events:
4864 %% Replaced with a single %
4866 %d The detail name
4868 %e The event name
4870 %P The pattern, either <event> or <event-detail>
4872 %W The object argument to the notify bind command
4874 %T The treectrl widget which generated the event
4876 %? A list of the format {char value char value ...} for each %-sub‐
4878 stitution character and the value it is replaced by
4879 The following events may be generated by a treectrl widget:
4881 <ActiveItem>
4883 Generated whenever the active item changes.
4884 %c The current active item
4886 %p The previous active item
4888 <Collapse-before>
4890 Generated before an item is collapsed.
4891 %I The item id
4893 <Collapse-after>
4895 Generated after an item is collapsed.
4896 %I The item id
4898 <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 %I The item id
4905 <Expand-after>
4907 Generated after an item is expanded.
4908 %I The item id
4910 <ItemDelete>
4912 Generated when items are about to be deleted by the item delete
4913 command.
4914 %i List of items ids being deleted.
4916 <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 %h List of items ids which are no longer visible.
4924 %v List of items ids which are now visible.
4926 <Scroll-x>
4928 Generated whenever the view in the treectrl changes in such a
4929 way that a horizontal scrollbar should be redisplayed.
4930 %l Same as the first fraction appended to -xscrollcommand.
4932 Think lower.
4933 %u Same as the second fraction appended to -xscrollcommand.
4935 Think upper.
4936 <Scroll-y>
4938 Generated whenever the view in the treectrl changes in such a
4939 way that a vertical scrollbar should be redisplayed.
4940 %l Same as the first fraction appended to -yscrollcommand.
4942 Think lower.
4943 %u Same as the second fraction appended to -yscrollcommand.
4945 Think upper.
4946 <Selection>
4948 Generated whenever the selection changes. This event gives
4949 information about how the selection changed.
4950 %c Same as the selection count widget command
4952 %D List of newly-deselected item ids
4954 %S List of newly-selected item ids
4956
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 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 # 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 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 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 The following dynamic events may be generated by the library scripts:
4996 <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 <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 <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 <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 %H The header-row that contains the column header.
5029 %C The column whose header is dragged within the header-row.
5031 %b The column to move the dragged column(s) before. Valid
5033 for <ColumnDrag-receive> only.
5034 <Drag-begin>
5036 <Drag-receive>
5038 <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 %I The item that the user dropped the dragged items on.
5046 %l (lowercase L) The list of dragged items.
5048 <Edit-begin>
5050 <Edit-accept>
5052 <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 %I The item containing the edited text element.
5059 %C The column containing the edited text element.
5061 %E The name of the edited text element.
5063 %t The edited text.
5065 <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 %H The header-row that contains the column header.
5072 %C The column whose header was clicked.
5074 <Header-state>
5076 Generated when the column header option -state is changed by the
5077 library scripts during Motion and Button events.
5078 %H The header-row that displays the column header.
5080 %C The column within the header-row whose header option
5082 -state changed.
5083 %s The new value of the column header option -state.
5085
5087 Tk automatically creates class bindings for treectrl widgets that give
5088 them the following default behavior.
5089 [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 [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 [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 [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 [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 [6] The Next and Prior keys move the active cursor forward or back‐
5118 wards by one screenful, without affecting the selection.
5119 [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 [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 [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 [10] The Space and Select keys set the selection to the active item.
5134 [11] Control-/ selects the entire contents of the widget.
5136 [12] Control-\\ clears any selection in the widget.
5138 [13] The + and - keys expand or collapse the active item, the Return
5140 key toggles the active item.
5141 [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
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 [1] Only linear gradients are supported.
5153 [2] Gradients can only be painted left-to-right or top-to-bottom,
5155 not at arbitrary angles.
5156 [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 [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 [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 Gradients may be used in the following places:
5172 [1] The -gridleftcolor and -gridrightcolor options of columns.
5174 [2] The -itembackground option of columns.
5176 [3] The -fill and -outline options of rect elements.
5178 [4] The -fill and -outline options of the marquee configure command.
5180 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 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 $T gradient create myGradient -stops {{0 white} {1 gray}} -steps 8
5195 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
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 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 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 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
5235 Get the unique identifier for the leftmost visible column:
5236 set id [$T column index "first visible"]
5238 Delete the leftmost column:
5240 $T column delete "order 0"
5242 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 $T column move "last prev visible" tail
5247 Get the unique identifier for the first visible item:
5249 set id [$T item index "first visible"]
5251 Delete the parent of the item that is under the point x,y:
5253 $T item delete "nearest $x $y parent"
5255 Add the 10th child of the second child of the root item to the selec‐
5257 tion:
5258 $T selection add "root firstchild nextsibling child 10"
5260 Move a column that the user drag-and-dropped:
5262 $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
5271 bind(n), bitmap(n), image(n), listbox(n), options(n)
5272
5274 tree, widget
5275treectrl 2.4.1 treectrl(n)