1treectrl(n) Tk Commands treectrl(n)
2
6 treectrl - Create and manipulate hierarchical multicolumn widgets
7
9 package require treectrl 2.2.10
10 treectrl pathName ?options?
12 pathName activate itemDesc
14 pathName bbox ?area?
16 pathName canvasx screenx
18 pathName canvasy screeny
20 pathName cget option
22 pathName collapse ?-recurse? ?itemDesc ...?
24 pathName column option column ?arg ...?
26 pathName column bbox columnDesc
28 pathName column cget columnDesc option
30 pathName column configure columnDesc ?option? ?value? ?option value
32 ...?
33 pathName column compare column1 op column2
35 pathName column count ?columnDesc?
37 pathName column create ?option value ...?
39 pathName column delete first ?last?
41 pathName column dragcget option
43 pathName column dragconfigure ?option? ?value? ?option value ...?
45 pathName column index columnDesc
47 pathName column id columnDesc
49 pathName column list ?-visible?
51 pathName column move columnDesc beforeDesc
53 pathName column neededwidth columnDesc
55 pathName column order columnDesc ?-visible?
57 pathName column tag option ?arg arg ...?
59 pathName column tag add columnDesc tagList
61 pathName column tag expr columnDesc tagExpr
63 pathName column tag names columnDesc
65 pathName column tag remove columnDesc tagList
67 pathName column width columnDesc
69 pathName compare itemDesc1 op itemDesc2
71 pathName configure ?option? ?value option value ...?
73 pathName contentbox
75 pathName debug option ?arg arg ...?
77 pathName debug alloc
79 pathName debug cget option
81 pathName debug configure ?option? ?value? ?option value ...?
83 pathName debug dinfo option
85 pathName debug expose x1 y1 x2 y2
87 pathName debug scroll
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 element 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 identify x y
123 pathName index itemDesc
125 pathName item option ?arg ...?
127 pathName item ancestors itemDesc
129 pathName item bbox itemDesc ?column? ?element?
131 pathName item cget itemDesc option
133 pathName item children itemDesc
135 pathName item collapse itemDesc ?-recurse?
137 pathName item compare itemDesc1 op itemDesc2
139 pathName item complex itemDesc ?list...?
141 pathName item configure itemDesc ?option? ?value? ?option value ...?
143 pathName item count ?itemDesc?
145 pathName item create ?option value ...?
147 pathName item delete first ?last?
149 pathName item descendants itemDesc
151 pathName item dump itemDesc
153 pathName item element command itemDesc column element ?arg ...?
155 pathName item element actual itemDesc column element option
157 pathName item element cget itemDesc column element option
159 pathName item element configure itemDesc column element ?option?
161 ?value? ?option value ...?
162 pathName item element perstate itemDesc column element option
164 ?stateList?
165 pathName item enabled itemDesc ?boolean?
167 pathName item expand itemDesc ?-recurse?
169 pathName item firstchild parent ?child?
171 pathName item id itemDesc
173 pathName item image itemDesc ?column? ?image? ?column image ...?
175 pathName item isancestor itemDesc descendant
177 pathName item isopen itemDesc
179 pathName item lastchild parent ?child?
181 pathName item nextsibling sibling ?next?
183 pathName item numchildren itemDesc
185 pathName item order itemDesc ?-visible?
187 pathName item parent itemDesc
189 pathName item prevsibling sibling ?prev?
191 pathName item range first last
193 pathName item remove itemDesc
195 pathName item rnc itemDesc
197 pathName item sort itemDesc ?option ...?
199 pathName item span itemDesc ?column? ?numColumns? ?column numColumns
201 ...?
202 pathName item state command itemDesc ?arg ...?
204 pathName item state forcolumn itemDesc column ?stateDescList?
206 pathName item state get itemDesc ?stateName?
208 pathName item state set itemDesc ?lastItem? stateDescList
210 pathName item style command itemDesc ?arg ...?
212 pathName item style elements itemDesc column
214 pathName item style map itemDesc column style map
216 pathName item style set itemDesc ?column? ?style? ?column style ...?
218 pathName item tag option ?arg arg ...?
220 pathName item tag add itemDesc tagList
222 pathName item tag expr itemDesc tagExpr
224 pathName item tag names itemDesc
226 pathName item tag remove itemDesc tagList
228 pathName item text itemDesc ?column? ?text? ?column text ...?
230 pathName item toggle itemDesc ?-recurse?
232 pathName marquee option ?arg ...?
234 pathName marquee anchor ?x y?
236 pathName marquee cget option
238 pathName marquee configure ?option? ?value? ?option value ...?
240 pathName marquee coords ?x1 y1 x2 y2?
242 pathName marquee corner ?x y?
244 pathName marquee identify
246 pathName notify option ?arg ...?
248 pathName notify bind ?object? ?pattern? ?+??script?
250 pathName notify configure object pattern ?option? ?value? ?option value
252 ...?
253 pathName notify detailnames eventName
255 pathName notify eventnames
257 pathName notify generate pattern ?charMap? ?percentsCommand?
259 pathName notify install pattern ?percentsCommand?
261 pathName notify install detail eventName detail ?percentsCommand?
263 pathName notify install event eventName ?percentsCommand?
265 pathName notify linkage pattern
267 pathName notify linkage eventName ?detail?
269 pathName notify unbind object ?pattern?
271 pathName notify uninstall pattern
273 pathName notify uninstall detail eventName detail
275 pathName notify uninstall event eventName
277 pathName numcolumns
279 pathName numitems
281 pathName orphans
283 pathName range first last
285 pathName scan option args
287 pathName scan mark x y
289 pathName scan dragto x y ?gain?
291 pathName see itemDesc ?columnDesc? ?option value ...?
293 pathName selection option args
295 pathName selection add first ?last?
297 pathName selection anchor ?itemDesc?
299 pathName selection clear ?first? ?last?
301 pathName selection count
303 pathName selection get ?first? ?last?
305 pathName selection includes itemDesc
307 pathName selection modify select deselect
309 pathName state option args
311 pathName state define stateName
313 pathName state linkage stateName
315 pathName state names
317 pathName state undefine ?stateName ...?
319 pathName style option ?element? ?arg arg ...?
321 pathName style cget style option
323 pathName style configure style ?option? ?value? ?option value ...?
325 pathName style create style ?option value ...?
327 pathName style delete ?style ...?
329 pathName style elements style ?elementList?
331 pathName style layout style element ?option? ?value? ?option value ...?
333 pathName style names
335 pathName toggle ?-recurse? ?itemDesc ...?
337 pathName xview ?args?
339 pathName xview
341 pathName xview moveto fraction
343 pathName xview scroll number what
345 pathName yview ?args?
347 pathName yview
349 pathName yview moveto fraction
351 pathName yview scroll number what
353
356 treectrl pathName ?options?
357 The treectrl command creates a new window (given by the pathName argu‐
359 ment) and makes it into a treectrl widget. Additional options,
360 described above, may be specified on the command line or in the option
361 database to configure aspects of the treectrl such as its background
362 color and relief. The treectrl command returns the path name of the
363 new window. At the time this command is invoked, there must not exist
364 a window named pathName, but pathName's parent must exist.
365 A treectrl is a widget which displays items in a one- or two-dimen‐
367 sional arrangement. Items have a parent-child relationship with other
368 items. Items have a set of states, which are boolean properties.
369 Items may be spread about one or more columns. For each column of an
370 item there is a style associated, which determines how to display the
371 item's column taking into account the item's current state set. One
372 column can be defined to display the data in a hierarchical structure.
373 Normally the origin of the coordinate system is at the upper-left cor‐
375 ner of the window containing the treectrl. It is possible to adjust
376 the origin of the coordinate system relative to the origin of the win‐
377 dow using the xview and yview widget commands; this is typically used
378 for scrolling.
379 A treectrl widget can be horizontal or vertical oriented like many
381 other Tk widgets. For displaying hierarchical data only vertical ori‐
382 entation is useful, since only then the children of an item are dis‐
383 played directly below their parent. If the treectrl widget is used
384 only to display data in a multicolumn listbox, the specification of an
385 orientation will give useful results.
386
388 -background
389 -borderwidth
391 -cursor
393 -font
395 -highlightbackground
397 -highlightcolor
399 -highlightthickness
401 -orient
403 -relief
405 -takefocus
407 -xscrollcommand
409 -yscrollcommand
411 -foreground
413 See the option manual entry for details on the standard options.
414
416 Command-Line Switch: -backgroundimage
417 Database Name: backgroundImage
418 Database Class: BackgroundImage
419 Specifies the name of an image to draw as the list background.
422 The image is tiled horizontally and vertically to fill the con‐
423 tent area of the list. If the image is transparent it is drawn
424 on top of the background color(s).
425 Command-Line Switch: -backgroundmode
427 Database Name: backgroundMode
428 Database Class: BackgroundMode
429 Specifies how the background color of items is chosen in each
432 column. The value should be one of row, column, order, or
433 ordervisible. The default is row. This option has only an
434 effect for columns which have -itembackground defined as list of
435 two or more colors (see section COLUMNS below for more on this).
436 If row or column is specified, the background color is chosen
437 based on the location of the item in the 1- or 2-dimensional
438 grid of items as layed out on the screen; this layout of items
439 is affected by the -orient and -wrap options as well as item
440 visibility. When order or ordervisible is specified, the back‐
441 ground color is chosen based on the result of the item order
442 command, regardless of the layout of items.
443 Command-Line Switch: -buttonbitmap
445 Database Name: buttonBitmap
446 Database Class: ButtonBitmap
447 Specifies the bitmap to be used as the expand/collapse button to
450 the left of an item. This is a per-state option. If a bitmap is
451 specified for a certain item state, it overrides the effects of
452 -usetheme.
453 Command-Line Switch: -buttoncolor
455 Database Name: buttonColor
456 Database Class: ButtonColor
457 Specifies the foreground color which should be used for drawing
460 the outline and the plus or minus sign of the button to the left
461 of an item.
462 Command-Line Switch: -buttonimage
464 Database Name: buttonImage
465 Database Class: ButtonImage
466 Specifies the image to be used as the expand/collapse button to
469 the left of an item. This is a per-state option. If an image is
470 specified for a certain item state, it overrides the effects of
471 -buttonbitmap and -usetheme.
472 Command-Line Switch: -buttonsize
474 Database Name: buttonSize
475 Database Class: ButtonSize
476 Specifies the width and height of the button drawn to the left
479 of an item in any of the forms acceptable to Tk_GetPixels.
480 Command-Line Switch: -buttonthickness
482 Database Name: buttonThickness
483 Database Class: ButtonThickness
484 Specifies the width of the outline and the plus or minus sign of
487 the button to the left of an item in any of the forms acceptable
488 to Tk_GetPixels.
489 Command-Line Switch: -columnprefix
491 Database Name: columnPrefix
492 Database Class: ColumnPrefix
493 Specifies an ascii string that changes the way column ids are
496 reported and processed. If this option is a non-empty string,
497 the usual integer value of a column id is prefixed with the
498 given string. This can aid debugging but it is important your
499 code doesn't assume column ids are integers if you use it.
500 Command-Line Switch: -columnproxy
502 Database Name: columnProxy
503 Database Class: ColumnProxy
504 If this option specifies a non empty value, it should be a
507 screen distance in any of the forms acceptable to Tk_GetPixels.
508 Then a 1 pixel thick vertical line will be drawn at the speci‐
509 fied screen distance from the left edge of the treectrl widget,
510 which reaches from top to bottom of the treectrl widget and uses
511 an inverting color (i.e black on lighter background, white on
512 darker background). This line can be used to give the user a
513 visual feedback during column resizing.
514 Command-Line Switch: -columnresizemode
516 Database Name: columnResizeMode
517 Database Class: ColumnResizeMode
518 Specifies the visual feedback used when resizing columns. The
521 value should be one of proxy or realtime. For proxy, a 1-pixel
522 thick vertical line is drawn representing where the right edge
523 of the column will be after resizing. For realtime, the column's
524 size is changed while the user is dragging the right edge of the
525 column.
526 Command-Line Switch: -columntagexpr
528 Database Name: columnTagExpr
529 Database Class: ColumnTagExpr
530 Specifies a boolean that enables or disables tag expressions in
533 column descriptions. See ITEM AND COLUMN TAGS.
534 Command-Line Switch: -defaultstyle
536 Database Name: defaultStyle
537 Database Class: DefaultStyle
538 This option is deprecated; use the column option -itemstyle
541 instead. Specifies a list of styles, one per column, to apply
542 to each item created by the item create command. The number of
543 styles in the list can be different from the number of tree col‐
544 umns. Each list element should be a valid style name or an
545 empty string to indicate no style should be applied to a spe‐
546 cific column. The list of styles is updated if a style is
547 deleted or if a column is moved.
548 Command-Line Switch: -doublebuffer
550 Database Name: doubleBuffer
551 Database Class: DoubleBuffer
552 This option no longer has any effect, but was left in for com‐
555 patibility. It used to control the amount of double-buffering
556 that was used when displaying a treectrl.
557 Command-Line Switch: -height
559 Database Name: height
560 Database Class: Height
561 Specifies the desired height for the window in any of the forms
564 acceptable to Tk_GetPixels. The default is 200 pixels. If this
565 option is less than or equal to zero then the window will not
566 request any size at all.
567 Command-Line Switch: -indent
569 Database Name: indent
570 Database Class: Indent
571 Specifies the screen distance an item is indented relative to
574 its parent item in any of the forms acceptable to Tk_GetPixels.
575 The default is 19 pixels.
576 Command-Line Switch: -itemheight
578 Database Name: itemHeight
579 Database Class: ItemHeight
580 Specifies a fixed height for every item in any of the forms
583 acceptable to Tk_GetPixels. If non-zero, this option overrides
584 the requested height of an item and the -minitemheight option.
585 The default is 0, which means that every item has the height
586 requested by the arrangement of elements in each column. Items
587 are never shorter than the maximum height of a button.
588 Command-Line Switch: -itemprefix
590 Database Name: itemPrefix
591 Database Class: ItemPrefix
592 Specifies an ascii string that changes the way item ids are
595 reported and processed. If this option is a non-empty string,
596 the usual integer value of an item id is prefixed with the given
597 string. This can aid debugging but it is important your code
598 doesn't assume item ids are integers if you use it.
599 Command-Line Switch: -itemtagexpr
601 Database Name: itemTagExpr
602 Database Class: ItemTagExpr
603 Specifies a boolean that enables or disables tag expressions in
606 item descriptions. See ITEM AND COLUMN TAGS.
607 Command-Line Switch: -itemwidth
609 Database Name: itemWidth
610 Database Class: ItemWidth
611 Specifies a fixed width for every item in any of the forms
614 acceptable to Tk_GetPixels. If more than one column is visible,
615 then this option has no effect. If the -orient option is verti‐
616 cal, and the -wrap option is unspecified, then this option has
617 no effect (in that case all items are as wide as the column).
618 Command-Line Switch: -itemwidthequal
620 Database Name: itemWidthEqual
621 Database Class: ItemWidthEqual
622 Specifies a boolean that says whether all items should have the
625 same width. If more than one column is visible, then this
626 option has no effect. If the -orient option is vertical, and
627 the -wrap option is unspecified, then this option has no effect
628 (in that case all items are as wide as the column). If the
629 -itemwidth option is specified, then this option has no effect.
630 Command-Line Switch: -itemwidthmultiple
632 Database Name: itemWidthMultiple
633 Database Class: ItemWidthMultiple
634 Specifies a screen distance that every item's width will be
637 evenly divisible by in any of the forms acceptable to Tk_GetPix‐
638 els. If more than one column is visible, then this option has
639 no effect. If the -orient option is vertical, and the -wrap
640 option is unspecified, then this option has no effect (in that
641 case all items are as wide as the column). If the -itemwidth
642 option is specified, then this option has no effect.
643 Command-Line Switch: -linecolor
645 Database Name: lineColor
646 Database Class: LineColor
647 Specifies the color which should be used for drawing the con‐
650 necting lines between related items.
651 Command-Line Switch: -linestyle
653 Database Name: lineStyle
654 Database Class: LineStyle
655 Specifies the style of the connecting lines between related
658 items, should be dot which is the default, or solid.
659 Command-Line Switch: -linethickness
661 Database Name: lineThickness
662 Database Class: LineThickness
663 Specifies the thickness of the connecting lines between related
666 items in any of the forms acceptable to Tk_GetPixels.
667 Command-Line Switch: -minitemheight
669 Database Name: minItemHeight
670 Database Class: MinItemHeight
671 Specifies a minimum height for every item in any of the forms
674 acceptable to Tk_GetPixels. The default is 0, which means that
675 every item has the height requested by the arrangement of ele‐
676 ments in each column. This option has no effect if the
677 -itemheight option is specified. Items are never shorter than
678 the maximum height of a button.
679 Command-Line Switch: -rowproxy
681 Database Name: rowProxy
682 Database Class: RowProxy
683 If this option specifies a non empty value, it should be a
686 screen distance in any of the forms acceptable to Tk_GetPixels.
687 Then a 1 pixel thick horizontal line will be drawn at the speci‐
688 fied screen distance from the top edge of the treectrl widget,
689 which reaches from left to right of the treectrl widget and uses
690 an inverting color (i.e black on lighter background, white on
691 darker background). This line can be used to give the user a
692 visual feedback during row resizing.
693 Command-Line Switch: -scrollmargin
695 Database Name: scrollMargin
696 Database Class: ScrollMargin
697 Specifies a positive screen distance in any of the forms accept‐
700 able to Tk_GetPixels. This option is used by the default bind‐
701 ings to determine how close to the edges of the contentbox the
702 mouse pointer must be before scrolling occurs. Specifying a
703 positive value is useful when items may be drag-and-dropped.
704 Defaults to 0.
705 Command-Line Switch: -selectmode
707 Database Name: selectMode
708 Database Class: SelectMode
709 Specifies one of several styles for manipulating the selection.
712 The value of the option may be arbitrary, but the default bind‐
713 ings expect it to be either single, browse, multiple, or
714 extended; the default value is browse.
715 Command-Line Switch: -showbuttons
717 Database Name: showButtons
718 Database Class: ShowButtons
719 Specifies a boolean value that determines whether this widget
722 leaves indentation space to display the expand/collapse buttons
723 next to items. The default value is true. The item option
724 -button determines whether any item has a button. See also the
725 treectrl option -showrootbutton.
726 Command-Line Switch: -showheader
728 Database Name: showHeader
729 Database Class: ShowHeader
730 Specifies a boolean value that determines whether this widget
733 should display the header line with the column names at the top
734 of the widget. The default value is true.
735 Command-Line Switch: -showlines
737 Database Name: showLines
738 Database Class: ShowLines
739 Specifies a boolean value that determines whether this widget
742 should draw the connecting lines between related items. The
743 default value is true.
744 Command-Line Switch: -showroot
746 Database Name: showRoot
747 Database Class: ShowRoot
748 Specifies a boolean value that determines whether this widget
751 should draw the root item. By suppressing the drawing of the
752 root item the widget can have multiple items that appear as
753 toplevel items. The default value is true.
754 Command-Line Switch: -showrootbutton
756 Database Name: showRootButton
757 Database Class: ShowRootButton
758 Specifies a boolean value that determines whether this widget
761 leaves indentation space to display the expand/collapse button
762 next to the root item. The default value is false. The item
763 option -button determines whether the root item has a button.
764 Command-Line Switch: -showrootchildbuttons
766 Database Name: showRootChildButtons
767 Database Class: ShowRootChildButtons
768 Specifies a boolean value that determines whether this widget
771 should draw the expand/collapse buttons next to children of the
772 root item. The default value is true.
773 Command-Line Switch: -showrootlines
775 Database Name: showRootLines
776 Database Class: ShowRootLines
777 Specifies a boolean value that determines whether this widget
780 should draw the connecting lines between children of the root
781 item. The default value is true.
782 Command-Line Switch: -treecolumn
784 Database Name: treeColumn
785 Database Class: TreeColumn
786 Specifies a column description that determines which column dis‐
789 plays the buttons and lines. The default is unspecified.
790 Command-Line Switch: -usetheme
792 Database Name: useTheme
793 Database Class: UseTheme
794 Specifies a boolean value that determines whether this widget
797 should draw parts of itself using a platform-specific theme man‐
798 ager. The default is false.
799 Command-Line Switch: -width
801 Database Name: width
802 Database Class: Width
803 Specifies the desired width for the window in any of the forms
806 acceptable to Tk_GetPixels. The default is 200 pixel. If this
807 option is less than or equal to zero then the window will not
808 request any size at all.
809 Command-Line Switch: -wrap
811 Database Name: wrap
812 Database Class: Wrap
813 Specifies whether items are arranged in a 1- or 2-dimensional
816 layout.
817 If the value is an empty string (the default), then items are
819 arranged from top to bottom (-orient vertical) or from left to
820 right (-orient horizontal) in a 1-dimensional layout.
821 If the value is "N items", then no more than N items will appear
823 in a vertical group (-orient vertical) or horizontal group
824 (-orient horizontal).
825 If the value is "N pixels", then no vertical group of items will
827 be taller than N pixels (-orient vertical) or no horizontal
828 group of items will be wider than N pixels (-orient horizontal).
829 If the value is window, then a no vertical group of items will
831 be taller than the window (-orient vertical) or no horizontal
832 group of items will be wider than the window (-orient horizon‐
833 tal).
834 It is also possible to cause wrapping to occur on a per-item
836 basis by using the item option -wrap. See the item create com‐
837 mand for that option.
838 Command-Line Switch: -xscrolldelay
840 Database Name: xScrollDelay
841 Database Class: ScrollDelay
842 This option controls how quickly horizontal scrolling occurs
845 while dragging the mouse with button 1 pressed. The value
846 should be a list of 1 or 2 integers interpreted as microseconds.
847 If 2 values are specified, then the first value determines the
848 intial delay after the first scroll, and the second value deter‐
849 mines the delay for all scrolling after the first. If only 1
850 value is specified, each scroll takes place after that delay.
851 Command-Line Switch: -xscrollincrement
853 Database Name: xScrollIncrement
854 Database Class: ScrollIncrement
855 Specifies an increment for horizontal scrolling, in any of the
858 usual forms permitted for screen distances. If the value of
859 this option is greater than zero, the horizontal view in the
860 window will be constrained so that the x coordinate at the left
861 edge of the window is always an even multiple of -xscrollincre‐
862 ment; furthermore, the units for scrolling (e.g., the change in
863 view when the left and right arrows of a scrollbar are selected)
864 will also be -xscrollincrement. If the value of this option is
865 less than or equal to zero, then horizontal scrolling snaps to
866 the left of an item, or part of an item if items are wider than
867 the contentbox.
868 Command-Line Switch: -yscrolldelay
870 Database Name: yScrollDelay
871 Database Class: ScrollDelay
872 This option controls how quickly vertical scrolling occurs while
875 dragging the mouse with button 1 pressed. The value should be a
876 list of 1 or 2 integers interpreted as microseconds. If 2 val‐
877 ues are specified, then the first value determines the intial
878 delay after the first scroll, and the second value determines
879 the delay for all scrolling after the first. If only 1 value is
880 specified, each scroll takes place after that delay.
881 Command-Line Switch: -yscrollincrement
883 Database Name: yScrollIncrement
884 Database Class: ScrollIncrement
885 Specifies an increment for vertical scrolling, in any of the
888 usual forms permitted for screen distances. If the value of
889 this option is greater than zero, the vertical view in the win‐
890 dow will be constrained so that the y coordinate at the top edge
891 of the window is always an even multiple of -yscrollincrement;
892 furthermore, the units for scrolling (e.g., the change in view
893 when the top and bottom arrows of a scrollbar are selected) will
894 also be -yscrollincrement. If the value of this option is less
895 than or equal to zero, then vertical scrolling snaps to the top
896 of an item, or part of an item if items are taller than the con‐
897 tentbox.
898
900 Columns and items may have any number of tags associated with them. A
901 tag is just a string of characters, and it may take any form, including
902 that of an integer, although the characters '(', ')', '&', '|', '^' and
903 '!' should be avoided.
904 The same tag may be associated with many columns or items. This is com‐
906 monly done to group items in various interesting ways; for example, in
907 a file browser all directories might be given the tag "directory".
908 Tag expressions are used in column descriptions and item descriptions
910 to specify which columns and items to operate on. A tag expression can
911 be a single tag name or a logical expression of tags using operators
912 '&&', '||', '^' and '!', and parenthesized subexpressions. For exam‐
913 ple:
914 or equivalently:
917 will return the unique ids of any items with either "a" or "b" tags,
920 but not both.
921 Within a tag expression a tag name may be enclosed in double quotes to
923 avoid special processing of the operator characters. For example:
924 will return the unique ids of any items with either "a&&b" or "c" tags;
927 in this example the && is not treated as an operator. A double-quote
928 may be escaped within a quoted tag name using a backslash '\'.
929 Tag operators may be bypassed completely by setting the -columntagexpr
931 and -itemtagexpr options. This can be useful if your application has
932 column or item tags containing arbitrary text.
933
937 The treectrl command creates a new Tcl command whose name is the same
938 as the path name of the treectrl's window. This command may be used to
939 invoke various operations on the widget. It has the following general
940 form:
941 pathName option ?arg arg ...?
943 PathName is the name of the command, which is the same as the treectrl
945 widget's path name. Option and the args determine the exact behavior
946 of the command. The following commands are possible for treectrl wid‐
947 gets:
948 pathName activate itemDesc
950 Sets the active item to the one described by itemDesc, and
951 switches on the state active for this item. From now on the
952 item can be retrieved with the item description active. An
953 <ActiveItem> event is generated.
954 pathName bbox ?area?
956 Returns a list with four elements giving the bounding box (left,
957 top, right and bottom) of an area of the window. If area is not
958 specified, then the result is the bounding box of the entire
959 window. If area is content, then the result is the part of the
960 window not including borders, headers, or locked columns. If
961 area is header, then the result is the part of the window not
962 including borders where column titles are displayed. If area is
963 left, then the result is the part of the window not including
964 borders or headers where left-locked columns are displayed. If
965 area is right, then the result is the part of the window not
966 including borders or headers where right-locked columns are dis‐
967 played. An empty string is returned if the display area has no
968 height or width, which can be true for various reasons such as
969 the window is too small, or the header is not displayed, or
970 there aren't any locked columns.
971 pathName canvasx screenx
973 Given a window x-coordinate in the treectrl screenx, this com‐
974 mand returns the treectrl x-coordinate that is displayed at that
975 location.
976 pathName canvasy screeny
978 Given a window y-coordinate in the treectrl screeny, this com‐
979 mand returns the treectrl y-coordinate that is displayed at that
980 location.
981 pathName cget option
983 Returns the current value of the configuration option given by
984 option. Option may have any of the values accepted by the tree
985 command.
986 pathName collapse ?-recurse? ?itemDesc ...?
988 Use item collapse instead.
989 pathName column option column ?arg ...?
991 This command is used to manipulate the columns of the treectrl
992 widget (see section COLUMNS below). The exact behavior of the
993 command depends on the option argument that follows the column
994 argument. The following forms of the command are supported:
995 pathName column bbox columnDesc
997 Returns a list with four elements giving the bounding box
998 of the header of the column specified by the column
999 description columnDesc. If the treectrl is configured
1000 not to display the column headers by means of the -show‐
1001 header option, then an empty list is returned instead.
1002 pathName column cget columnDesc option
1004 This command returns the current value of the option
1005 named option for the column specified by the column
1006 description columnDesc, ColumnDesc may also be the string
1007 tail to specify the tail column. Option may have any of
1008 the values accepted by the column configure widget com‐
1009 mand.
1010 pathName column configure columnDesc ?option? ?value? ?option
1012 value ...?
1013 This command is similar to the configure widget command
1014 except that it modifies options associated with the col‐
1015 umns specified by the column description columnDesc
1016 instead of modifying options for the overall treectrl
1017 widget. ColumnDesc may be the string tail to specify the
1018 tail column. If columnDesc refers to more than one col‐
1019 umn, then at least one option-value pair must be given.
1020 If no option is specified, the command returns a list
1021 describing all of the available options for columnDesc
1022 (see Tk_ConfigureInfo for information on the format of
1023 this list). If option is specified with no value, then
1024 the command returns a list describing the one named
1025 option (this list will be identical to the corresponding
1026 sublist of the value returned if no option is specified).
1027 If one or more option-value pairs are specified, then the
1028 command modifies the given option(s) to have the given
1029 value(s) for columnDesc; in this case the command returns
1030 an empty string.
1031 See COLUMNS below for details on the options available
1033 for columns.
1034 pathName column compare column1 op column2
1036 For both column descriptions column1 and column2 the
1037 index is retrieved (as returned from the column order
1038 widget command). Then these indexes are compared using
1039 the operator op, which must be either <, <=, ==, >=, >,
1040 or !=. The return value of this command is 1 if the com‐
1041 parison evaluated to true, 0 otherwise.
1042 pathName column count ?columnDesc?
1044 If no additional arguments are given, the result is a
1045 decimal string giving the number of columns created by
1046 the column create widget command which haven't been
1047 deleted by the column delete widget command; in this case
1048 the tail column is not counted. If columnDesc is given,
1049 then the result is the number of columns that match that
1050 column description.
1051 pathName column create ?option value ...?
1053 This command creates a new column in the treectrl widget.
1054 The new column is placed to the right of all other col‐
1055 umns (except the tail column). Any option-value arguments
1056 configure the new column according to the column config‐
1057 ure command. The return value is the unique identifier of
1058 the new column.
1059 pathName column delete first ?last?
1061 Deletes the specified column(s). First and last must be
1062 valid column descriptions. If both first and last are
1063 specified, then they may refer to a single column only.
1064 The tail column cannot be deleted and it is an error to
1065 specify it. The order of first and last doesn't matter,
1066 and first may be equal to last.
1067 pathName column dragcget option
1069 pathName column dragconfigure ?option? ?value? ?option value
1071 ...?
1072 The user can move a column within a treectrl by drag-and-
1073 drop. Feedback consists of a semi-transparent photo image
1074 of the header of the column being dragged and a 2-pixel-
1075 thick vertical line to indicate where the column may be
1076 dropped. The drag image consists of a colored background
1077 rectangle plus the image and/or text displayed in the
1078 column header. The 2-pixel-thick line will be drawn over
1079 the left edge of the column before which the dragged col‐
1080 umn may be dropped.
1081 The library scripts generate a <ColumnDrag-accept> event
1083 when the user has successfully drag-and-drop'd a column.
1084 You will have to bind a script to this event if you want
1085 to move the dragged column.
1086 The following configuration options are supported:
1088 -enable boolean
1090 Controls whether the user is allowed to rearrange
1091 columns by drag-and-drop.
1092 -imagealpha alpha
1094 Alpha is an integer from 0 (invisible) to 255
1095 (opaque) controlling the transparency of the drag
1096 image. Any value outside this range is clipped.
1097 -imagecolor background
1099 Background is the color of the drag image back‐
1100 ground rectangle.
1101 -imagecolumn column
1103 Column specifies the column to create the drag
1104 image from.
1105 -imageoffset offset
1107 Offset is the horizontal screen distance the drag
1108 image is offset from its starting position.
1109 -indicatorcolor color
1111 Color is the color of the 2-pixel-thick line.
1112 -indicatorcolumn column
1114 The 2-pixel-thick line will be drawn over the left
1115 or right edge of column.
1116 -indicatorside side
1118 Specifies whether the 2-pixel-thick line will be
1119 drawn over the left or right edge of the column
1120 specified by -indicatorcolumn.
1121 pathName column index columnDesc
1123 Deprecated. Use column id instead.
1124 pathName column id columnDesc
1126 This command resolves the column description columnDesc
1127 into a list of unique column identifiers. If the col‐
1128 umn(s) described by columnDesc don't exist, this command
1129 returns an empty list.
1130 pathName column list ?-visible?
1132 This command returns a list of identifiers for every col‐
1133 umn (except the tail) from left to right. If -visible is
1134 given, only columns whose -visible option is true are
1135 returned.
1136 pathName column move columnDesc beforeDesc
1138 Moves the column specified by columnDesc to the left of
1139 the column specified by beforeDesc. Both columnDesc and
1140 beforeDesc must be valid column descriptions. If before‐
1141 Desc is the string tail, the column columnDesc will
1142 become the last column.
1143 pathName column neededwidth columnDesc
1145 This command returns a decimal string giving the needed
1146 width of the column specified by the column description
1147 columnDesc. The needed width is the maximum of the width
1148 of the column header and the width of the widest style in
1149 any visible item.
1150 pathName column order columnDesc ?-visible?
1152 This command returns a decimal string giving the position
1153 of the column specified by the column description column‐
1154 Desc in the list of columns starting from zero for the
1155 leftmost column. If -visible is given, only columns
1156 whose -visible option is true are considered, and -1 is
1157 returned if columnDesc's -visible option is false.
1158 pathName column tag option ?arg arg ...?
1160 This command is used to manipulate tags on columns. The
1161 exact behavior of the command depends on the option argu‐
1162 ment that follows the column tag argument. The following
1163 forms of the command are supported:
1164 pathName column tag add columnDesc tagList
1166 Adds each tag in tagList to the columns specified
1167 by the column description columnDesc. Duplicate
1168 tags are ignored. The list of tags for a column
1169 can also be changed via a column's -tags option.
1170 pathName column tag expr columnDesc tagExpr
1172 Evaluates the tag expression tagExpr against every
1173 column specified by the column description column‐
1174 Desc. The result is 1 if the tag expression evalu‐
1175 ates to true for every column, 0 otherwise.
1176 pathName column tag names columnDesc
1178 Returns a list of tag names assigned to the col‐
1179 umns specified by the column description column‐
1180 Desc. The result is the union of any tags assigned
1181 to the columns.
1182 pathName column tag remove columnDesc tagList
1184 Removes each tag in tagList from the columns spec‐
1185 ified by the column description columnDesc. It is
1186 not an error if any of the columns do not use any
1187 of the tags. The list of tags for a column can
1188 also be changed via a column's -tags option.
1189 pathName column width columnDesc
1191 This command returns a decimal string giving the width in
1192 pixels of the column specified by the column description
1193 columnDesc, even if the treectrl is configured to not
1194 display the column headers by means of the -showheader
1195 option.
1196 pathName compare itemDesc1 op itemDesc2
1198 Deprecated. Use the item compare command instead.
1199 pathName configure ?option? ?value option value ...?
1201 Query or modify the configuration options of the widget. If no
1202 option is specified, returns a list describing all of the avail‐
1203 able options for pathName (see Tk_ConfigureInfo for information
1204 on the format of this list). If option is specified with no
1205 value, then the command returns a list describing the one named
1206 option (this list will be identical to the corresponding sublist
1207 of the value returned if no option is specified). If one or
1208 more option-value pairs are specified, then the command modifies
1209 the given widget option(s) to have the given value(s); in this
1210 case the command returns an empty string. Option may have any
1211 of the values accepted by the treectrl command.
1212 pathName contentbox
1214 Returns a list with four elements giving the bounding box of the
1215 screen area used to display items. This is the area of the win‐
1216 dow not including borders, column headers, or locked columns. An
1217 empty string is returned if the display area has no height or
1218 width, which can happen if the window is too small.
1219 pathName debug option ?arg arg ...?
1221 This command is used to facilitate debugging of the treectrl
1222 widget. The exact behavior of the command depends on the option
1223 argument that follows the debug argument. The following forms
1224 of the command are supported:
1225 pathName debug alloc
1227 Returns a string giving partial statistics on memory
1228 allocations, if the package was built with TREECTRL_DEBUG
1229 defined.
1230 pathName debug cget option
1232 This command returns the current value of the debugging
1233 option named option. Option may have any of the values
1234 accepted by the debug configure widget command.
1235 pathName debug configure ?option? ?value? ?option value ...?
1237 This command is similar to the configure widget command
1238 except that it modifies debugging options instead of mod‐
1239 ifying options for the overall treectrl widget. If no
1240 option is specified, the command returns a list describ‐
1241 ing all of the available debugging options (see Tk_Con‐
1242 figureInfo for information on the format of this list).
1243 If option is specified with no value, then the command
1244 returns a list describing the one named option (this list
1245 will be identical to the corresponding sublist of the
1246 value returned if no option is specified). If one or
1247 more option-value pairs are specified, then the command
1248 modifies the given debugging option(s) to have the given
1249 value(s); in this case the command returns an empty
1250 string.
1251 The following debugging options are supported:
1253 -displaydelay millis
1255 Specifies a time duration in milliseconds, which
1256 should be waited after something has been drawn to
1257 the screen. Setting this option has only an
1258 effect, if the debugging options -enable and -dis‐
1259 play are switched on.
1260 -data boolean
1262 If this option is switched on (together with the
1263 debugging option -enable), at various places a
1264 consistence check on the internal data structure
1265 is made (e.g. for every item is checked, if the
1266 registered number of children is equal to the num‐
1267 ber of child items). If an inconsistency was
1268 found, a Tcl background error is raised.
1269 -display boolean
1271 If this option is switched on (together with the
1272 debugging option -enable), at varios places addi‐
1273 tional debugging output is printed to stdout.
1274 -drawcolor color
1276 When specified, areas of the window are painted
1277 with this color when drawing in those areas is
1278 about to occur. Setting this option has only an
1279 effect if the debugging options -enable and -dis‐
1280 play are switched on.
1281 -enable boolean
1283 All other debugging options only take effect if
1284 this option is also switched on.
1285 -erasecolor color
1287 When specified, areas of the window which have
1288 been marked as "invalid" (for example, when part
1289 of the window is exposed) are painted with this
1290 color. If you use an unusual color for this
1291 option (like pink), superflous screen redraws can
1292 be spotted more easily. Setting this option has
1293 only an effect if the debugging options -enable
1294 and -display are switched on.
1295 -span boolean
1297 Debugging related to column spanning.
1298 -textlayout boolean
1300 Debugging related to text-element layout.
1301 pathName debug dinfo option
1303 Returns a string describing display-related stuff. Option
1304 must be one of alloc, ditem, onscreen or range.
1305 pathName debug expose x1 y1 x2 y2
1307 Causes the area of the window bounded by the given win‐
1308 dow-coords to be marked as invalid. This simulates uncov‐
1309 ering part of the window.
1310 pathName debug scroll
1312 Returns a string useful for debugging vertical scrolling.
1313 pathName depth ?itemDesc?
1315 If the additional argument itemDesc is given, then the result is
1316 a decimal string giving the depth of the item described by
1317 itemDesc. If no itemDesc is specified, then the maximum depth
1318 of all items in the treectrl widget is returned instead. Depth
1319 is defined as the number of ancestors an item has.
1320 pathName dragimage option ?arg ...?
1322 This command is used to manipulate the dragimage, one or more
1323 dotted lines around rectangular regions of the treectrl widget.
1324 The exact behavior of the command depends on the option argument
1325 that follows the dragimage argument. The following forms of the
1326 command are supported:
1327 pathName dragimage add itemDesc ?column? ?element?
1329 Adds the shapes of the item described by itemDesc to the
1330 shapes of the dragimage. Specifying additional arguments
1331 reduces the number of rectangles that are added to the
1332 dragimage. If no additional arguments is specified, for
1333 every element of the item in every column a dotted rec‐
1334 tangles is added. If column is specified, all elements
1335 in other columns are ignored. If also element is speci‐
1336 fied, only a rectangle for this one element of the speci‐
1337 fied item in the given column is added.
1338 pathName dragimage cget option
1340 This command returns the current value of the dragimage
1341 option named option. Option may have any of the values
1342 accepted by the dragimage configure widget command.
1343 pathName dragimage clear
1345 Removes all shapes (if there are any) from the dragimage.
1346 This command does not modify the dragimage offset.
1347 pathName dragimage configure ?option? ?value? ?option value ...?
1349 This command is similar to the configure widget command
1350 except that it modifies the dragimage options instead of
1351 modifying options for the overall treectrl widget. If no
1352 option is specified, the command returns a list describ‐
1353 ing all of the available dragimage options (see Tk_Con‐
1354 figureInfo for information on the format of this list).
1355 If option is specified with no value, then the command
1356 returns a list describing the one named dragimage option
1357 (this list will be identical to the corresponding sublist
1358 of the value returned if no option is specified). If one
1359 or more option-value pairs are specified, then the com‐
1360 mand modifies the given dragimage option(s) to have the
1361 given value(s); in this case the command returns an empty
1362 string.
1363 The following dragimage options are supported:
1365 -visible boolean
1367 Specifies a boolean value which determines whether
1368 the dragimage should currently be visible.
1369 pathName dragimage offset ?x y?
1371 Returns a list containing the x and y offsets of the
1372 dragimage, if no additional arguments are specified. The
1373 dragimage offset is the screen distance, the image is
1374 displayed relative to the item its shape is derived from.
1375 If two coordinates are specified, sets the dragimage off‐
1376 set to the given coordinates x and y.
1377 pathName element option ?element? ?arg arg ...?
1379 This command is used to manipulate elements (see ELEMENTS
1380 below). The exact behavior of the command depends on the option
1381 argument that follows the element argument. The following forms
1382 of the command are supported:
1383 pathName element cget element option
1385 This command returns the current value of the option
1386 named option associated with the element given by ele‐
1387 ment. Option may have any of the values accepted by the
1388 element configure widget command.
1389 pathName element configure element ?option? ?value? ?option
1391 value ...?
1392 This command is similar to the configure widget command
1393 except that it modifies options associated with the ele‐
1394 ment given by element instead of modifying options for
1395 the overall treectrl widget. If no option is specified,
1396 the command returns a list describing all of the avail‐
1397 able options for element (see Tk_ConfigureInfo for infor‐
1398 mation on the format of this list). If option is speci‐
1399 fied with no value, then the command returns a list
1400 describing the one named option (this list will be iden‐
1401 tical to the corresponding sublist of the value returned
1402 if no option is specified). If one or more option-value
1403 pairs are specified, then the command modifies the given
1404 option(s) to have the given value(s) in element; in this
1405 case the command returns an empty string. See ELEMENTS
1406 below for details on the options available for elements.
1407 pathName element create element type ?option value ...?
1409 Create a new elememt in pathName of type type with name
1410 element. The exact format of the arguments after type
1411 depends on type, but generally consist of specifications
1412 for zero or more element options. See the subsections on
1413 individual element types below for more on the syntax of
1414 this command. This command returns the name for the new
1415 element.
1416 pathName element delete ?element ...?
1418 Deletes each of the named elements and returns an empty
1419 string. If an element is deleted while it is still con‐
1420 figured as an element of one or more styles by means of
1421 the style elements widget command, it is also removed
1422 from the element lists of these styles.
1423 pathName element names
1425 Returns a list containing the names of all existing ele‐
1426 ments.
1427 pathName element perstate element option stateList
1429 This command returns the value of the per-state option
1430 named option for element for a certain state. StateList
1431 is a list of state names (static and dynamic, see STATES)
1432 which specifies the state to use.
1433 pathName element type element
1435 Returns the type of the element given by element, such as
1436 rect or text.
1437 pathName expand ?-recurse? ?itemDesc ...?
1439 Use item expand instead.
1440 pathName identify x y
1442 Returns a list describing what is displayed at the given window
1443 coordinates x and y. If the coordinates are outside the window,
1444 over the borders, or over any whitespace in the window, then the
1445 result is an empty string; otherwise the first word of the
1446 result is header or item.
1447 If the coordinates are over a column header, then the first word
1449 of the result is header, followed by the unique id of the column
1450 (or the string tail). If the x coordinate is near the left or
1451 right end of a column, then a third word left or right is
1452 appended to the result.
1453 If the coordinates are over an item, then the first word of the
1455 result is item followed by the unique id of that item. If the
1456 coordinates are not over the area for displaying buttons and
1457 lines, then column and a unique column id are the 3rd and 4th
1458 words of the result. If the coordinates are over an element
1459 within that column, then element and an element name are the 5th
1460 and 6th words of the result.
1461 If the coordinates are over a button, then the first word of the
1463 result is item, followed by the unique id of that item, followed
1464 by the word button.
1465 If the coordinates are over a line descending from an ancestor
1467 of an item (but not the parent of that item), then the first
1468 word of the result is item, followed by the unique id of that
1469 item, followed by the word line, followed by the unique id of
1470 the item the line is coming from. This is used to collapse the
1471 ancestor when the line is clicked on.
1472 pathName index itemDesc
1474 Deprecated. Use item id instead.
1475 pathName item option ?arg ...?
1477 This command is used to manipulate items. The exact behavior of
1478 the command depends on the option argument that follows the item
1479 argument. The following forms of the command are supported:
1480 pathName item ancestors itemDesc
1482 Returns a list containing the item ids of the ancestors
1483 of the item specified by itemDesc. The first list value
1484 is the parent, the second is the parent's parent, an so
1485 on. The last list value will be the root item if itemDesc
1486 is a descendant of the root item.
1487 pathName item bbox itemDesc ?column? ?element?
1489 Returns a list with four elements giving the bounding box
1490 of the item described by itemDesc. If no further argu‐
1491 ment is specified, the bbox spans the area of the item
1492 over all non-locked columns. If a column is specified,
1493 only the area of the item in this column is considered.
1494 If an additional element is specified, the area of this
1495 element in column of the specified item is returned.
1496 pathName item cget itemDesc option
1498 Returns the current value of the configuration option for
1499 the item specified by itemDesc whose name is option.
1500 Option may have any of the values accepted by the item
1501 configure command.
1502 pathName item children itemDesc
1504 Returns a list containing the item ids of all children of
1505 the item specified by itemDesc in the correct order from
1506 the first child to the last child.
1507 pathName item collapse itemDesc ?-recurse?
1509 Switches off the open state of the item(s) described by
1510 itemDesc. If an item has descendants, then they are no
1511 longer displayed. If an item is already closed, then
1512 this command has no effect on that item. If -recurse is
1513 specified, then all descendants of the items described by
1514 itemDesc will also be collapsed. For every item that
1515 actually will be collapsed, two events are generated: a
1516 <Collapse-before> event before the item state is changed,
1517 and a <Collapse-after> event after the item state was
1518 changed.
1519 pathName item compare itemDesc1 op itemDesc2
1521 From both items described by the itemDescs the index is
1522 retrieved (as returned from the item order widget com‐
1523 mand). Then these indexes are compared using the opera‐
1524 tor op, which must be either <, <=, ==, >=, >, or !=.
1525 The return value of this command is 1 if the comparison
1526 evaluated to true, 0 otherwise.
1527 pathName item complex itemDesc ?list...?
1529 This horrible command is now deprecated. Use item element
1530 configure instead. For every column of the treectrl there
1531 may be specified one list. Each list should look like
1532 this:
1533 { {element option value ...} {element option value ...} ...}
1535 Every option must be known by the element's type (see
1537 ELEMENTS below). Each option will be set to value for
1538 the element in this one column in this item.
1539 pathName item configure itemDesc ?option? ?value? ?option value
1541 ...?
1542 If no option is specified, returns a list describing all
1543 of the available options for the item given by itemDesc
1544 (see Tk_ConfigureInfo for information on the format of
1545 this list). If option is specified with no value, then
1546 the command returns a list describing the one named
1547 option (this list will be identical to the corresponding
1548 sublist of the value returned if no option is specified).
1549 If one or more option-value pairs are specified, then the
1551 command modifies the given item option(s) to have the
1552 given value(s); in this case the command returns an empty
1553 string. This is the only case where itemDesc may refer to
1554 multiple items.
1555 The following options are supported by this command (see
1557 item create for the meaning of each option):
1558 -button boolean|auto
1560 -height height
1562 -tags tagList
1564 -visible boolean
1566 -wrap boolean
1568 pathName item count ?itemDesc?
1570 If no additional arguments are given, the result is a
1571 decimal string giving the number of items created by the
1572 item create widget command which haven't been deleted by
1573 the item delete widget command, plus 1 for the ever-
1574 present root item. If the optional argument itemDesc is
1575 given, then the result is the number of items that match
1576 that item description.
1577 pathName item create ?option value ...?
1579 Creates some new items and optionally returns a list of
1580 unique identifiers for those items. The new items have
1581 the states open and enabled set by default. If the
1582 treectrl widget currently has the focus, the state focus
1583 is also set.
1584 The following options are supported by this command:
1586 -button boolean|auto
1588 The value of this option must have one of the
1589 forms accepted by Tcl_GetBoolean or be the word
1590 auto (or any abbreviation of it). It indicates
1591 whether or not an expand/collapse button should be
1592 drawn next to the item, typically to indicate that
1593 the item has children. If the value of this
1594 option is auto, then a button is displayed next to
1595 the item whenever the item has any children whose
1596 item option -visible is true. The button will
1597 only be displayed if:
1598 [1] the column specified by the treectrl option
1600 -treecolumn is visible, and
1601 [2] the treectrl option -showbuttons is true,
1603 and
1604 [3] for the root item, the treectrl option
1606 -showrootbutton is true.
1607 -count numItems
1609 Specifies the number of items to create. Must be
1610 >= 0. Defaults to 1.
1611 -height height
1613 Specifies a fixed height in any of the forms
1614 acceptable to Tk_GetPixels. Must be >= 0. If
1615 height is zero then the item's height is unspeci‐
1616 fied. Defaults to 0.
1617 -nextsibling itemDesc
1619 Specifies the item before which the new items will
1620 be inserted. The new items will have the same par‐
1621 ent as itemDesc.
1622 -open boolean
1624 Specifies whether the items should be open or
1625 closed. Default is true.
1626 -parent itemDesc
1628 Specifies the item which the new items will be the
1629 children of. The new items will be appended to the
1630 list of children of itemDesc.
1631 -prevsibling itemDesc
1633 Specifies the item after which the new items will
1634 be inserted. The new items will have the same par‐
1635 ent as itemDesc.
1636 -returnid boolean
1638 Specifies whether or not to return a list of item
1639 identifiers for the newly created items. Specify‐
1640 ing false is useful when creating a large number
1641 of items in the console or to improve performance.
1642 Default is true.
1643 -tags tagList
1645 TagList is a list of tag names to be added to the
1646 new items.
1647 -visible boolean
1649 Boolean must have one of the forms accepted by
1650 Tcl_GetBoolean. It indicates that the item should
1651 be displayed in the list. The item will only be
1652 displayed if: a) each ancestor is a descendant of
1653 the root item (not an orphan); and b) each ances‐
1654 tor's -visible option is true
1655 -wrap boolean
1657 Boolean must have one of the forms accepted by
1658 Tcl_GetBoolean. It indicates that this item should
1659 be the first one in a horizontal range or vertical
1660 range of items. See also the widget option -wrap.
1661 pathName item delete first ?last?
1663 Deletes the specified item(s). First and last must be
1664 valid item descriptions. If last isn't specified, then
1665 first may specify multiple items. If both first and last
1666 are specified, they must each decribe a single item with
1667 a common ancestor; then the range of items between first
1668 and last is deleted. The order of first and last doesn't
1669 matter.
1670 Deleting an item deletes any child items of the deleted
1672 item recursively. If the current active item is deleted,
1673 the root item becomes the new active item. If the cur‐
1674 rent selection anchor item is deleted, the root item
1675 becomes the new anchor item. There is no way to delete
1676 the root item of the treectrl widget; in all cases the
1677 specification of the root item is ignored.
1678 For each call to this command, two events may be gener‐
1680 ated. If any of the deleted items are selected, then a
1681 <Selection> event is generated just before the items are
1682 deleted. If any items are going to be deleted, then an
1683 <ItemDelete> event event is generated just before the
1684 items are deleted.
1685 pathName item descendants itemDesc
1687 Returns a list containing the item ids of the descendants
1688 of the item specified by itemDesc, i.e. the children,
1689 grandchildren, great-grandchildren etc, of the item.
1690 pathName item dump itemDesc
1692 Returns a list with 4 words in the form index index
1693 indexVis indexVis.
1694 pathName item element command itemDesc column element ?arg ...?
1696 This command is used to manipulate elements of the item.
1697 The exact behavior of the command depends on the command
1698 argument that follows the element argument. The follow‐
1699 ing forms of the command are supported:
1700 pathName item element actual itemDesc column element
1702 option
1703 Deprecated. Use item element perstate instead.
1704 pathName item element cget itemDesc column element option
1706 This command returns the value of the option named
1707 option associated with element inside column of
1708 the item described by itemDesc, if it was already
1709 configured for the actual item. Option may have
1710 any of the values accepted by the type of the
1711 specified element (see ELEMENTS below)
1712 pathName item element configure itemDesc column element
1714 ?option? ?value? ?option value ...?
1715 This command modifies configuration options for an
1716 element in a column of an item. If no option is
1717 specified, the command returns a list describing
1718 all of the available options for the element (see
1719 Tk_ConfigureInfo for information on the format of
1720 this list). If option is specified with no value,
1721 then the command returns a list describing the one
1722 named option (this list will be identical to the
1723 corresponding sublist of the value returned if no
1724 option is specified).
1725 If one or more option-value pairs are specified,
1727 then the command modifies the given option(s) to
1728 have the given value(s) in the element inside col‐
1729 umn of the item(s) described by itemDesc; in this
1730 case the command returns an empty string. This is
1731 the only case where itemDesc may refer to multiple
1732 items.
1733 It is possible to configure multiple elements in
1735 multiple columns with a single call. To configure
1736 another element in the same column, append a ´+'
1737 argument followed by the element name. To config‐
1738 ure elements in another column, append a ',' argu‐
1739 ment followed by the column. For example:
1740 $C1 $E1 -text "hello" + $E2 -text "world" , \
1742 $C2 $E3 -fill Blue , \
1743 $C3 $E1 -text "apples and oranges"
1744 Each of the column description arguments to this
1746 command may refer to multiple columns if at least
1747 one option-value pair is given.
1748 pathName item element perstate itemDesc column element
1750 option ?stateList?
1751 This command returns the current value of the per-
1752 state option named option for element inside col‐
1753 umn of the item described by itemDesc. If
1754 stateList is specified, the list of state names
1755 (static and dynamic, see STATES) is used in place
1756 of the current state for item and column.
1757 pathName item enabled itemDesc ?boolean?
1759 Returns 1 if the item described by itemDesc has the state
1760 enabled switched on, 0 otherwise. If boolean is speci‐
1761 fied, then the enabled state of every item described by
1762 the item description itemDesc is set accordingly. All
1763 items are enabled when first created. Disabled items can‐
1764 not be selected, and are ignored by the default key-navi‐
1765 gation and mouse bindings.
1766 pathName item expand itemDesc ?-recurse?
1768 Switches on the open state of the item(s) described by
1769 itemDesc. If an item has descendants, then they are now
1770 displayed. If an item is already open, then this command
1771 has no effect on that item. If -recurse is specified,
1772 then all descendants of the items described by itemDesc
1773 will also be expanded. For every item that actually will
1774 be expanded, two events are generated: an <Expand-before>
1775 event before the item state is changed, and an <Expand-
1776 after> event after the item state was changed.
1777 pathName item firstchild parent ?child?
1779 If child is not specified, returns the item id of the
1780 first child of the item described by parent. If child is
1781 specified, it must describe an item that is neither the
1782 root item nor an ancestor of parent. Then it will become
1783 the new first child of parent.
1784 pathName item id itemDesc
1786 This command resolves the item description itemDesc into
1787 a list of unique item identifiers. If itemDesc doesn't
1788 refer to any existing items, then this command returns an
1789 empty list.
1790 pathName item image itemDesc ?column? ?image? ?column image ...?
1792 This command sets or retrieves the value of the per-state
1793 -image option for the first image element in one or more
1794 columns. If no column is specified, this command returns
1795 a list of values, one per column. If no image is speci‐
1796 fied, this command returns the value for column.
1797 If one or more column-image pairs is specified, then the
1799 value of the -image option in each column is set to
1800 image. In this case itemDesc may refer to multiple items
1801 and each column may refer to multiple columns.
1802 Note that this command is provided as a convenience. Use
1804 the item element configure or item element cget commands
1805 if you want to set or retrieve the value of the -image
1806 option for a specific image element.
1807 pathName item isancestor itemDesc descendant
1809 Returns 1 if the item described by itemDesc is a direct
1810 or indirect parent of the item decribed by descendant, 0
1811 otherwise.
1812 pathName item isopen itemDesc
1814 Returns 1 if the item described by itemDesc has the state
1815 open switched on, 0 otherwise.
1816 pathName item lastchild parent ?child?
1818 If child is not specified, returns the item id of the
1819 last child of the item described by parent. If child is
1820 specified, it must describe an item that is not an ances‐
1821 tor of parent. Then it will become the new last child of
1822 parent.
1823 pathName item nextsibling sibling ?next?
1825 If next is not specified, returns the item id of the next
1826 sibling of the item described by sibling. If next is
1827 specified, it must describe an item that is not an ances‐
1828 tor of sibling. Then it will become the new next sibling
1829 of sibling.
1830 pathName item numchildren itemDesc
1832 Returns the number of children of the item described by
1833 itemDesc.
1834 pathName item order itemDesc ?-visible?
1836 This command returns the position of the item itemDesc
1837 relative to its toplevel ancestor (usually the root item,
1838 unless the ancestor is an orphan). If you imagine all the
1839 items flattened into a vertical list, the result of this
1840 command is the row the item falls in. If the optional
1841 argument -visible is given, only the items whose ances‐
1842 tors are expanded, and whose -visible option is true, get
1843 counted; in this case -1 is returned if the item is not
1844 visible.
1845 pathName item parent itemDesc
1847 Returns the item id of the parent of the item described
1848 by itemDesc.
1849 pathName item prevsibling sibling ?prev?
1851 If prev is not specified, returns the item id of the pre‐
1852 vious sibling of the item described by sibling. If prev
1853 is specified, it must describe an item that is not an
1854 ancestor of sibling. Then it will become the new previ‐
1855 ous sibling of sibling.
1856 pathName item range first last
1858 Returns a list containing the item ids of all items in
1859 the range between first and last, inclusive. The order
1860 between first and last doesn't matter, and the result is
1861 always sorted by the increasing order of the items (as
1862 returned by the item order command). The items specified
1863 by first and last must share a common ancestor.
1864 pathName item remove itemDesc
1866 Removes the item described by itemDesc from the list of
1867 children of its parent, so that it will become an orphan.
1868 pathName item rnc itemDesc
1870 Returns a list of two integers, which corresponds to the
1871 row and column of the item described by itemDesc. The row
1872 and column corresponds to the on-screen arrangement of
1873 items as determined by the -orient and -wrap options. If
1874 the item is not displayed, this command returns an empty
1875 string.
1876 pathName item sort itemDesc ?option ...?
1878 Sorts the children of the item described by itemDesc, and
1879 redisplays the tree with the items in the new order.
1880 The range of items which should be sorted can be
1882 restricted by means of the -first and/or -last options,
1883 which should be children of the item described by
1884 itemDesc; the order between these two limiting items
1885 doesn't matter.
1886 The sort column can be specified by means of the -column
1888 option; this option can be used repeatedly to define a
1889 multicolumn sort. The sorting is done by looking at the
1890 text of the element specified by the -element option,
1891 which must be a text element defined in the style of the
1892 sorting column, by default the first text element is
1893 used.
1894 If the -notreally option is specified, no rearranging of
1896 the items is done; instead the sorted items are returned
1897 as result of the command.
1898 By default ASCII sorting is used with the result returned
1900 in increasing order. Any of the following options may be
1901 specified to control the sorting process of the previ‐
1902 ously specified column (unique abbreviations are
1903 accepted):
1904 -ascii Use string comparison with ASCII collation order.
1906 This is the default.
1907 -command command
1909 Use command as a comparison command. To compare
1910 two items, evaluate a Tcl script consisting of
1911 command with the numerical ids of the two items
1912 appended as additional arguments. The script
1913 should return an integer less than, equal to, or
1914 greater than zero if the first item is to be con‐
1915 sidered less than, equal to, or greater than the
1916 second, respectively.
1917 -decreasing
1919 Sort the items in decreasing order ("largest"
1920 items first).
1921 -dictionary
1923 Use dictionary-style comparison. This is the same
1924 as -ascii except (a) case is ignored except as a
1925 tie-breaker and (b) if two strings contain embed‐
1926 ded numbers, the numbers compare as integers, not
1927 characters. For example, in -dictionary mode,
1928 bigBoy sorts between bigbang and bigboy, and x10y
1929 sorts between x9y and x11y.
1930 -increasing
1932 Sort the items in increasing order ("smallest"
1933 items first). This is the default.
1934 -integer
1936 Convert to integers and use integer comparison.
1937 -real Convert to floating-point values and use floating
1939 comparison.
1940 pathName item span itemDesc ?column? ?numColumns? ?column num‐
1942 Columns ...?
1943 This command sets or retrieves the number of columns that
1944 a style covers. If no column is specified, the return
1945 value is a list of spans, one per column. If no num‐
1946 Columns is specified, the return value is the span for
1947 column.
1948 If one or more column-numColumns pairs is specified, the
1950 span for each column is set to numColumns. In this case
1951 itemDesc may refer to multiple items and each column may
1952 refer to multiple columns.
1953 pathName item state command itemDesc ?arg ...?
1955 This command is used to manipulate the states of an item.
1956 The exact behavior of the command depends on the command
1957 argument that follows the style argument. The following
1958 forms of the command are supported:
1959 pathName item state forcolumn itemDesc column ?stat‐
1961 eDescList?
1962 Just like item state set but manipulates dynamic
1963 states for a single item column, not the item as a
1964 whole. If stateDescList is unspecified, this com‐
1965 mand returns a list containing the names of all
1966 the dynamic states which are switched on in col‐
1967 umn.
1968 If stateDescList is specified, then itemDesc may
1970 refer to multiple items and column may refer to
1971 multiple columns.
1972 pathName item state get itemDesc ?stateName?
1974 If no stateName is specified, returns a list con‐
1975 taining the names of all (static and dynamic)
1976 states which are currently switched on for the
1977 item described by itemDesc. If a stateName is
1978 specified, 1 is returned if the specified state is
1979 currently switched on for the item, 0 otherwise.
1980 pathName item state set itemDesc ?lastItem? stateDescList
1982 Every element of stateDescList must be the name of
1983 a dynamic state (see STATES below), optionally
1984 preceded by a ~ or ! character. Every state with
1985 a leading ! will be switched off for the item
1986 described by itemDesc, every state with a leading
1987 ~ will be toggled, and every state without leading
1988 ! or ~ will be switched on. If lastItem is speci‐
1989 fied, the state changes will be made for all items
1990 in the range between itemDesc and lastItem. If
1991 lastItem unspecified, then the state changes are
1992 made for all items described by itemDesc.
1993 pathName item style command itemDesc ?arg ...?
1995 This command is used to manipulate the styles of an item.
1996 The exact behavior of the command depends on the command
1997 argument that follows the style argument. The following
1998 forms of the command are supported:
1999 pathName item style elements itemDesc column
2001 This command returns a list containing the names
2002 of elements which were configured by the item ele‐
2003 ment configure command for the item described by
2004 itemDesc in column. If there is no style assigned
2005 to column an error is returned.
2006 pathName item style map itemDesc column style map
2008 Like the item style set command, this command may
2009 be used to assign a style to a specific column of
2010 an item. Unlike item style set, this command can
2011 transfer configuration values of elements in the
2012 current style to elements in the new style speci‐
2013 fied by style. Map must be a list of elementOld-
2014 elementNew pairs, where elementOld is an element
2015 in the current style, and elementNew is an element
2016 in the style specified by style. Both elementOld
2017 and elementNew must be of the same type (bitmap,
2018 text etc). ItemDesc may refer to multiple items
2019 and column may refer to multiple columns.
2020 pathName item style set itemDesc ?column? ?style? ?column
2022 style ...?
2023 This command sets or retrieves the style assigned
2024 to one or more columns. If no column is speci‐
2025 fied, this command returns a list containing the
2026 names of the styles set for all columns of the
2027 item described by itemDesc. If no style is speci‐
2028 fied, this command returns the name of the style
2029 set for the item described by itemDesc in column.
2030 If one or more column-style pairs is specified,
2032 then the style in each column is set to style. In
2033 this case itemDesc may refer to multiple items and
2034 each column may refer to multiple columns.
2035 pathName item tag option ?arg arg ...?
2037 This command is used to manipulate tags on items. The
2038 exact behavior of the command depends on the option argu‐
2039 ment that follows the item tag argument. The following
2040 forms of the command are supported:
2041 pathName item tag add itemDesc tagList
2043 Adds each tag in tagList to the items specified by
2044 the item description itemDesc. Duplicate tags are
2045 ignored. The list of tags for an item can also be
2046 changed via an item's -tags option.
2047 pathName item tag expr itemDesc tagExpr
2049 Evaluates the tag expression tagExpr against every
2050 item specified by the item description itemDesc.
2051 The result is 1 if the tag expression evaluates to
2052 true for every item, 0 otherwise.
2053 pathName item tag names itemDesc
2055 Returns a list of tag names assigned to the items
2056 specified by the item description itemDesc. The
2057 result is the union of any tags assigned to the
2058 items.
2059 pathName item tag remove itemDesc tagList
2061 Removes each tag in tagList from the items speci‐
2062 fied by the item description itemDesc. It is not
2063 an error if any of the items do not use any of the
2064 tags. The list of tags for an item can also be
2065 changed via an item's -tags option.
2066 pathName item text itemDesc ?column? ?text? ?column text ...?
2068 This command sets or retrieves the value of the -text
2069 option for the first text element in one or more columns.
2070 If no column is specified, this command returns a list of
2071 values, one per column. If no text is specified, this
2072 command returns the value for column.
2073 If one or more column-text pairs is specified, then the
2075 value of the -text option in each column is set to text.
2076 In this case itemDesc may refer to multiple items and
2077 each column may refer to multiple columns.
2078 Note that this command is provided as a convenience. Use
2080 the item element configure or item element cget commands
2081 if you want to set or retrieve the value of the -text
2082 option for a specific text element.
2083 pathName item toggle itemDesc ?-recurse?
2085 Changes the open state of the item(s) described by
2086 itemDesc. If the open state is currently switched off,
2087 then this command does the same as the item expand widget
2088 command; otherwise the same as the item collapse widget
2089 command. If -recurse is specified, then the open state
2090 of all descendants of the items described by itemDesc
2091 will also be toggled.
2092 pathName marquee option ?arg ...?
2094 This command is used to manipulate the marquee, a rectangular
2095 region of the treectrl widget optionally marked with a surround‐
2096 ing dotted line. One corner point of the marquee is fixed as
2097 long as the marquee is visible and called the anchor; the diago‐
2098 nally opposite corner is dragged with the mouse while resizing
2099 the marquee and simply called the corner. All coordinates han‐
2100 dled by this widget command are treectrl coordinates, i.e. the
2101 canvasx or canvasy widget command should be used before any win‐
2102 dow coordinates can be used. The exact behavior of the command
2103 depends on the option argument that follows the marquee argu‐
2104 ment. The following forms of the command are supported:
2105 pathName marquee anchor ?x y?
2107 Returns a list containing the x and y coordinates of the
2108 anchor, if no additional arguments are specified. If two
2109 coordinates are specified, sets the anchor to the given
2110 coordinates x and y.
2111 pathName marquee cget option
2113 This command returns the current value of the marquee
2114 option named option. Option may have any of the values
2115 accepted by the marquee configure widget command.
2116 pathName marquee configure ?option? ?value? ?option value ...?
2118 This command is similar to the configure widget command
2119 except that it modifies the marquee options instead of
2120 modifying options for the overall treectrl widget. If no
2121 option is specified, the command returns a list describ‐
2122 ing all of the available marquee options (see Tk_Config‐
2123 ureInfo for information on the format of this list). If
2124 option is specified with no value, then the command
2125 returns a list describing the one named marquee option
2126 (this list will be identical to the corresponding sublist
2127 of the value returned if no option is specified). If one
2128 or more option-value pairs are specified, then the com‐
2129 mand modifies the given marquee option(s) to have the
2130 given value(s); in this case the command returns an empty
2131 string.
2132 The following marquee options are supported:
2134 -visible boolean
2136 Specifies a boolean value which determines whether
2137 the dotted line surrounding the region of the mar‐
2138 quee should currently be visible.
2139 pathName marquee coords ?x1 y1 x2 y2?
2141 Returns a list containing the x and y coordinates of the
2142 anchor followed by the x and y coordinates of the corner,
2143 if no additional arguments are specified. If four coor‐
2144 dinates are specified, sets the anchor to the given coor‐
2145 dinates x1 and y1 and the corner to the coordinates x2
2146 and y2.
2147 pathName marquee corner ?x y?
2149 Returns a list containing the x and y coordinates of the
2150 corner, if no additional arguments are specified. If two
2151 coordinates are specified, sets the corner to the given
2152 coordinates x and y.
2153 pathName marquee identify
2155 Returns a list with information about any items inter‐
2156 secting the marquee. The format of the returned list is:
2157 {
2159 {item {column element element ...} {column element element ...} ...}
2160 {item {column element element ...} {column element element ...} ...}
2161 ...
2162 }
2163 There may be zero sublists following an item id if the
2165 marquee is in the button/line area of an item. There may
2166 be zero element names following a column id if the item-
2167 column has no style or if the marquee does not intersect
2168 any elements in that column.
2169 pathName notify option ?arg ...?
2171 Many Tk widgets communicate with the outside world via -command
2172 callbacks and/or virtual events. For example, the Text widget
2173 evaluates its -yscrollcommand when the view in the widget
2174 changes, and generates a <<Modified>> virtual event when text is
2175 inserted or deleted. A treectrl widget replaces both methods of
2176 communication with its own event mechanism accessed through the
2177 notify subcommands.
2178 The exact behavior of the command depends on the option argument
2180 that follows the notify argument. The following forms of the
2181 command are supported:
2182 pathName notify bind ?object? ?pattern? ?+??script?
2184 This command associates Tcl scripts with events generated
2185 by a treectrl widget. If all three arguments are speci‐
2186 fied, notify bind will arrange for script (a Tcl script)
2187 to be evaluated whenever the event(s) specified by pat‐
2188 tern are generated by this treectrl widget. If script is
2189 prefixed with a "+", then it is appended to any existing
2190 binding for pattern; otherwise script replaces any
2191 existing binding. If script is an empty string then the
2192 current binding for pattern is destroyed, leaving pattern
2193 unbound. In all of the cases where a script argument is
2194 provided, notify bind returns an empty string.
2195 If pattern is specified without a script, then the script
2197 currently bound to pattern is returned, or an empty
2198 string is returned if there is no binding for pattern. If
2199 neither pattern nor script is specified, then the return
2200 value is a list whose elements are all the patterns for
2201 which there exist bindings for object.
2202 The object argument determines which window(s) the bind‐
2204 ing applies to. If object begins with a dot, as in
2205 .a.b.c, then it must be the path name for a window; oth‐
2206 erwise it may be an arbitrary string. Like the regular
2207 bind command, bindings on window names are automatically
2208 removed if that window is destroyed.
2209 pathName notify configure object pattern ?option? ?value?
2211 ?option value ...?
2212 This command sets and retrieves options for bindings cre‐
2213 ated by the notify bind command.
2214 If no option is specified, the command returns a list
2216 with option-value pairs describing all the available
2217 binding options for pattern on object. If option is
2218 specified with no value, then the command returns the
2219 current value of that option. If one or more option-
2220 value pairs are specified, then the command modifies the
2221 given option(s) to have the given value(s) for the bind‐
2222 ing; in this case the command returns an empty string.
2223 The following binding options are supported:
2225 -active boolean
2227 Specifies if the binding should be active. As
2228 long as this option is specified as false, a bind‐
2229 ing script will not be evaluated when the corre‐
2230 sponding event is generated.
2231 pathName notify detailnames eventName
2233 Returns a list containing the names of all details, which
2234 are installed for the event with the name eventName by
2235 means of the notify install widget command or by the
2236 treectrl widget itself.
2237 pathName notify eventnames
2239 Returns a list containing the names of all events, which
2240 are installed by means of the notify install widget com‐
2241 mand or by the treectrl widget itself.
2242 pathName notify generate pattern ?charMap? ?percentsCommand?
2244 This command causes the treectrl widget to generate an
2245 event. This command is typically used to generate dynamic
2246 events created by the notify install command, but may be
2247 used to generate static events also. The event specified
2248 by pattern is generated, and any active binding scripts
2249 on the event are evaluated after undergoing %-substitu‐
2250 tion. If there are details defined for the event, pat‐
2251 tern must describe an <eventName-detail> pair, otherwise
2252 pattern should be <eventName>.
2253 The optional charMap is a list of char-value pairs as in
2255 the form returned by array get. Each char has to be
2256 exactly one character. The charMap is used in %-substi‐
2257 tution.
2258 If percentsCommand is specified, then it will be used to
2260 perform %-substitution on any scripts bound to the event.
2261 If percentsCommand is not specified and the event is
2262 dynamic, then the %-subtitution command passed to notify
2263 install will be used if it was provided. If the event is
2264 static or no %-substitution command is available, then
2265 all %-substitution is done using charMap only . See
2266 notify install for a description of percentsCommand.
2267 pathName notify install pattern ?percentsCommand?
2269 This command installs a new event or detail specified by
2270 pattern. Events created by this command are called
2271 dynamic, whereas events created by the treectrl widget
2272 itself are called static. This command may be called to
2273 set or retrieve the percentsCommand for an existing
2274 dynamic event.
2275 The optional percentsCommand is a list containing the
2277 name of a Tcl command, plus any optional arguments, to
2278 which five additional arguments will be appended. The
2279 command will be called to perform %-substitution on any
2280 scripts bound to the event specified by pattern (see
2281 EVENTS AND SCRIPT SUBSTITUTIONS). PercentsCommand should
2282 be defined as follows:
2283 proc percentsCommand {?arg arg ...? char object event detail charMap} {
2285 switch -- $char {
2286 ...
2287 }
2288 return $value
2289 }
2290 The optional arg arguments are part of the percentsCom‐
2292 mand list. Char is the %-character to be substituted.
2293 Object is the same as the argument to notify bind. Event
2294 and detail specify the event. CharMap is the same as the
2295 argument to notify generate. PercentsCommand should
2296 return the value to replace the %-character by. If an
2297 error occurs evaluating percentsCommand, the %-character
2298 is replaced by itself.
2299 notify install returns the current percentsCommand for
2301 the event, or an error if the event is not dynamic.
2302 pathName notify install detail eventName detail ?percentsCom‐
2304 mand?
2305 Deprecated. Use notify install with a pattern of <event‐
2306 Name-detail> instead.
2307 pathName notify install event eventName ?percentsCommand?
2309 Deprecated. Use notify install with a pattern of <event‐
2310 Name> instead.
2311 pathName notify linkage pattern
2313 Returns a string indicating whether the specified event
2314 or detail is created by means of the notify install wid‐
2315 get command (dynamic) or by the treectrl widget itself
2316 (static).
2317 pathName notify linkage eventName ?detail?
2319 Deprecated. Use notify linkage with a pattern of <event‐
2320 Name> or <eventName-detail> instead.
2321 pathName notify unbind object ?pattern?
2323 If no pattern is specified, all bindings on object are
2324 removed. If pattern is specified, then the current bind‐
2325 ing for pattern is destroyed, leaving pattern unbound.
2326 pathName notify uninstall pattern
2328 If the event or detail specified by pattern is static
2329 (i.e. created by the treectrl widget itself), an error is
2330 generated. Otherwise the dynamic event or detail is
2331 removed. If an event name is specified without a detail,
2332 all details for that event are also removed.
2333 pathName notify uninstall detail eventName detail
2335 Deprecated. Use notify uninstall with a pattern of
2336 <eventName-detail> instead.
2337 pathName notify uninstall event eventName
2339 Deprecated. Use notify uninstall with a pattern of
2340 <eventName> instead.
2341 pathName numcolumns
2343 Deprecated. Use the column count command instead.
2344 pathName numitems
2346 Deprecated. Use the item count command instead.
2347 pathName orphans
2349 Returns a list containing the item ids of all items which have
2350 no parent. When an item is created, it has no parent by
2351 default, and can later become an orphan by means of the item
2352 remove widget command. The root item is not returned.
2353 pathName range first last
2355 Deprecated. Use the item range command instead.
2356 pathName scan option args
2358 This command is used to implement scanning on treectrls. It has
2359 two forms, depending on option:
2360 pathName scan mark x y
2362 Records x and y and the treectrl's current view; used in
2363 conjunction with later scan dragto commands. Typically
2364 this command is associated with a mouse button press in
2365 the widget and x and y are the coordinates of the mouse.
2366 It returns an empty string.
2367 pathName scan dragto x y ?gain?
2369 This command computes the difference between its x and y
2370 arguments (which are typically mouse coordinates) and the
2371 x and y arguments to the last scan mark command for the
2372 widget. It then adjusts the view by gain times the dif‐
2373 ference in coordinates, where gain defaults to 10. This
2374 command is typically associated with mouse motion events
2375 in the widget, to produce the effect of dragging the
2376 treectrl at high speed through its window. The return
2377 value is an empty string.
2378 pathName see itemDesc ?columnDesc? ?option value ...?
2380 Adjust the view in the treectrl so that the item described by
2381 itemDesc is visible. If the item is already visible then the
2382 command has no effect; otherwise the treectrl scrolls to bring
2383 the item into view, and the corresponding <Scroll-x> and/or
2384 <Scroll-y> events are generated. If columnDesc is specified then
2385 a specific column of the item is scrolled into view instead of
2386 the entire item.
2387 The following options are supported:
2389 -center flags
2391 Flags is a string that contains zero or more of the char‐
2392 acters x or y. This option is used to center the item
2393 horizontally and/or vertically in the window. The item
2394 will be centered regardless of whether it is already vis‐
2395 ible.
2396 pathName selection option args
2398 This command is used to adjust the selection within a treectrl.
2399 It has several forms, depending on option:
2400 pathName selection add first ?last?
2402 First and last (if specified) must be valid item descrip‐
2403 tions. If both first and last are specified, then they
2404 may refer to a single item only; in this case the command
2405 adds every unselected item in the range between first and
2406 last, inclusive, to the selection without affecting the
2407 selected state of items outside that range. If only
2408 first is specified, then every unselected item specified
2409 by first is added to the selection. A <Selection> event
2410 is generated if any items were added to the selection.
2411 pathName selection anchor ?itemDesc?
2413 If itemDesc is specified, the selection anchor is set to
2414 the described item. The selection anchor is the end of
2415 the selection that is fixed while dragging out a selec‐
2416 tion with the mouse. The item description anchor may be
2417 used to refer to the anchor item. This command doesn't
2418 modify the selection state of any item. Returns the
2419 unique id of the selection anchor item.
2420 pathName selection clear ?first? ?last?
2422 First and last (if specified) must be valid item descrip‐
2423 tions. If both first and last are specified, then they
2424 may refer to a single item only; in this case any
2425 selected items between first and last (inclusive) are
2426 removed from the selection without affecting the selected
2427 state of items outside that range. If only first is
2428 specified, then every selected item specified by first is
2429 removed from the selection. If neither first nor last
2430 are specified, then all selected items are removed from
2431 the selection. A <Selection> event is generated if any
2432 items were removed from the selection.
2433 pathName selection count
2435 Returns an integer indicating the number of items in the
2436 treectrl that are currently selected.
2437 pathName selection get ?first? ?last?
2439 When no additional arguments are given, the result is an
2440 unsorted list containing the item ids of all of the items
2441 in the treectrl that are currently selected. If there
2442 are no items selected in the treectrl, then an empty
2443 string is returned. The optional arguments first and
2444 last are treated as indices into the sorted list of
2445 selected items; these arguments allow in-place lindex and
2446 lrange operations on the selection. For example:
2447 pathName selection includes itemDesc
2451 Returns 1 if the item described by itemDesc is currently
2452 selected, 0 if it isn't.
2453 pathName selection modify select deselect
2455 Both arguments select and deselect are a possibly-empty
2456 list of item descriptions. Any unselected items in
2457 select are added to the selection, and any selected items
2458 in deselect are removed from the selection (except for
2459 those items which are also in select). A <Selection>
2460 event is generated if any items were selected or dese‐
2461 lected.
2462 pathName state option args
2464 This command is used to manipulate the list of user-defined
2465 states, see section STATES below. The exact behavior of the
2466 command depends on the option argument that follows the state
2467 argument. The following forms of the command are supported:
2468 pathName state define stateName
2470 Defines a new state with the name stateName, which must
2471 not be the name of an existing state.
2472 pathName state linkage stateName
2474 Returns a string indicating whether the specified state
2475 is user-defined by means of the state define widget com‐
2476 mand (dynamic) or predefined by the treectrl widget
2477 itself (static).
2478 pathName state names
2480 Returns a list containing the names of all user-defined
2481 states.
2482 pathName state undefine ?stateName ...?
2484 Every stateName must be the name of a user-defined state.
2485 Removes this state from the list of user-defined states.
2486 pathName style option ?element? ?arg arg ...?
2488 This command is used to manipulate styles, which can be thought
2489 of as a geometry manager for elements. The exact behavior of
2490 the command depends on the option argument that follows the
2491 style argument. The following forms of the command are sup‐
2492 ported:
2493 pathName style cget style option
2495 This command returns the current value of the option
2496 named option associated with the style given by style.
2497 Option may have any of the values accepted by the style
2498 configure widget command.
2499 pathName style configure style ?option? ?value? ?option value
2501 ...?
2502 This command is similar to the configure widget command
2503 except that it modifies options associated with the style
2504 given by style instead of modifying options for the over‐
2505 all treectrl widget. If no option is specified, the com‐
2506 mand returns a list describing all of the available
2507 options for style (see Tk_ConfigureInfo for information
2508 on the format of this list). If option is specified with
2509 no value, then the command returns a list describing the
2510 one named option (this list will be identical to the cor‐
2511 responding sublist of the value returned if no option is
2512 specified). If one or more option-value pairs are speci‐
2513 fied, then the command modifies the given option(s) to
2514 have the given value(s) in style; in this case the com‐
2515 mand returns an empty string.
2516 The options of a style have effect on all elements man‐
2518 aged by the style. The following options are supported:
2519 -orient varName
2521 This option specifies which orientation should be
2522 used when laying out the elements associated with
2523 this style. Must be either horizontal (the
2524 default) or vertical or an abbreviation of one of
2525 these.
2526 pathName style create style ?option value ...?
2528 Create a new style in pathName with name style. After
2529 style there may be any number of option-value pairs, each
2530 of which sets one of the configuration options for the
2531 style. These same option-value pairs may be used in
2532 style configure widget commands to change the style's
2533 configuration. Returns the name of the new style.
2534 pathName style delete ?style ...?
2536 Deletes each of the named styles and returns an empty
2537 string. If a style is deleted while it is still used to
2538 display one or more items, it is also removed from the
2539 style list of these items.
2540 pathName style elements style ?elementList?
2542 Specifies the elements which should be layed out by this
2543 style. Each element of elementList must be the name of
2544 an element created by the widget command element create.
2545 Duplicate names in elementList are ignored. An element
2546 which was specified in a former call of this command for
2547 style but is not included in elementList, will be deleted
2548 from the elements layed out by style.
2549 If the elementList argument is not specified, a list is
2551 returned containing the currently defined elements of
2552 style.
2553 pathName style layout style element ?option? ?value? ?option
2555 value ...?
2556 This command is similar to the configure widget command
2557 except that it modifies options used by style for laying
2558 out element instead of modifying options for the overall
2559 treectrl widget. If no option is specified, the command
2560 returns a list with option-value pairs describing all of
2561 the available options for the layout. If option is spec‐
2562 ified with no value, then the command returns the value
2563 of the named option. If one or more option-value pairs
2564 are specified, then the command modifies the given
2565 option(s) to have the given value(s) for the layout; in
2566 this case the command returns an empty string.
2567 The options of a layout have effect on exactly the one
2569 element element managed by style. The following options
2570 are supported:
2571 -detach boolean
2573 Specifies whether the element should be positioned
2574 by itself, i.e. independent from the other ele‐
2575 ments.
2576 -draw boolean
2578 This is a per-state option that determines whether
2579 an element should be drawn. If the value of the
2580 option evaluates to false for a given item state,
2581 then the element is not drawn, although it still
2582 consumes space in the layout.
2583 -expand flags
2585 This option allows the external padding around the
2586 element to increase when a style has more screen
2587 space than it needs. Flags is a string that con‐
2588 tains zero or more of the characters n, s, w or e.
2589 Each letter refers to the padding on the top, bot‐
2590 tom, left, or right that should be allowed to
2591 increase. This option is typically used to jus‐
2592 tify an element.
2593 -iexpand flags
2595 This option allows the internal padding of the
2596 element and the display area of the element to
2597 increase when a style has more screen space than
2598 it needs. Flags is a string that contains zero
2599 or more of the characters x, y, n, s, w or e. For
2600 n, s, w and e, each letter refers to the padding
2601 on the top, bottom, left, or right that should be
2602 allowed to increase. For x and y, each letter
2603 refers to the horizontal and vertical screen space
2604 the element can display itself in (i.e., the space
2605 between the padding). Note that if the -union
2606 option is specified for this element, then the x
2607 and y flags have no effect, since the size of an
2608 element with -union layout is determined by the
2609 elements it surrounds.
2610 -indent boolean
2612 Specifies whether the element should be positioned
2613 to the right of the button/line area in the tree
2614 column. This option is ignored unless the -detach
2615 option is true.
2616 -ipadx amount
2618 -ipady amount
2620 Amount specifies how much internal padding to
2621 leave on the left and right (for -ipadx) or top
2622 and bottom (for -ipady) side of the element.
2623 Amount may be a list of two values to specify pad‐
2624 ding for the two sides separately, it defaults to
2625 0.
2626 -minheight pixels
2628 -height pixels
2630 -maxheight pixels
2632 Specifies the minimum, fixed, and maximum height
2633 of the element.
2634 -minwidth pixels
2636 -width pixels
2638 -maxwidth pixels
2640 Specifies the minimum, fixed, and maximum width of
2641 the element.
2642 -padx amount
2644 -pady amount
2646 Amount specifies how much external padding to
2647 leave on the left and right (for -padx) or top and
2648 bottom (for -pady) side of the element. Amount
2649 may be a list of two values to specify padding for
2650 the two sides separately, it defaults to 0.
2651 -squeeze flags
2653 This option allows the display area of an element
2654 to decrease when a style has less space than it
2655 needs. Flags is a string that contains zero or
2656 more of the characters x or y. x allows display
2657 area to decrease horizontally, y allows display
2658 area to decrease vertically. This option is typi‐
2659 cally used for text elements and will cause the
2660 text element to display an ellipsis (...) and/or
2661 wrap lines.
2662 -sticky flags
2664 This option controls how the actual display infor‐
2665 mation (image, text, etc) of an element is posi‐
2666 tioned (or stretched) within its display area.
2667 Flags is a string that contains zero or more of
2668 the characters n, s, w or e. Each letter refers to
2669 the top, bottom, left or right side of the display
2670 area that the display information should "stick"
2671 to.
2672 -union elementList
2674 Specifies a list of other elements which this ele‐
2675 ment will surround. The size of an element with
2676 -union layout is determined by the size and posi‐
2677 tion of the elements in elementList. The -ipadx
2678 and -ipady options in this case refer to the dis‐
2679 tance of the edges of the display area of this
2680 element from those elements it surrounds. This
2681 option is typically used to display a selection
2682 rectangle around a piece of text. If none of the
2683 elements in elementList are visible, then the ele‐
2684 ment is not displayed.
2685 -visible boolean
2687 This is a per-state option that controls visibil‐
2688 ity of an element. If the value of the option
2689 evaluates to false for a given item state, then
2690 the element is not displayed and consumes no space
2691 in the layout.
2692 pathName style names
2694 Returns a list containing the names of all existing
2695 styles.
2696 pathName toggle ?-recurse? ?itemDesc ...?
2698 Use item toggle instead.
2699 pathName xview ?args?
2701 This command is used to query and change the horizontal position
2702 of the information displayed in the treectrl's window. It can
2703 take any of the following forms:
2704 pathName xview
2706 Returns a list containing two elements. Each element is
2707 a real fraction between 0 and 1; together they describe
2708 the horizontal span that is visible in the window. For
2709 example, if the first element is .2 and the second ele‐
2710 ment is .6, 20% of the tree's area is off-screen to the
2711 left, the middle 40% is visible in the window, and 40% of
2712 the tree is off-screen to the right. These are the same
2713 values passed to scrollbars via the -xscrollcommand
2714 option.
2715 pathName xview moveto fraction
2717 Adjusts the view in the window so that fraction of the
2718 total width of the tree is off-screen to the left. Frac‐
2719 tion must be a fraction between 0 and 1. A <Scroll-x>
2720 event is generated.
2721 pathName xview scroll number what
2723 This command shifts the view in the window left or right
2724 according to number and what. Number must be an integer.
2725 What must be either units or pages or an abbreviation of
2726 one of these. If what is units, the view adjusts left or
2727 right in units determined by the -xscrollincrement option
2728 (which may be zero, see the description of that option).
2729 If what is pages then the view adjusts in units of nine-
2730 tenths the window's width. If number is negative then
2731 information farther to the left becomes visible; if it
2732 is positive then information farther to the right becomes
2733 visible. A <Scroll-x> event is generated.
2734 pathName yview ?args?
2736 This command is used to query and change the vertical position
2737 of the information displayed in the treectrl's window. It can
2738 take any of the following forms:
2739 pathName yview
2741 Returns a list containing two elements. Each element is
2742 a real fraction between 0 and 1; together they describe
2743 the vertical span that is visible in the window. For
2744 example, if the first element is .6 and the second ele‐
2745 ment is 1.0, the lowest 40% of the tree's area is visible
2746 in the window. These are the same values passed to
2747 scrollbars via the -yscrollcommand option.
2748 pathName yview moveto fraction
2750 Adjusts the view in the window so that fraction of the
2751 tree's area is off-screen to the top. Fraction is a
2752 fraction between 0 and 1. A <Scroll-y> event is gener‐
2753 ated.
2754 pathName yview scroll number what
2756 This command adjusts the view in the window up or down
2757 according to number and what. Number must be an integer.
2758 What must be either units or pages. If what is units,
2759 the view adjusts up or down in units of the
2760 -yscrollincrement option (which may be zero, see the
2761 description of that option). If what is pages then the
2762 view adjusts in units of nine-tenths the window's height.
2763 If number is negative then higher information becomes
2764 visible; if it is positive then lower information
2765 becomes visible. A <Scroll-y> event is generated.
2766
2768 A treectrl widget is capable of displaying multiple columns next to
2769 each other. An item can be considered as a row, which reaches over all
2770 columns.
2771 Columns in a treectrl may be specified in a number of ways. See COLUMN
2773 DESCRIPTION below.
2774 There is always one special column, the tail column, which fills all
2776 space to the right of the last ordinary column. This column has no
2777 number; it can only be specified by the keyword tail.
2778 When a column configuration option is specified as per-state, the state
2780 names are normal, active, pressed or up, i.e. do not use item state
2781 names.
2782 The following options are supported for columns:
2784 -arrow direction
2786 Indicates whether or not an arrow should be drawn in the column
2787 header. Direction must have one of the values none (the
2788 default), up, or down.
2789 -arrowbitmap bitmap
2791 Specifies as a per-state option the bitmap to use to draw the
2792 arrow if this column's -arrow option is not none.
2793 -arrowimage image
2795 Specifies as a per-state option the image to use to draw the
2796 arrow if this column's -arrow option is not none. If an image
2797 is specified for a certain state, it overrides the -arrowbitmap
2798 option.
2799 -arrowside side
2801 Indicates on which side of the bitmap/image/text the arrow
2802 should be drawn. Side must be either left or right (the
2803 default).
2804 -arrowgravity side
2806 Indicates onto which side an arrow should be packed, if there is
2807 more space available for drawing the arrow then needed. Side
2808 must be either left (the default) or right.
2809 -arrowpadx amount
2811 Amount specifies how much padding to leave on the left and right
2812 of the arrow. Amount may be a list of two values to specify
2813 padding for left and right separately; it defaults to 6.
2814 -arrowpady amount
2816 Amount specifies how much padding to leave on the top and bottom
2817 of the arrow. Amount may be a list of two values to specify
2818 padding for top and bottom separately; it defaults to 0.
2819 -bitmap bitmap
2821 Specifies the bitmap to display in the element to the left of
2822 the column title.
2823 -background color
2825 Specifies as a per-state option the color to use for the back‐
2826 ground of the column header.
2827 -borderwidth size
2829 Specifies a non-negative value indicating the width of the 3-D
2830 border to draw around the outside of the column header (if such
2831 a border is being drawn; the -relief column option determines
2832 this). The value may have any of the forms acceptable to
2833 Tk_GetPixels.
2834 -button boolean
2836 Indicates whether or not the column header should be treated
2837 like a pushbutton. When this option is true, the default bind‐
2838 ings track <Button-1> events in the header and generate a
2839 <Header-invoke> event when a <ButtonRelease-1> event occurs in
2840 the header. See DYNAMIC EVENTS.
2841 -expand boolean
2843 Indicates whether or not any extra horizontal space should be
2844 distributed to this column. This option has no effect if the
2845 -width option is set.
2846 -font fontName
2848 Specifies the font to use for the column title inside the column
2849 header.
2850 -image image
2852 Specifies the image to display in the element to the left of the
2853 column title. This option overrides the -bitmap column option.
2854 -imagepadx amount
2856 Amount specifies how much padding to leave on the left and right
2857 of the image (or bitmap). Amount may be a list of two values to
2858 specify padding for left and right separately; it defaults to 6.
2859 -imagepady amount
2861 Amount specifies how much padding to leave on the top and bottom
2862 of the image (or bitmap). Amount may be a list of two values to
2863 specify padding for top and bottom separately; it defaults to 0.
2864 -itembackground colorList
2866 Specifies a list of zero or more colors, which are used as
2867 alternating background colors for items in this column. See
2868 also the -backgroundmode widget option for more on this.
2869 -itemjustify justification
2871 This option determines how the item styles in this column line
2872 up with each other. Must be one of left, center, or right. The
2873 default value is an empty string (for compatibility with older
2874 versions), in which case the column option -justify is used to
2875 align item styles in this column.
2876 -itemstyle style
2878 Style is the name of a style that should be set in this column
2879 for newly-created items.
2880 -justify justification
2882 This option determines how the image and text in the column
2883 header are positioned. It also affects the position of item
2884 styles in this column unless the column option -itemjustify is
2885 specified. Must be one of left (the default), center, or right.
2886 -lock lock
2888 This option allows a column to stick to the left or right edge
2889 of the window. A locked column scrolls vertically but not hori‐
2890 zontally. Must be one of none (the default), left, or right.
2891 -maxwidth size
2893 Specifies the maximum size, in screen units, that will be per‐
2894 mitted for this column. If size is an empty string, then there
2895 is no limit on the maximum size of the column. This option has
2896 no effect if the -width option is set.
2897 -minwidth size
2899 Specifies the minimum size, in screen units, that will be per‐
2900 mitted for this column. If size is an empty string, then the
2901 minimum size of the column is zero. This option has no effect
2902 if the -width option is set.
2903 -resize boolean
2905 Specifies a boolean value that indicates whether the user should
2906 be allowed to resize the column by dragging the edge of the col‐
2907 umn's header. Default is true.
2908 -squeeze boolean
2910 Specifies a boolean value that indicates whether or not the col‐
2911 umn should shrink when the content width of the treectrl is less
2912 than the total needed width of all visible columns. Defaults to
2913 false, which means the column will not get smaller than its
2914 needed width. The column will not get smaller than the value of
2915 its -minwidth option, if specified. This option has no effect if
2916 the -width option is set.
2917 -state state
2919 Specifies one of three states for the column header: normal,
2920 active, or pressed. The active state is used when the mouse is
2921 over the header. The pressed state is used when the mouse but‐
2922 ton is pressed in the header.
2923 -stepwidth size
2925 Deprecated. Use the treectrl's -itemwidthmultiple option
2926 instead.
2927 -tags tagList
2929 TagList is a list of tag names that can be used to identify the
2930 column. See also the column tag command.
2931 -text text
2933 Specifies a text string to be displayed as the column title.
2934 -textcolor color
2936 Specifies a color, which should be used as foreground color to
2937 display the column title.
2938 -textlines count
2940 Specifies the maximum number of lines of text to display in the
2941 column title. If this value is zero, the number of lines dis‐
2942 played is determined by any newline characters and the effects
2943 of wrapping when the column width is less than needed. The
2944 default is 1. Note: Under OSX/Aqua this value is always set to 1
2945 when the treectrl's -usetheme option is true, because the
2946 Appearance Manager uses a fixed height for the column header;
2947 there is only room for a single line of text.
2948 -textpadx amount
2950 Amount specifies how much padding to leave on the left and right
2951 of the text. Amount may be a list of two values to specify pad‐
2952 ding for left and right separately; it defaults to 6.
2953 -textpady amount
2955 Amount specifies how much padding to leave on the top and bottom
2956 of the text. Amount may be a list of two values to specify pad‐
2957 ding for top and bottom separately; it defaults to 0.
2958 -uniform group
2960 When a non-empty value is supplied, this option places the col‐
2961 umn in a uniform group with other columns that have the same
2962 value for -uniform. The space for columns belonging to a uniform
2963 group is allocated so that their sizes are always in strict pro‐
2964 portion to their -weight values. This option is based on the
2965 grid geometry manager.
2966 -visible boolean
2968 Indicates whether or not the column should be displayed.
2969 -weight integer
2971 Sets the relative weight for apportioning any extra space among
2972 columns. A weight of zero (0) indicates the column will not
2973 deviate from its requested size. A column whose weight is two
2974 will grow at twice the rate as a column of weight one when extra
2975 space is allocated to columns. This option is based on the grid
2976 geometry manager.
2977 -width size
2979 Specifies a fixed width for the column. If this value is an
2980 empty string, then the column width is calculated as the maximum
2981 of: a) the width requested by items; b) the width requested by
2982 the column's header; and c) the column's -minwidth option. This
2983 calculated width is also affected by the -expand, -squeeze,
2984 -uniform and -weight options. In any case, the calculated width
2985 will not be greater than the -maxwidth option, if specified.
2986 -widthhack boolean
2988 Deprecated. Use the treectrl's -itemwidthequal option instead.
2989
2991 Many of the commands and options for a treectrl take as an argument a
2992 description of which column to operate on. See the EXAMPLES section
2993 for examples. The initial part of a column description must begin with
2994 one of the following terms:
2995 id Specifies the unique column identifier, where id should be the
2997 return value of a prior call of the column create widget com‐
2998 mand. See also the -columnprefix option.
2999 QUALIFIERS
3001 Specifies a list of qualifiers. This gives the same result as
3002 all followed by QUALIFIERS; i.e., every column is tested for a
3003 match.
3004 tagExpr QUALIFIERS
3006 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3007 which every column's tags are tested for a match. This keyword
3008 cannot be followed by any modifiers unless a single column is
3009 matched. You may run into trouble if tagExpr looks like a column
3010 id or other keyword; also, tagExpr must look like a single list
3011 element since column descriptions are properly-formed lists. To
3012 be safe you may want to use the tag qualifier followed by tag‐
3013 Expr.
3014 all QUALIFIERS
3016 Indicates every column, including the tail column if the command
3017 allows it, which match QUALIFIERS.
3018 first QUALIFIERS
3020 Indicates the leftmost column of the treectrl which matches
3021 QUALIFIERS.
3022 end QUALIFIERS
3024 last QUALIFIERS
3026 Indicates the rightmost column of the treectrl (but not the tail
3027 column) which matches QUALIFIERS.
3028 list columnDescs
3030 ColumnDescs is a list (a single argument, i.e. "list {a b c}"
3031 not "list a b c") of other column descriptions. This keyword
3032 cannot be followed by any modifiers unless a single column is
3033 matched.
3034 order n QUALIFIERS
3036 Indicates the nth column in the list of columns as returned by
3037 the column order command.
3038 range first last QUALIFIERS
3040 First and last specify a range of columns. This keyword cannot
3041 be followed by any modifiers unless a single column is speci‐
3042 fied.
3043 tail Indicates the ever-present tail column of the treectrl.
3045 tree Indicates the column specified by the -treecolumn option of the
3047 treectrl.
3048 The initial part of the column description (matching any of the values
3050 above) may be followed by one or more modifiers. A modifier changes
3051 the column used relative to the description up to this point. It may
3052 be specified in any of the following forms:
3053 next QUALIFIERS
3055 Use the column to the right matching QUALIFIERS.
3056 prev QUALIFIERS
3058 Use the column to the left matching QUALIFIERS. The word QUALI‐
3059 FIERS above represents a sequence of zero or more of the follow‐
3060 ing terms that changes which column is chosen:
3061 state stateList
3063 StateList is a list of column state names. Only columns that
3064 have the given states set (or unset if the '!' prefix is used)
3065 are considered.
3066 tag tagExpr
3068 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3069 which a column's tags are tested for a match.
3070 !tail When this qualifier is given, the tail column is not matched.
3072 visible
3074 When this qualifier is given, only columns whose -visible option
3075 is TRUE are considered.
3076 !visible
3078 When this qualifier is given, only columns whose -visible option
3079 is FALSE are considered.
3080
3082 For every item a set of boolean states is managed. These states play an
3083 integral role in the appearance of each item. The following states are
3084 predefined for every item:
3085 active At all times this state is set for exactly one item. The active
3087 item is used with keyboard navigation. When the treectrl widget
3088 is created or when the active item is deleted, the root item
3089 will become the active item. This state can be modified by
3090 means of the widget command activate.
3091 enabled
3093 This state is set for every item when it is created. Disabled
3094 items cannot be selected and are ignored by the default bindings
3095 when navigating via the keyboard. This state can be modified by
3096 means of the widget command item enabled.
3097 focus This state is set for every item, if the treectrl widget cur‐
3099 rently has the focus. It cannot be modified by means of a wid‐
3100 get command, but is maintained in reaction to the <FocusIn> and
3101 <FocusOut> events.
3102 open If this state is switched on, the descendants of the item are
3104 displayed - the item is expanded. If this state is switched
3105 off, the descendants of the item are not displayed - the item is
3106 collapsed. For a new item this state is switched on by default.
3107 This state can be modified by means of the widget commands item
3108 expand, item collapse, or item toggle.
3109 selected
3111 This state is set for every item included in the selection. It
3112 can be modified by means of the widget command selection.
3113 By means of the state define widget command up to 27 additional states
3115 can be defined.
3116
3118 The visual appearance of an item can change depending on the state the
3119 item is in, such as being the active item, being included in the selec‐
3120 tion, being collapsed, or some combination of those or other states.
3121 When a configuration option is described as per-state, it means the
3122 option describes a value which varies depending on the state of the
3123 item. If a per-state option is specified as a single value, the value
3124 is used for all states. Otherwise the per-state option must be speci‐
3125 fied as an even-numbered list. For example, to use the font "Times 12
3126 bold" in a text element regardless of the item state you can write:
3127 $T element configure MyTextElement -font {{Times 12 bold}}
3129 However, to use a different font when the item is selected you could
3131 write:
3132 $T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}
3134 In the example above, the -font option reads "value stateList value
3136 stateList". If stateList is an empty list, the preceding value is used
3137 regardless of the item state. A non-empty stateList specifies a list of
3138 states which must be set for the item in order to use the preceding
3139 value. Each stateList can also include state names preceded by a !
3140 sign, indicating the state must *not* be set for the item. For example:
3141 $T element configure MyRectElement -fill {blue {selected focus} gray {selected !focus}}
3143 In the example above, the rect element is filled with blue when the
3145 treectrl has the focus and the item is selected. If the treectrl does
3146 not have the focus, the example specifies that gray should be used for
3147 selected items. Also note that if the item is not selected, no color is
3148 specified for the -fill option.
3149 Each value-stateList pair is checked in order from left to right. The
3151 value associated with the first stateList that matches the current item
3152 state is used. So stateLists should be listed from most-specific to
3153 least-specific.
3154 $T element configure MyRectElement -fill {gray {selected} blue {selected focus}}
3156 Written this way, gray will always be used for selected items since it
3158 appears first, and blue will never be used for selected items regard‐
3159 less of the focus.
3160 A value followed by an empty stateList should always be last since it
3162 will be chosen regardless of the item's state.
3163
3165 Elements are the smallest building blocks which are handled by a treec‐
3166 trl widget. One or more elements together can be combined to a style,
3167 which can be considered as a blueprint for an item. An element can be
3168 of type bitmap, border, image, rect, text or window. For each element
3169 type there is a section below describing the options which can modify
3170 an element of that type.
3171 All of the element configuration options described below are unspeci‐
3173 fied by default, meaning that no value whatsoever has been given to the
3174 option. It may seem strange to you that a boolean option would be
3175 unspecified instead of simply "true" or "false". The reason for this is
3176 that when an element displayed by an item has no value specified for an
3177 option, the element refers to the master element created by the element
3178 create command for a value for that option. This allows items which are
3179 displaying a certain element to be redisplayed when the master ele‐
3180 ment's options change. The item element configure command can be used
3181 to override the master element's configuration options for a specific
3182 item.
3183
3185 An element of type bitmap can be used to display a bitmap in an item.
3186 The following options are supported for bitmap elements:
3187 -background color
3189 Specifies as a per-state option the color to use for each of the
3190 bitmap's '0' valued pixels. If the value for a certain state is
3191 an empty string (the default), the bitmap is drawn transparent.
3192 -bitmap bitmap
3194 Specifies as a per-state option the bitmap to display in the
3195 element.
3196 -draw boolean
3198 Deprecated; use the style layout option -draw instead. Speci‐
3199 fies as a per-state option whether to draw the element. If the
3200 value for a certain state is an empty string (the default), it
3201 is treated as true and the element will be drawn.
3202 -foreground color
3204 Specifies as a per-state option the color to use for each of the
3205 bitmap's '1' valued pixels. If the value for a certain state is
3206 an empty string (the default), the bitmap's foreground color is
3207 black.
3208
3210 An element of type border can be used to display a 3D border in an
3211 item. The following options are supported for border elements:
3212 -background color
3214 Specifies as a per-state option the color to use for the back‐
3215 ground of the border. If the value for a certain state is an
3216 empty string (the default), the element will not be drawn.
3217 -draw boolean
3219 Deprecated; use the style layout option -draw instead. Speci‐
3220 fies as a per-state option whether to draw the element. If the
3221 value for a certain state is an empty string (the default), it
3222 is treated as true and the element will be drawn.
3223 -filled boolean
3225 Specifies whether the interior of the border should be filled
3226 with the background color. If this option is unspecified (the
3227 default), it it treated as false which means that only the edges
3228 of the border will be drawn.
3229 -height size
3231 Specifies the height of the border. If this value is unspecified
3232 (the default), the border will be exactly as tall as its display
3233 area as determined by the style layout options.
3234 -relief relief
3236 Specifies as a per-state option the relief of the border. If the
3237 value for a certain state is an empty string (the default), it
3238 is treated as flat. For acceptable values see the description
3239 of the -relief option in the options manual page.
3240 -thickness thickness
3242 Specifies the thickness of the edges of the border.
3243 -width size
3245 Specifies the width of the border. If this value is unspecified
3246 (the default), the border will be exactly as wide as its display
3247 area as determined by the style layout options.
3248
3250 An element of type image can be used to display an image in an item.
3251 The following options are supported for image elements:
3252 -draw boolean
3254 Deprecated; use the style layout option -draw instead. Speci‐
3255 fies as a per-state option whether to draw the element. If the
3256 value for a certain state is an empty string (the default), it
3257 is treated as true and the element will be drawn.
3258 -height size
3260 Specifies the requested height of the display area for this ele‐
3261 ment. If unspecified (the default), the element requests a
3262 height equal to the height of the image, or zero if there is no
3263 image.
3264 -image image
3266 Specifies as a per-state option the image to display in the ele‐
3267 ment.
3268 -width size
3270 Specifies the requested width of the display area for this ele‐
3271 ment. If unspecified (the default), the element requests a
3272 width equal to the width of the image, or zero if there is no
3273 image.
3274
3276 An element of type rect can be used to display a rectangle in an item.
3277 The following options are supported for rectangle elements:
3278 -draw boolean
3280 Deprecated; use the style layout option -draw instead. Speci‐
3281 fies as a per-state option whether to draw the element. If the
3282 value for a certain state is an empty string (the default), it
3283 is treated as true and the element will be drawn.
3284 -fill color
3286 Specifies as a per-state option the color to be used to fill the
3287 rectangle's area. If the color for a certain state is an empty
3288 string (the default), then the rectangle will not be filled (but
3289 the outline may still be drawn).
3290 -height size
3292 Specifies the height of the rectangle. If this value is unspeci‐
3293 fied (the default), the rectangle will be exactly as tall as its
3294 display area as determined by the style layout options.
3295 -open open
3297 This option may be used to get an incomplete drawing of the out‐
3298 line. Open is a string that contains zero or more of the char‐
3299 acters n, s, e or w. Each letter refers to a side (north,
3300 south, east, or west) that the outline will not be drawn. The
3301 default is the empty string, which causes the outline to be
3302 drawn completely.
3303 -outline color
3305 Specifies as a per-state option the color to be used to draw the
3306 outline of the rectangle. If the color for a certain state is
3307 an empty string (the default), then no outline is drawn for the
3308 rectangle.
3309 -outlinewidth outlineWidth
3311 Specifies the width of the outline to be drawn around the rec‐
3312 tangle's region. outlineWidth may be in any of the forms
3313 acceptable to Tk_GetPixels. If this option is specified as an
3314 empty string (the default), then no outline is drawn.
3315 -showfocus boolean
3317 Specifies a boolean value indicating whether a "focus ring"
3318 should be drawn around the rectangle, if the item containing the
3319 rectangle is the active item and the treectrl widget currently
3320 has the focus. If this option is specified as an empty string
3321 (the default), then a focus rectangle is not drawn.
3322 -width size
3324 Specifies the width of the rectangle. If this value is unspeci‐
3325 fied (the default), the rectangle will be exactly as wide as its
3326 display area as determined by the style layout options.
3327
3329 An element of type text can be used to display a text in an item. The
3330 following options are supported for text elements:
3331 -draw boolean
3333 Deprecated; use the style layout option -draw instead. Speci‐
3334 fies as a per-state option whether to draw the element. If the
3335 value for a certain state is an empty string (the default), it
3336 is treated as true and the element will be drawn.
3337 -data data
3339 Specifies a value that together with the -datatype and -format
3340 options will be displayed as text.
3341 -datatype dataType
3343 Specifies the type of information in the -data option. Accept‐
3344 able values are double, integer, long, string, or time.
3345 -fill color
3347 Specifies as a per-state option the foreground color to use when
3348 displaying the text. If the color for a certain state is an
3349 empty string (the default), then the text will be displayed
3350 using the color specified by the treectrl's -foreground option.
3351 -format formatString
3353 This option specifies the format string used to display the
3354 value of the -data option. If -datatype is time, formatString
3355 should be a valid format string for the Tcl clock command. For
3356 all other -datatype values formatString should be a valid format
3357 string for the Tcl format command. If this value is unspecified
3358 the following defaults are used: for -datatype double "%g", for
3359 -datatype integer "%d", for -datatype long "%ld", for -datatype
3360 string "%s", and for -datatype time the default format string of
3361 the Tcl clock command.
3362 -font font
3364 Specifies as a per-state option the font to use when displaying
3365 the text. If the font for a certain state is an empty string,
3366 the text is displayed using the font specified by the treectrl's
3367 -font option.
3368 -justify how
3370 Specifies how to justify the text when multiple lines are dis‐
3371 played. How must be one of the values left, right, or center.
3372 If this option is specified as an empty string (the default),
3373 left is used.
3374 -lines lineCount
3376 Specifies the maximum number of lines to display. If more than
3377 lineCount lines would be displayed, the last line will be trun‐
3378 cated with an ellipsis at the right. If this option is speci‐
3379 fied as zero or an empty string (the default), there is no limit
3380 to the number of lines displayed.
3381 -lmargin1 pixels
3383 Pixels is a screen distance that specifies how much a line of
3384 text should be indented. If a line of text wraps, this option
3385 only applies to the first line on the display; the -lmargin2
3386 option controls the indentation for subsequent lines. If this
3387 option is specified as zero or an empty string (the default),
3388 then the line is not indented. This option was based on the Tk
3389 Text widget tag option of the same name.
3390 -lmargin2 pixels
3392 Pixels is a screen distance that specifies how much a line of
3393 text should be indented. If a line of text wraps, this option
3394 only applies to the second and later display lines for a line of
3395 text. If this option is specified as zero or an empty string
3396 (the default), then the line is not indented. This option was
3397 based on the Tk Text widget tag option of the same name.
3398 -text string
3400 String specifies a string to be displayed by the element.
3401 String may contain newline characters in which case multiple
3402 lines of text will be displayed. If this option is specified,
3403 the -data, -datatype, -format, and -textvariable options are
3404 ignored.
3405 -textvariable varName
3407 Specifies the name of a variable. The value of the variable is
3408 a string to be displayed by the element; if the variable value
3409 changes then the element will automatically update itself to
3410 display the new value. If this option is specified, the -data,
3411 -datatype, and -format options are ignored.
3412 -underline charIndex
3414 Specifies the integer index of a character to underline. 0 cor‐
3415 responds to the first character. If charIndex is unspecified
3416 (the default), less than zero or greater than the index of the
3417 last displayed character, the underline is not drawn.
3418 -width size
3420 Specifies the maximum line length in any of the forms acceptable
3421 to Tk_GetPixels. For text to wrap lines the value of the -width
3422 option must be less than the needed width of the text, or the
3423 display area for this element must be less than the needed width
3424 of the text. For the display area to be less than the needed
3425 width of the text, one of the style layout options -maxwidth,
3426 -width or -squeeze must be used.
3427 -wrap mode
3429 Mode specifies how to handle lines in the text that are longer
3430 than the maximum line length. Acceptable values are none, char
3431 or word. If this option is unspecified (the default), word is
3432 used. See the -width option for a description of how the maxi‐
3433 mum line length is determined.
3434
3436 An element of type window can be used to display a Tk window in an
3437 item. The following options are supported for window elements:
3438 -clip boolean
3440 Specifies whether the associated Tk window is a borderless frame
3441 which should be used to clip its child window so it doesn't
3442 overlap the header, borders, or other items or columns. When
3443 this option is true, the treectrl manages the geometry of both
3444 the -window widget and its first child widget; in this case the
3445 -window widget (which should be a borderless frame) is kept
3446 sized and positioned so that it is never out-of-bounds.
3447 -destroy boolean
3449 Specifies whether the associated Tk window should be destroyed
3450 when the element is deleted. The element is deleted when the
3451 item containing the element is deleted, when the column contain‐
3452 ing the element is deleted, or when the style assigned to the
3453 item's column is changed. If this option is unspecified (the
3454 default), it is treated as false and the Tk window will not be
3455 destroyed.
3456 -draw boolean
3458 Deprecated; use the style layout option -draw instead. Speci‐
3459 fies as a per-state option whether to draw the element. If the
3460 value for a certain state is an empty string (the default), it
3461 is treated as true and the element will be drawn.
3462 -window pathName
3464 Specifies the window to associate with this element. The window
3465 specified by pathName must either be a child of the treectrl
3466 widget or a child of some ancestor of the treectrl widget. Path‐
3467 Name may not refer to a top-level window. This option cannot be
3468 specified by the element create or element configure commands,
3469 only by the item element configure command; i.e., the element
3470 must be associated with a particular item.
3471
3473 Many of the commands for a treectrl take as an argument a description
3474 of which items to operate on. An item description is a properly-formed
3475 tcl list of keywords and arguments. The first word of an item descrip‐
3476 tion must be one of the following:
3477 id Specifies the unique item identifier, where id should be the
3479 return value of a prior call of the item create widget command,
3480 or 0 to specify the ever-present root item. See also the -item‐
3481 prefix option.
3482 QUALIFIERS
3484 Specifies a list of qualifiers. This gives the same result as
3485 all followed by QUALIFIERS; i.e., every item is tested for a
3486 match.
3487 tagExpr QUALIFIERS
3489 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3490 which every item's tags are tested for a match. This keyword
3491 cannot be followed by any modifiers unless a single item is
3492 matched. You may run into trouble if tagExpr looks like an item
3493 id or other keyword; also, tagExpr must look like a single list
3494 element since item descriptions are properly-formed lists. To be
3495 safe you may want to use the tag qualifier followed by tagExpr.
3496 active Indicates the item that is currently active, i.e. normally the
3498 item specified as argument of the last successful activate wid‐
3499 get command, or the root item if no such call happened yet.
3500 anchor Indicates the anchor item of the selection, i.e. normally the
3502 item specified as argument of the last successful selection
3503 anchor widget command, or the root item if no such call happened
3504 yet.
3505 all QUALIFIERS
3507 Indicates every item including orphans which match QUALIFIERS.
3508 This keyword cannot be followed by any modifiers unless a single
3509 item is matched.
3510 first QUALIFIERS
3512 Indicates the first item of the treectrl (the root item), or the
3513 first item matching QUALIFIERS.
3514 end QUALIFIERS
3516 last QUALIFIERS
3518 Indicates the last item which matches QUALIFIERS.
3519 list itemDescs
3521 ItemDescs is a list (a single argument, i.e. "list {a b c}" not
3522 "list a b c") of other item descriptions. This keyword cannot
3523 be followed by any modifiers unless a single item is matched.
3524 nearest x y
3526 Indicates the item nearest to the point given by x and y.
3527 rnc row column
3529 Indicates the item in the given row and column. The row and
3530 column corresponds to the on-screen arrangement of items as
3531 determined by the -orient and -wrap options. You can memorize
3532 rnc as an abbreviation of "row 'n' column".
3533 range first last QUALIFIERS
3535 First and last specify a range of items. This keyword cannot be
3536 followed by any modifiers unless a single item is matched.
3537 root Indicates the root item of the treectrl.
3539 The initial part of the item description (matching any of the values
3541 above) may be followed by one or more modifiers. A modifier changes
3542 the item used relative to the description up to this point. It may be
3543 specified in any of the following forms:
3544 above Use the item one row above in this column.
3546 ancestors QUALIFIERS
3548 Use the ancestors of the item (like item ancestors but QUALI‐
3549 FIERS may change which ancestors match). This keyword cannot be
3550 followed by any modifiers.
3551 below Use the item one row below in this column.
3553 bottom Use the item in the last row of this column.
3555 child n QUALIFIERS
3557 Use the nth child of the item.
3558 children QUALIFIERS
3560 Use the children of the item (like item children but QUALIFIERS
3561 may change which children match). This keyword cannot be fol‐
3562 lowed by any modifiers.
3563 descendants QUALIFIERS
3565 Use the descendants of the item (like item descendants but QUAL‐
3566 IFIERS may change which descendants match). This keyword cannot
3567 be followed by any modifiers.
3568 firstchild QUALIFIERS
3570 Use the first child of the item.
3571 lastchild QUALIFIERS
3573 Use the last child of the item.
3574 left Use the item one column to the left in the same row.
3576 leftmost
3578 Use the item of the first column in the same row.
3579 next QUALIFIERS
3581 Use the next item, which is the first item from the following
3582 list: the first child, the next sibling or the next sibling of
3583 the nearest ancestor which has one.
3584 nextsibling QUALIFIERS
3586 Use the next sibling of the item.
3587 parent Use the parent of the item.
3589 prev QUALIFIERS
3591 Use the last child of the previous sibling, or the parent if
3592 there is no previous sibling.
3593 prevsibling QUALIFIERS
3595 Use the previous sibling of the item.
3596 right Use the item one column to the right in the same row.
3598 rightmost
3600 Use the item of the last column in the same row.
3601 sibling n QUALIFIERS
3603 Use the nth child of the item's parent.
3604 top Use the item in the first row of this column. The word QUALI‐
3606 FIERS above represents a series of zero or more of the following
3607 terms that changes which item is chosen:
3608 depth depth
3610 Matches items whose depth (as returned by the depth command) is
3611 equal to depth.
3612 state stateList
3614 StateList is a list of item state names (static and dynamic, see
3615 STATES). Only items that have the given states set (or unset if
3616 the '!' prefix is used) are considered.
3617 tag tagExpr
3619 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3620 which an item's tags are tested for a match.
3621 visible
3623 When this qualifier is given, only items that are displayed are
3624 considered.
3625 !visible
3627 When this qualifier is given, only items that are *not* dis‐
3628 played are considered. To get the first item in the list that
3629 is enabled:
3630 $T item id "first state enabled"
3632 To get the ancestors that are not open of the last item in the
3634 list:
3635 $T item id "last ancestors state !open"
3637 To get the visible descendants of the root item:
3639 $T item id "root descendants visible"
3641 To get the every hidden item with tag "a" or "b":
3643 $T item id "all !visible tag a||b"
3645 $T item id "!visible tag a||b"
3646 $T item id "tag a||b !visible"
3647 $T item id "a||b !visible"
3648
3651 The script argument to notify bind is a Tcl script, which will be eval‐
3652 uated whenever the given event is generated. Script will be executed in
3653 the same interpreter that the notify bind command was executed in, and
3654 it will run at global level (only global variables will be accessible).
3655 If script contains any % characters, then the script will not be evalu‐
3656 ated directly. Instead, a new script will be generated by replacing
3657 each %, and the character following it, with information from the cur‐
3658 rent event. Unlike the regular Tk bind mechanism, each event generated
3659 by a treectrl widget has its own set of %-substitutions.
3660 The following %-substitutions are valid for all static events:
3662 %% Replaced with a single %
3664 %d The detail name
3666 %e The event name
3668 %P The pattern, either <event> or <event-detail>
3670 %W The object argument to the notify bind command
3672 %T The treectrl widget which generated the event
3674 %? A list of the format {char value char value ...} for each
3676 %-substitution character and the value it is replaced by
3677 The following events may be generated by a treectrl widget:
3679 <ActiveItem>
3681 Generated whenever the active item changes.
3682 %c The current active item
3684 %p The previous active item
3686 <Collapse-before>
3688 Generated before an item is collapsed.
3689 %I The item id
3691 <Collapse-after>
3693 Generated after an item is collapsed.
3694 %I The item id
3696 <Expand-before>
3698 Generated before an item is expanded. This event is useful if
3699 you want to add child items to the item just before the item is
3700 expanded.
3701 %I The item id
3703 <Expand-after>
3705 Generated after an item is expanded.
3706 %I The item id
3708 <ItemDelete>
3710 Generated when items are about to be deleted by the item delete
3711 command.
3712 %i List of items ids being deleted.
3714 <ItemVisibility>
3716 Generated when items become visible on screen and when items are
3717 no longer visible on screen. This event is useful if you have a
3718 very large number of items and want to assign styles only when
3719 items are actually going to be displayed.
3720 %h List of items ids which are no longer visible.
3722 %v List of items ids which are now visible.
3724 <Scroll-x>
3726 Generated whenever the view in the treectrl changes in such a
3727 way that a horizontal scrollbar should be redisplayed.
3728 %l Same as the first fraction appended to -xscrollcommand. Think
3730 lower.
3731 %u Same as the second fraction appended to -xscrollcommand.
3733 Think upper.
3734 <Scroll-y>
3736 Generated whenever the view in the treectrl changes in such a
3737 way that a vertical scrollbar should be redisplayed.
3738 %l Same as the first fraction appended to -yscrollcommand. Think
3740 lower.
3741 %u Same as the second fraction appended to -yscrollcommand.
3743 Think upper.
3744 <Selection>
3746 Generated whenever the selection changes. This event gives
3747 information about how the selection changed.
3748 %c Same as the selection count widget command
3750 %D List of newly-deselected item ids
3752 %S List of newly-selected item ids
3754
3756 In addition to the pre-defined static events such as <ActiveItem> and
3757 <Selection>, new dynamic events can be created by using the notify
3758 install command.
3759 The following events may be generated by the library scripts:
3761 <ColumnDrag-begin>
3763 <ColumnDrag-receive>
3765 <ColumnDrag-end>
3767 Generated whenever the user drag-and-drops a column header. The
3768 library scripts do not actually move a dragged column. You must
3769 bind to the receive event to move the column. See EXAMPLES.
3770 %C The column that was dragged
3772 %b The column to move the dragged column before
3774 <Drag-begin>
3776 <Drag-receive>
3778 <Drag-end>
3780 Generated whenever the user drag-and-drops a file into a direc‐
3781 tory. This event is generated by the filelist-bindings.tcl
3782 library code, which is not used by default. See the "Explorer"
3783 demos.
3784 %I The item that the user dropped the dragged items on.
3786 %l (lowercase L) The list of dragged items.
3788 <Edit-begin>
3790 <Edit-accept>
3792 <Edit-end>
3794 The filelist-bindings.tcl code will display a text-editing win‐
3795 dow if the user clicks on a selected file/folder name. See the
3796 "Explorer" demos.
3797 %I The item containing the edited text element
3799 %C The column containing the edited text element
3801 %E The name of the edited text element
3803 %t The edited text
3805 <Header-invoke>
3807 Generated whenever the user clicks and releases the left mouse
3808 button in a column header if the column's -button option is
3809 true. You can bind a script to this event to sort the list.
3810 %C The column whose header was clicked
3812 The library scripts provide an example of using a dynamic event called
3813 <Header-invoke>, which is generated when the mouse button is released
3814 over a column header.
3815 treectrl .t
3817 puts "header %C clicked in treectrl %T"
3818 }
3819 proc ::TreeCtrl::Release1 {w x y} {
3820 ...
3821 $w notify generate <Header-invoke> [list C $Priv(column)] \
3822 [list ::TreeCtrl::PercentsCmd $w]
3823 ...
3824 }
3825 In the example a new treectrl widget is created and the <Header-invoke>
3827 event is installed. For convenience there is no percentsCommand argu‐
3828 ment to notify install; instead the call to notify generate specifies
3829 the %-substitution command. A script is bound to the event with notify
3830 bind which will print out the column number and widget name to the con‐
3831 sole (in the demos, <Header-invoke> is used to sort the list based on
3832 the column that was clicked). The charMap argument to notify generate
3833 provides a list of %-substitution characters and values which is used
3834 by ::TreeCtrl::PercentsCmd. In this example any %C in any script bound
3835 to the <Header-invoke> event will be replaced by the value of
3836 $Priv(column).
3837
3839 Tk automatically creates class bindings for treectrl widgets that give
3840 them the following default behavior.
3841 [1] Clicking mouse button 1 over an item positions the active cursor
3843 on the item, sets the input focus to this widget, and resets the
3844 selection of the widget to this item, if it is not already in
3845 the selection.
3846 [2] Clicking mouse button 1 with the Control key down will reposi‐
3848 tion the active cursor and add the item to the selection without
3849 ever removing any items from the selection.
3850 [3] If the mouse is dragged out of the widget while button 1 is
3852 pressed, the treectrl will automatically scroll to make more
3853 items visible (if there are more items off-screen on the side
3854 where the mouse left the window).
3855 [4] The Left and Right keys move the active cursor one item to the
3857 left or right; for an hierarchical tree with vertical orienta‐
3858 tion nothing will happen, since it has no two items in the same
3859 row. The selection is set to include only the active item. If
3860 Left or Right is typed with the Shift key down, then the active
3861 cursor moves and the selection is extended to include the new
3862 item.
3863 [5] The Up and Down keys move the active cursor one item up or down.
3865 The selection is set to include only the active item. If Up or
3866 Down is typed with the Shift key down, then the active cursor
3867 moves and the selection is extended to include the new item.
3868 [6] The Next and Prior keys move the active cursor forward or back‐
3870 wards by one screenful, without affecting the selection.
3871 [7] Control-Next and Control-Prior scroll the view right or left by
3873 one page without moving the active cursor or affecting the
3874 selection. Control-Left and Control-Right behave the same.
3875 [8] The Home and End keys scroll to the left or right end of the
3877 widget without moving the active cursor or affecting the selec‐
3878 tion.
3879 [9] The Control-Home and Control-End keys scroll to the top or bot‐
3881 tom of the widget, they also activate and select the first or
3882 last item. If also the Shift key is down, then the active cur‐
3883 sor moves and the selection is extended to include the new item.
3884 [10] The Space and Select keys set the selection to the active item.
3886 [11] Control-/ selects the entire contents of the widget.
3888 [12] Control-\\ clears any selection in the widget.
3890 [13] The + and - keys expand or collapse the active item, the Return
3892 key toggles the active item.
3893 [14] The mousewheel scrolls the view of the widget four lines up or
3895 down depending on the direction, the wheel was turned. The
3896 active cursor or the selection is not affected.
3897
3899 Get the unique identifier for the leftmost visible column:
3900 set id [$T column index "first visible"]
3902 Delete the leftmost column:
3904 $T column delete "order 0"
3906 Take the visible column that is to the left of the last column, and
3908 move that column in front of the tail column:
3909 $T column move "last prev visible" tail
3911 Get the unique identifier for the first visible item:
3913 set id [$T item index "first visible"]
3915 Delete the parent of the item that is under the point x,y:
3917 $T item delete "nearest $x $y parent"
3919 Add the 10th child of the second child of the root item to the selec‐
3921 tion:
3922 $T selection add "root firstchild nextsibling child 10"
3924 Move a column that the user drag-and-dropped:
3926 $T column dragconfigure -enable yes
3928 $T notify install <ColumnDrag-receive>
3929 $T notify bind MyTag <ColumnDrag-receive> {
3930 %T column move %C %b
3931 }
3932
3935 bind(n), bitmap(n), image(n), listbox(n), options(n)
3936
3938 tree, widget
3939treectrl 2.2.10 treectrl(n)