1treectrl(n) Tk Commands treectrl(n)
2
6 treectrl - Create and manipulate hierarchical multicolumn widgets
7
9 package require treectrl 2.2.3
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 state option args
293 pathName state define stateName
295 pathName state linkage stateName
297 pathName state names
299 pathName state undefine ?stateName ...?
301 pathName see itemDesc
303 pathName selection option args
305 pathName selection add first ?last?
307 pathName selection anchor ?itemDesc?
309 pathName selection clear ?first? ?last?
311 pathName selection count
313 pathName selection get ?first? ?last?
315 pathName selection includes itemDesc
317 pathName selection modify select deselect
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: -defaultstyle
528 Database Name: defaultStyle
529 Database Class: DefaultStyle
530 This option is deprecated; use the column option -itemstyle
533 instead. Specifies a list of styles, one per column, to apply
534 to each item created by the item create command. The number of
535 styles in the list can be different from the number of tree col‐
536 umns. Each list element should be a valid style name or an
537 empty string to indicate no style should be applied to a spe‐
538 cific column. The list of styles is updated if a style is
539 deleted or if a column is moved.
540 Command-Line Switch: -doublebuffer
542 Database Name: doubleBuffer
543 Database Class: DoubleBuffer
544 Specifies if double-buffering should be used to improve display‐
547 ing. The value should be one of none, window, or item. For
548 none no double-buffering is used at all, which may be most mem‐
549 ory efficient, but will probably generate some flickering on the
550 screen. For window the complete tree is double-buffered, which
551 requires a buffer big enough to contain the complete widget.
552 For item, which is the default, every item is separately double-
553 buffered, so it works with a buffer size as big as the biggest
554 item.
555 Command-Line Switch: -height
557 Database Name: height
558 Database Class: Height
559 Specifies the desired height for the window in any of the forms
562 acceptable to Tk_GetPixels. The default is 200 pixels. If this
563 option is less than or equal to zero then the window will not
564 request any size at all.
565 Command-Line Switch: -indent
567 Database Name: indent
568 Database Class: Indent
569 Specifies the screen distance an item is indented relative to
572 its parent item in any of the forms acceptable to Tk_GetPixels.
573 The default is 19 pixels.
574 Command-Line Switch: -itemheight
576 Database Name: itemHeight
577 Database Class: ItemHeight
578 Specifies a fixed height for every item in any of the forms
581 acceptable to Tk_GetPixels. If non-zero, this option overrides
582 the requested height of an item and the -minitemheight option.
583 The default is 0, which means that every item has the height
584 requested by the arrangement of elements in each column. Items
585 are never shorter than the maximum height of a button.
586 Command-Line Switch: -itemprefix
588 Database Name: itemPrefix
589 Database Class: ItemPrefix
590 Specifies an ascii string that changes the way item ids are
593 reported and processed. If this option is a non-empty string,
594 the usual integer value of an item id is prefixed with the given
595 string. This can aid debugging but it is important your code
596 doesn't assume item ids are integers if you use it.
597 Command-Line Switch: -itemwidth
599 Database Name: itemWidth
600 Database Class: ItemWidth
601 Specifies a fixed width for every item in any of the forms
604 acceptable to Tk_GetPixels. If more than one column is visible,
605 then this option has no effect. If the -orient option is verti‐
606 cal, and the -wrap option is unspecified, then this option has
607 no effect (in that case all items are as wide as the column).
608 Command-Line Switch: -itemwidthequal
610 Database Name: itemWidthEqual
611 Database Class: ItemWidthEqual
612 Specifies a boolean that says whether all items should have the
615 same width. If more than one column is visible, then this
616 option has no effect. If the -orient option is vertical, and
617 the -wrap option is unspecified, then this option has no effect
618 (in that case all items are as wide as the column). If the
619 -itemwidth option is specified, then this option has no effect.
620 Command-Line Switch: -itemwidthmultiple
622 Database Name: itemWidthMultiple
623 Database Class: ItemWidthMultiple
624 Specifies a screen distance that every item's width will be
627 evenly divisible by in any of the forms acceptable to Tk_GetPix‐
628 els. If more than one column is visible, then this option has
629 no effect. If the -orient option is vertical, and the -wrap
630 option is unspecified, then this option has no effect (in that
631 case all items are as wide as the column). If the -itemwidth
632 option is specified, then this option has no effect.
633 Command-Line Switch: -linecolor
635 Database Name: lineColor
636 Database Class: LineColor
637 Specifies the color which should be used for drawing the con‐
640 necting lines between related items.
641 Command-Line Switch: -linestyle
643 Database Name: lineStyle
644 Database Class: LineStyle
645 Specifies the style of the connecting lines between related
648 items, should be dot which is the default, or solid.
649 Command-Line Switch: -linethickness
651 Database Name: lineThickness
652 Database Class: LineThickness
653 Specifies the thickness of the connecting lines between related
656 items in any of the forms acceptable to Tk_GetPixels.
657 Command-Line Switch: -minitemheight
659 Database Name: minItemHeight
660 Database Class: MinItemHeight
661 Specifies a minimum height for every item in any of the forms
664 acceptable to Tk_GetPixels. The default is 0, which means that
665 every item has the height requested by the arrangement of ele‐
666 ments in each column. This option has no effect if the
667 -itemheight option is specified. Items are never shorter than
668 the maximum height of a button.
669 Command-Line Switch: -rowproxy
671 Database Name: rowProxy
672 Database Class: RowProxy
673 If this option specifies a non empty value, it should be a
676 screen distance in any of the forms acceptable to Tk_GetPixels.
677 Then a 1 pixel thick horizontal line will be drawn at the speci‐
678 fied screen distance from the top edge of the treectrl widget,
679 which reaches from left to right of the treectrl widget and uses
680 an inverting color (i.e black on lighter background, white on
681 darker background). This line can be used to give the user a
682 visual feedback during row resizing.
683 Command-Line Switch: -scrollmargin
685 Database Name: scrollMargin
686 Database Class: ScrollMargin
687 Specifies a positive screen distance in any of the forms accept‐
690 able to Tk_GetPixels. This option is used by the default bind‐
691 ings to determine how close to the edges of the contentbox the
692 mouse pointer must be before scrolling occurs. Specifying a
693 positive value is useful when items may be drag-and-dropped.
694 Defaults to 0.
695 Command-Line Switch: -selectmode
697 Database Name: selectMode
698 Database Class: SelectMode
699 Specifies one of several styles for manipulating the selection.
702 The value of the option may be arbitrary, but the default bind‐
703 ings expect it to be either single, browse, multiple, or
704 extended; the default value is browse.
705 Command-Line Switch: -showbuttons
707 Database Name: showButtons
708 Database Class: ShowButtons
709 Specifies a boolean value that determines whether this widget
712 leaves indentation space to display the expand/collapse buttons
713 next to items. The default value is true. The item option
714 -button determines whether any item has a button. See also the
715 treectrl option -showrootbutton.
716 Command-Line Switch: -showheader
718 Database Name: showHeader
719 Database Class: ShowHeader
720 Specifies a boolean value that determines whether this widget
723 should display the header line with the column names at the top
724 of the widget. The default value is true.
725 Command-Line Switch: -showlines
727 Database Name: showLines
728 Database Class: ShowLines
729 Specifies a boolean value that determines whether this widget
732 should draw the connecting lines between related items. The
733 default value is true.
734 Command-Line Switch: -showroot
736 Database Name: showRoot
737 Database Class: ShowRoot
738 Specifies a boolean value that determines whether this widget
741 should draw the root item. By suppressing the drawing of the
742 root item the widget can have multiple items that appear as
743 toplevel items. The default value is true.
744 Command-Line Switch: -showrootbutton
746 Database Name: showRootButton
747 Database Class: ShowRootButton
748 Specifies a boolean value that determines whether this widget
751 leaves indentation space to display the expand/collapse button
752 next to the root item. The default value is false. The item
753 option -button determines whether the root item has a button.
754 Command-Line Switch: -showrootlines
756 Database Name: showRootLines
757 Database Class: ShowRootLines
758 Specifies a boolean value that determines whether this widget
761 should draw the connecting lines between children of the root
762 item. The default value is true.
763 Command-Line Switch: -treecolumn
765 Database Name: treeColumn
766 Database Class: TreeColumn
767 Specifies a column description that determines which column dis‐
770 plays the buttons and lines. The default is unspecified.
771 Command-Line Switch: -usetheme
773 Database Name: useTheme
774 Database Class: UseTheme
775 Specifies a boolean value that determines whether this widget
778 should draw parts of itself using a platform-specific theme man‐
779 ager. The default is false.
780 Command-Line Switch: -width
782 Database Name: width
783 Database Class: Width
784 Specifies the desired width for the window in any of the forms
787 acceptable to Tk_GetPixels. The default is 200 pixel. If this
788 option is less than or equal to zero then the window will not
789 request any size at all.
790 Command-Line Switch: -wrap
792 Database Name: wrap
793 Database Class: Wrap
794 Specifies whether items are arranged in a 1- or 2-dimensional
797 layout. If the value is an empty string (the default), then
798 items are arranged from top to bottom (-orient vertical) or from
799 left to right (-orient horizontal) in a 1-dimensional layout.
800 If the value is "N items", then a no more than N items will
801 appear in a vertical group (-orient vertical) or horizontal
802 group (-orient horizontal). If the value is "N pixels", then a
803 no vertical group of items will be taller than N pixels (-orient
804 vertical) or no horizontal group of items will be wider than N
805 pixels (-orient horizontal). If the value is window, then a no
806 vertical group of items will be taller than the window (-orient
807 vertical) or no horizontal group of items will be wider than the
808 window (-orient horizontal).
809 Command-Line Switch: -xscrolldelay
811 Database Name: xScrollDelay
812 Database Class: ScrollDelay
813 This option controls how quickly horizontal scrolling occurs
816 while dragging the mouse with button 1 pressed. The value
817 should be a list of 1 or 2 integers interpreted as microseconds.
818 If 2 values are specified, then the first value determines the
819 intial delay after the first scroll, and the second value deter‐
820 mines the delay for all scrolling after the first. If only 1
821 value is specified, each scroll takes place after that delay.
822 Command-Line Switch: -xscrollincrement
824 Database Name: xScrollIncrement
825 Database Class: ScrollIncrement
826 Specifies an increment for horizontal scrolling, in any of the
829 usual forms permitted for screen distances. If the value of
830 this option is greater than zero, the horizontal view in the
831 window will be constrained so that the x coordinate at the left
832 edge of the window is always an even multiple of -xscrollincre‐
833 ment; furthermore, the units for scrolling (e.g., the change in
834 view when the left and right arrows of a scrollbar are selected)
835 will also be -xscrollincrement. If the value of this option is
836 less than or equal to zero, then horizontal scrolling snaps to
837 the left of an item, or part of an item if items are wider than
838 the contentbox.
839 Command-Line Switch: -yscrolldelay
841 Database Name: yScrollDelay
842 Database Class: ScrollDelay
843 This option controls how quickly vertical scrolling occurs while
846 dragging the mouse with button 1 pressed. The value should be a
847 list of 1 or 2 integers interpreted as microseconds. If 2 val‐
848 ues are specified, then the first value determines the intial
849 delay after the first scroll, and the second value determines
850 the delay for all scrolling after the first. If only 1 value is
851 specified, each scroll takes place after that delay.
852 Command-Line Switch: -yscrollincrement
854 Database Name: yScrollIncrement
855 Database Class: ScrollIncrement
856 Specifies an increment for vertical scrolling, in any of the
859 usual forms permitted for screen distances. If the value of
860 this option is greater than zero, the vertical view in the win‐
861 dow will be constrained so that the y coordinate at the top edge
862 of the window is always an even multiple of -yscrollincrement;
863 furthermore, the units for scrolling (e.g., the change in view
864 when the top and bottom arrows of a scrollbar are selected) will
865 also be -yscrollincrement. If the value of this option is less
866 than or equal to zero, then vertical scrolling snaps to the top
867 of an item, or part of an item if items are taller than the con‐
868 tentbox.
869
871 Columns and items may have any number of tags associated with them. A
872 tag is just a string of characters, and it may take any form, including
873 that of an integer, although the characters '(', ')', '&', '|', '^' and
874 '!' should be avoided.
875 The same tag may be associated with many columns or items. This is com‐
877 monly done to group items in various interesting ways; for example, in
878 a file browser all directories might be given the tag "directory".
879 Tag expressions are used in column descriptions and item descriptions
881 to specify which columns and items to operate on. A tag expression can
882 be a single tag name or a logical expression of tags using operators
883 '&&', '||', '^' and '!', and parenthesized subexpressions. For exam‐
884 ple:
885 or equivalently:
888 will return the unique ids of any items with either "a" or "b" tags,
891 but not both.
892
894 The treectrl command creates a new Tcl command whose name is the same
895 as the path name of the treectrl's window. This command may be used to
896 invoke various operations on the widget. It has the following general
897 form:
898 pathName option ?arg arg ...?
900 PathName is the name of the command, which is the same as the treectrl
902 widget's path name. Option and the args determine the exact behavior
903 of the command. The following commands are possible for treectrl wid‐
904 gets:
905 pathName activate itemDesc
907 Sets the active item to the one described by itemDesc, and
908 switches on the state active for this item. From now on the
909 item can be retrieved with the item description active. An
910 <ActiveItem> event is generated.
911 pathName bbox ?area?
913 Returns a list with four elements giving the bounding box (left,
914 top, right and bottom) of an area of the window. If area is not
915 specified, then the result is the bounding box of the entire
916 window. If area is content, then the result is the part of the
917 window not including borders, headers, or locked columns. If
918 area is header, then the result is the part of the window not
919 including borders where column titles are displayed. If area is
920 left, then the result is the part of the window not including
921 borders or headers where left-locked columns are displayed. If
922 area is right, then the result is the part of the window not
923 including borders or headers where right-locked columns are dis‐
924 played. An empty string is returned if the display area has no
925 height or width, which can be true for various reasons such as
926 the window is too small, or the header is not displayed, or
927 there aren't any locked columns.
928 pathName canvasx screenx
930 Given a window x-coordinate in the treectrl screenx, this com‐
931 mand returns the treectrl x-coordinate that is displayed at that
932 location.
933 pathName canvasy screeny
935 Given a window y-coordinate in the treectrl screeny, this com‐
936 mand returns the treectrl y-coordinate that is displayed at that
937 location.
938 pathName cget option
940 Returns the current value of the configuration option given by
941 option. Option may have any of the values accepted by the tree
942 command.
943 pathName collapse ?-recurse? ?itemDesc ...?
945 Use item collapse instead.
946 pathName column option column ?arg ...?
948 This command is used to manipulate the columns of the treectrl
949 widget (see section COLUMNS below). The exact behavior of the
950 command depends on the option argument that follows the column
951 argument. The following forms of the command are supported:
952 pathName column bbox columnDesc
954 Returns a list with four elements giving the bounding box
955 of the header of the column specified by the column
956 description columnDesc. If the treectrl is configured
957 not to display the column headers by means of the -show‐
958 header option, then an empty list is returned instead.
959 pathName column cget columnDesc option
961 This command returns the current value of the option
962 named option for the column specified by the column
963 description columnDesc, ColumnDesc may also be the string
964 tail to specify the tail column. Option may have any of
965 the values accepted by the column configure widget com‐
966 mand.
967 pathName column configure columnDesc ?option? ?value? ?option
969 value ...?
970 This command is similar to the configure widget command
971 except that it modifies options associated with the col‐
972 umns specified by the column description columnDesc
973 instead of modifying options for the overall treectrl
974 widget. ColumnDesc may be the string tail to specify the
975 tail column. If columnDesc refers to more than one col‐
976 umn, then at least one option-value pair must be given.
977 If no option is specified, the command returns a list
978 describing all of the available options for columnDesc
979 (see Tk_ConfigureInfo for information on the format of
980 this list). If option is specified with no value, then
981 the command returns a list describing the one named
982 option (this list will be identical to the corresponding
983 sublist of the value returned if no option is specified).
984 If one or more option-value pairs are specified, then the
985 command modifies the given option(s) to have the given
986 value(s) for columnDesc; in this case the command returns
987 an empty string.
988 See COLUMNS below for details on the options available
990 for columns.
991 pathName column compare column1 op column2
993 For both column descriptions column1 and column2 the
994 index is retrieved (as returned from the column order
995 widget command). Then these indexes are compared using
996 the operator op, which must be either <, <=, ==, >=, >,
997 or !=. The return value of this command is 1 if the com‐
998 parison evaluated to true, 0 otherwise.
999 pathName column count ?columnDesc?
1001 If no additional arguments are given, the result is a
1002 decimal string giving the number of columns created by
1003 the column create widget command which haven't been
1004 deleted by the column delete widget command; in this case
1005 the tail column is not counted. If columnDesc is given,
1006 then the result is the number of columns that match that
1007 column description.
1008 pathName column create ?option value ...?
1010 This command creates a new column in the treectrl widget.
1011 The new column is placed to the right of all other col‐
1012 umns (except the tail column). Any option-value arguments
1013 configure the new column according to the column config‐
1014 ure command. The return value is the unique identifier of
1015 the new column.
1016 pathName column delete first ?last?
1018 Deletes the specified column(s). First and last must be
1019 valid column descriptions. If both first and last are
1020 specified, then they may refer to a single column only.
1021 The tail column cannot be deleted and it is an error to
1022 specify it. The order of first and last doesn't matter,
1023 and first may be equal to last.
1024 pathName column dragcget option
1026 pathName column dragconfigure ?option? ?value? ?option value
1028 ...?
1029 The user can move a column within a treectrl by drag-and-
1030 drop. Feedback consists of a semi-transparent photo image
1031 of the header of the column being dragged and a 2-pixel-
1032 thick vertical line to indicate where the column may be
1033 dropped. The drag image consists of a colored background
1034 rectangle plus the image and/or text displayed in the
1035 column header. The 2-pixel-thick line will be drawn over
1036 the left edge of the column before which the dragged col‐
1037 umn may be dropped.
1038 The library scripts generate a <ColumnDrag-accept> event
1040 when the user has successfully drag-and-drop'd a column.
1041 You will have to bind a script to this event if you want
1042 to move the dragged column.
1043 The following configuration options are supported:
1045 -enable boolean
1047 Controls whether the user is allowed to rearrange
1048 columns by drag-and-drop.
1049 -imagealpha alpha
1051 Alpha is an integer from 0 (invisible) to 255
1052 (opaque) controlling the transparency of the drag
1053 image. Any value outside this range is clipped.
1054 -imagecolor background
1056 Background is the color of the drag image back‐
1057 ground rectangle.
1058 -imagecolumn column
1060 Column specifies the column to create the drag
1061 image from.
1062 -imageoffset offset
1064 Offset is the horizontal screen distance the drag
1065 image is offset from its starting position.
1066 -indicatorcolor color
1068 Color is the color of the 2-pixel-thick line.
1069 -indicatorcolumn column
1071 The 2-pixel-thick line will be drawn over the left
1072 or right edge of column.
1073 -indicatorside side
1075 Specifies whether the 2-pixel-thick line will be
1076 drawn over the left or right edge of the column
1077 specified by -indicatorcolumn.
1078 pathName column index columnDesc
1080 Deprecated. Use column id instead.
1081 pathName column id columnDesc
1083 This command resolves the column description columnDesc
1084 into a list of unique column identifiers. If the col‐
1085 umn(s) described by columnDesc don't exist, this command
1086 returns an empty list.
1087 pathName column list ?-visible?
1089 This command returns a list of identifiers for every col‐
1090 umn (except the tail) from left to right. If -visible is
1091 given, only columns whose -visible option is true are
1092 returned.
1093 pathName column move columnDesc beforeDesc
1095 Moves the column specified by columnDesc to the left of
1096 the column specified by beforeDesc. Both columnDesc and
1097 beforeDesc must be valid column descriptions. If before‐
1098 Desc is the string tail, the column columnDesc will
1099 become the last column.
1100 pathName column neededwidth columnDesc
1102 This command returns a decimal string giving the needed
1103 width of the column specified by the column description
1104 columnDesc. The needed width is the maximum of the width
1105 of the column header and the width of the widest style in
1106 any visible item.
1107 pathName column order columnDesc ?-visible?
1109 This command returns a decimal string giving the position
1110 of the column specified by the column description column‐
1111 Desc in the list of columns starting from zero for the
1112 leftmost column. If -visible is given, only columns
1113 whose -visible option is true are considered, and -1 is
1114 returned if columnDesc's -visible option is false.
1115 pathName column tag option ?arg arg ...?
1117 This command is used to manipulate tags on columns. The
1118 exact behavior of the command depends on the option argu‐
1119 ment that follows the column tag argument. The following
1120 forms of the command are supported:
1121 pathName column tag add columnDesc tagList
1123 Adds each tag in tagList to the columns specified
1124 by the column description columnDesc. Duplicate
1125 tags are ignored. The list of tags for a column
1126 can also be changed via a column's -tags option.
1127 pathName column tag expr columnDesc tagExpr
1129 Evaluates the tag expression tagExpr against every
1130 column specified by the column description column‐
1131 Desc. The result is 1 if the tag expression evalu‐
1132 ates to true for every column, 0 otherwise.
1133 pathName column tag names columnDesc
1135 Returns a list of tag names assigned to the col‐
1136 umns specified by the column description column‐
1137 Desc. The result is the union of any tags assigned
1138 to the columns.
1139 pathName column tag remove columnDesc tagList
1141 Removes each tag in tagList from the columns spec‐
1142 ified by the column description columnDesc. It is
1143 not an error if any of the columns do not use any
1144 of the tags. The list of tags for a column can
1145 also be changed via a column's -tags option.
1146 pathName column width columnDesc
1148 This command returns a decimal string giving the width in
1149 pixels of the column specified by the column description
1150 columnDesc, even if the treectrl is configured to not
1151 display the column headers by means of the -showheader
1152 option.
1153 pathName compare itemDesc1 op itemDesc2
1155 Deprecated. Use the item compare command instead.
1156 pathName configure ?option? ?value option value ...?
1158 Query or modify the configuration options of the widget. If no
1159 option is specified, returns a list describing all of the avail‐
1160 able options for pathName (see Tk_ConfigureInfo for information
1161 on the format of this list). If option is specified with no
1162 value, then the command returns a list describing the one named
1163 option (this list will be identical to the corresponding sublist
1164 of the value returned if no option is specified). If one or
1165 more option-value pairs are specified, then the command modifies
1166 the given widget option(s) to have the given value(s); in this
1167 case the command returns an empty string. Option may have any
1168 of the values accepted by the treectrl command.
1169 pathName contentbox
1171 Returns a list with four elements giving the bounding box of the
1172 screen area used to display items. This is the area of the win‐
1173 dow not including borders, column headers, or locked columns. An
1174 empty string is returned if the display area has no height or
1175 width, which can happen if the window is too small.
1176 pathName debug option ?arg arg ...?
1178 This command is used to facilitate debugging of the treectrl
1179 widget. The exact behavior of the command depends on the option
1180 argument that follows the debug argument. The following forms
1181 of the command are supported:
1182 pathName debug alloc
1184 Returns a string giving partial statistics on memory
1185 allocations, if the package was built with TREECTRL_DEBUG
1186 defined.
1187 pathName debug cget option
1189 This command returns the current value of the debugging
1190 option named option. Option may have any of the values
1191 accepted by the debug configure widget command.
1192 pathName debug configure ?option? ?value? ?option value ...?
1194 This command is similar to the configure widget command
1195 except that it modifies debugging options instead of mod‐
1196 ifying options for the overall treectrl widget. If no
1197 option is specified, the command returns a list describ‐
1198 ing all of the available debugging options (see Tk_Con‐
1199 figureInfo for information on the format of this list).
1200 If option is specified with no value, then the command
1201 returns a list describing the one named option (this list
1202 will be identical to the corresponding sublist of the
1203 value returned if no option is specified). If one or
1204 more option-value pairs are specified, then the command
1205 modifies the given debugging option(s) to have the given
1206 value(s); in this case the command returns an empty
1207 string.
1208 The following debugging options are supported:
1210 -displaydelay millis
1212 Specifies a time duration in milliseconds, which
1213 should be waited after something has been drawn to
1214 the screen. Setting this option has only an
1215 effect, if the debugging options -enable and -dis‐
1216 play are switched on.
1217 -data boolean
1219 If this option is switched on (together with the
1220 debugging option -enable), at various places a
1221 consistence check on the internal data structure
1222 is made (e.g. for every item is checked, if the
1223 registered number of children is equal to the num‐
1224 ber of child items). If an inconsistency was
1225 found, a Tcl background error is raised.
1226 -display boolean
1228 If this option is switched on (together with the
1229 debugging option -enable), at varios places addi‐
1230 tional debugging output is printed to stdout.
1231 -drawcolor color
1233 When specified, areas of the window are painted
1234 with this color when drawing in those areas is
1235 about to occur. Setting this option has only an
1236 effect if the debugging options -enable and -dis‐
1237 play are switched on.
1238 -enable boolean
1240 All other debugging options only take effect if
1241 this option is also switched on.
1242 -erasecolor color
1244 When specified, areas of the window which have
1245 been marked as "invalid" (for example, when part
1246 of the window is exposed) are painted with this
1247 color. If you use an unusual color for this
1248 option (like pink), superflous screen redraws can
1249 be spotted more easily. Setting this option has
1250 only an effect if the debugging options -enable
1251 and -display are switched on.
1252 -span boolean
1254 Debugging related to column spanning.
1255 -textlayout boolean
1257 Debugging related to text-element layout.
1258 pathName debug dinfo option
1260 Returns a string describing display-related stuff. Option
1261 must be one of alloc, ditem, onscreen or range.
1262 pathName debug expose x1 y1 x2 y2
1264 Causes the area of the window bounded by the given win‐
1265 dow-coords to be marked as invalid. This simulates uncov‐
1266 ering part of the window.
1267 pathName debug scroll
1269 Returns a string useful for debugging vertical scrolling.
1270 pathName depth ?itemDesc?
1272 If the additional argument itemDesc is given, then the result is
1273 a decimal string giving the depth of the item described by
1274 itemDesc. If no itemDesc is specified, then the maximum depth
1275 of all items in the treectrl widget is returned instead. Depth
1276 is defined as the number of ancestors an item has.
1277 pathName dragimage option ?arg ...?
1279 This command is used to manipulate the dragimage, one or more
1280 dotted lines around rectangular regions of the treectrl widget.
1281 The exact behavior of the command depends on the option argument
1282 that follows the dragimage argument. The following forms of the
1283 command are supported:
1284 pathName dragimage add itemDesc ?column? ?element?
1286 Adds the shapes of the item described by itemDesc to the
1287 shapes of the dragimage. Specifying additional arguments
1288 reduces the number of rectangles that are added to the
1289 dragimage. If no additional arguments is specified, for
1290 every element of the item in every column a dotted rec‐
1291 tangles is added. If column is specified, all elements
1292 in other columns are ignored. If also element is speci‐
1293 fied, only a rectangle for this one element of the speci‐
1294 fied item in the given column is added.
1295 pathName dragimage cget option
1297 This command returns the current value of the dragimage
1298 option named option. Option may have any of the values
1299 accepted by the dragimage configure widget command.
1300 pathName dragimage clear
1302 Removes all shapes (if there are any) from the dragimage.
1303 This command does not modify the dragimage offset.
1304 pathName dragimage configure ?option? ?value? ?option value ...?
1306 This command is similar to the configure widget command
1307 except that it modifies the dragimage options instead of
1308 modifying options for the overall treectrl widget. If no
1309 option is specified, the command returns a list describ‐
1310 ing all of the available dragimage options (see Tk_Con‐
1311 figureInfo for information on the format of this list).
1312 If option is specified with no value, then the command
1313 returns a list describing the one named dragimage option
1314 (this list will be identical to the corresponding sublist
1315 of the value returned if no option is specified). If one
1316 or more option-value pairs are specified, then the com‐
1317 mand modifies the given dragimage option(s) to have the
1318 given value(s); in this case the command returns an empty
1319 string.
1320 The following dragimage options are supported:
1322 -visible boolean
1324 Specifies a boolean value which determines whether
1325 the dragimage should currently be visible.
1326 pathName dragimage offset ?x y?
1328 Returns a list containing the x and y offsets of the
1329 dragimage, if no additional arguments are specified. The
1330 dragimage offset is the screen distance, the image is
1331 displayed relative to the item its shape is derived from.
1332 If two coordinates are specified, sets the dragimage off‐
1333 set to the given coordinates x and y.
1334 pathName element option ?element? ?arg arg ...?
1336 This command is used to manipulate elements (see ELEMENTS
1337 below). The exact behavior of the command depends on the option
1338 argument that follows the element argument. The following forms
1339 of the command are supported:
1340 pathName element cget element option
1342 This command returns the current value of the option
1343 named option associated with the element given by ele‐
1344 ment. Option may have any of the values accepted by the
1345 element configure widget command.
1346 pathName element configure element ?option? ?value? ?option
1348 value ...?
1349 This command is similar to the configure widget command
1350 except that it modifies options associated with the ele‐
1351 ment given by element instead of modifying options for
1352 the overall treectrl widget. If no option is specified,
1353 the command returns a list describing all of the avail‐
1354 able options for element (see Tk_ConfigureInfo for infor‐
1355 mation on the format of this list). If option is speci‐
1356 fied with no value, then the command returns a list
1357 describing the one named option (this list will be iden‐
1358 tical to the corresponding sublist of the value returned
1359 if no option is specified). If one or more option-value
1360 pairs are specified, then the command modifies the given
1361 option(s) to have the given value(s) in element; in this
1362 case the command returns an empty string. See ELEMENTS
1363 below for details on the options available for elements.
1364 pathName element create element type ?option value ...?
1366 Create a new elememt in pathName of type type with name
1367 element. The exact format of the arguments after type
1368 depends on type, but generally consist of specifications
1369 for zero or more element options. See the subsections on
1370 individual element types below for more on the syntax of
1371 this command. This command returns the name for the new
1372 element.
1373 pathName element delete ?element ...?
1375 Deletes each of the named elements and returns an empty
1376 string. If an element is deleted while it is still con‐
1377 figured as an element of one or more styles by means of
1378 the style elements widget command, it is also removed
1379 from the element lists of these styles.
1380 pathName element names
1382 Returns a list containing the names of all existing ele‐
1383 ments.
1384 pathName element perstate element option stateList
1386 This command returns the value of the per-state option
1387 named option for element for a certain state. StateList
1388 is a list of state names (static and dynamic, see STATES)
1389 which specifies the state to use.
1390 pathName element type element
1392 Returns the type of the element given by element, such as
1393 rect or text.
1394 pathName expand ?-recurse? ?itemDesc ...?
1396 Use item expand instead.
1397 pathName identify x y
1399 Returns a list describing what is displayed at the given window
1400 coordinates x and y. If the coordinates are outside the window,
1401 over the borders, or over any whitespace in the window, then the
1402 result is an empty string; otherwise the first word of the
1403 result is header or item.
1404 If the coordinates are over a column header, then the first word
1406 of the result is header, followed by the unique id of the column
1407 (or the string tail). If the x coordinate is near the left or
1408 right end of a column, then a third word left or right is
1409 appended to the result.
1410 If the coordinates are over an item, then the first word of the
1412 result is item followed by the unique id of that item. If the
1413 coordinates are not over the area for displaying buttons and
1414 lines, then column and a unique column id are the 3rd and 4th
1415 words of the result. If the coordinates are over an element
1416 within that column, then element and an element name are the 5th
1417 and 6th words of the result.
1418 If the coordinates are over a button, then the first word of the
1420 result is item, followed by the unique id of that item, followed
1421 by the word button.
1422 If the coordinates are over a line descending from an ancestor
1424 of an item (but not the parent of that item), then the first
1425 word of the result is item, followed by the unique id of that
1426 item, followed by the word line, followed by the unique id of
1427 the item the line is coming from. This is used to collapse the
1428 ancestor when the line is clicked on.
1429 pathName index itemDesc
1431 Deprecated. Use item id instead.
1432 pathName item option ?arg ...?
1434 This command is used to manipulate items. The exact behavior of
1435 the command depends on the option argument that follows the item
1436 argument. The following forms of the command are supported:
1437 pathName item ancestors itemDesc
1439 Returns a list containing the item ids of the ancestors
1440 of the item specified by itemDesc. The first list value
1441 is the parent, the second is the parent's parent, an so
1442 on. The last list value will be the root item if itemDesc
1443 is a descendant of the root item.
1444 pathName item bbox itemDesc ?column? ?element?
1446 Returns a list with four elements giving the bounding box
1447 of the item described by itemDesc. If no further argu‐
1448 ment is specified, the bbox spans the area of the item
1449 over all non-locked columns. If a column is specified,
1450 only the area of the item in this column is considered.
1451 If an additional element is specified, the area of this
1452 element in column of the specified item is returned.
1453 pathName item cget itemDesc option
1455 Returns the current value of the configuration option for
1456 the item specified by itemDesc whose name is option.
1457 Option may have any of the values accepted by the item
1458 configure command.
1459 pathName item children itemDesc
1461 Returns a list containing the item ids of all children of
1462 the item specified by itemDesc in the correct order from
1463 the first child to the last child.
1464 pathName item collapse itemDesc ?-recurse?
1466 Switches off the open state of the item(s) described by
1467 itemDesc. If an item has descendants, then they are no
1468 longer displayed. If an item is already closed, then
1469 this command has no effect on that item. If -recurse is
1470 specified, then all descendants of the items described by
1471 itemDesc will also be collapsed. For every item that
1472 actually will be collapsed, two events are generated: a
1473 <Collapse-before> event before the item state is changed,
1474 and a <Collapse-after> event after the item state was
1475 changed.
1476 pathName item compare itemDesc1 op itemDesc2
1478 From both items described by the itemDescs the index is
1479 retrieved (as returned from the item order widget com‐
1480 mand). Then these indexes are compared using the opera‐
1481 tor op, which must be either <, <=, ==, >=, >, or !=.
1482 The return value of this command is 1 if the comparison
1483 evaluated to true, 0 otherwise.
1484 pathName item complex itemDesc ?list...?
1486 This horrible command is now deprecated. Use item element
1487 configure instead. For every column of the treectrl there
1488 may be specified one list. Each list should look like
1489 this:
1490 { {element option value ...} {element option value ...} ...}
1492 Every option must be known by the element's type (see
1494 ELEMENTS below). Each option will be set to value for
1495 the element in this one column in this item.
1496 pathName item configure itemDesc ?option? ?value? ?option value
1498 ...?
1499 If no option is specified, returns a list describing all
1500 of the available options for the item given by itemDesc
1501 (see Tk_ConfigureInfo for information on the format of
1502 this list). If option is specified with no value, then
1503 the command returns a list describing the one named
1504 option (this list will be identical to the corresponding
1505 sublist of the value returned if no option is specified).
1506 If one or more option-value pairs are specified, then the
1508 command modifies the given item option(s) to have the
1509 given value(s); in this case the command returns an empty
1510 string. This is the only case where itemDesc may refer to
1511 multiple items.
1512 The following options are supported by this command (see
1514 item create for the meaning of each option):
1515 -button boolean|auto
1517 -height height
1519 -tags tagList
1521 -visible boolean
1523 pathName item count ?itemDesc?
1525 If no additional arguments are given, the result is a
1526 decimal string giving the number of items created by the
1527 item create widget command which haven't been deleted by
1528 the item delete widget command, plus 1 for the ever-
1529 present root item. If the optional argument itemDesc is
1530 given, then the result is the number of items that match
1531 that item description.
1532 pathName item create ?option value ...?
1534 Creates some new items and optionally returns a list of
1535 unique identifiers for those items. The new items have
1536 the states open and enabled set by default. If the
1537 treectrl widget currently has the focus, the state focus
1538 is also set.
1539 The following options are supported by this command:
1541 -button boolean|auto
1543 The value of this option must have one of the
1544 forms accepted by Tcl_GetBoolean or be the word
1545 auto (or any abbreviation of it). It indicates
1546 whether or not an expand/collapse button should be
1547 drawn next to the item, typically to indicate that
1548 the item has children. If the value of this
1549 option is auto, then a button is displayed next to
1550 the item whenever the item has any children whose
1551 item option -visible is true. The button will
1552 only be displayed if:
1553 [1] the column specified by the treectrl option
1555 -treecolumn is visible, and
1556 [2] the treectrl option -showbuttons is true,
1558 and
1559 [3] for the root item, the treectrl option
1561 -showrootbutton is true.
1562 -count numItems
1564 Specifies the number of items to create. Must be
1565 >= 0. Defaults to 1.
1566 -height height
1568 Specifies a fixed height in any of the forms
1569 acceptable to Tk_GetPixels. Must be >= 0. If
1570 height is zero then the item's height is unspeci‐
1571 fied. Defaults to 0.
1572 -nextsibling itemDesc
1574 Specifies the item before which the new items will
1575 be inserted. The new items will have the same par‐
1576 ent as itemDesc.
1577 -open boolean
1579 Specifies whether the items should be open or
1580 closed. Default is true.
1581 -parent itemDesc
1583 Specifies the item which the new items will be the
1584 children of. The new items will be appended to the
1585 list of children of itemDesc.
1586 -prevsibling itemDesc
1588 Specifies the item after which the new items will
1589 be inserted. The new items will have the same par‐
1590 ent as itemDesc.
1591 -returnid boolean
1593 Specifies whether or not to return a list of item
1594 identifiers for the newly created items. Specify‐
1595 ing false is useful when creating a large number
1596 of items in the console or to improve performance.
1597 Default is true.
1598 -tags tagList
1600 TagList is a list of tag names to be added to the
1601 new items.
1602 -visible boolean
1604 Boolean must have one of the forms accepted by
1605 Tcl_GetBoolean. It indicates that the item should
1606 be displayed in the list. The item will only be
1607 displayed if: a) each ancestor is a descendant of
1608 the root item (not an orphan); and b) each ances‐
1609 tor's -visible option is true
1610 pathName item delete first ?last?
1612 Deletes the specified item(s). First and last must be
1613 valid item descriptions. If last isn't specified, then
1614 first may specify multiple items. If both first and last
1615 are specified, they must each decribe a single item with
1616 a common ancestor; then the range of items between first
1617 and last is deleted. The order of first and last doesn't
1618 matter.
1619 Deleting an item deletes any child items of the deleted
1621 item recursively. If the current active item is deleted,
1622 the root item becomes the new active item. If the cur‐
1623 rent selection anchor item is deleted, the root item
1624 becomes the new anchor item. There is no way to delete
1625 the root item of the treectrl widget; in all cases the
1626 specification of the root item is ignored.
1627 For each call to this command, two events may be gener‐
1629 ated. If any of the deleted items are selected, then a
1630 <Selection> event is generated just before the items are
1631 deleted. If any items are going to be deleted, then an
1632 <ItemDelete> event event is generated just before the
1633 items are deleted.
1634 pathName item descendants itemDesc
1636 Returns a list containing the item ids of the descendants
1637 of the item specified by itemDesc, i.e. the children,
1638 grandchildren, great-grandchildren etc, of the item.
1639 pathName item dump itemDesc
1641 Returns a list with 4 words in the form index index
1642 indexVis indexVis.
1643 pathName item element command itemDesc column element ?arg ...?
1645 This command is used to manipulate elements of the item.
1646 The exact behavior of the command depends on the command
1647 argument that follows the element argument. The follow‐
1648 ing forms of the command are supported:
1649 pathName item element actual itemDesc column element
1651 option
1652 Deprecated. Use item element perstate instead.
1653 pathName item element cget itemDesc column element option
1655 This command returns the value of the option named
1656 option associated with element inside column of
1657 the item described by itemDesc, if it was already
1658 configured for the actual item. Option may have
1659 any of the values accepted by the type of the
1660 specified element (see ELEMENTS below)
1661 pathName item element configure itemDesc column element
1663 ?option? ?value? ?option value ...?
1664 This command modifies configuration options for an
1665 element in a column of an item. If no option is
1666 specified, the command returns a list describing
1667 all of the available options for the element (see
1668 Tk_ConfigureInfo for information on the format of
1669 this list). If option is specified with no value,
1670 then the command returns a list describing the one
1671 named option (this list will be identical to the
1672 corresponding sublist of the value returned if no
1673 option is specified).
1674 If one or more option-value pairs are specified,
1676 then the command modifies the given option(s) to
1677 have the given value(s) in the element inside col‐
1678 umn of the item(s) described by itemDesc; in this
1679 case the command returns an empty string. This is
1680 the only case where itemDesc may refer to multiple
1681 items.
1682 It is possible to configure multiple elements in
1684 multiple columns with a single call. To configure
1685 another element in the same column, append a ´+'
1686 argument followed by the element name. To config‐
1687 ure elements in another column, append a ',' argu‐
1688 ment followed by the column. For example:
1689 $C1 $E1 -text "hello" + $E2 -text "world" , \
1691 $C2 $E3 -fill Blue , \
1692 $C3 $E1 -text "apples and oranges"
1693 Each of the column description arguments to this
1695 command may refer to multiple columns if at least
1696 one option-value pair is given.
1697 pathName item element perstate itemDesc column element
1699 option ?stateList?
1700 This command returns the current value of the per-
1701 state option named option for element inside col‐
1702 umn of the item described by itemDesc. If
1703 stateList is specified, the list of state names
1704 (static and dynamic, see STATES) is used in place
1705 of the current state for item and column.
1706 pathName item enabled itemDesc ?boolean?
1708 Returns 1 if the item described by itemDesc has the state
1709 enabled switched on, 0 otherwise. If boolean is speci‐
1710 fied, then the enabled state of every item described by
1711 the item description itemDesc is set accordingly. All
1712 items are enabled when first created. Disabled items can‐
1713 not be selected, and are ignored by the default key-navi‐
1714 gation and mouse bindings.
1715 pathName item expand itemDesc ?-recurse?
1717 Switches on the open state of the item(s) described by
1718 itemDesc. If an item has descendants, then they are now
1719 displayed. If an item is already open, then this command
1720 has no effect on that item. If -recurse is specified,
1721 then all descendants of the items described by itemDesc
1722 will also be expanded. For every item that actually will
1723 be expanded, two events are generated: an <Expand-before>
1724 event before the item state is changed, and an <Expand-
1725 after> event after the item state was changed.
1726 pathName item firstchild parent ?child?
1728 If child is not specified, returns the item id of the
1729 first child of the item described by parent. If child is
1730 specified, it must describe an item that is neither the
1731 root item nor an ancestor of parent. Then it will become
1732 the new first child of parent.
1733 pathName item id itemDesc
1735 This command resolves the item description itemDesc into
1736 a list of unique item identifiers. If itemDesc doesn't
1737 refer to any existing items, then this command returns an
1738 empty list.
1739 pathName item image itemDesc ?column? ?image? ?column image ...?
1741 This command sets or retrieves the value of the per-state
1742 -image option for the first image element in one or more
1743 columns. If no column is specified, this command returns
1744 a list of values, one per column. If no image is speci‐
1745 fied, this command returns the value for column.
1746 If one or more column-image pairs is specified, then the
1748 value of the -image option in each column is set to
1749 image. In this case itemDesc may refer to multiple items
1750 and each column may refer to multiple columns.
1751 Note that this command is provided as a convenience. Use
1753 the item element configure or item element cget commands
1754 if you want to set or retrieve the value of the -image
1755 option for a specific image element.
1756 pathName item isancestor itemDesc descendant
1758 Returns 1 if the item described by itemDesc is a direct
1759 or indirect parent of the item decribed by descendant, 0
1760 otherwise.
1761 pathName item isopen itemDesc
1763 Returns 1 if the item described by itemDesc has the state
1764 open switched on, 0 otherwise.
1765 pathName item lastchild parent ?child?
1767 If child is not specified, returns the item id of the
1768 last child of the item described by parent. If child is
1769 specified, it must describe an item that is not an ances‐
1770 tor of parent. Then it will become the new last child of
1771 parent.
1772 pathName item nextsibling sibling ?next?
1774 If next is not specified, returns the item id of the next
1775 sibling of the item described by sibling. If next is
1776 specified, it must describe an item that is not an ances‐
1777 tor of sibling. Then it will become the new next sibling
1778 of sibling.
1779 pathName item numchildren itemDesc
1781 Returns the number of children of the item described by
1782 itemDesc.
1783 pathName item order itemDesc ?-visible?
1785 This command returns the position of the item itemDesc
1786 relative to its toplevel ancestor (usually the root item,
1787 unless the ancestor is an orphan). If you imagine all the
1788 items flattened into a vertical list, the result of this
1789 command is the row the item falls in. If the optional
1790 argument -visible is given, only the items whose ances‐
1791 tors are expanded, and whose -visible option is true, get
1792 counted; in this case -1 is returned if the item is not
1793 visible.
1794 pathName item parent itemDesc
1796 Returns the item id of the parent of the item described
1797 by itemDesc.
1798 pathName item prevsibling sibling ?prev?
1800 If prev is not specified, returns the item id of the pre‐
1801 vious sibling of the item described by sibling. If prev
1802 is specified, it must describe an item that is not an
1803 ancestor of sibling. Then it will become the new previ‐
1804 ous sibling of sibling.
1805 pathName item range first last
1807 Returns a list containing the item ids of all items in
1808 the range between first and last, inclusive. The order
1809 between first and last doesn't matter, and the result is
1810 always sorted by the increasing order of the items (as
1811 returned by the item order command). The items specified
1812 by first and last must share a common ancestor.
1813 pathName item remove itemDesc
1815 Removes the item described by itemDesc from the list of
1816 children of its parent, so that it will become an orphan.
1817 pathName item rnc itemDesc
1819 Returns a list of two integers, which corresponds to the
1820 row and column of the item described by itemDesc. The row
1821 and column corresponds to the on-screen arrangement of
1822 items as determined by the -orient and -wrap options. If
1823 the item is not displayed, this command returns an empty
1824 string.
1825 pathName item sort itemDesc ?option ...?
1827 Sorts the children of the item described by itemDesc, and
1828 redisplays the tree with the items in the new order.
1829 The range of items which should be sorted can be
1831 restricted by means of the -first and/or -last options,
1832 which should be children of the item described by
1833 itemDesc; the order between these two limiting items
1834 doesn't matter.
1835 The sort column can be specified by means of the -column
1837 option; this option can be used repeatedly to define a
1838 multicolumn sort. The sorting is done by looking at the
1839 text of the element specified by the -element option,
1840 which must be a text element defined in the style of the
1841 sorting column, by default the first text element is
1842 used.
1843 If the -notreally option is specified, no rearranging of
1845 the items is done; instead the sorted items are returned
1846 as result of the command.
1847 By default ASCII sorting is used with the result returned
1849 in increasing order. Any of the following options may be
1850 specified to control the sorting process of the previ‐
1851 ously specified column (unique abbreviations are
1852 accepted):
1853 -ascii Use string comparison with ASCII collation order.
1855 This is the default.
1856 -command command
1858 Use command as a comparison command. To compare
1859 two items, evaluate a Tcl script consisting of
1860 command with the numerical ids of the two items
1861 appended as additional arguments. The script
1862 should return an integer less than, equal to, or
1863 greater than zero if the first item is to be con‐
1864 sidered less than, equal to, or greater than the
1865 second, respectively.
1866 -decreasing
1868 Sort the items in decreasing order ("largest"
1869 items first).
1870 -dictionary
1872 Use dictionary-style comparison. This is the same
1873 as -ascii except (a) case is ignored except as a
1874 tie-breaker and (b) if two strings contain embed‐
1875 ded numbers, the numbers compare as integers, not
1876 characters. For example, in -dictionary mode,
1877 bigBoy sorts between bigbang and bigboy, and x10y
1878 sorts between x9y and x11y.
1879 -increasing
1881 Sort the items in increasing order ("smallest"
1882 items first). This is the default.
1883 -integer
1885 Convert to integers and use integer comparison.
1886 -real Convert to floating-point values and use floating
1888 comparison.
1889 pathName item span itemDesc ?column? ?numColumns? ?column num‐
1891 Columns ...?
1892 This command sets or retrieves the number of columns that
1893 a style covers. If no column is specified, the return
1894 value is a list of spans, one per column. If no num‐
1895 Columns is specified, the return value is the span for
1896 column.
1897 If one or more column-numColumns pairs is specified, the
1899 span for each column is set to numColumns. In this case
1900 itemDesc may refer to multiple items and each column may
1901 refer to multiple columns.
1902 pathName item state command itemDesc ?arg ...?
1904 This command is used to manipulate the states of an item.
1905 The exact behavior of the command depends on the command
1906 argument that follows the style argument. The following
1907 forms of the command are supported:
1908 pathName item state forcolumn itemDesc column ?stat‐
1910 eDescList?
1911 Just like item state set but manipulates dynamic
1912 states for a single item column, not the item as a
1913 whole. If stateDescList is unspecified, this com‐
1914 mand returns a list containing the names of all
1915 the dynamic states which are switched on in col‐
1916 umn.
1917 If stateDescList is specified, then itemDesc may
1919 refer to multiple items and column may refer to
1920 multiple columns.
1921 pathName item state get itemDesc ?stateName?
1923 If no stateName is specified, returns a list con‐
1924 taining the names of all (static and dynamic)
1925 states which are currently switched on for the
1926 item described by itemDesc. If a stateName is
1927 specified, 1 is returned if the specified state is
1928 currently switched on for the item, 0 otherwise.
1929 pathName item state set itemDesc ?lastItem? stateDescList
1931 Every element of stateDescList must be the name of
1932 a dynamic state (see STATES below), optionally
1933 preceded by a ~ or ! character. Every state with
1934 a leading ! will be switched off for the item
1935 described by itemDesc, every state with a leading
1936 ~ will be toggled, and every state without leading
1937 ! or ~ will be switched on. If lastItem is speci‐
1938 fied, the state changes will be made for all items
1939 in the range between itemDesc and lastItem. If
1940 lastItem unspecified, then the state changes are
1941 made for all items described by itemDesc.
1942 pathName item style command itemDesc ?arg ...?
1944 This command is used to manipulate the styles of an item.
1945 The exact behavior of the command depends on the command
1946 argument that follows the style argument. The following
1947 forms of the command are supported:
1948 pathName item style elements itemDesc column
1950 This command returns a list containing the names
1951 of elements which were configured by the item ele‐
1952 ment configure command for the item described by
1953 itemDesc in column. If there is no style assigned
1954 to column an error is returned.
1955 pathName item style map itemDesc column style map
1957 Like the item style set command, this command may
1958 be used to assign a style to a specific column of
1959 an item. Unlike item style set, this command can
1960 transfer configuration values of elements in the
1961 current style to elements in the new style speci‐
1962 fied by style. Map must be a list of elementOld-
1963 elementNew pairs, where elementOld is an element
1964 in the current style, and elementNew is an element
1965 in the style specified by style. Both elementOld
1966 and elementNew must be of the same type (bitmap,
1967 text etc). ItemDesc may refer to multiple items
1968 and column may refer to multiple columns.
1969 pathName item style set itemDesc ?column? ?style? ?column
1971 style ...?
1972 This command sets or retrieves the style assigned
1973 to one or more columns. If no column is speci‐
1974 fied, this command returns a list containing the
1975 names of the styles set for all columns of the
1976 item described by itemDesc. If no style is speci‐
1977 fied, this command returns the name of the style
1978 set for the item described by itemDesc in column.
1979 If one or more column-style pairs is specified,
1981 then the style in each column is set to style. In
1982 this case itemDesc may refer to multiple items and
1983 each column may refer to multiple columns.
1984 pathName item tag option ?arg arg ...?
1986 This command is used to manipulate tags on items. The
1987 exact behavior of the command depends on the option argu‐
1988 ment that follows the item tag argument. The following
1989 forms of the command are supported:
1990 pathName item tag add itemDesc tagList
1992 Adds each tag in tagList to the items specified by
1993 the item description itemDesc. Duplicate tags are
1994 ignored. The list of tags for an item can also be
1995 changed via an item's -tags option.
1996 pathName item tag expr itemDesc tagExpr
1998 Evaluates the tag expression tagExpr against every
1999 item specified by the item description itemDesc.
2000 The result is 1 if the tag expression evaluates to
2001 true for every item, 0 otherwise.
2002 pathName item tag names itemDesc
2004 Returns a list of tag names assigned to the items
2005 specified by the item description itemDesc. The
2006 result is the union of any tags assigned to the
2007 items.
2008 pathName item tag remove itemDesc tagList
2010 Removes each tag in tagList from the items speci‐
2011 fied by the item description itemDesc. It is not
2012 an error if any of the items do not use any of the
2013 tags. The list of tags for an item can also be
2014 changed via an item's -tags option.
2015 pathName item text itemDesc ?column? ?text? ?column text ...?
2017 This command sets or retrieves the value of the -text
2018 option for the first text element in one or more columns.
2019 If no column is specified, this command returns a list of
2020 values, one per column. If no text is specified, this
2021 command returns the value for column.
2022 If one or more column-text pairs is specified, then the
2024 value of the -text option in each column is set to text.
2025 In this case itemDesc may refer to multiple items and
2026 each column may refer to multiple columns.
2027 Note that this command is provided as a convenience. Use
2029 the item element configure or item element cget commands
2030 if you want to set or retrieve the value of the -text
2031 option for a specific text element.
2032 pathName item toggle itemDesc ?-recurse?
2034 Changes the open state of the item(s) described by
2035 itemDesc. If the open state is currently switched off,
2036 then this command does the same as the item expand widget
2037 command; otherwise the same as the item collapse widget
2038 command. If -recurse is specified, then the open state
2039 of all descendants of the items described by itemDesc
2040 will also be toggled.
2041 pathName marquee option ?arg ...?
2043 This command is used to manipulate the marquee, a rectangular
2044 region of the treectrl widget optionally marked with a surround‐
2045 ing dotted line. One corner point of the marquee is fixed as
2046 long as the marquee is visible and called the anchor; the diago‐
2047 nally opposite corner is dragged with the mouse while resizing
2048 the marquee and simply called the corner. All coordinates han‐
2049 dled by this widget command are treectrl coordinates, i.e. the
2050 canvasx or canvasy widget command should be used before any win‐
2051 dow coordinates can be used. The exact behavior of the command
2052 depends on the option argument that follows the marquee argu‐
2053 ment. The following forms of the command are supported:
2054 pathName marquee anchor ?x y?
2056 Returns a list containing the x and y coordinates of the
2057 anchor, if no additional arguments are specified. If two
2058 coordinates are specified, sets the anchor to the given
2059 coordinates x and y.
2060 pathName marquee cget option
2062 This command returns the current value of the marquee
2063 option named option. Option may have any of the values
2064 accepted by the marquee configure widget command.
2065 pathName marquee configure ?option? ?value? ?option value ...?
2067 This command is similar to the configure widget command
2068 except that it modifies the marquee options instead of
2069 modifying options for the overall treectrl widget. If no
2070 option is specified, the command returns a list describ‐
2071 ing all of the available marquee options (see Tk_Config‐
2072 ureInfo for information on the format of this list). If
2073 option is specified with no value, then the command
2074 returns a list describing the one named marquee option
2075 (this list will be identical to the corresponding sublist
2076 of the value returned if no option is specified). If one
2077 or more option-value pairs are specified, then the com‐
2078 mand modifies the given marquee option(s) to have the
2079 given value(s); in this case the command returns an empty
2080 string.
2081 The following marquee options are supported:
2083 -visible boolean
2085 Specifies a boolean value which determines whether
2086 the dotted line surrounding the region of the mar‐
2087 quee should currently be visible.
2088 pathName marquee coords ?x1 y1 x2 y2?
2090 Returns a list containing the x and y coordinates of the
2091 anchor followed by the x and y coordinates of the corner,
2092 if no additional arguments are specified. If four coor‐
2093 dinates are specified, sets the anchor to the given coor‐
2094 dinates x1 and y1 and the corner to the coordinates x2
2095 and y2.
2096 pathName marquee corner ?x y?
2098 Returns a list containing the x and y coordinates of the
2099 corner, if no additional arguments are specified. If two
2100 coordinates are specified, sets the corner to the given
2101 coordinates x and y.
2102 pathName marquee identify
2104 Returns a list with information about any items inter‐
2105 secting the marquee. The format of the returned list is:
2106 {
2108 {item {column element element ...} {column element element ...} ...}
2109 {item {column element element ...} {column element element ...} ...}
2110 ...
2111 }
2112 There may be zero sublists following an item id if the
2114 marquee is in the button/line area of an item. There may
2115 be zero element names following a column id if the item-
2116 column has no style or if the marquee does not intersect
2117 any elements in that column.
2118 pathName notify option ?arg ...?
2120 Many Tk widgets communicate with the outside world via -command
2121 callbacks and/or virtual events. For example, the Text widget
2122 evaluates its -yscrollcommand when the view in the widget
2123 changes, and generates a <<Modified>> virtual event when text is
2124 inserted or deleted. A treectrl widget replaces both methods of
2125 communication with its own event mechanism accessed through the
2126 notify subcommands.
2127 The exact behavior of the command depends on the option argument
2129 that follows the notify argument. The following forms of the
2130 command are supported:
2131 pathName notify bind ?object? ?pattern? ?+??script?
2133 This command associates Tcl scripts with events generated
2134 by a treectrl widget. If all three arguments are speci‐
2135 fied, notify bind will arrange for script (a Tcl script)
2136 to be evaluated whenever the event(s) specified by pat‐
2137 tern are generated by this treectrl widget. If script is
2138 prefixed with a "+", then it is appended to any existing
2139 binding for pattern; otherwise script replaces any
2140 existing binding. If script is an empty string then the
2141 current binding for pattern is destroyed, leaving pattern
2142 unbound. In all of the cases where a script argument is
2143 provided, notify bind returns an empty string.
2144 If pattern is specified without a script, then the script
2146 currently bound to pattern is returned, or an empty
2147 string is returned if there is no binding for pattern. If
2148 neither pattern nor script is specified, then the return
2149 value is a list whose elements are all the patterns for
2150 which there exist bindings for object.
2151 The object argument determines which window(s) the bind‐
2153 ing applies to. If object begins with a dot, as in
2154 .a.b.c, then it must be the path name for a window; oth‐
2155 erwise it may be an arbitrary string. Like the regular
2156 bind command, bindings on window names are automatically
2157 removed if that window is destroyed.
2158 pathName notify configure object pattern ?option? ?value?
2160 ?option value ...?
2161 This command sets and retrieves options for bindings cre‐
2162 ated by the notify bind command.
2163 If no option is specified, the command returns a list
2165 with option-value pairs describing all the available
2166 binding options for pattern on object. If option is
2167 specified with no value, then the command returns the
2168 current value of that option. If one or more option-
2169 value pairs are specified, then the command modifies the
2170 given option(s) to have the given value(s) for the bind‐
2171 ing; in this case the command returns an empty string.
2172 The following binding options are supported:
2174 -active boolean
2176 Specifies if the binding should be active. As
2177 long as this option is specified as false, a bind‐
2178 ing script will not be evaluated when the corre‐
2179 sponding event is generated.
2180 pathName notify detailnames eventName
2182 Returns a list containing the names of all details, which
2183 are installed for the event with the name eventName by
2184 means of the notify install widget command or by the
2185 treectrl widget itself.
2186 pathName notify eventnames
2188 Returns a list containing the names of all events, which
2189 are installed by means of the notify install widget com‐
2190 mand or by the treectrl widget itself.
2191 pathName notify generate pattern ?charMap? ?percentsCommand?
2193 This command causes the treectrl widget to generate an
2194 event. This command is typically used to generate dynamic
2195 events created by the notify install command, but may be
2196 used to generate static events also. The event specified
2197 by pattern is generated, and any active binding scripts
2198 on the event are evaluated after undergoing %-substitu‐
2199 tion. If there are details defined for the event, pat‐
2200 tern must describe an <eventName-detail> pair, otherwise
2201 pattern should be <eventName>.
2202 The optional charMap is a list of char-value pairs as in
2204 the form returned by array get. Each char has to be
2205 exactly one character. The charMap is used in %-substi‐
2206 tution.
2207 If percentsCommand is specified, then it will be used to
2209 perform %-substitution on any scripts bound to the event.
2210 If percentsCommand is not specified and the event is
2211 dynamic, then the %-subtitution command passed to notify
2212 install will be used if it was provided. If the event is
2213 static or no %-substitution command is available, then
2214 all %-substitution is done using charMap only . See
2215 notify install for a description of percentsCommand.
2216 pathName notify install pattern ?percentsCommand?
2218 This command installs a new event or detail specified by
2219 pattern. Events created by this command are called
2220 dynamic, whereas events created by the treectrl widget
2221 itself are called static. This command may be called to
2222 set or retrieve the percentsCommand for an existing
2223 dynamic event.
2224 The optional percentsCommand is a list containing the
2226 name of a Tcl command, plus any optional arguments, to
2227 which five additional arguments will be appended. The
2228 command will be called to perform %-substitution on any
2229 scripts bound to the event specified by pattern (see
2230 EVENTS AND SCRIPT SUBSTITUTIONS). PercentsCommand should
2231 be defined as follows:
2232 proc percentsCommand {?arg arg ...? char object event detail charMap} {
2234 switch -- $char {
2235 ...
2236 }
2237 return $value
2238 }
2239 The optional arg arguments are part of the percentsCom‐
2241 mand list. Char is the %-character to be substituted.
2242 Object is the same as the argument to notify bind. Event
2243 and detail specify the event. CharMap is the same as the
2244 argument to notify generate. PercentsCommand should
2245 return the value to replace the %-character by. If an
2246 error occurs evaluating percentsCommand, the %-character
2247 is replaced by itself.
2248 notify install returns the current percentsCommand for
2250 the event, or an error if the event is not dynamic.
2251 pathName notify install detail eventName detail ?percentsCom‐
2253 mand?
2254 Deprecated. Use notify install with a pattern of <event‐
2255 Name-detail> instead.
2256 pathName notify install event eventName ?percentsCommand?
2258 Deprecated. Use notify install with a pattern of <event‐
2259 Name> instead.
2260 pathName notify linkage pattern
2262 Returns a string indicating whether the specified event
2263 or detail is created by means of the notify install wid‐
2264 get command (dynamic) or by the treectrl widget itself
2265 (static).
2266 pathName notify linkage eventName ?detail?
2268 Deprecated. Use notify linkage with a pattern of <event‐
2269 Name> or <eventName-detail> instead.
2270 pathName notify unbind object ?pattern?
2272 If no pattern is specified, all bindings on object are
2273 removed. If pattern is specified, then the current bind‐
2274 ing for pattern is destroyed, leaving pattern unbound.
2275 pathName notify uninstall pattern
2277 If the event or detail specified by pattern is static
2278 (i.e. created by the treectrl widget itself), an error is
2279 generated. Otherwise the dynamic event or detail is
2280 removed. If an event name is specified without a detail,
2281 all details for that event are also removed.
2282 pathName notify uninstall detail eventName detail
2284 Deprecated. Use notify uninstall with a pattern of
2285 <eventName-detail> instead.
2286 pathName notify uninstall event eventName
2288 Deprecated. Use notify uninstall with a pattern of
2289 <eventName> instead.
2290 pathName numcolumns
2292 Deprecated. Use the column count command instead.
2293 pathName numitems
2295 Deprecated. Use the item count command instead.
2296 pathName orphans
2298 Returns a list containing the item ids of all items which have
2299 no parent. When an item is created, it has no parent by
2300 default, and can later become an orphan by means of the item
2301 remove widget command. The root item is not returned.
2302 pathName range first last
2304 Deprecated. Use the item range command instead.
2305 pathName scan option args
2307 This command is used to implement scanning on treectrls. It has
2308 two forms, depending on option:
2309 pathName scan mark x y
2311 Records x and y and the treectrl's current view; used in
2312 conjunction with later scan dragto commands. Typically
2313 this command is associated with a mouse button press in
2314 the widget and x and y are the coordinates of the mouse.
2315 It returns an empty string.
2316 pathName scan dragto x y ?gain?
2318 This command computes the difference between its x and y
2319 arguments (which are typically mouse coordinates) and the
2320 x and y arguments to the last scan mark command for the
2321 widget. It then adjusts the view by gain times the dif‐
2322 ference in coordinates, where gain defaults to 10. This
2323 command is typically associated with mouse motion events
2324 in the widget, to produce the effect of dragging the
2325 treectrl at high speed through its window. The return
2326 value is an empty string.
2327 pathName state option args
2329 This command is used to manipulate the list of user-defined
2330 states, see section STATES below. The exact behavior of the
2331 command depends on the option argument that follows the state
2332 argument. The following forms of the command are supported:
2333 pathName state define stateName
2335 Defines a new state with the name stateName, which must
2336 not be the name of an existing state.
2337 pathName state linkage stateName
2339 Returns a string indicating whether the specified state
2340 is user-defined by means of the state define widget com‐
2341 mand (dynamic) or predefined by the treectrl widget
2342 itself (static).
2343 pathName state names
2345 Returns a list containing the names of all user-defined
2346 states.
2347 pathName state undefine ?stateName ...?
2349 Every stateName must be the name of a user-defined state.
2350 Removes this state from the list of user-defined states.
2351 pathName see itemDesc
2353 Adjust the view in the treectrl so that the item described by
2354 itemDesc is visible. If the item is already visible then the
2355 command has no effect; otherwise the treectrl scrolls to bring
2356 the item into view, and the corresponding <Scroll-x> and/or
2357 <Scroll-y> events are generated.
2358 pathName selection option args
2360 This command is used to adjust the selection within a treectrl.
2361 It has several forms, depending on option:
2362 pathName selection add first ?last?
2364 First and last (if specified) must be valid item descrip‐
2365 tions. If both first and last are specified, then they
2366 may refer to a single item only; in this case the command
2367 adds every unselected item in the range between first and
2368 last, inclusive, to the selection without affecting the
2369 selected state of items outside that range. If only
2370 first is specified, then every unselected item specified
2371 by first is added to the selection. A <Selection> event
2372 is generated if any items were added to the selection.
2373 pathName selection anchor ?itemDesc?
2375 If itemDesc is specified, the selection anchor is set to
2376 the described item. The selection anchor is the end of
2377 the selection that is fixed while dragging out a selec‐
2378 tion with the mouse. The item description anchor may be
2379 used to refer to the anchor item. This command doesn't
2380 modify the selection state of any item. Returns the
2381 unique id of the selection anchor item.
2382 pathName selection clear ?first? ?last?
2384 First and last (if specified) must be valid item descrip‐
2385 tions. If both first and last are specified, then they
2386 may refer to a single item only; in this case any
2387 selected items between first and last (inclusive) are
2388 removed from the selection without affecting the selected
2389 state of items outside that range. If only first is
2390 specified, then every selected item specified by first is
2391 removed from the selection. If neither first nor last
2392 are specified, then all selected items are removed from
2393 the selection. A <Selection> event is generated if any
2394 items were removed from the selection.
2395 pathName selection count
2397 Returns an integer indicating the number of items in the
2398 treectrl that are currently selected.
2399 pathName selection get ?first? ?last?
2401 When no additional arguments are given, the result is an
2402 unsorted list containing the item ids of all of the items
2403 in the treectrl that are currently selected. If there
2404 are no items selected in the treectrl, then an empty
2405 string is returned. The optional arguments first and
2406 last are treated as indices into the sorted list of
2407 selected items; these arguments allow in-place lindex and
2408 lrange operations on the selection. For example:
2409 pathName selection includes itemDesc
2413 Returns 1 if the item described by itemDesc is currently
2414 selected, 0 if it isn't.
2415 pathName selection modify select deselect
2417 Both arguments select and deselect are a possibly-empty
2418 list of item descriptions. Any unselected items in
2419 select are added to the selection, and any selected items
2420 in deselect are removed from the selection (except for
2421 those items which are also in select). A <Selection>
2422 event is generated if any items were selected or dese‐
2423 lected.
2424 pathName style option ?element? ?arg arg ...?
2426 This command is used to manipulate styles, which can be thought
2427 of as a geometry manager for elements. The exact behavior of
2428 the command depends on the option argument that follows the
2429 style argument. The following forms of the command are sup‐
2430 ported:
2431 pathName style cget style option
2433 This command returns the current value of the option
2434 named option associated with the style given by style.
2435 Option may have any of the values accepted by the style
2436 configure widget command.
2437 pathName style configure style ?option? ?value? ?option value
2439 ...?
2440 This command is similar to the configure widget command
2441 except that it modifies options associated with the style
2442 given by style instead of modifying options for the over‐
2443 all treectrl widget. If no option is specified, the com‐
2444 mand returns a list describing all of the available
2445 options for style (see Tk_ConfigureInfo for information
2446 on the format of this list). If option is specified with
2447 no value, then the command returns a list describing the
2448 one named option (this list will be identical to the cor‐
2449 responding sublist of the value returned if no option is
2450 specified). If one or more option-value pairs are speci‐
2451 fied, then the command modifies the given option(s) to
2452 have the given value(s) in style; in this case the com‐
2453 mand returns an empty string.
2454 The options of a style have effect on all elements man‐
2456 aged by the style. The following options are supported:
2457 -orient varName
2459 This option specifies which orientation should be
2460 used when laying out the elements associated with
2461 this style. Must be either horizontal (the
2462 default) or vertical or an abbreviation of one of
2463 these.
2464 pathName style create style ?option value ...?
2466 Create a new style in pathName with name style. After
2467 style there may be any number of option-value pairs, each
2468 of which sets one of the configuration options for the
2469 style. These same option-value pairs may be used in
2470 style configure widget commands to change the style's
2471 configuration. Returns the name of the new style.
2472 pathName style delete ?style ...?
2474 Deletes each of the named styles and returns an empty
2475 string. If a style is deleted while it is still used to
2476 display one or more items, it is also removed from the
2477 style list of these items.
2478 pathName style elements style ?elementList?
2480 Specifies the elements which should be layed out by this
2481 style. Each element of elementList must be the name of
2482 an element created by the widget command element create.
2483 Duplicate names in elementList are ignored. An element
2484 which was specified in a former call of this command for
2485 style but is not included in elementList, will be deleted
2486 from the elements layed out by style.
2487 If the elementList argument is not specified, a list is
2489 returned containing the currently defined elements of
2490 style.
2491 pathName style layout style element ?option? ?value? ?option
2493 value ...?
2494 This command is similar to the configure widget command
2495 except that it modifies options used by style for laying
2496 out element instead of modifying options for the overall
2497 treectrl widget. If no option is specified, the command
2498 returns a list with option-value pairs describing all of
2499 the available options for the layout. If option is spec‐
2500 ified with no value, then the command returns the value
2501 of the named option. If one or more option-value pairs
2502 are specified, then the command modifies the given
2503 option(s) to have the given value(s) for the layout; in
2504 this case the command returns an empty string.
2505 The options of a layout have effect on exactly the one
2507 element element managed by style. The following options
2508 are supported:
2509 -detach boolean
2511 Specifies whether the element should be positioned
2512 by itself, i.e. independent from the other ele‐
2513 ments.
2514 -draw boolean
2516 This is a per-state option that determines whether
2517 an element should be drawn. If the value of the
2518 option evaluates to false for a given item state,
2519 then the element is not drawn, although it still
2520 consumes space in the layout.
2521 -expand flags
2523 This option allows the external padding around the
2524 element to increase when a style has more screen
2525 space than it needs. Flags is a string that con‐
2526 tains zero or more of the characters n, s, w or e.
2527 Each letter refers to the padding on the top, bot‐
2528 tom, left, or right that should be allowed to
2529 increase. This option is typically used to jus‐
2530 tify an element.
2531 -iexpand flags
2533 This option allows the internal padding of the
2534 element and the display area of the element to
2535 increase when a style has more screen space than
2536 it needs. Flags is a string that contains zero
2537 or more of the characters x, y, n, s, w or e. For
2538 n, s, w and e, each letter refers to the padding
2539 on the top, bottom, left, or right that should be
2540 allowed to increase. For x and y, each letter
2541 refers to the horizontal and vertical screen space
2542 the element can display itself in (i.e., the space
2543 between the padding). Note that if the -union
2544 option is specified for this element, then the x
2545 and y flags have no effect, since the size of an
2546 element with -union layout is determined by the
2547 elements it surrounds.
2548 -indent boolean
2550 Specifies whether the element should be positioned
2551 to the right of the button/line area in the tree
2552 column. This option is ignored unless the -detach
2553 option is true.
2554 -ipadx amount
2556 -ipady amount
2558 Amount specifies how much internal padding to
2559 leave on the left and right (for -ipadx) or top
2560 and bottom (for -ipady) side of the element.
2561 Amount may be a list of two values to specify pad‐
2562 ding for the two sides separately, it defaults to
2563 0.
2564 -minheight pixels
2566 -height pixels
2568 -maxheight pixels
2570 Specifies the minimum, fixed, and maximum height
2571 of the element.
2572 -minwidth pixels
2574 -width pixels
2576 -maxwidth pixels
2578 Specifies the minimum, fixed, and maximum width of
2579 the element.
2580 -padx amount
2582 -pady amount
2584 Amount specifies how much external padding to
2585 leave on the left and right (for -padx) or top and
2586 bottom (for -pady) side of the element. Amount
2587 may be a list of two values to specify padding for
2588 the two sides separately, it defaults to 0.
2589 -squeeze flags
2591 This option allows the display area of an element
2592 to decrease when a style has less space than it
2593 needs. Flags is a string that contains zero or
2594 more of the characters x or y. x allows display
2595 area to decrease horizontally, y allows display
2596 area to decrease vertically. This option is typi‐
2597 cally used for text elements and will cause the
2598 text element to display an ellipsis (...) and/or
2599 wrap lines.
2600 -sticky flags
2602 This option controls how the actual display infor‐
2603 mation (image, text, etc) of an element is posi‐
2604 tioned (or stretched) within its display area.
2605 Flags is a string that contains zero or more of
2606 the characters n, s, w or e. Each letter refers to
2607 the top, bottom, left or right side of the display
2608 area that the display information should "stick"
2609 to.
2610 -union elementList
2612 Specifies a list of other elements which this ele‐
2613 ment will surround. The size of an element with
2614 -union layout is determined by the size and posi‐
2615 tion of the elements in elementList. The -ipadx
2616 and -ipady options in this case refer to the dis‐
2617 tance of the edges of the display area of this
2618 element from those elements it surrounds. This
2619 option is typically used to display a selection
2620 rectangle around a piece of text. If none of the
2621 elements in elementList are visible, then the ele‐
2622 ment is not displayed.
2623 -visible boolean
2625 This is a per-state option that controls visibil‐
2626 ity of an element. If the value of the option
2627 evaluates to false for a given item state, then
2628 the element is not displayed and consumes no space
2629 in the layout.
2630 pathName style names
2632 Returns a list containing the names of all existing
2633 styles.
2634 pathName toggle ?-recurse? ?itemDesc ...?
2636 Use item toggle instead.
2637 pathName xview ?args?
2639 This command is used to query and change the horizontal position
2640 of the information displayed in the treectrl's window. It can
2641 take any of the following forms:
2642 pathName xview
2644 Returns a list containing two elements. Each element is
2645 a real fraction between 0 and 1; together they describe
2646 the horizontal span that is visible in the window. For
2647 example, if the first element is .2 and the second ele‐
2648 ment is .6, 20% of the tree's area is off-screen to the
2649 left, the middle 40% is visible in the window, and 40% of
2650 the tree is off-screen to the right. These are the same
2651 values passed to scrollbars via the -xscrollcommand
2652 option.
2653 pathName xview moveto fraction
2655 Adjusts the view in the window so that fraction of the
2656 total width of the tree is off-screen to the left. Frac‐
2657 tion must be a fraction between 0 and 1. A <Scroll-x>
2658 event is generated.
2659 pathName xview scroll number what
2661 This command shifts the view in the window left or right
2662 according to number and what. Number must be an integer.
2663 What must be either units or pages or an abbreviation of
2664 one of these. If what is units, the view adjusts left or
2665 right in units determined by the -xscrollincrement option
2666 (which may be zero, see the description of that option).
2667 If what is pages then the view adjusts in units of nine-
2668 tenths the window's width. If number is negative then
2669 information farther to the left becomes visible; if it
2670 is positive then information farther to the right becomes
2671 visible. A <Scroll-x> event is generated.
2672 pathName yview ?args?
2674 This command is used to query and change the vertical position
2675 of the information displayed in the treectrl's window. It can
2676 take any of the following forms:
2677 pathName yview
2679 Returns a list containing two elements. Each element is
2680 a real fraction between 0 and 1; together they describe
2681 the vertical span that is visible in the window. For
2682 example, if the first element is .6 and the second ele‐
2683 ment is 1.0, the lowest 40% of the tree's area is visible
2684 in the window. These are the same values passed to
2685 scrollbars via the -yscrollcommand option.
2686 pathName yview moveto fraction
2688 Adjusts the view in the window so that fraction of the
2689 tree's area is off-screen to the top. Fraction is a
2690 fraction between 0 and 1. A <Scroll-y> event is gener‐
2691 ated.
2692 pathName yview scroll number what
2694 This command adjusts the view in the window up or down
2695 according to number and what. Number must be an integer.
2696 What must be either units or pages. If what is units,
2697 the view adjusts up or down in units of the
2698 -yscrollincrement option (which may be zero, see the
2699 description of that option). If what is pages then the
2700 view adjusts in units of nine-tenths the window's height.
2701 If number is negative then higher information becomes
2702 visible; if it is positive then lower information
2703 becomes visible. A <Scroll-y> event is generated.
2704
2706 A treectrl widget is capable of displaying multiple columns next to
2707 each other. An item can be considered as a row, which reaches over all
2708 columns.
2709 Columns in a treectrl may be specified in a number of ways. See COLUMN
2711 DESCRIPTION below.
2712 There is always one special column, the tail column, which fills all
2714 space to the right of the last ordinary column. This column has no
2715 number; it can only be specified by the keyword tail.
2716 When a column configuration option is specified as per-state, the state
2718 names are normal, active, pressed or up, i.e. do not use item state
2719 names.
2720 The following options are supported for columns:
2722 -arrow direction
2724 Indicates whether or not an arrow should be drawn in the column
2725 header. Direction must have one of the values none (the
2726 default), up, or down.
2727 -arrowbitmap bitmap
2729 Specifies as a per-state option the bitmap to use to draw the
2730 arrow if this column's -arrow option is not none.
2731 -arrowimage image
2733 Specifies as a per-state option the image to use to draw the
2734 arrow if this column's -arrow option is not none. If an image
2735 is specified for a certain state, it overrides the -arrowbitmap
2736 option.
2737 -arrowside side
2739 Indicates on which side of the bitmap/image/text the arrow
2740 should be drawn. Side must be either left or right (the
2741 default).
2742 -arrowgravity side
2744 Indicates onto which side an arrow should be packed, if there is
2745 more space available for drawing the arrow then needed. Side
2746 must be either left (the default) or right.
2747 -arrowpadx amount
2749 Amount specifies how much padding to leave on the left and right
2750 of the arrow. Amount may be a list of two values to specify
2751 padding for left and right separately; it defaults to 6.
2752 -arrowpady amount
2754 Amount specifies how much padding to leave on the top and bottom
2755 of the arrow. Amount may be a list of two values to specify
2756 padding for top and bottom separately; it defaults to 0.
2757 -bitmap bitmap
2759 Specifies the bitmap to display in the element to the left of
2760 the column title.
2761 -background color
2763 Specifies as a per-state option the color to use for the back‐
2764 ground of the column header.
2765 -borderwidth size
2767 Specifies a non-negative value indicating the width of the 3-D
2768 border to draw around the outside of the column header (if such
2769 a border is being drawn; the -relief column option determines
2770 this). The value may have any of the forms acceptable to
2771 Tk_GetPixels.
2772 -button boolean
2774 Indicates whether or not the column header should be treated
2775 like a pushbutton. When this option is true, the default bind‐
2776 ings track <Button-1> events in the header and generate a
2777 <Header-invoke> event when a <ButtonRelease-1> event occurs in
2778 the header. See DYNAMIC EVENTS.
2779 -expand boolean
2781 Indicates whether or not any extra horizontal space should be
2782 distributed to this column. This option has no effect if the
2783 -width option is set.
2784 -font fontName
2786 Specifies the font to use for the column title inside the column
2787 header.
2788 -image image
2790 Specifies the image to display in the element to the left of the
2791 column title. This option overrides the -bitmap column option.
2792 -imagepadx amount
2794 Amount specifies how much padding to leave on the left and right
2795 of the image (or bitmap). Amount may be a list of two values to
2796 specify padding for left and right separately; it defaults to 6.
2797 -imagepady amount
2799 Amount specifies how much padding to leave on the top and bottom
2800 of the image (or bitmap). Amount may be a list of two values to
2801 specify padding for top and bottom separately; it defaults to 0.
2802 -itembackground colorList
2804 Specifies a list of zero or more colors, which are used as
2805 alternating background colors for items in this column. See
2806 also the -backgroundmode widget option for more on this.
2807 -itemjustify justification
2809 This option determines how the item styles in this column line
2810 up with each other. Must be one of left, center, or right. The
2811 default value is an empty string (for compatibility with older
2812 versions), in which case the column option -justify is used to
2813 align item styles in this column.
2814 -itemstyle style
2816 Style is the name of a style that should be set in this column
2817 for newly-created items.
2818 -justify justification
2820 This option determines how the image and text in the column
2821 header are positioned. It also affects the position of item
2822 styles in this column unless the column option -itemjustify is
2823 specified. Must be one of left (the default), center, or right.
2824 -lock lock
2826 This option allows a column to stick to the left or right edge
2827 of the window. A locked column scrolls vertically but not hori‐
2828 zontally. Must be one of none (the default), left, or right.
2829 -maxwidth size
2831 Specifies the maximum size, in screen units, that will be per‐
2832 mitted for this column. If size is an empty string, then there
2833 is no limit on the maximum size of the column. This option has
2834 no effect if the -width option is set.
2835 -minwidth size
2837 Specifies the minimum size, in screen units, that will be per‐
2838 mitted for this column. If size is an empty string, then the
2839 minimum size of the column is zero. This option has no effect
2840 if the -width option is set.
2841 -resize boolean
2843 Specifies a boolean value that indicates whether the user should
2844 be allowed to resize the column by dragging the edge of the col‐
2845 umn's header. Default is true.
2846 -squeeze boolean
2848 Specifies a boolean value that indicates whether or not the col‐
2849 umn should shrink when the content width of the treectrl is less
2850 than the total needed width of all visible columns. Defaults to
2851 false, which means the column will not get smaller than its
2852 needed width. The column will not get smaller than the value of
2853 its -minwidth option, if specified. This option has no effect if
2854 the -width option is set.
2855 -state state
2857 Specifies one of three states for the column header: normal,
2858 active, or pressed. The active state is used when the mouse is
2859 over the header. The pressed state is used when the mouse but‐
2860 ton is pressed in the header.
2861 -stepwidth size
2863 Deprecated. Use the treectrl's -itemwidthmultiple option
2864 instead.
2865 -tags tagList
2867 TagList is a list of tag names that can be used to identify the
2868 column. See also the column tag command.
2869 -text text
2871 Specifies a text string to be displayed as the column title.
2872 -textcolor color
2874 Specifies a color, which should be used as foreground color to
2875 display the column title.
2876 -textlines count
2878 Specifies the maximum number of lines of text to display in the
2879 column title. If this value is zero, the number of lines dis‐
2880 played is determined by any newline characters and the effects
2881 of wrapping when the column width is less than needed. The
2882 default is 1. Note: Under OSX/Aqua this value is always set to 1
2883 when the treectrl's -usetheme option is true, because the
2884 Appearance Manager uses a fixed height for the column header;
2885 there is only room for a single line of text.
2886 -textpadx amount
2888 Amount specifies how much padding to leave on the left and right
2889 of the text. Amount may be a list of two values to specify pad‐
2890 ding for left and right separately; it defaults to 6.
2891 -textpady amount
2893 Amount specifies how much padding to leave on the top and bottom
2894 of the text. Amount may be a list of two values to specify pad‐
2895 ding for top and bottom separately; it defaults to 0.
2896 -uniform group
2898 When a non-empty value is supplied, this option places the col‐
2899 umn in a uniform group with other columns that have the same
2900 value for -uniform. The space for columns belonging to a uniform
2901 group is allocated so that their sizes are always in strict pro‐
2902 portion to their -weight values. This option is based on the
2903 grid geometry manager.
2904 -visible boolean
2906 Indicates whether or not the column should be displayed.
2907 -weight integer
2909 Sets the relative weight for apportioning any extra space among
2910 columns. A weight of zero (0) indicates the column will not
2911 deviate from its requested size. A column whose weight is two
2912 will grow at twice the rate as a column of weight one when extra
2913 space is allocated to columns. This option is based on the grid
2914 geometry manager.
2915 -width size
2917 Specifies a fixed width for the column. If this value is an
2918 empty string, then the column width is calculated as the maximum
2919 of: a) the width requested by items; b) the width requested by
2920 the column's header; and c) the column's -minwidth option. This
2921 calculated width is also affected by the -expand, -squeeze,
2922 -uniform and -weight options. In any case, the calculated width
2923 will not be greater than the -maxwidth option, if specified.
2924 -widthhack boolean
2926 Deprecated. Use the treectrl's -itemwidthequal option instead.
2927
2929 Many of the commands and options for a treectrl take as an argument a
2930 description of which column to operate on. See the EXAMPLES section
2931 for examples. The initial part of a column description must begin with
2932 one of the following terms:
2933 id Specifies the unique column identifier, where id should be the
2935 return value of a prior call of the column create widget com‐
2936 mand. See also the -columnprefix option.
2937 QUALIFIERS
2939 Specifies a list of qualifiers. This gives the same result as
2940 all followed by QUALIFIERS; i.e., every column is tested for a
2941 match.
2942 tagExpr QUALIFIERS
2944 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
2945 which every column's tags are tested for a match. This keyword
2946 cannot be followed by any modifiers unless a single column is
2947 matched. You may run into trouble if tagExpr looks like a column
2948 id or other keyword; also, tagExpr must look like a single list
2949 element since column descriptions are properly-formed lists. To
2950 be safe you may want to use the tag qualifier followed by tag‐
2951 Expr.
2952 all QUALIFIERS
2954 Indicates every column, including the tail column if the command
2955 allows it, which match QUALIFIERS.
2956 first QUALIFIERS
2958 Indicates the leftmost column of the treectrl which matches
2959 QUALIFIERS.
2960 end QUALIFIERS
2962 last QUALIFIERS
2964 Indicates the rightmost column of the treectrl (but not the tail
2965 column) which matches QUALIFIERS.
2966 list columnDescs
2968 ColumnDescs is a list (a single argument, i.e. "list {a b c}"
2969 not "list a b c") of other column descriptions. This keyword
2970 cannot be followed by any modifiers unless a single column is
2971 matched.
2972 order n QUALIFIERS
2974 Indicates the nth column in the list of columns as returned by
2975 the column order command.
2976 range first last QUALIFIERS
2978 First and last specify a range of columns. This keyword cannot
2979 be followed by any modifiers unless a single column is speci‐
2980 fied.
2981 tail Indicates the ever-present tail column of the treectrl.
2983 tree Indicates the column specified by the -treecolumn option of the
2985 treectrl.
2986 The initial part of the column description (matching any of the values
2988 above) may be followed by one or more modifiers. A modifier changes
2989 the column used relative to the description up to this point. It may
2990 be specified in any of the following forms:
2991 next QUALIFIERS
2993 Use the column to the right matching QUALIFIERS.
2994 prev QUALIFIERS
2996 Use the column to the left matching QUALIFIERS. The word QUALI‐
2997 FIERS above represents a sequence of zero or more of the follow‐
2998 ing terms that changes which column is chosen:
2999 state stateList
3001 StateList is a list of column state names. Only columns that
3002 have the given states set (or unset if the '!' prefix is used)
3003 are considered.
3004 tag tagExpr
3006 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3007 which a column's tags are tested for a match.
3008 !tail When this qualifier is given, the tail column is not matched.
3010 visible
3012 When this qualifier is given, only columns whose -visible option
3013 is TRUE are considered.
3014 !visible
3016 When this qualifier is given, only columns whose -visible option
3017 is FALSE are considered.
3018
3020 For every item a set of boolean states is managed. These states play an
3021 integral role in the appearance of each item. The following states are
3022 predefined for every item:
3023 active At all times this state is set for exactly one item. The active
3025 item is used with keyboard navigation. When the treectrl widget
3026 is created or when the active item is deleted, the root item
3027 will become the active item. This state can be modified by
3028 means of the widget command activate.
3029 enabled
3031 This state is set for every item when it is created. Disabled
3032 items cannot be selected and are ignored by the default bindings
3033 when navigating via the keyboard. This state can be modified by
3034 means of the widget command item enabled.
3035 focus This state is set for every item, if the treectrl widget cur‐
3037 rently has the focus. It cannot be modified by means of a wid‐
3038 get command, but is maintained in reaction to the <FocusIn> and
3039 <FocusOut> events.
3040 open If this state is switched on, the descendants of the item are
3042 displayed - the item is expanded. If this state is switched
3043 off, the descendants of the item are not displayed - the item is
3044 collapsed. For a new item this state is switched on by default.
3045 This state can be modified by means of the widget commands item
3046 expand, item collapse, or item toggle.
3047 selected
3049 This state is set for every item included in the selection. It
3050 can be modified by means of the widget command selection.
3051 By means of the state define widget command up to 27 additional states
3053 can be defined.
3054
3056 The visual appearance of an item can change depending on the state the
3057 item is in, such as being the active item, being included in the selec‐
3058 tion, being collapsed, or some combination of those or other states.
3059 When a configuration option is described as per-state, it means the
3060 option describes a value which varies depending on the state of the
3061 item. If a per-state option is specified as a single value, the value
3062 is used for all states. Otherwise the per-state option must be speci‐
3063 fied as an even-numbered list. For example, to use the font "Times 12
3064 bold" in a text element regardless of the item state you can write:
3065 $T element configure MyTextElement -font {{Times 12 bold}}
3067 However, to use a different font when the item is selected you could
3069 write:
3070 $T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}
3072 In the example above, the -font option reads "value stateList value
3074 stateList". If stateList is an empty list, the preceding value is used
3075 regardless of the item state. A non-empty stateList specifies a list of
3076 states which must be set for the item in order to use the preceding
3077 value. Each stateList can also include state names preceded by a !
3078 sign, indicating the state must *not* be set for the item. For example:
3079 $T element configure MyRectElement -fill {blue {selected focus} gray {selected !focus}}
3081 In the example above, the rect element is filled with blue when the
3083 treectrl has the focus and the item is selected. If the treectrl does
3084 not have the focus, the example specifies that gray should be used for
3085 selected items. Also note that if the item is not selected, no color is
3086 specified for the -fill option.
3087
3089 Elements are the smallest building blocks which are handled by a treec‐
3090 trl widget. One or more elements together can be combined to a style,
3091 which can be considered as a blueprint for an item. An element can be
3092 of type bitmap, border, image, rect, text or window. For each element
3093 type there is a section below describing the options which can modify
3094 an element of that type.
3095 All of the element configuration options described below are unspeci‐
3097 fied by default, meaning that no value whatsoever has been given to the
3098 option. It may seem strange to you that a boolean option would be
3099 unspecified instead of simply "true" or "false". The reason for this is
3100 that when an element displayed by an item has no value specified for an
3101 option, the element refers to the master element created by the element
3102 create command for a value for that option. This allows items which are
3103 displaying a certain element to be redisplayed when the master ele‐
3104 ment's options change. The item element configure command can be used
3105 to override the master element's configuration options for a specific
3106 item.
3107
3109 An element of type bitmap can be used to display a bitmap in an item.
3110 The following options are supported for bitmap elements:
3111 -background color
3113 Specifies as a per-state option the color to use for each of the
3114 bitmap's '0' valued pixels. If the value for a certain state is
3115 an empty string (the default), the bitmap is drawn transparent.
3116 -bitmap bitmap
3118 Specifies as a per-state option the bitmap to display in the
3119 element.
3120 -draw boolean
3122 Deprecated; use the style layout option -draw instead. Speci‐
3123 fies as a per-state option whether to draw the element. If the
3124 value for a certain state is an empty string (the default), it
3125 is treated as true and the element will be drawn.
3126 -foreground color
3128 Specifies as a per-state option the color to use for each of the
3129 bitmap's '1' valued pixels. If the value for a certain state is
3130 an empty string (the default), the bitmap's foreground color is
3131 black.
3132
3134 An element of type border can be used to display a 3D border in an
3135 item. The following options are supported for border elements:
3136 -background color
3138 Specifies as a per-state option the color to use for the back‐
3139 ground of the border. If the value for a certain state is an
3140 empty string (the default), the element will not be drawn.
3141 -draw boolean
3143 Deprecated; use the style layout option -draw instead. Speci‐
3144 fies as a per-state option whether to draw the element. If the
3145 value for a certain state is an empty string (the default), it
3146 is treated as true and the element will be drawn.
3147 -filled boolean
3149 Specifies whether the interior of the border should be filled
3150 with the background color. If this option is unspecified (the
3151 default), it it treated as false which means that only the edges
3152 of the border will be drawn.
3153 -height size
3155 Specifies the height of the border. If this value is unspecified
3156 (the default), the border will be exactly as tall as its display
3157 area as determined by the style layout options.
3158 -relief relief
3160 Specifies as a per-state option the relief of the border. If the
3161 value for a certain state is an empty string (the default), it
3162 is treated as flat. For acceptable values see the description
3163 of the -relief option in the options manual page.
3164 -thickness thickness
3166 Specifies the thickness of the edges of the border.
3167 -width size
3169 Specifies the width of the border. If this value is unspecified
3170 (the default), the border will be exactly as wide as its display
3171 area as determined by the style layout options.
3172
3174 An element of type image can be used to display an image in an item.
3175 The following options are supported for image elements:
3176 -draw boolean
3178 Deprecated; use the style layout option -draw instead. Speci‐
3179 fies as a per-state option whether to draw the element. If the
3180 value for a certain state is an empty string (the default), it
3181 is treated as true and the element will be drawn.
3182 -height size
3184 Specifies the requested height of the display area for this ele‐
3185 ment. If unspecified (the default), the element requests a
3186 height equal to the height of the image, or zero if there is no
3187 image.
3188 -image image
3190 Specifies as a per-state option the image to display in the ele‐
3191 ment.
3192 -width size
3194 Specifies the requested width of the display area for this ele‐
3195 ment. If unspecified (the default), the element requests a
3196 width equal to the width of the image, or zero if there is no
3197 image.
3198
3200 An element of type rect can be used to display a rectangle in an item.
3201 The following options are supported for rectangle elements:
3202 -draw boolean
3204 Deprecated; use the style layout option -draw instead. Speci‐
3205 fies as a per-state option whether to draw the element. If the
3206 value for a certain state is an empty string (the default), it
3207 is treated as true and the element will be drawn.
3208 -fill color
3210 Specifies as a per-state option the color to be used to fill the
3211 rectangle's area. If the color for a certain state is an empty
3212 string (the default), then the rectangle will not be filled (but
3213 the outline may still be drawn).
3214 -height size
3216 Specifies the height of the rectangle. If this value is unspeci‐
3217 fied (the default), the rectangle will be exactly as tall as its
3218 display area as determined by the style layout options.
3219 -open open
3221 This option may be used to get an incomplete drawing of the out‐
3222 line. Open is a string that contains zero or more of the char‐
3223 acters n, s, e or w. Each letter refers to a side (north,
3224 south, east, or west) that the outline will not be drawn. The
3225 default is the empty string, which causes the outline to be
3226 drawn completely.
3227 -outline color
3229 Specifies as a per-state option the color to be used to draw the
3230 outline of the rectangle. If the color for a certain state is
3231 an empty string (the default), then no outline is drawn for the
3232 rectangle.
3233 -outlinewidth outlineWidth
3235 Specifies the width of the outline to be drawn around the rec‐
3236 tangle's region. outlineWidth may be in any of the forms
3237 acceptable to Tk_GetPixels. If this option is specified as an
3238 empty string (the default), then no outline is drawn.
3239 -showfocus boolean
3241 Specifies a boolean value indicating whether a "focus ring"
3242 should be drawn around the rectangle, if the item containing the
3243 rectangle is the active item and the treectrl widget currently
3244 has the focus. If this option is specified as an empty string
3245 (the default), then a focus rectangle is not drawn.
3246 -width size
3248 Specifies the width of the rectangle. If this value is unspeci‐
3249 fied (the default), the rectangle will be exactly as wide as its
3250 display area as determined by the style layout options.
3251
3253 An element of type text can be used to display a text in an item. The
3254 following options are supported for text elements:
3255 -draw boolean
3257 Deprecated; use the style layout option -draw instead. Speci‐
3258 fies as a per-state option whether to draw the element. If the
3259 value for a certain state is an empty string (the default), it
3260 is treated as true and the element will be drawn.
3261 -data data
3263 Specifies a value that together with the -datatype and -format
3264 options will be displayed as text.
3265 -datatype dataType
3267 Specifies the type of information in the -data option. Accept‐
3268 able values are double, integer, long, string, or time.
3269 -fill color
3271 Specifies as a per-state option the foreground color to use when
3272 displaying the text. If the color for a certain state is an
3273 empty string (the default), then the text will be displayed
3274 using the color specified by the treectrl's -foreground option.
3275 -format formatString
3277 This option specifies the format string used to display the
3278 value of the -data option. If -datatype is time, formatString
3279 should be a valid format string for the Tcl clock command. For
3280 all other -datatype values formatString should be a valid format
3281 string for the Tcl format command. If this value is unspecified
3282 the following defaults are used: for -datatype double "%g", for
3283 -datatype integer "%d", for -datatype long "%ld", for -datatype
3284 string "%s", and for -datatype time the default format string of
3285 the Tcl clock command.
3286 -font font
3288 Specifies as a per-state option the font to use when displaying
3289 the text. If the font for a certain state is an empty string,
3290 the text is displayed using the font specified by the treectrl's
3291 -font option.
3292 -justify how
3294 Specifies how to justify the text when multiple lines are dis‐
3295 played. How must be one of the values left, right, or center.
3296 If this option is specified as an empty string (the default),
3297 left is used.
3298 -lines lineCount
3300 Specifies the maximum number of lines to display. If more than
3301 lineCount lines would be displayed, the last line will be trun‐
3302 cated with an ellipsis at the right. If this option is speci‐
3303 fied as zero or an empty string (the default), there is no limit
3304 to the number of lines displayed.
3305 -text string
3307 String specifies a string to be displayed by the element.
3308 String may contain newline characters in which case multiple
3309 lines of text will be displayed. If this option is specified,
3310 the -data, -datatype, -format, and -textvariable options are
3311 ignored.
3312 -textvariable varName
3314 Specifies the name of a variable. The value of the variable is
3315 a string to be displayed by the element; if the variable value
3316 changes then the element will automatically update itself to
3317 display the new value. If this option is specified, the -data,
3318 -datatype, and -format options are ignored.
3319 -underline charIndex
3321 Specifies the integer index of a character to underline. 0 cor‐
3322 responds to the first character. If charIndex is unspecified
3323 (the default), less than zero or greater than the index of the
3324 last displayed character, the underline is not drawn.
3325 -width size
3327 Specifies the maximum line length in any of the forms acceptable
3328 to Tk_GetPixels. For text to wrap lines the value of the -width
3329 option must be less than the needed width of the text, or the
3330 display area for this element must be less than the needed width
3331 of the text. For the display area to be less than the needed
3332 width of the text, one of the style layout options -maxwidth,
3333 -width or -squeeze must be used.
3334 -wrap mode
3336 Mode specifies how to handle lines in the text that are longer
3337 than the maximum line length. Acceptable values are none, char
3338 or word. If this option is unspecified (the default), word is
3339 used. See the -width option for a description of how the maxi‐
3340 mum line length is determined.
3341
3343 An element of type window can be used to display a Tk window in an
3344 item. The following options are supported for window elements:
3345 -clip boolean
3347 Specifies whether the associated Tk window is a borderless frame
3348 which should be used to clip its child window so it doesn't
3349 overlap the header, borders, or other items or columns. When
3350 this option is true, the treectrl manages the geometry of both
3351 the -window widget and its first child widget; in this case the
3352 -window widget (which should be a borderless frame) is kept
3353 sized and positioned so that it is never out-of-bounds.
3354 -destroy boolean
3356 Specifies whether the associated Tk window should be destroyed
3357 when the element is deleted. The element is deleted when the
3358 item containing the element is deleted, when the column contain‐
3359 ing the element is deleted, or when the style assigned to the
3360 item's column is changed. If this option is unspecified (the
3361 default), it is treated as false and the Tk window will not be
3362 destroyed.
3363 -draw boolean
3365 Deprecated; use the style layout option -draw instead. Speci‐
3366 fies as a per-state option whether to draw the element. If the
3367 value for a certain state is an empty string (the default), it
3368 is treated as true and the element will be drawn.
3369 -window pathName
3371 Specifies the window to associate with this element. The window
3372 specified by pathName must either be a child of the treectrl
3373 widget or a child of some ancestor of the treectrl widget. Path‐
3374 Name may not refer to a top-level window. This option cannot be
3375 specified by the element create or element configure commands,
3376 only by the item element configure command; i.e., the element
3377 must be associated with a particular item.
3378
3380 Many of the commands for a treectrl take as an argument a description
3381 of which items to operate on. An item description is a properly-formed
3382 tcl list of keywords and arguments. The first word of an item descrip‐
3383 tion must be one of the following:
3384 id Specifies the unique item identifier, where id should be the
3386 return value of a prior call of the item create widget command,
3387 or 0 to specify the ever-present root item. See also the -item‐
3388 prefix option.
3389 QUALIFIERS
3391 Specifies a list of qualifiers. This gives the same result as
3392 all followed by QUALIFIERS; i.e., every item is tested for a
3393 match.
3394 tagExpr QUALIFIERS
3396 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3397 which every item's tags are tested for a match. This keyword
3398 cannot be followed by any modifiers unless a single item is
3399 matched. You may run into trouble if tagExpr looks like an item
3400 id or other keyword; also, tagExpr must look like a single list
3401 element since item descriptions are properly-formed lists. To be
3402 safe you may want to use the tag qualifier followed by tagExpr.
3403 active Indicates the item that is currently active, i.e. normally the
3405 item specified as argument of the last successful activate wid‐
3406 get command, or the root item if no such call happened yet.
3407 anchor Indicates the anchor item of the selection, i.e. normally the
3409 item specified as argument of the last successful selection
3410 anchor widget command, or the root item if no such call happened
3411 yet.
3412 all QUALIFIERS
3414 Indicates every item including orphans which match QUALIFIERS.
3415 This keyword cannot be followed by any modifiers unless a single
3416 item is matched.
3417 first QUALIFIERS
3419 Indicates the first item of the treectrl (the root item), or the
3420 first item matching QUALIFIERS.
3421 end QUALIFIERS
3423 last QUALIFIERS
3425 Indicates the last item which matches QUALIFIERS.
3426 list itemDescs
3428 ItemDescs is a list (a single argument, i.e. "list {a b c}" not
3429 "list a b c") of other item descriptions. This keyword cannot
3430 be followed by any modifiers unless a single item is matched.
3431 nearest x y
3433 Indicates the item nearest to the point given by x and y.
3434 rnc row column
3436 Indicates the item in the given row and column. The row and
3437 column corresponds to the on-screen arrangement of items as
3438 determined by the -orient and -wrap options. You can memorize
3439 rnc as an abbreviation of "row 'n' column".
3440 range first last QUALIFIERS
3442 First and last specify a range of items. This keyword cannot be
3443 followed by any modifiers unless a single item is matched.
3444 root Indicates the root item of the treectrl.
3446 The initial part of the item description (matching any of the values
3448 above) may be followed by one or more modifiers. A modifier changes
3449 the item used relative to the description up to this point. It may be
3450 specified in any of the following forms:
3451 above Use the item one row above in this column.
3453 ancestors QUALIFIERS
3455 Use the ancestors of the item (like item ancestors but QUALI‐
3456 FIERS may change which ancestors match). This keyword cannot be
3457 followed by any modifiers.
3458 below Use the item one row below in this column.
3460 bottom Use the item in the last row of this column.
3462 child n QUALIFIERS
3464 Use the nth child of the item.
3465 children QUALIFIERS
3467 Use the children of the item (like item children but QUALIFIERS
3468 may change which children match). This keyword cannot be fol‐
3469 lowed by any modifiers.
3470 descendants QUALIFIERS
3472 Use the descendants of the item (like item descendants but QUAL‐
3473 IFIERS may change which descendants match). This keyword cannot
3474 be followed by any modifiers.
3475 firstchild QUALIFIERS
3477 Use the first child of the item.
3478 lastchild QUALIFIERS
3480 Use the last child of the item.
3481 left Use the item one column to the left in the same row.
3483 leftmost
3485 Use the item of the first column in the same row.
3486 next QUALIFIERS
3488 Use the next item, which is the first item from the following
3489 list: the first child, the next sibling or the next sibling of
3490 the nearest ancestor which has one.
3491 nextsibling QUALIFIERS
3493 Use the next sibling of the item.
3494 parent Use the parent of the item.
3496 prev QUALIFIERS
3498 Use the last child of the previous sibling, or the parent if
3499 there is no previous sibling.
3500 prevsibling QUALIFIERS
3502 Use the previous sibling of the item.
3503 right Use the item one column to the right in the same row.
3505 rightmost
3507 Use the item of the last column in the same row.
3508 sibling n QUALIFIERS
3510 Use the nth child of the item's parent.
3511 top Use the item in the first row of this column. The word QUALI‐
3513 FIERS above represents a series of zero or more of the following
3514 terms that changes which item is chosen:
3515 depth depth
3517 Matches items whose depth (as returned by the depth command) is
3518 equal to depth.
3519 state stateList
3521 StateList is a list of item state names (static and dynamic, see
3522 STATES). Only items that have the given states set (or unset if
3523 the '!' prefix is used) are considered.
3524 tag tagExpr
3526 TagExpr is a tag expression (see ITEM AND COLUMN TAGS) against
3527 which an item's tags are tested for a match.
3528 visible
3530 When this qualifier is given, only items that are displayed are
3531 considered.
3532 !visible
3534 When this qualifier is given, only items that are *not* dis‐
3535 played are considered. To get the first item in the list that
3536 is enabled:
3537 $T item id "first state enabled"
3539 To get the ancestors that are not open of the last item in the
3541 list:
3542 $T item id "last ancestors state !open"
3544 To get the visible descendants of the root item:
3546 $T item id "root descendants visible"
3548 To get the every hidden item with tag "a" or "b":
3550 $T item id "all !visible tag a||b"
3552 $T item id "!visible tag a||b"
3553 $T item id "tag a||b !visible"
3554 $T item id "a||b !visible"
3555
3558 The script argument to notify bind is a Tcl script, which will be eval‐
3559 uated whenever the given event is generated. Script will be executed in
3560 the same interpreter that the notify bind command was executed in, and
3561 it will run at global level (only global variables will be accessible).
3562 If script contains any % characters, then the script will not be evalu‐
3563 ated directly. Instead, a new script will be generated by replacing
3564 each %, and the character following it, with information from the cur‐
3565 rent event. Unlike the regular Tk bind mechanism, each event generated
3566 by a treectrl widget has its own set of %-substitutions.
3567 The following %-substitutions are valid for all static events:
3569 %% Replaced with a single %
3571 %d The detail name
3573 %e The event name
3575 %P The pattern, either <event> or <event-detail>
3577 %W The object argument to the notify bind command
3579 %T The treectrl widget which generated the event
3581 %? A list of the format {char value char value ...} for each
3583 %-substitution character and the value it is replaced by
3584 The following events may be generated by a treectrl widget:
3586 <ActiveItem>
3588 Generated whenever the active item changes.
3589 %c The current active item
3591 %p The previous active item
3593 <Collapse-before>
3595 Generated before an item is collapsed.
3596 %I The item id
3598 <Collapse-after>
3600 Generated after an item is collapsed.
3601 %I The item id
3603 <Expand-before>
3605 Generated before an item is expanded. This event is useful if
3606 you want to add child items to the item just before the item is
3607 expanded.
3608 %I The item id
3610 <Expand-after>
3612 Generated after an item is expanded.
3613 %I The item id
3615 <ItemDelete>
3617 Generated when items are about to be deleted by the item delete
3618 command.
3619 %i List of items ids being deleted.
3621 <ItemVisibility>
3623 Generated when items become visible on screen and when items are
3624 no longer visible on screen. This event is useful if you have a
3625 very large number of items and want to assign styles only when
3626 items are actually going to be displayed.
3627 %h List of items ids which are no longer visible.
3629 %v List of items ids which are now visible.
3631 <Scroll-x>
3633 Generated whenever the view in the treectrl changes in such a
3634 way that a horizontal scrollbar should be redisplayed.
3635 %l Same as the first fraction appended to -xscrollcommand. Think
3637 lower.
3638 %u Same as the second fraction appended to -xscrollcommand.
3640 Think upper.
3641 <Scroll-y>
3643 Generated whenever the view in the treectrl changes in such a
3644 way that a vertical scrollbar should be redisplayed.
3645 %l Same as the first fraction appended to -yscrollcommand. Think
3647 lower.
3648 %u Same as the second fraction appended to -yscrollcommand.
3650 Think upper.
3651 <Selection>
3653 Generated whenever the selection changes. This event gives
3654 information about how the selection changed.
3655 %c Same as the selection count widget command
3657 %D List of newly-deselected item ids
3659 %S List of newly-selected item ids
3661
3663 In addition to the pre-defined static events such as <ActiveItem> and
3664 <Selection>, new dynamic events can be created by using the notify
3665 install command.
3666 The following events may be generated by the library scripts:
3668 <ColumnDrag-begin>
3670 <ColumnDrag-receive>
3672 <ColumnDrag-end>
3674 Generated whenever the user drag-and-drops a column header. The
3675 library scripts do not actually move a dragged column. You must
3676 bind to the receive event to move the column. See EXAMPLES.
3677 %C The column that was dragged
3679 %b The column to move the dragged column before
3681 <Drag-begin>
3683 <Drag-receive>
3685 <Drag-end>
3687 Generated whenever the user drag-and-drops a file into a direc‐
3688 tory. This event is generated by the filelist-bindings.tcl
3689 library code, which is not used by default. See the "Explorer"
3690 demos.
3691 %I The item that the user dropped the dragged items on.
3693 %l (lowercase L) The list of dragged items.
3695 <Edit-begin>
3697 <Edit-accept>
3699 <Edit-end>
3701 The filelist-bindings.tcl code will display a text-editing win‐
3702 dow if the user clicks on a selected file/folder name. See the
3703 "Explorer" demos.
3704 %I The item containing the edited text element
3706 %C The column containing the edited text element
3708 %E The name of the edited text element
3710 %t The edited text
3712 <Header-invoke>
3714 Generated whenever the user clicks and releases the left mouse
3715 button in a column header if the column's -button option is
3716 true. You can bind a script to this event to sort the list.
3717 %C The column whose header was clicked
3719 The library scripts provide an example of using a dynamic event called
3720 <Header-invoke>, which is generated when the mouse button is released
3721 over a column header.
3722 treectrl .t
3724 puts "header %C clicked in treectrl %T"
3725 }
3726 proc ::TreeCtrl::Release1 {w x y} {
3727 ...
3728 $w notify generate <Header-invoke> [list C $Priv(column)] \
3729 [list ::TreeCtrl::PercentsCmd $w]
3730 ...
3731 }
3732 In the example a new treectrl widget is created and the <Header-invoke>
3734 event is installed. For convenience there is no percentsCommand argu‐
3735 ment to notify install; instead the call to notify generate specifies
3736 the %-substitution command. A script is bound to the event with notify
3737 bind which will print out the column number and widget name to the con‐
3738 sole (in the demos, <Header-invoke> is used to sort the list based on
3739 the column that was clicked). The charMap argument to notify generate
3740 provides a list of %-substitution characters and values which is used
3741 by ::TreeCtrl::PercentsCmd. In this example any %C in any script bound
3742 to the <Header-invoke> event will be replaced by the value of
3743 $Priv(column).
3744
3746 Tk automatically creates class bindings for treectrl widgets that give
3747 them the following default behavior.
3748 [1] Clicking mouse button 1 over an item positions the active cursor
3750 on the item, sets the input focus to this widget, and resets the
3751 selection of the widget to this item, if it is not already in
3752 the selection.
3753 [2] Clicking mouse button 1 with the Control key down will reposi‐
3755 tion the active cursor and add the item to the selection without
3756 ever removing any items from the selection.
3757 [3] If the mouse is dragged out of the widget while button 1 is
3759 pressed, the treectrl will automatically scroll to make more
3760 items visible (if there are more items off-screen on the side
3761 where the mouse left the window).
3762 [4] The Left and Right keys move the active cursor one item to the
3764 left or right; for an hierarchical tree with vertical orienta‐
3765 tion nothing will happen, since it has no two items in the same
3766 row. The selection is set to include only the active item. If
3767 Left or Right is typed with the Shift key down, then the active
3768 cursor moves and the selection is extended to include the new
3769 item.
3770 [5] The Up and Down keys move the active cursor one item up or down.
3772 The selection is set to include only the active item. If Up or
3773 Down is typed with the Shift key down, then the active cursor
3774 moves and the selection is extended to include the new item.
3775 [6] The Next and Prior keys move the active cursor forward or back‐
3777 wards by one screenful, without affecting the selection.
3778 [7] Control-Next and Control-Prior scroll the view right or left by
3780 one page without moving the active cursor or affecting the
3781 selection. Control-Left and Control-Right behave the same.
3782 [8] The Home and End keys scroll to the left or right end of the
3784 widget without moving the active cursor or affecting the selec‐
3785 tion.
3786 [9] The Control-Home and Control-End keys scroll to the top or bot‐
3788 tom of the widget, they also activate and select the first or
3789 last item. If also the Shift key is down, then the active cur‐
3790 sor moves and the selection is extended to include the new item.
3791 [10] The Space and Select keys set the selection to the active item.
3793 [11] Control-/ selects the entire contents of the widget.
3795 [12] Control-\\ clears any selection in the widget.
3797 [13] The + and - keys expand or collapse the active item, the Return
3799 key toggles the active item.
3800 [14] The mousewheel scrolls the view of the widget four lines up or
3802 down depending on the direction, the wheel was turned. The
3803 active cursor or the selection is not affected.
3804
3806 Get the unique identifier for the leftmost visible column:
3807 set id [$T column index "first visible"]
3809 Delete the leftmost column:
3811 $T column delete "order 0"
3813 Take the visible column that is to the left of the last column, and
3815 move that column in front of the tail column:
3816 $T column move "last prev visible" tail
3818 Get the unique identifier for the first visible item:
3820 set id [$T item index "first visible"]
3822 Delete the parent of the item that is under the point x,y:
3824 $T item delete "nearest $x $y parent"
3826 Add the 10th child of the second child of the root item to the selec‐
3828 tion:
3829 $T selection add "root firstchild nextsibling child 10"
3831 Move a column that the user drag-and-dropped:
3833 $T column dragconfigure -enable yes
3835 $T notify install <ColumnDrag-receive>
3836 $T notify bind MyTag <ColumnDrag-receive> {
3837 %T column move %C %b
3838 }
3839
3842 bind(n), bitmap(n), image(n), listbox(n), options(n)
3843
3845 tree, widget
3846treectrl 2.2.3 treectrl(n)