


treectrl(n)                Tk Commands                treectrl(n)


______________________________________________________________________________

NAME
       treectrl - Create and manipulate hierarchical multicolumn widgets

SYNOPSIS
       package require treectrl  2.3

       treectrl pathName ?options?

       pathName activate itemDesc

       pathName bbox ?area?

       pathName canvasx windowx

       pathName canvasy windowy

       pathName cget option

       pathName collapse ?-recurse? ?itemDesc ...?

       pathName column option column ?arg ...?

       pathName column bbox columnDesc

       pathName column cget columnDesc option

       pathName  column  configure  columnDesc  ?option? ?value? ?option value
       ...?

       pathName column compare column1 op column2

       pathName column count ?columnDesc?

       pathName column create ?option value ...?

       pathName column delete first ?last?

       pathName column dragcget option

       pathName column dragconfigure ?option? ?value? ?option value ...?

       pathName column index columnDesc

       pathName column id columnDesc

       pathName column list ?-visible?

       pathName column move columnDesc beforeDesc

       pathName column neededwidth columnDesc

       pathName column order columnDesc ?-visible?



treectrl                       2.3                              1





treectrl(n)                Tk Commands                treectrl(n)


       pathName column tag option ?arg arg ...?

       pathName column tag add columnDesc tagList

       pathName column tag expr columnDesc tagExpr

       pathName column tag names columnDesc

       pathName column tag remove columnDesc tagList

       pathName column width columnDesc

       pathName compare itemDesc1 op itemDesc2

       pathName configure ?option? ?value option value ...?

       pathName contentbox

       pathName debug option ?arg arg ...?

       pathName debug alloc

       pathName debug cget option

       pathName debug configure ?option? ?value? ?option value ...?

       pathName debug dinfo option

       pathName debug expose x1 y1 x2 y2

       pathName debug scroll

       pathName depth ?itemDesc?

       pathName dragimage option ?arg ...?

       pathName dragimage add itemDesc ?column? ?element?

       pathName dragimage cget option

       pathName dragimage clear

       pathName dragimage configure ?option? ?value? ?option value ...?

       pathName dragimage offset ?x y?

       pathName element option ?element? ?arg arg ...?

       pathName element cget element option

       pathName element configure element ?option? ?value? ?option value  ...?

       pathName element create element type ?option value ...?




treectrl                       2.3                              2





treectrl(n)                Tk Commands                treectrl(n)


       pathName element delete ?element ...?

       pathName element names

       pathName element perstate element option stateList

       pathName element type element

       pathName expand ?-recurse? ?itemDesc ...?

       pathName gradient option ?arg ...?

       pathName gradient api ?version?

       pathName gradient cget gradient option

       pathName gradient configure gradient ?option value ...?

       pathName gradient create name ?option value ...?

       pathName gradient delete ?name ...?

       pathName gradient names

       pathName gradient native ?preference?

       pathName identify x y

       pathName index itemDesc

       pathName item option ?arg ...?

       pathName item ancestors itemDesc

       pathName item bbox itemDesc ?column? ?element?

       pathName item buttonstate itemDesc ?state?

       pathName item cget itemDesc option

       pathName item children itemDesc

       pathName item collapse itemDesc ?-animate? ?-recurse?

       pathName item compare itemDesc1 op itemDesc2

       pathName item complex itemDesc ?list...?

       pathName item configure itemDesc ?option? ?value? ?option value ...?

       pathName item count ?itemDesc?

       pathName item create ?option value ...?




treectrl                       2.3                              3





treectrl(n)                Tk Commands                treectrl(n)


       pathName item delete first ?last?

       pathName item descendants itemDesc

       pathName item dump itemDesc

       pathName item element command itemDesc column element ?arg ...?

       pathName item element actual itemDesc column element option

       pathName item element cget itemDesc column element option

       pathName  item  element  configure  itemDesc  column  element  ?option?
       ?value? ?option value ...?

       pathName  item  element  perstate  itemDesc   column   element   option
       ?stateList?

       pathName item enabled itemDesc ?boolean?

       pathName item expand itemDesc ?-animate? ?-recurse?

       pathName item firstchild parent ?child?

       pathName item id itemDesc

       pathName item image itemDesc ?column? ?image? ?column image ...?

       pathName item isancestor itemDesc descendant

       pathName item isopen itemDesc

       pathName item lastchild parent ?child?

       pathName item nextsibling sibling ?next?

       pathName item numchildren itemDesc

       pathName item order itemDesc ?-visible?

       pathName item parent itemDesc

       pathName item prevsibling sibling ?prev?

       pathName item range first last

       pathName item remove itemDesc

       pathName item rnc itemDesc

       pathName item sort itemDesc ?option ...?

       pathName  item  span  itemDesc ?column? ?numColumns? ?column numColumns
       ...?



treectrl                       2.3                              4





treectrl(n)                Tk Commands                treectrl(n)


       pathName item state command itemDesc ?arg ...?

       pathName item state forcolumn itemDesc column ?stateDescList?

       pathName item state get itemDesc ?stateName?

       pathName item state set itemDesc ?lastItem? stateDescList

       pathName item style command itemDesc ?arg ...?

       pathName item style elements itemDesc column

       pathName item style map itemDesc column style map

       pathName item style set itemDesc ?column? ?style? ?column style ...?

       pathName item tag option ?arg arg ...?

       pathName item tag add itemDesc tagList

       pathName item tag expr itemDesc tagExpr

       pathName item tag names itemDesc

       pathName item tag remove itemDesc tagList

       pathName item text itemDesc ?column? ?text? ?column text ...?

       pathName item toggle itemDesc ?-animate? ?-recurse?

       pathName marquee option ?arg ...?

       pathName marquee anchor ?x y?

       pathName marquee cget option

       pathName marquee configure ?option? ?value? ?option value ...?

       pathName marquee coords ?x1 y1 x2 y2?

       pathName marquee corner ?x y?

       pathName marquee identify

       pathName notify option ?arg ...?

       pathName notify bind ?object? ?pattern? ?+??script?

       pathName notify configure object pattern ?option? ?value? ?option value
       ...?

       pathName notify detailnames eventName

       pathName notify eventnames



treectrl                       2.3                              5





treectrl(n)                Tk Commands                treectrl(n)


       pathName notify generate pattern ?charMap? ?percentsCommand?

       pathName notify install pattern ?percentsCommand?

       pathName notify install detail eventName detail ?percentsCommand?

       pathName notify install event eventName ?percentsCommand?

       pathName notify linkage pattern

       pathName notify linkage eventName ?detail?

       pathName notify unbind object ?pattern?

       pathName notify uninstall pattern

       pathName notify uninstall detail eventName detail

       pathName notify uninstall event eventName

       pathName numcolumns

       pathName numitems

       pathName orphans

       pathName range first last

       pathName scan option args

       pathName scan mark x y

       pathName scan dragto x y ?gain?

       pathName see itemDesc ?columnDesc? ?option value ...?

       pathName selection option args

       pathName selection add first ?last?

       pathName selection anchor ?itemDesc?

       pathName selection clear ?first? ?last?

       pathName selection count

       pathName selection get ?first? ?last?

       pathName selection includes itemDesc

       pathName selection modify select deselect

       pathName state option args




treectrl                       2.3                              6





treectrl(n)                Tk Commands                treectrl(n)


       pathName state define stateName

       pathName state linkage stateName

       pathName state names

       pathName state undefine ?stateName ...?

       pathName style option ?element? ?arg arg ...?

       pathName style cget style option

       pathName style configure style ?option? ?value? ?option value ...?

       pathName style create style ?option value ...?

       pathName style delete ?style ...?

       pathName style elements style ?elementList?

       pathName style layout style element ?option? ?value? ?option value ...?

       pathName style names

       pathName theme option ?arg ...?

       pathName theme platform

       pathName theme setwindowtheme appname

       pathName toggle ?-recurse? ?itemDesc ...?

       pathName xview ?args?

       pathName xview

       pathName xview moveto fraction

       pathName xview scroll number what

       pathName yview ?args?

       pathName yview

       pathName yview moveto fraction

       pathName yview scroll number what

_________________________________________________________________

DESCRIPTION
       treectrl pathName ?options?





treectrl                       2.3                              7





treectrl(n)                Tk Commands                treectrl(n)


       The treectrl command creates a new window (given by the pathName  argu-
       ment)  and  makes  it  into  a  treectrl  widget.   Additional options,
       described above, may be specified on the command line or in the  option
       database  to  configure  aspects of the treectrl such as its background
       color and relief.  The treectrl command returns the path  name  of  the
       new  window.  At the time this command is invoked, there must not exist
       a window named pathName, but pathName's parent must exist.

       A treectrl is a widget which displays items in  a  one-  or  two-dimen-
       sional  arrangement.  Items have a parent-child relationship with other
       items.  Items have a set  of  states,  which  are  boolean  properties.
       Items  may  be spread about one or more columns.  For each column of an
       item there is a style associated, which determines how to  display  the
       item's  column  taking  into account the item's current state set.  One
       column can be defined to display the data in a hierarchical  structure.

       Normally  the origin of the coordinate system is at the upper-left cor-
       ner of the window containing the treectrl.  It is  possible  to  adjust
       the  origin of the coordinate system relative to the origin of the win-
       dow using the xview and yview widget commands; this is  typically  used
       for scrolling.

       A  treectrl  widget  can  be  horizontal or vertical oriented like many
       other Tk widgets.  For displaying hierarchical data only vertical  ori-
       entation  is  useful,  since only then the children of an item are dis-
       played directly below their parent.  If the  treectrl  widget  is  used
       only  to display data in a multicolumn listbox, the specification of an
       orientation will give useful results.

STANDARD OPTIONS
       -background

       -borderwidth

       -cursor

       -font

       -highlightbackground

       -highlightcolor

       -highlightthickness

       -orient

       -relief

       -takefocus

       -xscrollcommand

       -yscrollcommand




treectrl                       2.3                              8





treectrl(n)                Tk Commands                treectrl(n)


       -foreground

       See the option manual entry for details on the standard options.

WIDGET SPECIFIC OPTIONS
       Command-Line Switch:    -backgroundimage
       Database Name:          backgroundImage
       Database Class:         BackgroundImage


              Specifies the name of an image to draw as the  list  background.
              The  image is tiled horizontally and vertically to fill the con-
              tent area of the list. If the image is transparent it  is  drawn
              on top of the background color(s).

       Command-Line Switch:    -backgroundmode
       Database Name:          backgroundMode
       Database Class:         BackgroundMode


              Specifies  how  the  background color of items is chosen in each
              column.  The value should be  one  of  row,  column,  order,  or
              ordervisible.  The  default  is  row.   This  option has only an
              effect for columns which have -itembackground defined as list of
              two or more colors (see section COLUMNS below for more on this).
              If row or column is specified, the background  color  is  chosen
              based  on  the  location  of the item in the 1- or 2-dimensional
              grid of items as layed out on the screen; this layout  of  items
              is  affected  by  the  -orient and -wrap options as well as item
              visibility.  When order or ordervisible is specified, the  back-
              ground  color  is  chosen  based on the result of the item order
              command, regardless of the layout of items.

       Command-Line Switch:    -bgimage
       Database Name:          bgImage
       Database Class:         BgImage


              Synonym for -backgroundimage.

       Command-Line Switch:    -bgimageanchor
       Database Name:          bgImageAnchor
       Database Class:         BgImageAnchor


              Specifies how the background image should be aligned in  any  of
              the forms acceptable to Tk_GetAnchor.  Must be one of the values
              n, ne, e, se, s, sw, w, nw, or center.  The default is nw.

       Command-Line Switch:    -bgimageopaque
       Database Name:          bgImageOpaque
       Database Class:         BgImageOpaque





treectrl                       2.3                              9





treectrl(n)                Tk Commands                treectrl(n)


              Specifies a boolean indicating whether  or  not  the  background
              image  is  fully opaque.  This is needed because there is no way
              in Tk to determine whether an  image  contains  transparency  or
              not.   The  default  value  is true, so if you use a transparent
              -backgroundimage you must set this to false.

       Command-Line Switch:    -bgimagescroll
       Database Name:          bgImageScroll
       Database Class:         BgImageScroll


              Specifies whether the background image scrolls  along  with  the
              items  or  whether  it  remains  locked in place relative to the
              edges of the window.  The value must be a string  that  contains
              zero or more of the characters x or y.  The default is xy.

       Command-Line Switch:    -bgimagetile
       Database Name:          bgImageTile
       Database Class:         BgImageTile


              Specifies  whether  the  background  image  is tiled along the x
              and/or y axes.  The value must be a string that contains zero or
              more of the characters x or y.  The default is xy.

       Command-Line Switch:    -buttonbitmap
       Database Name:          buttonBitmap
       Database Class:         ButtonBitmap


              Specifies the bitmap to be used as the expand/collapse button to
              the left of an item. This is a per-state option. If a bitmap  is
              specified  for a certain item state, it overrides the effects of
              -usetheme.

       Command-Line Switch:    -buttoncolor
       Database Name:          buttonColor
       Database Class:         ButtonColor


              Specifies the foreground color which should be used for  drawing
              the outline and the plus or minus sign of the button to the left
              of an item.

       Command-Line Switch:    -buttonimage
       Database Name:          buttonImage
       Database Class:         ButtonImage


              Specifies the image to be used as the expand/collapse button  to
              the left of an item. This is a per-state option.  If an image is
              specified for a certain item state, it overrides the effects  of
              -buttonbitmap and -usetheme.




treectrl                       2.3                             10





treectrl(n)                Tk Commands                treectrl(n)


       Command-Line Switch:    -buttonsize
       Database Name:          buttonSize
       Database Class:         ButtonSize


              Specifies  the  width and height of the button drawn to the left
              of an item in any of the forms acceptable to Tk_GetPixels.

       Command-Line Switch:    -buttonthickness
       Database Name:          buttonThickness
       Database Class:         ButtonThickness


              Specifies the width of the outline and the plus or minus sign of
              the button to the left of an item in any of the forms acceptable
              to Tk_GetPixels.

       Command-Line Switch:    -buttonttracking
       Database Name:          buttonTracking
       Database Class:         ButtonTracking


              Specifies a boolean that determines if the expand/collapse  but-
              tons  are  tracked  like  pushbuttons  when clicking them.  When
              true, buttons are not toggled until  the  <ButtonRelease>  event
              occurs  over  them.   When false, buttons are toggled as soon as
              the <ButtonPress> event occurs over them.  This option  defaults
              to true on Mac OS X and Gtk+, false on Win32 and X11.

       Command-Line Switch:    -canvaspadx
       Database Name:          canvasPadX
       Database Class:         CanvasPadX


              Specifies  the  width  of extra whitespace on the left and right
              edges of the canvas in any of the forms acceptable to Tk_GetPix-
              els.  The canvas is the virtual sheet of paper that all the vis-
              ible items are drawn onto, of which only a portion may be  visi-
              ble  in  the treectrl window.  The option value may be a list of
              one or two screen distances to specify padding for the two edges
              separately.  The default is 0.

       Command-Line Switch:    -canvaspady
       Database Name:          canvasPadY
       Database Class:         CanvasPadY


              Specifies  the  height of extra whitespace on the top and bottom
              edges of the canvas in any of the forms acceptable to Tk_GetPix-
              els.  The canvas is the virtual sheet of paper that all the vis-
              ible items are drawn onto, of which only a portion may be  visi-
              ble  in  the treectrl window.  The option value may be a list of
              one or two screen distances to specify padding for the two edges
              separately.  The default is 0.



treectrl                       2.3                             11





treectrl(n)                Tk Commands                treectrl(n)


       Command-Line Switch:    -columnprefix
       Database Name:          columnPrefix
       Database Class:         ColumnPrefix


              Specifies  an  ascii  string that changes the way column ids are
              reported and processed. If this option is  a  non-empty  string,
              the  usual  integer  value  of  a column id is prefixed with the
              given string. This can aid debugging but it  is  important  your
              code doesn't assume column ids are integers if you use it.

       Command-Line Switch:    -columnproxy
       Database Name:          columnProxy
       Database Class:         ColumnProxy


              If  this  option  specifies  a  non  empty value, it should be a
              screen distance in any of the forms acceptable to  Tk_GetPixels.
              Then  a  1 pixel thick vertical line will be drawn at the speci-
              fied screen distance from the left edge of the treectrl  widget,
              which reaches from top to bottom of the treectrl widget and uses
              an inverting color (i.e black on lighter  background,  white  on
              darker  background).   This  line can be used to give the user a
              visual feedback during column resizing.

       Command-Line Switch:    -columnresizemode
       Database Name:          columnResizeMode
       Database Class:         ColumnResizeMode


              Specifies the visual feedback used when  resizing  columns.  The
              value  should  be one of proxy or realtime. For proxy, a 1-pixel
              thick vertical line is drawn representing where the  right  edge
              of the column will be after resizing. For realtime, the column's
              size is changed while the user is dragging the right edge of the
              column.  The default is realtime.

       Command-Line Switch:    -columntagexpr
       Database Name:          columnTagExpr
       Database Class:         ColumnTagExpr


              Specifies  a boolean that enables or disables tag expressions in
              column descriptions. See ITEM AND COLUMN TAGS.

       Command-Line Switch:    -defaultstyle
       Database Name:          defaultStyle
       Database Class:         DefaultStyle


              This option is deprecated;  use  the  column  option  -itemstyle
              instead.   Specifies  a list of styles, one per column, to apply
              to each item created by the item create command. The  number  of
              styles  in  the  list  can  be different from the number of tree



treectrl                       2.3                             12





treectrl(n)                Tk Commands                treectrl(n)


              columns.  Each list element should be a valid style name  or  an
              empty  string  to  indicate no style should be applied to a spe-
              cific column. The list of  styles  is  updated  if  a  style  is
              deleted or if a column is moved.

       Command-Line Switch:    -doublebuffer
       Database Name:          doubleBuffer
       Database Class:         DoubleBuffer


              This  option  no longer has any effect, but was left in for com-
              patibility.  It used to control the amount  of  double-buffering
              that was used when displaying a treectrl.

       Command-Line Switch:    -height
       Database Name:          height
       Database Class:         Height


              Specifies  the desired height for the window in any of the forms
              acceptable to Tk_GetPixels.  The default is 200 pixels.  If this
              option  is  less  than or equal to zero then the window will not
              request any size at all.

       Command-Line Switch:    -indent
       Database Name:          indent
       Database Class:         Indent


              Specifies the screen distance an item is  indented  relative  to
              its  parent item in any of the forms acceptable to Tk_GetPixels.
              The default is 19 pixels.

       Command-Line Switch:    -itemgapx
       Database Name:          itemGapX
       Database Class:         ItemGapX


              Specifies the horizontal spacing between adjacent items  in  any
              of the forms acceptable to Tk_GetPixels.  The default is 0.

       Command-Line Switch:    -itemgapy
       Database Name:          itemGapY
       Database Class:         ItemGapY


              Specifies  the vertical spacing between adjacent items in any of
              the forms acceptable to Tk_GetPixels.  The default is 0.

       Command-Line Switch:    -itemheight
       Database Name:          itemHeight
       Database Class:         ItemHeight





treectrl                       2.3                             13





treectrl(n)                Tk Commands                treectrl(n)


              Specifies a fixed height for every item  in  any  of  the  forms
              acceptable  to  Tk_GetPixels. If non-zero, this option overrides
              the requested height of an item and the  -minitemheight  option.
              If  an  item's  own -height option is specified then that is the
              height used for the item. In any case, items are  never  shorter
              than  the  maximum  height of a button if they display one.  The
              default is 0.

       Command-Line Switch:    -itemprefix
       Database Name:          itemPrefix
       Database Class:         ItemPrefix


              Specifies an ascii string that changes  the  way  item  ids  are
              reported  and  processed.  If this option is a non-empty string,
              the usual integer value of an item id is prefixed with the given
              string.  This  can  aid  debugging but it is important your code
              doesn't assume item ids are integers if you use it.

       Command-Line Switch:    -itemtagexpr
       Database Name:          itemTagExpr
       Database Class:         ItemTagExpr


              Specifies a boolean that enables or disables tag expressions  in
              item descriptions. See ITEM AND COLUMN TAGS.

       Command-Line Switch:    -itemwidth
       Database Name:          itemWidth
       Database Class:         ItemWidth


              Specifies  a  fixed  width  for  every  item in any of the forms
              acceptable to Tk_GetPixels.  If more than one column is visible,
              then this option has no effect.  If the -orient option is verti-
              cal, and the -wrap option is unspecified, then this  option  has
              no effect (in that case all items are as wide as the column).

       Command-Line Switch:    -itemwidthequal
       Database Name:          itemWidthEqual
       Database Class:         ItemWidthEqual


              Specifies  a boolean that says whether all items should have the
              same width.  If more than  one  column  is  visible,  then  this
              option  has  no  effect.  If the -orient option is vertical, and
              the -wrap option is unspecified, then this option has no  effect
              (in  that  case  all  items  are as wide as the column).  If the
              -itemwidth option is specified, then this option has no  effect.

       Command-Line Switch:    -itemwidthmultiple
       Database Name:          itemWidthMultiple
       Database Class:         ItemWidthMultiple




treectrl                       2.3                             14





treectrl(n)                Tk Commands                treectrl(n)


              Specifies  a  screen  distance  that  every item's width will be
              evenly divisible by in any of the forms acceptable to Tk_GetPix-
              els.   If  more than one column is visible, then this option has
              no effect.  If the -orient option is  vertical,  and  the  -wrap
              option  is  unspecified, then this option has no effect (in that
              case all items are as wide as the column).   If  the  -itemwidth
              option is specified, then this option has no effect.

       Command-Line Switch:    -linecolor
       Database Name:          lineColor
       Database Class:         LineColor


              Specifies  the  color  which should be used for drawing the con-
              necting lines between related items.

       Command-Line Switch:    -linestyle
       Database Name:          lineStyle
       Database Class:         LineStyle


              Specifies the style of  the  connecting  lines  between  related
              items, should be dot which is the default, or solid.

       Command-Line Switch:    -linethickness
       Database Name:          lineThickness
       Database Class:         LineThickness


              Specifies  the thickness of the connecting lines between related
              items in any of the forms acceptable to Tk_GetPixels.

       Command-Line Switch:    -minitemheight
       Database Name:          minItemHeight
       Database Class:         MinItemHeight


              Specifies a minimum height for every item in any  of  the  forms
              acceptable  to Tk_GetPixels.  The default is 0, which means that
              every item has the height requested by the arrangement  of  ele-
              ments  in  each  column.  This  option  has  no  effect  if  the
              -itemheight option is specified.  Items are never  shorter  than
              the maximum height of a button.

       Command-Line Switch:    -rowproxy
       Database Name:          rowProxy
       Database Class:         RowProxy


              If  this  option  specifies  a  non  empty value, it should be a
              screen distance in any of the forms acceptable to  Tk_GetPixels.
              Then a 1 pixel thick horizontal line will be drawn at the speci-
              fied screen distance from the top edge of the  treectrl  widget,
              which reaches from left to right of the treectrl widget and uses



treectrl                       2.3                             15





treectrl(n)                Tk Commands                treectrl(n)


              an inverting color (i.e black on lighter  background,  white  on
              darker  background).   This  line can be used to give the user a
              visual feedback during row resizing.

       Command-Line Switch:    -scrollmargin
       Database Name:          scrollMargin
       Database Class:         ScrollMargin


              Specifies a positive screen distance in any of the forms accept-
              able  to Tk_GetPixels.  This option is used by the default bind-
              ings to determine how close to the edges of the  contentbox  the
              mouse  pointer  must  be  before scrolling occurs.  Specifying a
              positive value is useful when  items  may  be  drag-and-dropped.
              Defaults to 0.

       Command-Line Switch:    -selectmode
       Database Name:          selectMode
       Database Class:         SelectMode


              Specifies  one of several styles for manipulating the selection.
              The value of the option may be arbitrary, but the default  bind-
              ings  expect  it  to  be  either  single,  browse,  multiple, or
              extended;  the default value is browse.

       Command-Line Switch:    -showbuttons
       Database Name:          showButtons
       Database Class:         ShowButtons


              Specifies a boolean value that determines  whether  this  widget
              leaves  indentation space to display the expand/collapse buttons
              next to items.  The default value  is  true.   The  item  option
              -button  determines whether any item has a button.  See also the
              treectrl option -showrootbutton.

       Command-Line Switch:    -showheader
       Database Name:          showHeader
       Database Class:         ShowHeader


              Specifies a boolean value that determines  whether  this  widget
              should  display the header line with the column names at the top
              of the widget.  The default value is true.

       Command-Line Switch:    -showlines
       Database Name:          showLines
       Database Class:         ShowLines


              Specifies a boolean value that determines  whether  this  widget
              should  draw  the  connecting  lines between related items.  The
              default value is true on Win32 and X11, false on Mac  OS  X  and



treectrl                       2.3                             16





treectrl(n)                Tk Commands                treectrl(n)


              Gtk+.

       Command-Line Switch:    -showroot
       Database Name:          showRoot
       Database Class:         ShowRoot


              Specifies  a  boolean  value that determines whether this widget
              should draw the root item.  By suppressing the  drawing  of  the
              root  item  the  widget  can  have multiple items that appear as
              toplevel items.  The default value is true.

       Command-Line Switch:    -showrootbutton
       Database Name:          showRootButton
       Database Class:         ShowRootButton


              Specifies a boolean value that determines  whether  this  widget
              leaves  indentation  space to display the expand/collapse button
              next to the root item. The default value  is  false.   The  item
              option -button determines whether the root item has a button.

       Command-Line Switch:    -showrootchildbuttons
       Database Name:          showRootChildButtons
       Database Class:         ShowRootChildButtons


              Specifies  a  boolean  value that determines whether this widget
              should draw the expand/collapse buttons next to children of  the
              root item.  The default value is true.

       Command-Line Switch:    -showrootlines
       Database Name:          showRootLines
       Database Class:         ShowRootLines


              Specifies  a  boolean  value that determines whether this widget
              should draw the connecting lines between children  of  the  root
              item.  The default value is true.

       Command-Line Switch:    -treecolumn
       Database Name:          treeColumn
       Database Class:         TreeColumn


              Specifies a column description that determines which column dis-
              plays the buttons and lines.  The default is unspecified.

       Command-Line Switch:    -usetheme
       Database Name:          useTheme
       Database Class:         UseTheme


              Specifies a boolean value that determines  whether  this  widget



treectrl                       2.3                             17





treectrl(n)                Tk Commands                treectrl(n)


              should draw parts of itself using a platform-specific theme man-
              ager.  The default is true.

       Command-Line Switch:    -width
       Database Name:          width
       Database Class:         Width


              Specifies the desired width for the window in any of  the  forms
              acceptable  to Tk_GetPixels.  The default is 200 pixel.  If this
              option is less than or equal to zero then the  window  will  not
              request any size at all.

       Command-Line Switch:    -wrap
       Database Name:          wrap
       Database Class:         Wrap


              Specifies  whether  items  are arranged in a 1- or 2-dimensional
              layout.

              If the value is an empty string (the default),  then  items  are
              arranged  from  top to bottom (-orient vertical) or from left to
              right (-orient horizontal) in a 1-dimensional layout.

              If the value is "N items", then no more than N items will appear
              in  a  vertical  group  (-orient  vertical)  or horizontal group
              (-orient horizontal).

              If the value is "N pixels", then no vertical group of items will
              be  taller  than  N  pixels  (-orient vertical) or no horizontal
              group of items will be wider than N pixels (-orient horizontal).

              If  the  value is window, then a no vertical group of items will
              be taller than the window (-orient vertical)  or  no  horizontal
              group  of  items will be wider than the window (-orient horizon-
              tal).

              It is also possible to cause wrapping to  occur  on  a  per-item
              basis  by using the item option -wrap.  See the item create com-
              mand for that option.

       Command-Line Switch:    -xscrolldelay
       Database Name:          xScrollDelay
       Database Class:         ScrollDelay


              This option controls how  quickly  horizontal  scrolling  occurs
              while  dragging  the  mouse  with  button  1 pressed.  The value
              should be a list of 1 or 2 integers interpreted as microseconds.
              If  2  values are specified, then the first value determines the
              intial delay after the first scroll, and the second value deter-
              mines  the  delay  for  all scrolling after the first. If only 1
              value is specified, each scroll takes place after that delay.



treectrl                       2.3                             18





treectrl(n)                Tk Commands                treectrl(n)


       Command-Line Switch:    -xscrollincrement
       Database Name:          xScrollIncrement
       Database Class:         ScrollIncrement


              Specifies an increment for horizontal scrolling, in any  of  the
              usual  forms  permitted  for  screen distances.  If the value of
              this option is greater than zero, the  horizontal  view  in  the
              window  will be constrained so that the x coordinate at the left
              edge of the window is always an even multiple of  -xscrollincre-
              ment;  furthermore, the units for scrolling (e.g., the change in
              view when the left and right arrows of a scrollbar are selected)
              will  also be -xscrollincrement.  If the value of this option is
              less than or equal to zero, then horizontal scrolling  snaps  to
              the  left of an item, or part of an item if items are wider than
              the contentbox.

       Command-Line Switch:    -xscrollsmoothing
       Database Name:          xScrollSmoothing
       Database Class:         ScrollSmoothing


              Specifies whether scrolling should be done as if  -xscrollincre-
              ment=1  whenever  scrolling  is  performed  by non-unit amounts.
              When the value of this option is true and the xview  command  is
              called  to  scroll by "units", scrolling occurs according to the
              -xscrollincrement option, and all other scrolling is done as  if
              the  -xscrollincrement  option was set to 1.  The effect is that
              when dragging the scrollbar thumb scrolling is very smooth,  but
              when clicking the scrollbar buttons scrolling is done in coarser
              increments.  The default value is false.

       Command-Line Switch:    -yscrolldelay
       Database Name:          yScrollDelay
       Database Class:         ScrollDelay


              This option controls how quickly vertical scrolling occurs while
              dragging the mouse with button 1 pressed.  The value should be a
              list of 1 or 2 integers interpreted as microseconds.  If 2  val-
              ues  are  specified,  then the first value determines the intial
              delay after the first scroll, and the  second  value  determines
              the  delay for all scrolling after the first. If only 1 value is
              specified, each scroll takes place after that delay.

       Command-Line Switch:    -yscrollincrement
       Database Name:          yScrollIncrement
       Database Class:         ScrollIncrement


              Specifies an increment for vertical scrolling,  in  any  of  the
              usual  forms  permitted  for  screen distances.  If the value of
              this option is greater than zero, the vertical view in the  win-
              dow will be constrained so that the y coordinate at the top edge



treectrl                       2.3                             19





treectrl(n)                Tk Commands                treectrl(n)


              of the window is always an even multiple  of  -yscrollincrement;
              furthermore,  the  units for scrolling (e.g., the change in view
              when the top and bottom arrows of a scrollbar are selected) will
              also  be -yscrollincrement.  If the value of this option is less
              than or equal to zero, then vertical scrolling snaps to the  top
              of an item, or part of an item if items are taller than the con-
              tentbox.

       Command-Line Switch:    -yscrollsmoothing
       Database Name:          yScrollSmoothing
       Database Class:         ScrollSmoothing


              Specifies whether scrolling should be done as if  -yscrollincre-
              ment=1  whenever  scrolling  is  performed  by non-unit amounts.
              When the value of this option is true and the yview  command  is
              called  to  scroll by "units", scrolling occurs according to the
              -yscrollincrement option, and all other scrolling is done as  if
              the  -yscrollincrement  option was set to 1.  The effect is that
              when dragging the scrollbar thumb scrolling is very smooth,  but
              when clicking the scrollbar buttons scrolling is done in coarser
              increments.  The default value is false.


ITEM AND COLUMN TAGS
       Columns and items may have any number of tags associated with them.   A
       tag is just a string of characters, and it may take any form, including
       that of an integer, although the characters '(', ')', '&', '|', '^' and
       '!' should be avoided.

       The same tag may be associated with many columns or items. This is com-
       monly done to group items in various interesting ways; for example,  in
       a file browser all directories might be given the tag "directory".

       Tag  expressions  are used in column descriptions and item descriptions
       to specify which columns and items to operate on.  A tag expression can
       be  a  single  tag name or a logical expression of tags using operators
       '&&', '||', '^' and '!', and parenthesized subexpressions.   For  exam-
       ple:


       or equivalently:


       will  return  the  unique ids of any items with either "a" or "b" tags,
       but not both.

       Within a tag expression a tag name may be enclosed in double quotes  to
       avoid special processing of the operator characters. For example:


       will return the unique ids of any items with either "a&&b" or "c" tags;
       in this example the && is not treated as an  operator.  A  double-quote
       may be escaped within a quoted tag name using a backslash '\'.



treectrl                       2.3                             20





treectrl(n)                Tk Commands                treectrl(n)


       Tag  operators may be bypassed completely by setting the -columntagexpr
       and -itemtagexpr options. This can be useful if  your  application  has
       column or item tags containing arbitrary text.



WIDGET COMMAND
       The  treectrl  command creates a new Tcl command whose name is the same
       as the path name of the treectrl's window.  This command may be used to
       invoke  various operations on the widget.  It has the following general
       form:

       pathName option ?arg arg ...?

       PathName is the name of the command, which is the same as the  treectrl
       widget's  path  name.  Option and the args determine the exact behavior
       of the command.  The following commands are possible for treectrl  wid-
       gets:

       pathName activate itemDesc
              Sets  the  active  item  to  the  one described by itemDesc, and
              switches on the state active for this item.   From  now  on  the
              item  can  be  retrieved  with  the item description active.  An
              <ActiveItem> event is generated.

       pathName bbox ?area?
              Returns a list with four elements giving the bounding box (left,
              top,  right and bottom) of an area of the window. If area is not
              specified, then the result is the bounding  box  of  the  entire
              window.   If area is content, then the result is the part of the
              window not including borders, headers, or  locked  columns.   If
              area  is  header,  then the result is the part of the window not
              including borders where column titles are displayed.  If area is
              left,  then  the  result is the part of the window not including
              borders or headers where left-locked columns are displayed.   If
              area  is  right,  then  the result is the part of the window not
              including borders or headers where right-locked columns are dis-
              played.   An empty string is returned if the display area has no
              height or width, which can be true for various reasons  such  as
              the  window  is  too  small,  or the header is not displayed, or
              there aren't any locked columns.

       pathName canvasx windowx
              Translates the given window x-coordinate windowx in the treectrl
              to  canvas coordinate space.  The canvas is the virtual sheet of
              paper that all the visible items are drawn onto, of which only a
              portion may be visible in the treectrl window.  The marquee com-
              mand expects canvas coordinates.

       pathName canvasy windowy
              Translates the given window y-coordinate windowy in the treectrl
              to  canvas coordinate space.  The canvas is the virtual sheet of
              paper that all the visible items are drawn onto, of which only a
              portion  may  be  visible  in  the treectrl window.  The marquee



treectrl                       2.3                             21





treectrl(n)                Tk Commands                treectrl(n)


              command expects canvas coordinates.

       pathName cget option
              Returns the current value of the configuration option  given  by
              option.   Option may have any of the values accepted by the tree
              command.

       pathName collapse ?-recurse? ?itemDesc ...?
              Use item collapse instead.

       pathName column option column ?arg ...?
              This command is used to manipulate the columns of  the  treectrl
              widget  (see  section COLUMNS below).  The exact behavior of the
              command depends on the option argument that follows  the  column
              argument.  The following forms of the command are supported:

              pathName column bbox columnDesc
                     Returns a list with four elements giving the bounding box
                     of the header of  the  column  specified  by  the  column
                     description  columnDesc.   If  the treectrl is configured
                     not to display the column headers by means of the  -show-
                     header option, then an empty list is returned instead.

              pathName column cget columnDesc option
                     This  command  returns  the  current  value of the option
                     named option for  the  column  specified  by  the  column
                     description columnDesc, ColumnDesc may also be the string
                     tail to specify the tail column.  Option may have any  of
                     the  values  accepted by the column configure widget com-
                     mand.

              pathName column configure columnDesc ?option? ?value? ?option
              value ...?
                     This  command  is similar to the configure widget command
                     except that  it  modifies  options  associated  with  the
                     columns  specified  by  the column description columnDesc
                     instead of modifying options  for  the  overall  treectrl
                     widget.  ColumnDesc may be the string tail to specify the
                     tail column.  If columnDesc refers to more than one  col-
                     umn,  then  at least one option-value pair must be given.
                     If no option is specified, the  command  returns  a  list
                     describing  all  of  the available options for columnDesc
                     (see Tk_ConfigureInfo for information on  the  format  of
                     this  list).   If option is specified with no value, then
                     the command returns  a  list  describing  the  one  named
                     option  (this list will be identical to the corresponding
                     sublist of the value returned if no option is specified).
                     If one or more option-value pairs are specified, then the
                     command modifies the given option(s) to  have  the  given
                     value(s) for columnDesc; in this case the command returns
                     an empty string.

                     See COLUMNS below for details on  the  options  available
                     for columns.



treectrl                       2.3                             22





treectrl(n)                Tk Commands                treectrl(n)


              pathName column compare column1 op column2
                     For  both  column  descriptions  column1  and column2 the
                     index is retrieved (as returned  from  the  column  order
                     widget  command).   Then these indexes are compared using
                     the operator op, which must be either <,  <=,  ==, >=, >,
                     or !=.  The return value of this command is 1 if the com-
                     parison evaluated to true, 0 otherwise.

              pathName column count ?columnDesc?
                     If no additional arguments are given,  the  result  is  a
                     decimal  string  giving  the number of columns created by
                     the column  create  widget  command  which  haven't  been
                     deleted by the column delete widget command; in this case
                     the tail column is not counted.  If columnDesc is  given,
                     then  the result is the number of columns that match that
                     column description.

              pathName column create ?option value ...?
                     This command creates a new column in the treectrl widget.
                     The  new  column  is  placed  to  the  right of all other
                     columns (except the tail column). Any option-value  argu-
                     ments  configure  the  new column according to the column
                     configure command. The return value is the unique identi-
                     fier of the new column.

              pathName column delete first ?last?
                     Deletes  the  specified column(s). First and last must be
                     valid column descriptions. If both  first  and  last  are
                     specified,  then  they may refer to a single column only.
                     The tail column cannot be deleted and it is an  error  to
                     specify  it.  The order of first and last doesn't matter,
                     and first may be equal to last.

              pathName column dragcget option

              pathName column dragconfigure ?option? ?value? ?option value
              ...?
                     The user can move a column within a treectrl by drag-and-
                     drop. Feedback consists of a semi-transparent photo image
                     of  the header of the column being dragged and a 2-pixel-
                     thick vertical line to indicate where the column  may  be
                     dropped.  The drag image consists of a colored background
                     rectangle plus the image and/or  text  displayed  in  the
                     column  header. The 2-pixel-thick line will be drawn over
                     the left edge of the column before which the dragged col-
                     umn may be dropped.

                     The  library scripts generate a <ColumnDrag-accept> event
                     when the user has successfully drag-and-drop'd a  column.
                     You  will have to bind a script to this event if you want
                     to move the dragged column.

                     The following configuration options are supported:




treectrl                       2.3                             23





treectrl(n)                Tk Commands                treectrl(n)


                     -enable boolean
                             Controls whether the user is allowed to rearrange
                             columns by drag-and-drop.

                     -imagealpha alpha
                             Alpha  is  an  integer  from 0 (invisible) to 255
                             (opaque) controlling the transparency of the drag
                             image. Any value outside this range is clipped.

                     -imagecolor background
                             Background  is  the color of the drag image back-
                             ground rectangle.

                     -imagecolumn column
                             Column specifies the column to  create  the  drag
                             image from.

                     -imageoffset offset
                             Offset is the horizontal screen distance the drag
                             image is offset from its starting position.

                     -indicatorcolor color
                             Color is the color of the 2-pixel-thick line.

                     -indicatorcolumn column
                             The 2-pixel-thick line will  be  drawn  over  the
                             left or right edge of column.

                     -indicatorside side
                             Specifies  whether the 2-pixel-thick line will be
                             drawn over the left or right edge of  the  column
                             specified by -indicatorcolumn.

              pathName column index columnDesc
                     Deprecated. Use column id instead.

              pathName column id columnDesc
                     This  command  resolves the column description columnDesc
                     into a list of unique column  identifiers.  If  the  col-
                     umn(s)  described by columnDesc don't exist, this command
                     returns an empty list.

              pathName column list ?-visible?
                     This command returns a list of identifiers for every col-
                     umn  (except the tail) from left to right. If -visible is
                     given, only columns whose -visible  option  is  true  are
                     returned.

              pathName column move columnDesc beforeDesc
                     Moves  the  column specified by columnDesc to the left of
                     the column specified by beforeDesc. Both  columnDesc  and
                     beforeDesc must be valid column descriptions.  If before-
                     Desc is the  string  tail,  the  column  columnDesc  will
                     become the last column.



treectrl                       2.3                             24





treectrl(n)                Tk Commands                treectrl(n)


              pathName column neededwidth columnDesc
                     This  command  returns a decimal string giving the needed
                     width of the column specified by the  column  description
                     columnDesc.  The needed width is the maximum of the width
                     of the column header and the width of the widest style in
                     any visible item.

              pathName column order columnDesc ?-visible?
                     This command returns a decimal string giving the position
                     of the column specified by the column description column-
                     Desc  in  the  list of columns starting from zero for the
                     leftmost column.  If  -visible  is  given,  only  columns
                     whose  -visible  option is true are considered, and -1 is
                     returned if columnDesc's -visible option is false.

              pathName column tag option ?arg arg ...?
                     This command is used to manipulate tags on columns.   The
                     exact behavior of the command depends on the option argu-
                     ment that follows the column tag argument.  The following
                     forms of the command are supported:

                     pathName column tag add columnDesc tagList
                             Adds each tag in tagList to the columns specified
                             by the column description columnDesc.   Duplicate
                             tags  are  ignored. The list of tags for a column
                             can also be changed via a column's -tags  option.

                     pathName column tag expr columnDesc tagExpr
                             Evaluates  the  tag  expression  tagExpr  against
                             every column specified by the column  description
                             columnDesc. The result is 1 if the tag expression
                             evaluates to true for every column, 0  otherwise.

                     pathName column tag names columnDesc
                             Returns  a  list  of  tag  names  assigned to the
                             columns  specified  by  the  column   description
                             columnDesc.  The  result is the union of any tags
                             assigned to the columns.

                     pathName column tag remove columnDesc tagList
                             Removes each tag  in  tagList  from  the  columns
                             specified  by  the column description columnDesc.
                             It is not an error if any of the columns  do  not
                             use any of the tags.  The list of tags for a col-
                             umn can also be  changed  via  a  column's  -tags
                             option.

              pathName column width columnDesc
                     This command returns a decimal string giving the width in
                     pixels of the column specified by the column  description
                     columnDesc,  even  if  the  treectrl is configured to not
                     display the column headers by means  of  the  -showheader
                     option.




treectrl                       2.3                             25





treectrl(n)                Tk Commands                treectrl(n)


       pathName compare itemDesc1 op itemDesc2
              Deprecated. Use the item compare command instead.

       pathName configure ?option? ?value option value ...?
              Query  or modify the configuration options of the widget.  If no
              option is specified, returns a list describing all of the avail-
              able  options for pathName (see Tk_ConfigureInfo for information
              on the format of this list).  If option  is  specified  with  no
              value,  then the command returns a list describing the one named
              option (this list will be identical to the corresponding sublist
              of  the  value  returned  if no option is specified).  If one or
              more option-value pairs are specified, then the command modifies
              the  given widget option(s) to have the given value(s);  in this
              case the command returns an empty string.  Option may  have  any
              of the values accepted by the treectrl command.

       pathName contentbox
              Returns a list with four elements giving the bounding box of the
              screen area used to display items.  This is the area of the win-
              dow not including borders, column headers, or locked columns. An
              empty string is returned if the display area has  no  height  or
              width, which can happen if the window is too small.

       pathName debug option ?arg arg ...?
              This  command  is  used  to facilitate debugging of the treectrl
              widget.  The exact behavior of the command depends on the option
              argument  that  follows the debug argument.  The following forms
              of the command are supported:

              pathName debug alloc
                     Returns a string  giving  partial  statistics  on  memory
                     allocations, if the package was built with TREECTRL_DEBUG
                     defined.

              pathName debug cget option
                     This command returns the current value of  the  debugging
                     option  named  option.  Option may have any of the values
                     accepted by the debug configure widget command.

              pathName debug configure ?option? ?value? ?option value ...?
                     This command is similar to the configure  widget  command
                     except that it modifies debugging options instead of mod-
                     ifying options for the overall treectrl  widget.   If  no
                     option  is specified, the command returns a list describ-
                     ing all of the available debugging options  (see  Tk_Con-
                     figureInfo  for  information on the format of this list).
                     If option is specified with no value,  then  the  command
                     returns a list describing the one named option (this list
                     will be identical to the  corresponding  sublist  of  the
                     value  returned  if  no  option is specified).  If one or
                     more option-value pairs are specified, then  the  command
                     modifies  the given debugging option(s) to have the given
                     value(s); in this  case  the  command  returns  an  empty
                     string.



treectrl                       2.3                             26





treectrl(n)                Tk Commands                treectrl(n)


                     The following debugging options are supported:

                     -displaydelay millis
                             Specifies  a time duration in milliseconds, which
                             should be waited after something has  been  drawn
                             to  the  screen.  Setting this option has only an
                             effect, if  the  debugging  options  -enable  and
                             -display are switched on.

                     -data boolean
                             If  this option is switched on (together with the
                             debugging option -enable), at  various  places  a
                             consistence  check on the internal data structure
                             is made (e.g. for every item is checked,  if  the
                             registered  number  of  children  is equal to the
                             number of child items).  If an inconsistency  was
                             found, a Tcl background error is raised.

                     -display boolean
                             If  this option is switched on (together with the
                             debugging option -enable), at varios places addi-
                             tional debugging output is printed to stdout.

                     -drawcolor color
                             When  specified,  areas of the window are painted
                             with this color when drawing in  those  areas  is
                             about  to occur.  Setting this option has only an
                             effect if the debugging options -enable and -dis-
                             play are switched on.

                     -enable boolean
                             All  other  debugging options only take effect if
                             this option is also switched on.

                     -erasecolor color
                             When specified, areas of the  window  which  have
                             been  marked as "invalid" (for example, when part
                             of the window is exposed) are painted  with  this
                             color.   If  you  use  an  unusual color for this
                             option (like pink), superflous screen redraws can
                             be  spotted more easily.  Setting this option has
                             only an effect if the debugging  options  -enable
                             and -display are switched on.

                     -span boolean
                             Debugging related to column spanning.

                     -textlayout boolean
                             Debugging related to text-element layout.

              pathName debug dinfo option
                     Returns a string describing display-related stuff. Option
                     must be one of alloc, ditem, onscreen or range.




treectrl                       2.3                             27





treectrl(n)                Tk Commands                treectrl(n)


              pathName debug expose x1 y1 x2 y2
                     Causes the area of the window bounded by the  given  win-
                     dow-coords to be marked as invalid. This simulates uncov-
                     ering part of the window.

              pathName debug scroll
                     Returns a string useful for debugging vertical scrolling.

       pathName depth ?itemDesc?
              If the additional argument itemDesc is given, then the result is
              a decimal string giving the  depth  of  the  item  described  by
              itemDesc.   If  no itemDesc is specified, then the maximum depth
              of all items in the treectrl widget is returned instead.   Depth
              is defined as the number of ancestors an item has.

       pathName dragimage option ?arg ...?
              This  command  is  used to manipulate the dragimage, one or more
              dotted lines around rectangular regions of the treectrl  widget.
              The exact behavior of the command depends on the option argument
              that follows the dragimage argument.  The following forms of the
              command are supported:

              pathName dragimage add itemDesc ?column? ?element?
                     Adds  the shapes of the item described by itemDesc to the
                     shapes of the dragimage.  Specifying additional arguments
                     reduces  the  number  of rectangles that are added to the
                     dragimage.  If no additional arguments is specified,  for
                     every  element of the item in every column a dotted rect-
                     angles is added.  If column is specified, all elements in
                     other columns are ignored.  If also element is specified,
                     only a rectangle for this one element  of  the  specified
                     item in the given column is added.

              pathName dragimage cget option
                     This  command  returns the current value of the dragimage
                     option named option.  Option may have any of  the  values
                     accepted by the dragimage configure widget command.

              pathName dragimage clear
                     Removes all shapes (if there are any) from the dragimage.
                     This command does not modify the dragimage offset.

              pathName dragimage configure ?option? ?value? ?option value ...?
                     This  command  is similar to the configure widget command
                     except that it modifies the dragimage options instead  of
                     modifying options for the overall treectrl widget.  If no
                     option is specified, the command returns a list  describ-
                     ing  all  of the available dragimage options (see Tk_Con-
                     figureInfo for information on the format of  this  list).
                     If  option  is  specified with no value, then the command
                     returns a list describing the one named dragimage  option
                     (this list will be identical to the corresponding sublist
                     of the value returned if no option is specified).  If one
                     or  more  option-value  pairs  are  specified,  then  the



treectrl                       2.3                             28





treectrl(n)                Tk Commands                treectrl(n)


                     command modifies the given dragimage  option(s)  to  have
                     the  given  value(s); in this case the command returns an
                     empty string.

                     The following dragimage options are supported:

                     -visible boolean
                             Specifies  a  boolean  value   which   determines
                             whether  the  dragimage should currently be visi-
                             ble.

              pathName dragimage offset ?x y?
                     Returns a list containing the x  and  y  offsets  of  the
                     dragimage, if no additional arguments are specified.  The
                     dragimage offset is the screen  distance,  the  image  is
                     displayed relative to the item its shape is derived from.
                     If two coordinates are specified, sets the dragimage off-
                     set to the given coordinates x and y.

       pathName element option ?element? ?arg arg ...?
              This  command  is  used  to  manipulate  elements  (see ELEMENTS
              below).  The exact behavior of the command depends on the option
              argument that follows the element argument.  The following forms
              of the command are supported:

              pathName element cget element option
                     This command returns the  current  value  of  the  option
                     named  option  associated  with the element given by ele-
                     ment.  Option may have any of the values accepted by  the
                     element configure widget command.

              pathName element configure element ?option? ?value? ?option
              value ...?
                     This command is similar to the configure  widget  command
                     except  that it modifies options associated with the ele-
                     ment given by element instead of  modifying  options  for
                     the  overall treectrl widget.  If no option is specified,
                     the command returns a list describing all of  the  avail-
                     able options for element (see Tk_ConfigureInfo for infor-
                     mation on the format of this list).  If option is  speci-
                     fied  with  no  value,  then  the  command returns a list
                     describing the one named option (this list will be  iden-
                     tical  to the corresponding sublist of the value returned
                     if no option is specified).  If one or more  option-value
                     pairs  are specified, then the command modifies the given
                     option(s) to have the given value(s) in element; in  this
                     case  the  command returns an empty string.  See ELEMENTS
                     below for details on the options available for  elements.

              pathName element create element type ?option value ...?
                     Create  a  new elememt in pathName of type type with name
                     element.  The exact format of the  arguments  after  type
                     depends  on type, but generally consist of specifications
                     for zero or more element options.  See the subsections on



treectrl                       2.3                             29





treectrl(n)                Tk Commands                treectrl(n)


                     individual  element types below for more on the syntax of
                     this command.  This command returns the name for the  new
                     element.

              pathName element delete ?element ...?
                     Deletes  each  of the named elements and returns an empty
                     string.  If an element is deleted while it is still  con-
                     figured  as  an element of one or more styles by means of
                     the style elements widget command,  it  is  also  removed
                     from the element lists of these styles.

              pathName element names
                     Returns  a list containing the names of all existing ele-
                     ments.

              pathName element perstate element option stateList
                     This command returns the value of  the  per-state  option
                     named  option for element for a certain state.  StateList
                     is a list of state names (static and dynamic, see STATES)
                     which specifies the state to use.

              pathName element type element
                     Returns the type of the element given by element, such as
                     rect or text.

       pathName expand ?-recurse? ?itemDesc ...?
              Use item expand instead.

       pathName gradient option ?arg ...?
              This command is used to manipulate color gradients.  See  GRADI-
              ENTS  for  more  information  about  using gradients.  The exact
              behavior of the command depends on the option argument that fol-
              lows  the gradient argument.  The following forms of the command
              are supported:

              pathName gradient api ?version?
                     When version is specified this command sets the API  that
                     is used by the gradient command.  You must call this com-
                     mand before any gradients can be created.  The purpose of
                     this  is to avoid breaking your application if the gradi-
                     ent API changes in the future.  When version is not given
                     this command returns a list of the form:

                     {{available 1.0} {current 1.0}}

                     If  this  command has never been called for this treectrl
                     widget the result is:

                     {{available 1.0} {current unspecified}}


              pathName gradient cget gradient option
                     Returns the current value of the configuration option for
                     the  gradient specified by gradient whose name is option.



treectrl                       2.3                             30





treectrl(n)                Tk Commands                treectrl(n)


                     Option may have any of the values accepted by the  gradi-
                     ent configure command.

              pathName gradient configure gradient ?option value ...?
                     If  no  option  is  specified, the command returns a list
                     describing all of the  available  gradient  options  (see
                     Tk_ConfigureInfo  for  information  on the format of this
                     list).  If option is specified with no  value,  then  the
                     command  returns a list describing the one named gradient
                     option (this list will be identical to the  corresponding
                     sublist of the value returned if no option is specified).
                     If one or more option-value pairs are specified, then the
                     command modifies the given gradient option(s) to have the
                     given value(s); in this case the command returns an empty
                     string.

                     The  following options are supported (see gradient create
                     for the meaning of each option):

                     -bottom coordSpec

                     -left coordSpec

                     -orient direction

                     -right coordSpec

                     -steps stepCount

                     -stops stopsList

                     -top coordSpec

              pathName gradient create name ?option value ...?
                     Creates a new gradient with the name name, which must  be
                     a  unique  name  not  used by another gradient created by
                     this treectrl widget.

                     The following options are supported:

                     -bottom coordSpec

                     -left coordSpec

                     -right coordSpec

                     -top coordSpec
                             Each of these options specifies one edge  of  the
                             gradient brush.  If the option is specified as an
                             empty string (the default), the gradient  brush's
                             edge is the same as that of whatever rectangle is
                             being painted using the gradient.   See  GRADIENT
                             COORDINATES for details on gradient brush coordi-
                             nates.



treectrl                       2.3                             31





treectrl(n)                Tk Commands                treectrl(n)


                             The format of each of these options is a list  of
                             2  or  more  values  {value coordType ?arg ...?},
                             where value is a floating point  number  (usually
                             from  0.0  to  1.0) and coordType is one of area,
                             canvas, column or item.  The area keyword must be
                             followed  by  one of the same area names that the
                             bbox command accepts.  The column keyword may  be
                             followed   by  a  column  description  specifying
                             exactly one column.  The item keyword may be fol-
                             lowed  by  an item description specifying exactly
                             one item.

                     -orient direction
                             This option specifies the direction a linear gra-
                             dient  changes color in.  Must be either horizon-
                             tal (the default) or vertical or an  abbreviation
                             of one of these.

                     -steps stepCount
                             Specifies  the number of bands of color drawn for
                             each color stop described by the  -stops  option.
                             The  default value is 1, the maximum is 25.  This
                             option has no effect if gradients are drawn using
                             something  better  than Tk API calls.  See GRADI-
                             ENTS for more on this.

                     -stops stopsList
                             Specifies the color stops  along  this  gradient.
                             The argument stopsList has the following form:

                             {{offset color ?opacity?} {offset color ?opacity?} ...}

                             Each  offset  is a floating point number from 0.0
                             to 1.0 specifying the distance from the start  of
                             the  gradient where the color begins.  Each color
                             is a Tk color name or description.  Each optional
                             opacity  is  a  floating point number from 0.0 to
                             1.0 specifying how transparent the gradient is.

                             If stopsList is non-empty there must be at  least
                             two stops specified, and the first offset must be
                             0.0 and the last offset must be 1.0.   Any  other
                             stop  offsets must be listed in increasing order.
                             Specifying opacity has no effect if gradients are
                             drawn using Tk API calls.  See GRADIENTS for more
                             on this.

              pathName gradient delete ?name ...?
                     Deletes each gradient specified by name.  If the gradient
                     is still being used then it is not actually deleted until
                     all elements etc using the gradient  have  stopped  using
                     it.





treectrl                       2.3                             32





treectrl(n)                Tk Commands                treectrl(n)


              pathName gradient names
                     Returns  a  list  of names of all the gradients that have
                     been created by this treectrl widget.

              pathName gradient native ?preference?
                     Without any arguments, this  command  returns  a  boolean
                     indicating  whether  or  not the platform supports native
                     transparent gradients.   The  preference  argument  is  a
                     boolean that indicates whether native gradients should be
                     used; this can be used to  test  the  appearance  of  the
                     application.

       pathName identify x y
              Returns  a list describing what is displayed at the given window
              coordinates x and y.  If the coordinates are outside the window,
              over the borders, or over any whitespace in the window, then the
              result is an empty string;  otherwise  the  first  word  of  the
              result is header or item.

              If the coordinates are over a column header, then the first word
              of the result is header, followed by the unique id of the column
              (or  the  string tail).  If the x coordinate is near the left or
              right end of a column, then  a  third  word  left  or  right  is
              appended to the result.

              If  the coordinates are over an item, then the first word of the
              result is item followed by the unique id of that item.   If  the
              coordinates  are  not  over  the area for displaying buttons and
              lines, then column and a unique column id are the  3rd  and  4th
              words  of  the  result.  If  the coordinates are over an element
              within that column, then element and an element name are the 5th
              and 6th words of the result.

              If the coordinates are over a button, then the first word of the
              result is item, followed by the unique id of that item, followed
              by the word button.

              If  the  coordinates are over a line descending from an ancestor
              of an item (but not the parent of that  item),  then  the  first
              word  of  the  result is item, followed by the unique id of that
              item, followed by the word line, followed by the  unique  id  of
              the  item  the line is coming from. This is used to collapse the
              ancestor when the line is clicked on.

       pathName index itemDesc
              Deprecated. Use item id instead.

       pathName item option ?arg ...?
              This command is used to manipulate items.  The exact behavior of
              the command depends on the option argument that follows the item
              argument.  The following forms of the command are supported:

              pathName item ancestors itemDesc
                     Returns a list containing the item ids of  the  ancestors



treectrl                       2.3                             33





treectrl(n)                Tk Commands                treectrl(n)


                     of  the  item specified by itemDesc. The first list value
                     is the parent, the second is the parent's parent,  an  so
                     on. The last list value will be the root item if itemDesc
                     is a descendant of the root item.

              pathName item bbox itemDesc ?column? ?element?
                     Returns a list with four elements giving the bounding box
                     of  the  item described by itemDesc.  If no further argu-
                     ment is specified, the bbox spans the area  of  the  item
                     over  all  non-locked  columns. If a column is specified,
                     only the area of the item in this column  is  considered.
                     If  an  additional element is specified, the area of this
                     element in column of the specified item is returned.

              pathName item buttonstate itemDesc ?state?
                     If state is specified, this command sets the state of the
                     expand/collapse  button  for the single item specified by
                     itemDesc.  The state argument may be one of active,  nor-
                     mal  or pressed.  The current (or newly-set) state of the
                     button is returned.  The button state is used by the sys-
                     tem  theme,  if any, to change the appearance of the but-
                     ton.

              pathName item cget itemDesc option
                     Returns the current value of the configuration option for
                     the  item  specified  by  itemDesc  whose name is option.
                     Option may have any of the values accepted  by  the  item
                     configure command.

              pathName item children itemDesc
                     Returns a list containing the item ids of all children of
                     the item specified by itemDesc in the correct order  from
                     the first child to the last child.

              pathName item collapse itemDesc ?-animate? ?-recurse?
                     Switches  off  the open state of the item(s) described by
                     itemDesc.  If an item has descendants, then they  are  no
                     longer  displayed.   If  an  item is already closed, then
                     this command has no effect on that item.  If -animate  is
                     specified,  then item's button will animate as it transi-
                     tions between states if the theme supports  it;  in  this
                     case  only  one  item  may  be specified.  If -recurse is
                     specified, then all descendants of the items described by
                     itemDesc  will  also  be  collapsed.  For every item that
                     actually will be collapsed, two events are  generated:  a
                     <Collapse-before> event before the item state is changed,
                     and a <Collapse-after> event after  the  item  state  was
                     changed.

              pathName item compare itemDesc1 op itemDesc2
                     From  both  items described by the itemDescs the index is
                     retrieved (as returned from the item  order  widget  com-
                     mand).   Then these indexes are compared using the opera-
                     tor op, which must be either <,  <=,  ==, >=, >,  or  !=.



treectrl                       2.3                             34





treectrl(n)                Tk Commands                treectrl(n)


                     The  return  value of this command is 1 if the comparison
                     evaluated to true, 0 otherwise.

              pathName item complex itemDesc ?list...?
                     This horrible command is now deprecated. Use item element
                     configure instead. For every column of the treectrl there
                     may be specified one list.  Each list  should  look  like
                     this:

                     { {element option value ...} {element option value ...} ...}

                     Every  option  must  be  known by the element's type (see
                     ELEMENTS below).  Each option will be set  to  value  for
                     the element in this one column in this item.

              pathName item configure itemDesc ?option? ?value? ?option value
              ...?
                     If no option is specified, returns a list describing  all
                     of  the  available options for the item given by itemDesc
                     (see Tk_ConfigureInfo for information on  the  format  of
                     this  list).  If  option is specified with no value, then
                     the command returns  a  list  describing  the  one  named
                     option  (this list will be identical to the corresponding
                     sublist of the value returned if no option is specified).

                     If one or more option-value pairs are specified, then the
                     command modifies the given item  option(s)  to  have  the
                     given value(s); in this case the command returns an empty
                     string. This is the only case where itemDesc may refer to
                     multiple items.

                     The  following options are supported by this command (see
                     item create for the meaning of each option):

                     -button boolean|auto

                     -height height

                     -tags tagList

                     -visible boolean

                     -wrap boolean

              pathName item count ?itemDesc?
                     If no additional arguments are given,  the  result  is  a
                     decimal  string giving the number of items created by the
                     item create widget command which haven't been deleted  by
                     the  item delete widget command, plus 1 for the ever-pre-
                     sent root item.  If the  optional  argument  itemDesc  is
                     given,  then the result is the number of items that match
                     that item description.





treectrl                       2.3                             35





treectrl(n)                Tk Commands                treectrl(n)


              pathName item create ?option value ...?
                     Creates some new items and optionally returns a  list  of
                     unique  identifiers  for those items.  The new items have
                     the states open and  enabled  set  by  default.   If  the
                     treectrl  widget currently has the focus, the state focus
                     is also set.

                     The following options are supported by this command:

                     -button boolean|auto
                             The value of this option must  have  one  of  the
                             forms  accepted  by Tcl_GetBoolean or be the word
                             auto (or any abbreviation of  it).  It  indicates
                             whether  or  not an expand/collapse button should
                             be drawn next to the item, typically to  indicate
                             that the item has children.  If the value of this
                             option is auto, then a button is  displayed  next
                             to  the  item  whenever the item has any children
                             whose item option -visible is true.   The  button
                             will only be displayed if:

                             [1]    the   column  specified  by  the  treectrl
                                    option -treecolumn is visible, and

                             [2]    the treectrl option -showbuttons is  true,
                                    and

                             [3]    for  the  root  item,  the treectrl option
                                    -showrootbutton is true.

                     -count numItems
                             Specifies the number of items to create. Must  be
                             >= 0. Defaults to 1.

                     -height height
                             Specifies  a  fixed  height  in  any of the forms
                             acceptable to Tk_GetPixels.  Must  be  >=  0.  If
                             height is zero then the item's height is unspeci-
                             fied.  Defaults to 0.

                     -nextsibling itemDesc
                             Specifies the item before  which  the  new  items
                             will  be  inserted.  The  new items will have the
                             same parent as itemDesc.

                     -open boolean
                             Specifies whether the items  should  be  open  or
                             closed. Default is true.

                     -parent itemDesc
                             Specifies  the  item  which the new items will be
                             the children of. The new items will  be  appended
                             to the list of children of itemDesc.




treectrl                       2.3                             36





treectrl(n)                Tk Commands                treectrl(n)


                     -prevsibling itemDesc
                             Specifies the item after which the new items will
                             be inserted. The new items  will  have  the  same
                             parent as itemDesc.

                     -returnid boolean
                             Specifies whether or not to return a list of item
                             identifiers for the newly created items. Specify-
                             ing  false is useful when creating a large number
                             of items in the console  or  to  improve  perfor-
                             mance. Default is true.

                     -tags tagList
                             TagList is a list of tag names to be added to the
                             new items.

                     -visible boolean
                             Boolean must have one of the  forms  accepted  by
                             Tcl_GetBoolean. It indicates that the item should
                             be displayed in the list. The item will  only  be
                             displayed if: a) each ancestor is a descendant of
                             the root item (not an orphan); and b) each ances-
                             tor's -visible option is true

                     -wrap boolean
                             Boolean  must  have  one of the forms accepted by
                             Tcl_GetBoolean.  It  indicates  that  this   item
                             should  be the first one in a horizontal range or
                             vertical range of  items.  See  also  the  widget
                             option -wrap.

              pathName item delete first ?last?
                     Deletes  the  specified  item(s).  First and last must be
                     valid item descriptions.  If last isn't  specified,  then
                     first may specify multiple items.  If both first and last
                     are specified, they must each decribe a single item  with
                     a  common ancestor; then the range of items between first
                     and last is deleted.  The order of first and last doesn't
                     matter.

                     Deleting  an  item deletes any child items of the deleted
                     item recursively.  If the current active item is deleted,
                     the  root  item becomes the new active item.  If the cur-
                     rent selection anchor item  is  deleted,  the  root  item
                     becomes  the  new anchor item.  There is no way to delete
                     the root item of the treectrl widget; in  all  cases  the
                     specification of the root item is ignored.

                     For  each  call to this command, two events may be gener-
                     ated.  If any of the deleted items are selected,  then  a
                     <Selection>  event is generated just before the items are
                     deleted.  If any items are going to be deleted,  then  an
                     <ItemDelete>  event  event  is  generated just before the
                     items are deleted.



treectrl                       2.3                             37





treectrl(n)                Tk Commands                treectrl(n)


              pathName item descendants itemDesc
                     Returns a list containing the item ids of the descendants
                     of  the  item  specified  by itemDesc, i.e. the children,
                     grandchildren, great-grandchildren etc, of the item.

              pathName item dump itemDesc
                     Returns a list with 4  words  in  the  form  index  index
                     indexVis indexVis.

              pathName item element command itemDesc column element ?arg ...?
                     This  command is used to manipulate elements of the item.
                     The exact behavior of the command depends on the  command
                     argument  that follows the element argument.  The follow-
                     ing forms of the command are supported:

                     pathName item element actual itemDesc column element
                     option
                             Deprecated. Use item element perstate instead.

                     pathName item element cget itemDesc column element option
                             This command returns  the  value  of  the  option
                             named  option associated with element inside col-
                             umn of the item described by itemDesc, if it  was
                             already  configured  for the actual item.  Option
                             may have any of the values accepted by  the  type
                             of the specified element (see ELEMENTS below)

                     pathName  item  element  configure  itemDesc  column
                     element ?option? ?value? ?option value ...?
                             This  command  modifies configuration options for
                             an element in a column of an item.  If no  option
                             is specified, the command returns a list describ-
                             ing all of the available options for the  element
                             (see Tk_ConfigureInfo for information on the for-
                             mat of this list).  If option is  specified  with
                             no   value,  then  the  command  returns  a  list
                             describing the one named option (this  list  will
                             be  identical to the corresponding sublist of the
                             value returned if no option is specified).

                             If one or more option-value pairs are  specified,
                             then  the command modifies the given option(s) to
                             have the given value(s)  in  the  element  inside
                             column  of  the item(s) described by itemDesc; in
                             this case the command returns  an  empty  string.
                             This is the only case where itemDesc may refer to
                             multiple items.

                             It is possible to configure multiple elements  in
                             multiple columns with a single call. To configure
                             another element in the same column, append a  '+'
                             argument followed by the element name. To config-
                             ure elements in  another  column,  append  a  ','
                             argument followed by the column.  For example:



treectrl                       2.3                             38





treectrl(n)                Tk Commands                treectrl(n)


                                                     $C1 $E1 -text "hello" + $E2 -text "world" , \
                                                     $C2 $E3 -fill Blue , \
                                                     $C3 $E1 -text "apples and oranges"

                             Each  of the column description arguments to this
                             command may refer to multiple columns if at least
                             one option-value pair is given.

                     pathName item element perstate itemDesc column element
                     option ?stateList?
                             This command returns the  current  value  of  the
                             per-state  option named option for element inside
                             column of the  item  described  by  itemDesc.  If
                             stateList  is  specified, the list of state names
                             (static and dynamic, see STATES) is used in place
                             of the current state for item and column.

              pathName item enabled itemDesc ?boolean?
                     Returns 1 if the item described by itemDesc has the state
                     enabled switched on, 0 otherwise. If  boolean  is  speci-
                     fied,  then  the enabled state of every item described by
                     the item description itemDesc is  set  accordingly.   All
                     items are enabled when first created. Disabled items can-
                     not be selected, and are ignored by the default key-navi-
                     gation and mouse bindings.

              pathName item expand itemDesc ?-animate? ?-recurse?
                     Switches  on  the  open state of the item(s) described by
                     itemDesc.  If an item has descendants, then they are  now
                     displayed.  If an item is already open, then this command
                     has no effect on that item.  If  -animate  is  specified,
                     then item's button will animate as it transitions between
                     states if the theme supports it; in this  case  only  one
                     item  may  be  specified.  If -recurse is specified, then
                     all descendants of the items described by  itemDesc  will
                     also  be  expanded.  For every item that actually will be
                     expanded, two events are  generated:  an  <Expand-before>
                     event  before  the item state is changed, and an <Expand-
                     after> event after the item state was changed.

              pathName item firstchild parent ?child?
                     If child is not specified, returns the  item  id  of  the
                     first child of the item described by parent.  If child is
                     specified, it must describe an item that is  neither  the
                     root item nor an ancestor of parent.  Then it will become
                     the new first child of parent.

              pathName item id itemDesc
                     This command resolves the item description itemDesc  into
                     a  list  of  unique item identifiers. If itemDesc doesn't
                     refer to any existing items, then this command returns an
                     empty list.





treectrl                       2.3                             39





treectrl(n)                Tk Commands                treectrl(n)


              pathName item image itemDesc ?column? ?image? ?column image ...?
                     This command sets or retrieves the value of the per-state
                     -image  option for the first image element in one or more
                     columns.  If no column is specified, this command returns
                     a  list of values, one per column.  If no image is speci-
                     fied, this command returns the value for column.

                     If one or more column-image pairs is specified, then  the
                     value  of  the  -image  option  in  each column is set to
                     image.  In this case itemDesc may refer to multiple items
                     and each column may refer to multiple columns.

                     Note  that this command is provided as a convenience. Use
                     the item element configure or item element cget  commands
                     if  you  want  to set or retrieve the value of the -image
                     option for a specific image element.

              pathName item isancestor itemDesc descendant
                     Returns 1 if the item described by itemDesc is  a  direct
                     or  indirect parent of the item decribed by descendant, 0
                     otherwise.

              pathName item isopen itemDesc
                     Returns 1 if the item described by itemDesc has the state
                     open switched on, 0 otherwise.

              pathName item lastchild parent ?child?
                     If  child  is  not  specified, returns the item id of the
                     last child of the item described by parent.  If child  is
                     specified, it must describe an item that is not an ances-
                     tor of parent.  Then it will become the new last child of
                     parent.

              pathName item nextsibling sibling ?next?
                     If next is not specified, returns the item id of the next
                     sibling of the item described by  sibling.   If  next  is
                     specified, it must describe an item that is not an ances-
                     tor of sibling.  Then it will become the new next sibling
                     of sibling.

              pathName item numchildren itemDesc
                     Returns  the  number of children of the item described by
                     itemDesc.

              pathName item order itemDesc ?-visible?
                     This command returns the position of  the  item  itemDesc
                     relative to its toplevel ancestor (usually the root item,
                     unless the ancestor is an orphan). If you imagine all the
                     items  flattened into a vertical list, the result of this
                     command is the row the item falls  in.  If  the  optional
                     argument  -visible  is given, only the items whose ances-
                     tors are expanded, and whose -visible option is true, get
                     counted;  in  this case -1 is returned if the item is not
                     visible.



treectrl                       2.3                             40





treectrl(n)                Tk Commands                treectrl(n)


              pathName item parent itemDesc
                     Returns the item id of the parent of the  item  described
                     by itemDesc.

              pathName item prevsibling sibling ?prev?
                     If prev is not specified, returns the item id of the pre-
                     vious sibling of the item described by sibling.  If  prev
                     is  specified,  it  must  describe an item that is not an
                     ancestor of sibling.  Then it will become the new  previ-
                     ous sibling of sibling.

              pathName item range first last
                     Returns  a  list  containing the item ids of all items in
                     the range between first and last, inclusive.   The  order
                     between  first and last doesn't matter, and the result is
                     always sorted by the increasing order of  the  items  (as
                     returned by the item order command).  The items specified
                     by first and last must share a common ancestor.

              pathName item remove itemDesc
                     Removes the item described by itemDesc from the  list  of
                     children of its parent, so that it will become an orphan.

              pathName item rnc itemDesc
                     Returns a list of two integers, which corresponds to  the
                     row and column of the item described by itemDesc. The row
                     and column corresponds to the  on-screen  arrangement  of
                     items  as determined by the -orient and -wrap options. If
                     the item is not displayed, this command returns an  empty
                     string.

              pathName item sort itemDesc ?option ...?
                     Sorts the children of the item described by itemDesc, and
                     redisplays the tree with the items in the new order.

                     The  range  of  items  which  should  be  sorted  can  be
                     restricted  by  means of the -first and/or -last options,
                     which  should  be  children  of  the  item  described  by
                     itemDesc;  the  order  between  these  two limiting items
                     doesn't matter.

                     The sort column can be specified by means of the  -column
                     option;  this  option  can be used repeatedly to define a
                     multicolumn sort.  The sorting is done by looking at  the
                     text  of  the  element  specified by the -element option,
                     which must be a text element defined in the style of  the
                     sorting  column,  by  default  the  first text element is
                     used.

                     If the -notreally option is specified, no rearranging  of
                     the  items is done; instead the sorted items are returned
                     as result of the command.

                     By default ASCII sorting is used with the result returned



treectrl                       2.3                             41





treectrl(n)                Tk Commands                treectrl(n)


                     in increasing order.  Any of the following options may be
                     specified to control the sorting process  of  the  previ-
                     ously   specified   column   (unique   abbreviations  are
                     accepted):

                      -ascii Use string comparison with ASCII collation order.
                             This is the default.

                     -command command
                             Use  command as a comparison command.  To compare
                             two items, evaluate a Tcl  script  consisting  of
                             command  with  the numerical ids of the two items
                             appended as  additional  arguments.   The  script
                             should  return an integer less than, equal to, or
                             greater than zero if the first item is to be con-
                             sidered  less than, equal to, or greater than the
                             second, respectively.

                     -decreasing
                             Sort the items  in  decreasing  order  ("largest"
                             items first).

                     -dictionary
                             Use dictionary-style comparison. This is the same
                             as -ascii except (a) case is ignored except as  a
                             tie-breaker and (b) if two strings contain embed-
                             ded numbers, the numbers compare as integers, not
                             characters.   For  example,  in -dictionary mode,
                             bigBoy sorts between bigbang and bigboy, and x10y
                             sorts between x9y and x11y.

                     -increasing
                             Sort  the  items  in increasing order ("smallest"
                             items first). This is the default.

                     -integer
                             Convert to integers and use integer comparison.

                      -real  Convert to floating-point values and use floating
                             comparison.

              pathName item span itemDesc ?column? ?numColumns? ?column
              numColumns ...?
                     This command sets or retrieves the number of columns that
                     a  style  covers.   If no column is specified, the return
                     value is a list of spans, one per  column.   If  no  num-
                     Columns  is  specified,  the return value is the span for
                     column.

                     If one or more column-numColumns pairs is specified,  the
                     span  for  each column is set to numColumns. In this case
                     itemDesc may refer to multiple items and each column  may
                     refer to multiple columns.




treectrl                       2.3                             42





treectrl(n)                Tk Commands                treectrl(n)


              pathName item state command itemDesc ?arg ...?
                     This command is used to manipulate the states of an item.
                     The exact behavior of the command depends on the  command
                     argument  that follows the style argument.  The following
                     forms of the command are supported:

                     pathName item state forcolumn itemDesc column ?stat-
                     eDescList?
                             Just  like item state set but manipulates dynamic
                             states for a single item column, not the item  as
                             a  whole.  If  stateDescList is unspecified, this
                             command returns a list containing  the  names  of
                             all  the  dynamic states which are switched on in
                             column.

                             If stateDescList is specified, then itemDesc  may
                             refer  to  multiple items and column may refer to
                             multiple columns.

                     pathName item state get itemDesc ?stateName?
                             If no stateName is specified, returns a list con-
                             taining  the  names  of  all (static and dynamic)
                             states which are currently switched  on  for  the
                             item  described  by  itemDesc.  If a stateName is
                             specified, 1 is returned if the  specified  state
                             is  currently  switched on for the item, 0 other-
                             wise.

                     pathName item state set itemDesc ?lastItem? stateDescList
                             Every  element  of stateDescList must be the name
                             of a dynamic state (see STATES below), optionally
                             preceded by a ~ or ! character.  Every state with
                             a leading ! will be switched  off  for  the  item
                             described by itemDesc, every state with a leading
                             ~ will be toggled, and every state without  lead-
                             ing  !  or ~ will be switched on.  If lastItem is
                             specified, the state changes will be made for all
                             items in the range between itemDesc and lastItem.
                             If lastItem unspecified, then the  state  changes
                             are made for all items described by itemDesc.

              pathName item style command itemDesc ?arg ...?
                     This command is used to manipulate the styles of an item.
                     The exact behavior of the command depends on the  command
                     argument  that follows the style argument.  The following
                     forms of the command are supported:

                     pathName item style elements itemDesc column
                             This command returns a list containing the  names
                             of  elements  which  were  configured by the item
                             element configure command for the item  described
                             by  itemDesc  in  column.  If  there  is no style
                             assigned to column an error is returned.




treectrl                       2.3                             43





treectrl(n)                Tk Commands                treectrl(n)


                     pathName item style map itemDesc column style map
                             Like the item style set command, this command may
                             be used to assign a style to a specific column of
                             an item. Unlike item style set, this command  can
                             transfer  configuration values of elements in the
                             current style to elements in the new style speci-
                             fied by style.  Map must be a list of elementOld-
                             elementNew pairs, where elementOld is an  element
                             in  the  current style, and elementNew is an ele-
                             ment in the style specified by style.  Both  ele-
                             mentOld  and  elementNew must be of the same type
                             (bitmap, text etc).  ItemDesc may refer to multi-
                             ple  items  and  column  may  refer  to  multiple
                             columns.

                     pathName item style set itemDesc ?column? ?style? ?column
                     style ...?
                             This command sets or retrieves the style assigned
                             to one or more columns.  If no column  is  speci-
                             fied,  this command returns a list containing the
                             names of the styles set for all  columns  of  the
                             item described by itemDesc.  If no style is spec-
                             ified, this command returns the name of the style
                             set for the item described by itemDesc in column.

                             If one or more column-style pairs  is  specified,
                             then the style in each column is set to style. In
                             this case itemDesc may refer  to  multiple  items
                             and each column may refer to multiple columns.

              pathName item tag option ?arg arg ...?
                     This  command  is  used to manipulate tags on items.  The
                     exact behavior of the command depends on the option argu-
                     ment  that  follows the item tag argument.  The following
                     forms of the command are supported:

                     pathName item tag add itemDesc tagList
                             Adds each tag in tagList to the  items  specified
                             by the item description itemDesc.  Duplicate tags
                             are ignored. The list of tags  for  an  item  can
                             also be changed via an item's -tags option.

                     pathName item tag expr itemDesc tagExpr
                             Evaluates  the  tag  expression  tagExpr  against
                             every item  specified  by  the  item  description
                             itemDesc.  The  result is 1 if the tag expression
                             evaluates to true for every item, 0 otherwise.

                     pathName item tag names itemDesc
                             Returns a list of tag names assigned to the items
                             specified  by  the item description itemDesc. The
                             result is the union of any tags assigned  to  the
                             items.




treectrl                       2.3                             44





treectrl(n)                Tk Commands                treectrl(n)


                     pathName item tag remove itemDesc tagList
                             Removes each tag in tagList from the items speci-
                             fied by the item description itemDesc.  It is not
                             an  error  if  any of the items do not use any of
                             the tags.  The list of tags for an item can  also
                             be changed via an item's -tags option.

              pathName item text itemDesc ?column? ?text? ?column text ...?
                     This  command  sets  or  retrieves the value of the -text
                     option for the first text element in one or more columns.
                     If no column is specified, this command returns a list of
                     values, one per column.  If no text  is  specified,  this
                     command returns the value for column.

                     If  one  or more column-text pairs is specified, then the
                     value of the -text option in each column is set to  text.
                     In  this  case  itemDesc  may refer to multiple items and
                     each column may refer to multiple columns.

                     Note that this command is provided as a convenience.  Use
                     the  item element configure or item element cget commands
                     if you want to set or retrieve the  value  of  the  -text
                     option for a specific text element.

              pathName item toggle itemDesc ?-animate? ?-recurse?
                     Changes  the  open  state  of  the  item(s)  described by
                     itemDesc.  If the open state is currently  switched  off,
                     then this command does the same as the item expand widget
                     command; otherwise the same as the item  collapse  widget
                     command.   If  -animate  is specified, then item's button
                     will animate as it  transitions  between  states  if  the
                     theme  supports  it;  in  this  case only one item may be
                     specified.  If -recurse is specified, then the open state
                     of  all  descendants  of  the items described by itemDesc
                     will also be toggled.

       pathName marquee option ?arg ...?
              This command is used to manipulate the  marquee,  which  can  be
              used  to  implement  a  resizable selection rectangle, in a file
              browser for example.  One corner point of the marquee  is  fixed
              as  long  as  the  marquee is visible and called the anchor; the
              diagonally opposite corner  is  dragged  with  the  mouse  while
              resizing the marquee and simply called the corner.

              All  coordinates  handled  by  this  widget command are treectrl
              coordinates, i.e. the canvasx or canvasy widget  command  should
              be  used  to translate any window coordinates to marquee coordi-
              nates.

              By default, the marquee is displayed as a 1-pixel  thick  dotted
              rectangle.  If either of the -fill or -outline options is speci-
              fied, then the marquee is drawn  as  a  filled  and/or  outlined
              rectangle  of  the specified color(s).  The  -fill option should
              specify a transparent gradient to avoid hiding  what  is  inside



treectrl                       2.3                             45





treectrl(n)                Tk Commands                treectrl(n)


              the marquee.  See GRADIENTS for more info.

              The exact behavior of the command depends on the option argument
              that follows the marquee argument.  The following forms  of  the
              command are supported:

              pathName marquee anchor ?x y?
                     Returns  a list containing the x and y coordinates of the
                     anchor, if no additional arguments are specified.  If two
                     coordinates  are  specified, sets the anchor to the given
                     coordinates x and y.

              pathName marquee cget option
                     This command returns the current  value  of  the  marquee
                     option  named  option.  Option may have any of the values
                     accepted by the marquee configure widget command.

              pathName marquee configure ?option? ?value? ?option value ...?
                     This command is similar to the configure  widget  command
                     except  that  it  modifies the marquee options instead of
                     modifying options for the overall treectrl widget.  If no
                     option  is specified, the command returns a list describ-
                     ing all of the available marquee options (see  Tk_Config-
                     ureInfo  for information on the format of this list).  If
                     option is specified  with  no  value,  then  the  command
                     returns  a  list  describing the one named marquee option
                     (this list will be identical to the corresponding sublist
                     of the value returned if no option is specified).  If one
                     or more option-value pairs are specified, then  the  com-
                     mand  modifies  the  given  marquee option(s) to have the
                     given value(s); in this case the command returns an empty
                     string.

                     The following marquee options are supported:

                     -fill color
                             Specifies the color to fill the marquee rectangle
                             with.  See  the  comments  above  about  using  a
                             transparent gradient here.

                     -outline color
                             Specifies  the color to outline the marquee rect-
                             angle with.

                     -outlinewidth color
                             Specifies the width of the outline  drawn  inside
                             the  marquee's  rectangle.   The  outline  is not
                             drawn if this value is less than 1.  This  option
                             has  no effect if the -outline option is unspeci-
                             fied, i.e., the default dotted rectangle is unaf-
                             fected  by  this  option.  outlineWidth may be in
                             any of  the  forms  acceptable  to  Tk_GetPixels.
                             Defaults to 1.




treectrl                       2.3                             46





treectrl(n)                Tk Commands                treectrl(n)


                     -visible boolean
                             Specifies   a   boolean  value  which  determines
                             whether the marquee is displayed.

              pathName marquee coords ?x1 y1 x2 y2?
                     Returns a list containing the x and y coordinates of  the
                     anchor followed by the x and y coordinates of the corner,
                     if no additional arguments are specified.  If four  coor-
                     dinates are specified, sets the anchor to the given coor-
                     dinates x1 and y1 and the corner to  the  coordinates  x2
                     and y2.

              pathName marquee corner ?x y?
                     Returns  a list containing the x and y coordinates of the
                     corner, if no additional arguments are specified.  If two
                     coordinates  are  specified, sets the corner to the given
                     coordinates x and y.

              pathName marquee identify
                     Returns a list with information about  any  items  inter-
                     secting the marquee.  The format of the returned list is:

                     {
                         {item {column element element ...} {column element element ...} ...}
                         {item {column element element ...} {column element element ...} ...}
                         ...
                     }

                     There may be zero sublists following an item  id  if  the
                     marquee  is in the button/line area of an item. There may
                     be zero element names following a column id if the  item-
                     column  has no style or if the marquee does not intersect
                     any elements in that column.

       pathName notify option ?arg ...?
              Many Tk widgets communicate with the outside world via  -command
              callbacks  and/or  virtual  events. For example, the Text widget
              evaluates its  -yscrollcommand  when  the  view  in  the  widget
              changes, and generates a <<Modified>> virtual event when text is
              inserted or deleted.  A treectrl widget replaces both methods of
              communication  with its own event mechanism accessed through the
              notify subcommands.

              The exact behavior of the command depends on the option argument
              that  follows  the  notify argument.  The following forms of the
              command are supported:

              pathName notify bind ?object? ?pattern? ?+??script?
                     This command associates Tcl scripts with events generated
                     by  a treectrl widget.  If all three arguments are speci-
                     fied, notify bind will arrange for script (a Tcl  script)
                     to  be  evaluated whenever the event(s) specified by pat-
                     tern are generated by this treectrl widget.  If script is
                     prefixed  with a "+", then it is appended to any existing



treectrl                       2.3                             47





treectrl(n)                Tk Commands                treectrl(n)


                     binding  for  pattern;   otherwise  script  replaces  any
                     existing  binding.  If script is an empty string then the
                     current binding for pattern is destroyed, leaving pattern
                     unbound.  In  all of the cases where a script argument is
                     provided, notify bind returns an empty string.

                     If pattern is specified without a script, then the script
                     currently  bound  to  pattern  is  returned,  or an empty
                     string is returned if there is no binding for pattern. If
                     neither  pattern nor script is specified, then the return
                     value is a list whose elements are all the  patterns  for
                     which there exist bindings for object.

                     The  object argument determines which window(s) the bind-
                     ing applies to.  If object  begins  with  a  dot,  as  in
                     .a.b.c,  then it must be the path name for a window; oth-
                     erwise it may be an arbitrary string.  Like  the  regular
                     bind  command, bindings on window names are automatically
                     removed if that window is destroyed.

              pathName notify configure object pattern ?option? ?value?
              ?option value ...?
                     This command sets and retrieves options for bindings cre-
                     ated by the notify bind command.

                     If no option is specified, the  command  returns  a  list
                     with  option-value  pairs  describing  all  the available
                     binding options for pattern  on  object.   If  option  is
                     specified  with  no  value,  then the command returns the
                     current value of that option.  If  one  or  more  option-
                     value  pairs are specified, then the command modifies the
                     given option(s) to have the given value(s) for the  bind-
                     ing; in this case the command returns an empty string.

                     The following binding options are supported:

                     -active boolean
                             Specifies  if  the  binding should be active.  As
                             long as this option  is  specified  as  false,  a
                             binding  script  will  not  be evaluated when the
                             corresponding event is generated.

              pathName notify detailnames eventName
                     Returns a list containing the names of all details, which
                     are  installed  for  the event with the name eventName by
                     means of the notify install  widget  command  or  by  the
                     treectrl widget itself.

              pathName notify eventnames
                     Returns  a list containing the names of all events, which
                     are installed by means of the notify install widget  com-
                     mand or by the treectrl widget itself.





treectrl                       2.3                             48





treectrl(n)                Tk Commands                treectrl(n)


              pathName notify generate pattern ?charMap? ?percentsCommand?
                     This  command  causes  the treectrl widget to generate an
                     event. This command is typically used to generate dynamic
                     events  created by the notify install command, but may be
                     used to generate static events also.  The event specified
                     by  pattern  is generated, and any active binding scripts
                     on the event are evaluated after  undergoing  %-substitu-
                     tion.   If  there are details defined for the event, pat-
                     tern must describe an <eventName-detail> pair,  otherwise
                     pattern should be <eventName>.

                     The  optional charMap is a list of char-value pairs as in
                     the form returned by array get.   Each  char  has  to  be
                     exactly  one character.  The charMap is used in %-substi-
                     tution.

                     If percentsCommand is specified, then it will be used  to
                     perform %-substitution on any scripts bound to the event.
                     If percentsCommand is not  specified  and  the  event  is
                     dynamic,  then the %-subtitution command passed to notify
                     install will be used if it was provided. If the event  is
                     static  or  no  %-substitution command is available, then
                     all %-substitution is done  using  charMap  only  .   See
                     notify install for a description of percentsCommand.

              pathName notify install pattern ?percentsCommand?
                     This  command installs a new event or detail specified by
                     pattern.  Events  created  by  this  command  are  called
                     dynamic,  whereas  events  created by the treectrl widget
                     itself are called static.  This command may be called  to
                     set  or  retrieve  the  percentsCommand  for  an existing
                     dynamic event.

                     The optional percentsCommand is  a  list  containing  the
                     name  of  a  Tcl command, plus any optional arguments, to
                     which five additional arguments  will  be  appended.  The
                     command  will  be called to perform %-substitution on any
                     scripts bound to the  event  specified  by  pattern  (see
                     EVENTS AND SCRIPT SUBSTITUTIONS).  PercentsCommand should
                     be defined as follows:

                     proc percentsCommand {?arg arg ...? char object event detail charMap} {
                                             switch -- $char {
                                             ...
                                             }
                                             return $value
                     }

                     The optional arg arguments are part of  the  percentsCom-
                     mand  list.   Char  is the %-character to be substituted.
                     Object is the same as the argument to notify bind.  Event
                     and  detail specify the event. CharMap is the same as the
                     argument  to  notify  generate.   PercentsCommand  should
                     return  the  value  to replace the %-character by.  If an



treectrl                       2.3                             49





treectrl(n)                Tk Commands                treectrl(n)


                     error occurs evaluating percentsCommand, the  %-character
                     is replaced by itself.

                     notify  install  returns  the current percentsCommand for
                     the event, or an error if the event is not dynamic.

              pathName notify install detail eventName detail ?percentsCom-
              mand?
                     Deprecated.  Use notify install with a pattern of <event-
                     Name-detail> instead.

              pathName notify install event eventName ?percentsCommand?
                     Deprecated.  Use notify install with a pattern of <event-
                     Name> instead.

              pathName notify linkage pattern
                     Returns  a  string indicating whether the specified event
                     or detail is created by means of the notify install  wid-
                     get  command  (dynamic)  or by the treectrl widget itself
                     (static).

              pathName notify linkage eventName ?detail?
                     Deprecated.  Use notify linkage with a pattern of <event-
                     Name> or <eventName-detail> instead.

              pathName notify unbind object ?pattern?
                     If  no  pattern  is specified, all bindings on object are
                     removed.  If pattern is specified, then the current bind-
                     ing for pattern is destroyed, leaving pattern unbound.

              pathName notify uninstall pattern
                     If  the  event  or  detail specified by pattern is static
                     (i.e. created by the treectrl widget itself), an error is
                     generated.   Otherwise  the  dynamic  event  or detail is
                     removed. If an event name is specified without a  detail,
                     all details for that event are also removed.

              pathName notify uninstall detail eventName detail
                     Deprecated.   Use  notify  uninstall  with  a  pattern of
                     <eventName-detail> instead.

              pathName notify uninstall event eventName
                     Deprecated.  Use  notify  uninstall  with  a  pattern  of
                     <eventName> instead.

       pathName numcolumns
              Deprecated. Use the column count command instead.

       pathName numitems
              Deprecated. Use the item count command instead.

       pathName orphans
              Returns  a  list containing the item ids of all items which have
              no parent.  When an  item  is  created,  it  has  no  parent  by



treectrl                       2.3                             50





treectrl(n)                Tk Commands                treectrl(n)


              default,  and  can  later  become an orphan by means of the item
              remove widget command. The root item is not returned.

       pathName range first last
              Deprecated. Use the item range command instead.

       pathName scan option args
              This command is used to implement scanning on treectrls. It  has
              two forms, depending on option:

              pathName scan mark x y
                     Records x and y and the treectrl's current view;  used in
                     conjunction with later scan  dragto  commands.  Typically
                     this  command  is associated with a mouse button press in
                     the widget and x and y are the coordinates of the  mouse.
                     It returns an empty string.

              pathName scan dragto x y ?gain?
                     This  command computes the difference between its x and y
                     arguments (which are typically mouse coordinates) and the
                     x  and  y arguments to the last scan mark command for the
                     widget. It then adjusts the view by gain times  the  dif-
                     ference  in  coordinates, where gain defaults to 10. This
                     command is typically associated with mouse motion  events
                     in  the  widget,  to  produce  the effect of dragging the
                     treectrl at high speed through its  window.   The  return
                     value is an empty string.

       pathName see itemDesc ?columnDesc? ?option value ...?
              Adjust  the  view  in the treectrl so that the item described by
              itemDesc is visible.  If the item is already  visible  then  the
              command  has  no effect; otherwise the treectrl scrolls to bring
              the item into view,  and  the  corresponding  <Scroll-x>  and/or
              <Scroll-y> events are generated. If columnDesc is specified then
              a specific column of the item is scrolled into view  instead  of
              the entire item.

              The following options are supported:

              -center flags
                     Flags is a string that contains zero or more of the char-
                     acters x or y. This option is used  to  center  the  item
                     horizontally  and/or  vertically in the window.  The item
                     will be centered regardless of whether it is already vis-
                     ible.

       pathName selection option args
              This  command is used to adjust the selection within a treectrl.
              It has several forms, depending on option:

              pathName selection add first ?last?
                     First and last (if specified) must be valid item descrip-
                     tions.  If  both  first and last are specified, then they
                     may refer to a single item only; in this case the command



treectrl                       2.3                             51





treectrl(n)                Tk Commands                treectrl(n)


                     adds every unselected item in the range between first and
                     last, inclusive, to the selection without  affecting  the
                     selected  state  of  items  outside  that range.  If only
                     first is specified, then every unselected item  specified
                     by  first is added to the selection.  A <Selection> event
                     is generated if any items were added to the selection.

              pathName selection anchor ?itemDesc?
                     If itemDesc is specified, the selection anchor is set  to
                     the  described  item.  The selection anchor is the end of
                     the selection that is fixed while dragging out  a  selec-
                     tion  with the mouse.  The item description anchor may be
                     used to refer to the anchor item.  This  command  doesn't
                     modify  the  selection  state  of  any item.  Returns the
                     unique id of the selection anchor item.

              pathName selection clear ?first? ?last?
                     First and last (if specified) must be valid item descrip-
                     tions.  If  both  first and last are specified, then they
                     may refer to  a  single  item  only;  in  this  case  any
                     selected  items  between  first  and last (inclusive) are
                     removed from the selection without affecting the selected
                     state  of  items  outside  that  range.  If only first is
                     specified, then every selected item specified by first is
                     removed  from  the  selection.  If neither first nor last
                     are specified, then all selected items are  removed  from
                     the  selection.   A <Selection> event is generated if any
                     items were removed from the selection.

              pathName selection count
                     Returns an integer indicating the number of items in  the
                     treectrl that are currently selected.

              pathName selection get ?first? ?last?
                     When  no additional arguments are given, the result is an
                     unsorted list containing the item ids of all of the items
                     in  the  treectrl  that are currently selected.  If there
                     are no items selected in  the  treectrl,  then  an  empty
                     string  is  returned.   The  optional arguments first and
                     last are treated as  indices  into  the  sorted  list  of
                     selected items; these arguments allow in-place lindex and
                     lrange operations on the selection. For example:



              pathName selection includes itemDesc
                     Returns 1 if the item described by itemDesc is  currently
                     selected, 0 if it isn't.

              pathName selection modify select deselect
                     Both  arguments  select and deselect are a possibly-empty
                     list of  item  descriptions.   Any  unselected  items  in
                     select are added to the selection, and any selected items
                     in deselect are removed from the  selection  (except  for



treectrl                       2.3                             52





treectrl(n)                Tk Commands                treectrl(n)


                     those  items  which  are  also in select).  A <Selection>
                     event is generated if any items were  selected  or  dese-
                     lected.

       pathName state option args
              This  command  is  used  to  manipulate the list of user-defined
              states, see section STATES below.  The  exact  behavior  of  the
              command  depends  on  the option argument that follows the state
              argument.  The following forms of the command are supported:

              pathName state define stateName
                     Defines a new state with the name stateName,  which  must
                     not be the name of an existing state.

              pathName state linkage stateName
                     Returns  a  string indicating whether the specified state
                     is user-defined by means of the state define widget  com-
                     mand  (dynamic)  or  predefined  by  the  treectrl widget
                     itself (static).

              pathName state names
                     Returns a list containing the names of  all  user-defined
                     states.

              pathName state undefine ?stateName ...?
                     Every stateName must be the name of a user-defined state.
                     Removes this state from the list of user-defined  states.

       pathName style option ?element? ?arg arg ...?
              This  command is used to manipulate styles, which can be thought
              of as a geometry manager for elements.  The  exact  behavior  of
              the  command  depends  on  the  option argument that follows the
              style argument.  The following forms of  the  command  are  sup-
              ported:

              pathName style cget style option
                     This  command  returns  the  current  value of the option
                     named option associated with the style  given  by  style.
                     Option  may  have any of the values accepted by the style
                     configure widget command.

              pathName style configure style ?option? ?value? ?option value
              ...?
                     This  command  is similar to the configure widget command
                     except that it modifies options associated with the style
                     given by style instead of modifying options for the over-
                     all treectrl widget.  If no option is specified, the com-
                     mand  returns  a  list  describing  all  of the available
                     options for style (see Tk_ConfigureInfo  for  information
                     on the format of this list).  If option is specified with
                     no value, then the command returns a list describing  the
                     one named option (this list will be identical to the cor-
                     responding sublist of the value returned if no option  is
                     specified).   If  one  or  more  option-value  pairs  are



treectrl                       2.3                             53





treectrl(n)                Tk Commands                treectrl(n)


                     specified, then the command modifies the given  option(s)
                     to  have  the  given  value(s) in style; in this case the
                     command returns an empty string.

                     The options of a style have effect on all  elements  man-
                     aged by the style.  The following options are supported:

                     -orient varName
                             This option specifies which orientation should be
                             used when laying out the elements associated with
                             this  style.   Must  be  either  horizontal  (the
                             default) or vertical or an abbreviation of one of
                             these.

              pathName style create style ?option value ...?
                     Create  a  new  style in pathName with name style.  After
                     style there may be any number of option-value pairs, each
                     of  which  sets  one of the configuration options for the
                     style.  These same option-value  pairs  may  be  used  in
                     style  configure  widget  commands  to change the style's
                     configuration.  Returns the name of the new style.

              pathName style delete ?style ...?
                     Deletes each of the named styles  and  returns  an  empty
                     string.   If a style is deleted while it is still used to
                     display one or more items, it is also  removed  from  the
                     style list of these items.

              pathName style elements style ?elementList?
                     Specifies  the elements which should be layed out by this
                     style.  Each element of elementList must be the  name  of
                     an  element created by the widget command element create.
                     Duplicate names in elementList are ignored.   An  element
                     which  was specified in a former call of this command for
                     style but is not included in elementList, will be deleted
                     from the elements layed out by style.

                     If  the  elementList argument is not specified, a list is
                     returned containing the  currently  defined  elements  of
                     style.

              pathName style layout style element ?option? ?value? ?option
              value ...?
                     This command is similar to the configure  widget  command
                     except  that it modifies options used by style for laying
                     out element instead of modifying options for the  overall
                     treectrl  widget.  If no option is specified, the command
                     returns a list with option-value pairs describing all  of
                     the available options for the layout.  If option is spec-
                     ified with no value, then the command returns  the  value
                     of  the  named option.  If one or more option-value pairs
                     are  specified,  then  the  command  modifies  the  given
                     option(s)  to  have the given value(s) for the layout; in
                     this case the command returns an empty string.



treectrl                       2.3                             54





treectrl(n)                Tk Commands                treectrl(n)


                     The options of a layout have effect on  exactly  the  one
                     element  element managed by style.  The following options
                     are supported:

                     -detach boolean
                             Specifies whether the  element  should  be  posi-
                             tioned by itself, i.e. independent from the other
                             elements.

                     -draw boolean
                             This  is  a  per-state  option  that   determines
                             whether  an element should be drawn. If the value
                             of the option evaluates to false for a given item
                             state, then the element is not drawn, although it
                             still consumes space in the layout.

                     -expand flags
                             This option allows the  external  padding  around
                             the  element  to  increase  when a style has more
                             screen space than it needs.  Flags  is  a  string
                             that  contains  zero or more of the characters n,
                             s, w or e.  Each letter refers to the padding  on
                             the  top,  bottom,  left, or right that should be
                             allowed to increase.  This  option  is  typically
                             used to justify an element.

                     -iexpand flags
                             This  option  allows  the internal padding of the
                             element and the display area of  the  element  to
                             increase  when a style has more screen space than
                             it needs.  Flags  is a string that contains  zero
                             or  more  of  the  characters x, y, n, s, w or e.
                             For n, s, w and e,  each  letter  refers  to  the
                             padding  on  the top, bottom, left, or right that
                             should be allowed to increase.  For x and y, each
                             letter  refers  to  the  horizontal  and vertical
                             screen space the element can  display  itself  in
                             (i.e.,  the space between the padding). Note that
                             if the -union option is specified for  this  ele-
                             ment,  then  the  x  and  y flags have no effect,
                             since the size of an element with  -union  layout
                             is determined by the elements it surrounds.

                     -indent boolean
                             Specifies  whether  the  element  should be posi-
                             tioned to the right of the  button/line  area  in
                             the  tree  column.  This option is ignored unless
                             the -detach option is true.

                     -ipadx amount

                     -ipady amount
                             Amount specifies how  much  internal  padding  to
                             leave  on  the left and right (for -ipadx) or top



treectrl                       2.3                             55





treectrl(n)                Tk Commands                treectrl(n)


                             and bottom (for  -ipady)  side  of  the  element.
                             Amount  may  be  a  list of two values to specify
                             padding for the two sides separately, it defaults
                             to 0.

                     -minheight pixels

                     -height pixels

                     -maxheight pixels
                             Specifies  the minimum, fixed, and maximum height
                             of the element.

                     -minwidth pixels

                     -width pixels

                     -maxwidth pixels
                             Specifies the minimum, fixed, and  maximum  width
                             of the element.

                     -padx amount

                     -pady amount
                             Amount  specifies  how  much  external padding to
                             leave on the left and right (for  -padx)  or  top
                             and  bottom  (for  -pady)  side  of  the element.
                             Amount may be a list of  two  values  to  specify
                             padding for the two sides separately, it defaults
                             to 0.

                     -squeeze flags
                             This option allows the display area of an element
                             to  decrease  when a style has less space than it
                             needs.  Flags is a string that contains  zero  or
                             more  of the characters x or y.  x allows display
                             area to decrease horizontally, y  allows  display
                             area to decrease vertically.  This option is typ-
                             ically used for text elements and will cause  the
                             text  element to display an ellipsis (...) and/or
                             wrap lines.

                     -sticky flags
                             This  option  controls  how  the  actual  display
                             information  (image,  text, etc) of an element is
                             positioned  (or  stretched)  within  its  display
                             area.   Flags  is  a string that contains zero or
                             more of the characters n, s, w or e. Each  letter
                             refers  to the top, bottom, left or right side of
                             the display area  that  the  display  information
                             should "stick" to.

                     -union elementList
                             Specifies  a  list  of  other elements which this



treectrl                       2.3                             56





treectrl(n)                Tk Commands                treectrl(n)


                             element will surround.  The size  of  an  element
                             with  -union layout is determined by the size and
                             position of the  elements  in  elementList.   The
                             -ipadx  and  -ipady options in this case refer to
                             the distance of the edges of the display area  of
                             this  element  from  those elements it surrounds.
                             This option is typically used to display a selec-
                             tion rectangle around a piece of text. If none of
                             the elements in elementList are visible, then the
                             element is not displayed.

                     -visible boolean
                             This is a per-state option that controls visibil-
                             ity of an element. If the  value  of  the  option
                             evaluates  to  false for a given item state, then
                             the element is  not  displayed  and  consumes  no
                             space in the layout.

              pathName style names
                     Returns  a  list  containing  the  names  of all existing
                     styles.

       pathName theme option ?arg ...?
              This command is used  to  interact  with  the  platform-specific
              theme.   The exact behavior of the command depends on the option
              argument that follows the theme argument.  The  following  forms
              of the command are supported:

              pathName theme platform
                     Returns  the  API used to draw themed parts of the treec-
                     trl.  On Mac OS X the result is always aqua.  On MS  Win-
                     dows  the  result  is visualstyles if the uxtheme.dll was
                     loaded and visual themes are in  use,  otherwise  X11  is
                     returned  to  indicate  the Tk Xlib calls are drawing the
                     themed parts.  On Unix systems the result is gtk  if  the
                     Gtk+  version  of  treectrl  was  built, otherwise X11 is
                     returned.

              pathName theme setwindowtheme appname
                     The command is available on MS Windows only.  If  appname
                     is  "Explorer"  then  the item buttons look like those in
                     the Explorer file  browser  (disclosure  triangles  under
                     Windows Vista/7).  If appname is an empty string then the
                     buttons revert to their default appearance  according  to
                     the system's current visual style.

       pathName toggle ?-recurse? ?itemDesc ...?
              Use item toggle instead.

       pathName xview ?args?
              This command is used to query and change the horizontal position
              of the information displayed in the treectrl's window.   It  can
              take any of the following forms:




treectrl                       2.3                             57





treectrl(n)                Tk Commands                treectrl(n)


              pathName xview
                     Returns  a list containing two elements.  Each element is
                     a real fraction between 0 and 1;  together they  describe
                     the  horizontal  span that is visible in the window.  For
                     example, if the first element is .2 and the  second  ele-
                     ment  is  .6, 20% of the tree's area is off-screen to the
                     left, the middle 40% is visible in the window, and 40% of
                     the  tree is off-screen to the right.  These are the same
                     values  passed  to  scrollbars  via  the  -xscrollcommand
                     option.

              pathName xview moveto fraction
                     Adjusts  the  view  in the window so that fraction of the
                     total width of the tree is off-screen to the left.  Frac-
                     tion  must  be  a fraction between 0 and 1.  A <Scroll-x>
                     event is generated.

              pathName xview scroll number what
                     This command shifts the view in the window left or  right
                     according to number and what.  Number must be an integer.
                     What must be either units or pages or an abbreviation  of
                     one of these.  If what is units, the view adjusts left or
                     right in units determined by the -xscrollincrement option
                     (which  may be zero, see the description of that option).
                     If what is pages then the view adjusts in units of  nine-
                     tenths  the  window's  width.  If number is negative then
                     information farther to the left becomes visible;   if  it
                     is positive then information farther to the right becomes
                     visible.  A <Scroll-x> event is generated.

       pathName yview ?args?
              This command is used to query and change the  vertical  position
              of  the  information displayed in the treectrl's window.  It can
              take any of the following forms:

              pathName yview
                     Returns a list containing two elements.  Each element  is
                     a  real fraction between 0 and 1;  together they describe
                     the vertical span that is visible  in  the  window.   For
                     example,  if  the first element is .6 and the second ele-
                     ment is 1.0, the lowest 40% of the tree's area is visible
                     in  the  window.   These  are  the  same values passed to
                     scrollbars via the -yscrollcommand option.

              pathName yview moveto fraction
                     Adjusts the view in the window so that  fraction  of  the
                     tree's  area  is  off-screen  to  the top.  Fraction is a
                     fraction between 0 and 1.  A <Scroll-y> event  is  gener-
                     ated.

              pathName yview scroll number what
                     This  command  adjusts  the view in the window up or down
                     according to number and what.  Number must be an integer.
                     What  must  be  either units or pages.  If what is units,



treectrl                       2.3                             58





treectrl(n)                Tk Commands                treectrl(n)


                     the  view  adjusts  up  or   down   in   units   of   the
                     -yscrollincrement  option  (which  may  be  zero, see the
                     description of that option).  If what is pages  then  the
                     view adjusts in units of nine-tenths the window's height.
                     If number is negative  then  higher  information  becomes
                     visible;   if  it  is  positive  then  lower  information
                     becomes visible.  A <Scroll-y> event is generated.


COLUMNS
       A treectrl widget is capable of displaying  multiple  columns  next  to
       each other.  An item can be considered as a row, which reaches over all
       columns.

       Columns in a treectrl may be specified in a number of ways.  See COLUMN
       DESCRIPTION below.

       There  is  always  one special column, the tail column, which fills all
       space to the right of the last ordinary column.   This  column  has  no
       number; it can only be specified by the keyword tail.

       When a column configuration option is specified as per-state, the state
       names are normal, active, pressed or up, i.e.  do not  use  item  state
       names.

       The following options are supported for columns:

       -arrow direction
              Indicates  whether or not an arrow should be drawn in the column
              header.  Direction  must  have  one  of  the  values  none  (the
              default), up, or down.

       -arrowbitmap bitmap
              Specifies  as  a  per-state option the bitmap to use to draw the
              arrow if this column's -arrow option is not none.

       -arrowimage image
              Specifies as a per-state option the image to  use  to  draw  the
              arrow  if  this column's -arrow option is not none.  If an image
              is specified for a certain state, it overrides the  -arrowbitmap
              option.

       -arrowside side
              Indicates  on  which  side  of  the  bitmap/image/text the arrow
              should be drawn.   Side  must  be  either  left  or  right  (the
              default).

       -arrowgravity side
              Indicates onto which side an arrow should be packed, if there is
              more space available for drawing the arrow  then  needed.   Side
              must be either left (the default) or right.

       -arrowpadx amount
              Amount specifies how much padding to leave on the left and right



treectrl                       2.3                             59





treectrl(n)                Tk Commands                treectrl(n)


              of the arrow.  Amount may be a list of  two  values  to  specify
              padding for left and right separately; it defaults to 6.

       -arrowpady amount
              Amount specifies how much padding to leave on the top and bottom
              of the arrow.  Amount may be a list of  two  values  to  specify
              padding for top and bottom separately; it defaults to 0.

       -bitmap bitmap
              Specifies  the  bitmap  to display in the element to the left of
              the column title.

       -background color
              Specifies as a per-state option the color to use for  the  back-
              ground of the column header.

       -borderwidth size
              Specifies  a  non-negative value indicating the width of the 3-D
              border to draw around the outside of the column header (if  such
              a  border  is being drawn;  the -relief column option determines
              this).  The value may  have  any  of  the  forms  acceptable  to
              Tk_GetPixels.

       -button boolean
              Indicates  whether  or  not  the column header should be treated
              like a pushbutton.  When this option is true, the default  bind-
              ings  track  <Button-1>  events  in  the  header  and generate a
              <Header-invoke> event when a <ButtonRelease-1> event  occurs  in
              the header. See DYNAMIC EVENTS.

       -expand boolean
              Indicates  whether  or  not any extra horizontal space should be
              distributed to this column.  This option has no  effect  if  the
              -width option is set.

       -font fontName
              Specifies the font to use for the column title inside the column
              header.

       -image image
              Specifies the image to display in the element to the left of the
              column  title.  This option overrides the -bitmap column option.

       -imagepadx amount
              Amount specifies how much padding to leave on the left and right
              of the image (or bitmap).  Amount may be a list of two values to
              specify padding for left and right separately; it defaults to 6.

       -imagepady amount
              Amount specifies how much padding to leave on the top and bottom
              of the image (or bitmap).  Amount may be a list of two values to
              specify padding for top and bottom separately; it defaults to 0.





treectrl                       2.3                             60





treectrl(n)                Tk Commands                treectrl(n)


       -itembackground colorList
              Specifies a list of zero or  more  colors,  which  are  used  as
              alternating  background  colors  for  items in this column.  See
              also the -backgroundmode widget option for more on this.

       -itemjustify justification
              This option determines how the item styles in this  column  line
              up  with each other.  Must be one of left, center, or right. The
              default value is an empty string (for compatibility  with  older
              versions),  in  which case the column option -justify is used to
              align item styles in this column.

       -itemstyle style
              Style is the name of a style that should be set in  this  column
              for newly-created items.

       -justify justification
              This  option  determines  how  the  image and text in the column
              header are positioned. It also  affects  the  position  of  item
              styles  in  this column unless the column option -itemjustify is
              specified.  Must be one of left (the default), center, or right.

       -lock lock
              This  option  allows a column to stick to the left or right edge
              of the window.  A locked column scrolls vertically but not hori-
              zontally.  Must be one of none (the default), left, or right.

       -maxwidth size
              Specifies  the  maximum size, in screen units, that will be per-
              mitted for this column.  If size is an empty string, then  there
              is  no limit on the maximum size of the column.  This option has
              no effect if the -width option is set.

       -minwidth size
              Specifies the minimum size, in screen units, that will  be  per-
              mitted  for  this  column.  If size is an empty string, then the
              minimum size of the column is zero.  This option has  no  effect
              if the -width option is set.

       -resize boolean
              Specifies a boolean value that indicates whether the user should
              be allowed to resize the column by dragging the edge of the col-
              umn's header. Default is true.

       -squeeze boolean
              Specifies a boolean value that indicates whether or not the col-
              umn should shrink when the content width of the treectrl is less
              than  the total needed width of all visible columns. Defaults to
              false, which means the column will  not  get  smaller  than  its
              needed  width. The column will not get smaller than the value of
              its -minwidth option, if specified. This option has no effect if
              the -width option is set.





treectrl                       2.3                             61





treectrl(n)                Tk Commands                treectrl(n)


       -state state
              Specifies  one  of  three  states for the column header: normal,
              active, or pressed. The active state is used when the  mouse  is
              over  the header.  The pressed state is used when the mouse but-
              ton is pressed in the header.

       -stepwidth size
              Deprecated.  Use  the   treectrl's   -itemwidthmultiple   option
              instead.

       -tags tagList
              TagList  is a list of tag names that can be used to identify the
              column.  See also the column tag command.

       -text text
              Specifies a text string to be displayed as the column title.

       -textcolor color
              Specifies as a per-state option the color to display the  column
              title  with.   When the value of this option is unspecified, the
              title will be drawn according to the system theme, if any,  oth-
              erwise  the  Tk button foreground color (usually black) is used.
              The default is unspecified.

       -textlines count
              Specifies the maximum number of lines of text to display in  the
              column  title.   If this value is zero, the number of lines dis-
              played is determined by any newline characters and  the  effects
              of  wrapping  when  the  column  width  is less than needed. The
              default is 1. Note: Under OSX/Aqua this value is always set to 1
              when  the  treectrl's  -usetheme  option  is  true,  because the
              Appearance Manager uses a fixed height for  the  column  header;
              there is only room for a single line of text.

       -textpadx amount
              Amount specifies how much padding to leave on the left and right
              of the text.  Amount may be a list  of  two  values  to  specify
              padding for left and right separately; it defaults to 6.

       -textpady amount
              Amount specifies how much padding to leave on the top and bottom
              of the text.  Amount may be a list  of  two  values  to  specify
              padding for top and bottom separately; it defaults to 0.

       -uniform group
              When  a non-empty value is supplied, this option places the col-
              umn in a uniform group with other columns  that  have  the  same
              value for -uniform. The space for columns belonging to a uniform
              group is allocated so that their sizes are always in strict pro-
              portion  to  their  -weight values.  This option is based on the
              grid geometry manager.

       -visible boolean
              Indicates whether or not the column should be displayed.



treectrl                       2.3                             62





treectrl(n)                Tk Commands                treectrl(n)


       -weight integer
              Sets the relative weight for apportioning any extra space  among
              columns.   A  weight  of  zero (0) indicates the column will not
              deviate from its requested size.  A column whose weight  is  two
              will grow at twice the rate as a column of weight one when extra
              space is allocated to columns.  This option is based on the grid
              geometry manager.

       -width size
              Specifies  a  fixed  width  for  the column. If this value is an
              empty string, then the column width is calculated as the maximum
              of:  a)  the width requested by items; b) the width requested by
              the column's header; and c) the column's -minwidth option.  This
              calculated  width  is  also  affected  by the -expand, -squeeze,
              -uniform and -weight options. In any case, the calculated  width
              will not be greater than the -maxwidth option, if specified.

       -widthhack boolean
              Deprecated. Use the treectrl's -itemwidthequal option instead.


COLUMN DESCRIPTION
       Many  of  the commands and options for a treectrl take as an argument a
       description of which column to operate on.  See  the  EXAMPLES  section
       for examples.  The initial part of a column description must begin with
       one of the following terms:

       id     Specifies the unique column identifier, where id should  be  the
              return  value  of  a prior call of the column create widget com-
              mand.  See also the -columnprefix option.

       QUALIFIERS
              Specifies a list of qualifiers. This gives the  same  result  as
              all  followed  by QUALIFIERS; i.e., every column is tested for a
              match.

       tagExpr QUALIFIERS
              TagExpr is a tag expression (see ITEM AND COLUMN  TAGS)  against
              which  every column's tags are tested for a match.  This keyword
              cannot be followed by any modifiers unless a  single  column  is
              matched. You may run into trouble if tagExpr looks like a column
              id or other keyword; also, tagExpr must look like a single  list
              element  since column descriptions are properly-formed lists. To
              be safe you may want to use the tag qualifier followed  by  tag-
              Expr.

       all QUALIFIERS
              Indicates every column, including the tail column if the command
              allows it, which match QUALIFIERS.

       first QUALIFIERS
              Indicates the leftmost column  of  the  treectrl  which  matches
              QUALIFIERS.




treectrl                       2.3                             63





treectrl(n)                Tk Commands                treectrl(n)


       end QUALIFIERS

       last QUALIFIERS
              Indicates the rightmost column of the treectrl (but not the tail
              column) which matches QUALIFIERS.

       list columnDescs
              ColumnDescs is a list (a single argument, i.e. "list  {a  b  c}"
              not  "list  a  b c") of other column descriptions.  This keyword
              cannot be followed by any modifiers unless a  single  column  is
              matched.

       order n QUALIFIERS
              Indicates  the  nth column in the list of columns as returned by
              the column order command.

       range first last QUALIFIERS
              First and last specify a range of columns.  This keyword  cannot
              be  followed  by  any modifiers unless a single column is speci-
              fied.

       tail   Indicates the ever-present tail column of the treectrl.

       tree   Indicates the column specified by the -treecolumn option of  the
              treectrl.


       The  initial part of the column description (matching any of the values
       above) may be followed by one or more modifiers.   A  modifier  changes
       the  column  used relative to the description up to this point.  It may
       be specified in any of the following forms:

       next QUALIFIERS
              Use the column to the right matching QUALIFIERS.

       prev QUALIFIERS
              Use the column to the left matching QUALIFIERS.

       The word QUALIFIERS above represents a sequence of zero or more of  the
       following terms that changes which column is chosen:

       state stateList
              StateList  is  a  list of column state names.  Only columns that
              have the given states set (or unset if the '!' prefix  is  used)
              are considered.

       tag tagExpr
              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
              which a column's tags are tested for a match.

       !tail  When this qualifier is given, the tail column is not matched.

       visible
              When this qualifier is given, only columns whose -visible option



treectrl                       2.3                             64





treectrl(n)                Tk Commands                treectrl(n)


              is TRUE are considered.

       !visible
              When this qualifier is given, only columns whose -visible option
              is FALSE are considered.


STATES
       For every item a set of boolean states is managed. These states play an
       integral role in the appearance of each item.  The following states are
       predefined for every item:

       active At all times this state is set for exactly one item. The  active
              item is used with keyboard navigation.  When the treectrl widget
              is created or when the active item is  deleted,  the  root  item
              will  become  the  active  item.   This state can be modified by
              means of the widget command activate.

       enabled
              This state is set for every item when it is  created.   Disabled
              items cannot be selected and are ignored by the default bindings
              when navigating via the keyboard.  This state can be modified by
              means of the widget command item enabled.

       focus  This  state  is  set for every item, if the treectrl widget cur-
              rently has the focus.  It cannot be modified by means of a  wid-
              get  command, but is maintained in reaction to the <FocusIn> and
              <FocusOut> events.

       open   If this state is switched on, the descendants of  the  item  are
              displayed  -  the  item  is expanded.  If this state is switched
              off, the descendants of the item are not displayed - the item is
              collapsed.  For a new item this state is switched on by default.
              This state can be modified by means of the widget commands  item
              expand, item collapse, or item toggle.

       selected
              This  state is set for every item included in the selection.  It
              can be modified by means of the widget command selection.


       By means of the state define widget command up to 27 additional  states
       can be defined.

PER-STATE OPTIONS
       The  visual appearance of an item can change depending on the state the
       item is in, such as being the active item, being included in the selec-
       tion,  being  collapsed,  or some combination of those or other states.
       When a configuration option is described as  per-state,  it  means  the
       option  describes  a  value  which varies depending on the state of the
       item. If a per-state option is specified as a single value,  the  value
       is  used  for all states. Otherwise the per-state option must be speci-
       fied as an even-numbered list. For example, to use the font  "Times  12
       bold" in a text element regardless of the item state you can write:



treectrl                       2.3                             65





treectrl(n)                Tk Commands                treectrl(n)


       $T element configure MyTextElement -font {{Times 12 bold}}

       However,  to  use  a different font when the item is selected you could
       write:

       $T element configure MyTextElement -font {{Courier 10} selected {Times 12 bold} {}}

       In the example above, the -font option  reads  "value  stateList  value
       stateList".  If stateList is an empty list, the preceding value is used
       regardless of the item state. A non-empty stateList specifies a list of
       states  which  must  be  set for the item in order to use the preceding
       value. Each stateList can also include state  names  preceded  by  a  !
       sign, indicating the state must *not* be set for the item. For example:

       $T element configure MyRectElement -fill {blue {selected focus} gray {selected !focus}}

       In the example above, the rect element is filled  with  blue  when  the
       treectrl  has  the focus and the item is selected. If the treectrl does
       not have the focus, the example specifies that gray should be used  for
       selected items. Also note that if the item is not selected, no color is
       specified for the -fill option.

       Each value-stateList pair is checked in order from left to  right.  The
       value associated with the first stateList that matches the current item
       state is used. So stateLists should be  listed  from  most-specific  to
       least-specific.

       $T element configure MyRectElement -fill {gray {selected} blue {selected focus}}

       Written  this way, gray will always be used for selected items since it
       appears first, and blue will never be used for selected  items  regard-
       less of the focus.

       A  value  followed by an empty stateList should always be last since it
       will be chosen regardless of the item's state.

ELEMENTS
       Elements are the smallest building blocks which are handled by a treec-
       trl  widget.  One or more elements together can be combined to a style,
       which can be considered as a blueprint for an item.  An element can  be
       of  type bitmap, border, image, rect, text or window.  For each element
       type there is a section below describing the options which  can  modify
       an element of that type.

       All  of  the element configuration options described below are unspeci-
       fied by default, meaning that no value whatsoever has been given to the
       option.   It  may  seem  strange  to you that a boolean option would be
       unspecified instead of simply "true" or "false". The reason for this is
       that when an element displayed by an item has no value specified for an
       option, the element refers to the master element created by the element
       create command for a value for that option. This allows items which are
       displaying a certain element to be redisplayed  when  the  master  ele-
       ment's  options change.  The item element configure command can be used
       to override the master element's configuration options for  a  specific



treectrl                       2.3                             66





treectrl(n)                Tk Commands                treectrl(n)


       item.

BITMAP ELEMENT
       An  element  of type bitmap can be used to display a bitmap in an item.
       The following options are supported for bitmap elements:

       -background color
              Specifies as a per-state option the color to use for each of the
              bitmap's '0' valued pixels.  If the value for a certain state is
              an empty string (the default), the bitmap is drawn  transparent.

       -bitmap bitmap
              Specifies  as  a  per-state  option the bitmap to display in the
              element.

       -draw boolean
              Deprecated; use the style layout option -draw  instead.   Speci-
              fies  as  a per-state option whether to draw the element. If the
              value for a certain state is an empty string (the  default),  it
              is treated as true and the element will be drawn.

       -foreground color
              Specifies as a per-state option the color to use for each of the
              bitmap's '1' valued pixels.  If the value for a certain state is
              an  empty string (the default), the bitmap's foreground color is
              black.


BORDER ELEMENT
       An element of type border can be used to display  a  3D  border  in  an
       item.  The following options are supported for border elements:

       -background color
              Specifies  as  a per-state option the color to use for the back-
              ground of the border.  If the value for a certain  state  is  an
              empty string (the default), the element will not be drawn.

       -draw boolean
              Deprecated;  use  the style layout option -draw instead.  Speci-
              fies as a per-state option whether to draw the element.  If  the
              value  for  a certain state is an empty string (the default), it
              is treated as true and the element will be drawn.

       -filled boolean
              Specifies whether the interior of the border  should  be  filled
              with  the  background  color. If this option is unspecified (the
              default), it it treated as false which means that only the edges
              of the border will be drawn.

       -height size
              Specifies the height of the border. If this value is unspecified
              (the default), the border will be exactly as tall as its display
              area as determined by the style layout options.




treectrl                       2.3                             67





treectrl(n)                Tk Commands                treectrl(n)


       -relief relief
              Specifies as a per-state option the relief of the border. If the
              value for a certain state is an empty string (the  default),  it
              is  treated  as flat.  For acceptable values see the description
              of the -relief option in the options manual page.

       -thickness thickness
              Specifies the thickness of the edges of the border.

       -width size
              Specifies the width of the border. If this value is  unspecified
              (the default), the border will be exactly as wide as its display
              area as determined by the style layout options.


IMAGE ELEMENT
       An element of type image can be used to display an image  in  an  item.
       The following options are supported for image elements:

       -draw boolean
              Deprecated;  use  the style layout option -draw instead.  Speci-
              fies as a per-state option whether to draw the element.  If  the
              value  for  a certain state is an empty string (the default), it
              is treated as true and the element will be drawn.

       -height size
              Specifies the requested height of the display area for this ele-
              ment.   If  unspecified  (the  default),  the element requests a
              height equal to the height of the image, or zero if there is  no
              image.

       -image image
              Specifies as a per-state option the image to display in the ele-
              ment.

       -width size
              Specifies the requested width of the display area for this  ele-
              ment.   If  unspecified  (the  default),  the element requests a
              width equal to the width of the image, or zero if  there  is  no
              image.


RECTANGLE ELEMENT
       An  element of type rect can be used to display a rectangle in an item.
       The following options are supported for rectangle elements:

       -draw boolean
              Deprecated; use the style layout option -draw  instead.   Speci-
              fies  as  a per-state option whether to draw the element. If the
              value for a certain state is an empty string (the  default),  it
              is treated as true and the element will be drawn.

       -fill color
              Specifies as a per-state option the color to be used to fill the



treectrl                       2.3                             68





treectrl(n)                Tk Commands                treectrl(n)


              rectangle's area.  If the color for a certain state is an  empty
              string (the default), then the rectangle will not be filled (but
              the outline may still be drawn).

       -height size
              Specifies the height of the rectangle. If this value is unspeci-
              fied (the default), the rectangle will be exactly as tall as its
              display area as determined by the style layout options.

       -open open
              This option may be used to get an incomplete drawing of the out-
              line.   Open is a string that contains zero or more of the char-
              acters n, s, e or w.  Each  letter  refers  to  a  side  (north,
              south,  east,  or west) that the outline will not be drawn.  The
              default is the empty string, which  causes  the  outline  to  be
              drawn completely.

       -outline color
              Specifies as a per-state option the color to be used to draw the
              outline of the rectangle.  If the color for a certain  state  is
              an  empty string (the default), then no outline is drawn for the
              rectangle.

       -outlinewidth outlineWidth
              Specifies the width of the outline to be drawn around the  rect-
              angle's region.  outlineWidth may be in any of the forms accept-
              able to Tk_GetPixels.  If this option is specified as  an  empty
              string (the default), then no outline is drawn.

       -rx radius

       -ry radius
              Specifies the x and y radius of each corner of a rounded rectan-
              gle in any of the forms acceptable to Tk_GetPixels.

       -showfocus boolean
              Specifies a boolean value  indicating  whether  a  "focus  ring"
              should be drawn around the rectangle, if the item containing the
              rectangle is the active item and the treectrl  widget  currently
              has  the  focus.  If this option is specified as an empty string
              (the default), then a focus rectangle is not drawn.

       -width size
              Specifies the width of the rectangle. If this value is  unspeci-
              fied (the default), the rectangle will be exactly as wide as its
              display area as determined by the style layout options.


TEXT ELEMENT
       An element of type text can be used to display a text in an item.   The
       following options are supported for text elements:

       -draw boolean
              Deprecated;   use   the   style  layout  option  -draw  instead.



treectrl                       2.3                             69





treectrl(n)                Tk Commands                treectrl(n)


              Specifies as a per-state option whether to draw the element.  If
              the  value for a certain state is an empty string (the default),
              it is treated as true and the element will be drawn.

       -data data
              Specifies a value that together with the -datatype  and  -format
              options will be displayed as text.

       -datatype dataType
              Specifies  the type of information in the -data option.  Accept-
              able values are double, integer, long, string, or time.

       -fill color
              Specifies as a per-state option the foreground color to use when
              displaying  the  text.   If  the color for a certain state is an
              empty string (the default), then  the  text  will  be  displayed
              using  the color specified by the treectrl's -foreground option.

       -format formatString
              This option specifies the format  string  used  to  display  the
              value  of  the -data option.  If -datatype is time, formatString
              should be a valid format string for the Tcl clock command.   For
              all other -datatype values formatString should be a valid format
              string for the Tcl format command.  If this value is unspecified
              the  following defaults are used: for -datatype double "%g", for
              -datatype integer "%d", for -datatype long "%ld", for  -datatype
              string "%s", and for -datatype time the default format string of
              the Tcl clock command.

       -font font
              Specifies as a per-state option the font to use when  displaying
              the  text.   If the font for a certain state is an empty string,
              the text is displayed using the font specified by the treectrl's
              -font option.

       -justify how
              Specifies  how  to justify the text when multiple lines are dis-
              played.  How must be one of the values left, right,  or  center.
              If  this  option  is specified as an empty string (the default),
              left is used.

       -lines lineCount
              Specifies the maximum number of lines to display.  If more  than
              lineCount  lines would be displayed, the last line will be trun-
              cated with an ellipsis at the right.  If this option  is  speci-
              fied as zero or an empty string (the default), there is no limit
              to the number of lines displayed.

       -lmargin1 pixels
              Pixels is a screen distance that specifies how much  a  line  of
              text  should  be indented.  If a line of text wraps, this option
              only applies to the first line on  the  display;  the  -lmargin2
              option  controls  the indentation for subsequent lines.  If this
              option is specified as zero or an empty  string  (the  default),



treectrl                       2.3                             70





treectrl(n)                Tk Commands                treectrl(n)


              then  the line is not indented.  This option was based on the Tk
              Text widget tag option of the same name.

       -lmargin2 pixels
              Pixels is a screen distance that specifies how much  a  line  of
              text  should  be indented.  If a line of text wraps, this option
              only applies to the second and later display lines for a line of
              text.   If  this  option is specified as zero or an empty string
              (the default), then the line is not indented.  This  option  was
              based on the Tk Text widget tag option of the same name.

       -text string
              String  specifies  a  string  to  be  displayed  by the element.
              String may contain newline characters  in  which  case  multiple
              lines  of  text will be displayed.  If this option is specified,
              the -data, -datatype, -format,  and  -textvariable  options  are
              ignored.

       -textvariable varName
              Specifies  the name of a variable.  The value of the variable is
              a string to be displayed by the element;  if the variable  value
              changes  then  the  element  will automatically update itself to
              display the new value.  If this option is specified, the  -data,
              -datatype, and -format options are ignored.

       -underline charIndex
              Specifies the integer index of a character to underline.  0 cor-
              responds to the first character.  If  charIndex  is  unspecified
              (the  default),  less than zero or greater than the index of the
              last displayed character, the underline is not drawn.

       -width size
              Specifies the maximum line length in any of the forms acceptable
              to Tk_GetPixels.  For text to wrap lines the value of the -width
              option must be less than the needed width of the  text,  or  the
              display area for this element must be less than the needed width
              of the text.  For the display area to be less  than  the  needed
              width  of  the  text, one of the style layout options -maxwidth,
              -width or -squeeze must be used.

       -wrap mode
              Mode specifies how to handle lines in the text that  are  longer
              than  the maximum line length.  Acceptable values are none, char
              or word.  If this option is unspecified (the default),  word  is
              used.   See the -width option for a description of how the maxi-
              mum line length is determined.


WINDOW ELEMENT
       An element of type window can be used to display  a  Tk  window  in  an
       item.  The following options are supported for window elements:

       -clip boolean
              Specifies whether the associated Tk window is a borderless frame



treectrl                       2.3                             71





treectrl(n)                Tk Commands                treectrl(n)


              which should be used to clip its  child  window  so  it  doesn't
              overlap  the  header,  borders,  or other items or columns. When
              this option is true, the treectrl manages the geometry  of  both
              the  -window widget and its first child widget; in this case the
              -window widget (which should be  a  borderless  frame)  is  kept
              sized and positioned so that it is never out-of-bounds.

       -destroy boolean
              Specifies  whether  the associated Tk window should be destroyed
              when the element is deleted. The element  is  deleted  when  the
              item containing the element is deleted, when the column contain-
              ing the element is deleted, or when the style  assigned  to  the
              item's  column  is  changed.  If this option is unspecified (the
              default), it is treated as false and the Tk window will  not  be
              destroyed.

       -draw boolean
              Deprecated;  use  the style layout option -draw instead.  Speci-
              fies as a per-state option whether to draw the element.  If  the
              value  for  a certain state is an empty string (the default), it
              is treated as true and the element will be drawn.

       -window pathName
              Specifies the window to associate with this element. The  window
              specified  by  pathName  must  either be a child of the treectrl
              widget or a child of some ancestor of the treectrl widget. Path-
              Name  may not refer to a top-level window. This option cannot be
              specified by the element create or element  configure  commands,
              only  by  the  item element configure command; i.e., the element
              must be associated with a particular item.


ITEM DESCRIPTION
       Many of the commands for a treectrl take as an argument  a  description
       of  which items to operate on. An item description is a properly-formed
       tcl list of keywords and arguments.  The first word of an item descrip-
       tion must be one of the following:

       id     Specifies  the  unique  item  identifier, where id should be the
              return value of a prior call of the item create widget  command,
              or  0 to specify the ever-present root item. See also the -item-
              prefix option.

       QUALIFIERS
              Specifies a list of qualifiers. This gives the  same  result  as
              all  followed  by  QUALIFIERS;  i.e., every item is tested for a
              match.

       tagExpr QUALIFIERS
              TagExpr is a tag expression (see ITEM AND COLUMN  TAGS)  against
              which  every  item's  tags are tested for a match.  This keyword
              cannot be followed by any modifiers  unless  a  single  item  is
              matched.  You may run into trouble if tagExpr looks like an item
              id or other keyword; also, tagExpr must look like a single  list



treectrl                       2.3                             72





treectrl(n)                Tk Commands                treectrl(n)


              element since item descriptions are properly-formed lists. To be
              safe you may want to use the tag qualifier followed by  tagExpr.

       active Indicates  the  item that is currently active, i.e. normally the
              item specified as argument of the last successful activate  wid-
              get command, or the root item if no such call happened yet.

       anchor Indicates  the  anchor  item of the selection, i.e. normally the
              item specified as argument  of  the  last  successful  selection
              anchor widget command, or the root item if no such call happened
              yet.

       all QUALIFIERS
              Indicates every item including orphans which  match  QUALIFIERS.
              This keyword cannot be followed by any modifiers unless a single
              item is matched.

       first QUALIFIERS
              Indicates the first item of the treectrl (the root item), or the
              first item matching QUALIFIERS.

       end QUALIFIERS

       last QUALIFIERS
              Indicates the last item which matches QUALIFIERS.

       list itemDescs
              ItemDescs  is a list (a single argument, i.e. "list {a b c}" not
              "list a b c") of other item descriptions.  This  keyword  cannot
              be followed by any modifiers unless a single item is matched.

       nearest x y
              Indicates the item nearest to the point given by x and y.

       rnc row column
              Indicates  the  item  in  the given row and column.  The row and
              column corresponds to the  on-screen  arrangement  of  items  as
              determined  by  the -orient and -wrap options.  You can memorize
              rnc as an abbreviation of "row 'n' column".

       range first last QUALIFIERS
              First and last specify a range of items.  This keyword cannot be
              followed by any modifiers unless a single item is matched.

       root   Indicates the root item of the treectrl.


       The  initial  part  of the item description (matching any of the values
       above) may be followed by one or more modifiers.   A  modifier  changes
       the  item used relative to the description up to this point.  It may be
       specified in any of the following forms:

       above  Use the item one row above in this column.




treectrl                       2.3                             73





treectrl(n)                Tk Commands                treectrl(n)


       ancestors QUALIFIERS
              Use the ancestors of the item (like item  ancestors  but  QUALI-
              FIERS may change which ancestors match).  This keyword cannot be
              followed by any modifiers.

       below  Use the item one row below in this column.

       bottom Use the item in the last row of this column.

       child n QUALIFIERS
              Use the nth child of the item.

       children QUALIFIERS
              Use the children of the item (like item children but  QUALIFIERS
              may  change  which children match).  This keyword cannot be fol-
              lowed by any modifiers.

       descendants QUALIFIERS
              Use the descendants of the item (like item descendants but QUAL-
              IFIERS may change which descendants match).  This keyword cannot
              be followed by any modifiers.

       firstchild QUALIFIERS
              Use the first child of the item.

       lastchild QUALIFIERS
              Use the last child of the item.

       left   Use the item one column to the left in the same row.

       leftmost
              Use the item of the first column in the same row.

       next QUALIFIERS
              Use the next item, which is the first item  from  the  following
              list:  the  first child, the next sibling or the next sibling of
              the nearest ancestor which has one.

       nextsibling QUALIFIERS
              Use the next sibling of the item.

       parent Use the parent of the item.

       prev QUALIFIERS
              Use the last child of the previous sibling,  or  the  parent  if
              there is no previous sibling.

       prevsibling QUALIFIERS
              Use the previous sibling of the item.

       right  Use the item one column to the right in the same row.

       rightmost
              Use the item of the last column in the same row.



treectrl                       2.3                             74





treectrl(n)                Tk Commands                treectrl(n)


       sibling n QUALIFIERS
              Use the nth child of the item's parent.

       top    Use the item in the first row of this column.

       The  word  QUALIFIERS  above represents a series of zero or more of the
       following terms that changes which item is chosen:

       depth depth
              Matches items whose depth (as returned by the depth command)  is
              equal to depth.

       state stateList
              StateList is a list of item state names (static and dynamic, see
              STATES).  Only items that have the given states set (or unset if
              the '!' prefix is used) are considered.

       tag tagExpr
              TagExpr  is  a tag expression (see ITEM AND COLUMN TAGS) against
              which an item's tags are tested for a match.

       visible
              When this qualifier is given, only items that are displayed  are
              considered.

       !visible
              When  this  qualifier  is  given, only items that are *not* dis-
              played are considered.

       To get the first item in the list that is enabled:

       $T item id "first state enabled"

       To get the ancestors that are not open of the last item in the list:

       $T item id "last ancestors state !open"

       To get the visible descendants of the root item:

       $T item id "root descendants visible"

       To get the every hidden item with tag "a" or "b":

       $T item id "all !visible tag a||b"
       $T item id "!visible tag a||b"
       $T item id "tag a||b !visible"
       $T item id "a||b !visible"


EVENTS AND SCRIPT SUBSTITUTIONS
       The script argument to notify bind is a Tcl script, which will be eval-
       uated whenever the given event is generated. Script will be executed in
       the same interpreter that the notify bind command was executed in,  and
       it will run at global level (only global variables will be accessible).



treectrl                       2.3                             75





treectrl(n)                Tk Commands                treectrl(n)


       If script contains any % characters, then the script will not be evalu-
       ated  directly.   Instead,  a new script will be generated by replacing
       each %, and the character following it, with information from the  cur-
       rent  event. Unlike the regular Tk bind mechanism, each event generated
       by a treectrl widget has its own set of %-substitutions.

       The following %-substitutions are valid for all static events:

       %%     Replaced with a single %

       %d     The detail name

       %e     The event name

       %P     The pattern, either <event> or <event-detail>

       %W     The object argument to the notify bind command

       %T     The treectrl widget which generated the event

       %?     A list of the format {char value char value ...} for each %-sub-
              stitution character and the value it is replaced by


       The following events may be generated by a treectrl widget:

       <ActiveItem>
              Generated whenever the active item changes.

              %c     The current active item

              %p     The previous active item

       <Collapse-before>
              Generated before an item is collapsed.

              %I     The item id

       <Collapse-after>
              Generated after an item is collapsed.

              %I     The item id

       <Expand-before>
              Generated  before  an  item is expanded. This event is useful if
              you want to add child items to the item just before the item  is
              expanded.

              %I     The item id

       <Expand-after>
              Generated after an item is expanded.

              %I     The item id



treectrl                       2.3                             76





treectrl(n)                Tk Commands                treectrl(n)


       <ItemDelete>
              Generated  when items are about to be deleted by the item delete
              command.

              %i     List of items ids being deleted.

       <ItemVisibility>
              Generated when items become visible on screen and when items are
              no longer visible on screen.  This event is useful if you have a
              very large number of items and want to assign styles  only  when
              items are actually going to be displayed.

              %h     List of items ids which are no longer visible.

              %v     List of items ids which are now visible.

       <Scroll-x>
              Generated  whenever  the  view in the treectrl changes in such a
              way that a horizontal scrollbar should be redisplayed.

              %l     Same as the first fraction appended  to  -xscrollcommand.
                     Think lower.

              %u     Same  as the second fraction appended to -xscrollcommand.
                     Think upper.

       <Scroll-y>
              Generated whenever the view in the treectrl changes  in  such  a
              way that a vertical scrollbar should be redisplayed.

              %l     Same  as  the first fraction appended to -yscrollcommand.
                     Think lower.

              %u     Same as the second fraction appended to  -yscrollcommand.
                     Think upper.

       <Selection>
              Generated  whenever  the  selection  changes.  This  event gives
              information about how the selection changed.

              %c     Same as the selection count widget command

              %D     List of newly-deselected item ids

              %S     List of newly-selected item ids


DYNAMIC EVENTS
       In addition to the pre-defined static events such as  <ActiveItem>  and
       <Selection>,  new  dynamic  events  can  be created by using the notify
       install command.

       The following events may be generated by the library scripts:




treectrl                       2.3                             77





treectrl(n)                Tk Commands                treectrl(n)


       <ColumnDrag-begin>

       <ColumnDrag-receive>

       <ColumnDrag-end>
              Generated whenever the user drag-and-drops a column header.  The
              library  scripts do not actually move a dragged column. You must
              bind to the receive event to move the column. See EXAMPLES.

              %C     The column that was dragged

              %b     The column to move the dragged column before

       <Drag-begin>

       <Drag-receive>

       <Drag-end>
              Generated whenever the user drag-and-drops a file into a  direc-
              tory.  This  event  is  generated  by  the filelist-bindings.tcl
              library code, which is not used by default. See  the  "Explorer"
              demos.

              %I     The item that the user dropped the dragged items on.

              %l     (lowercase L) The list of dragged items.

       <Edit-begin>

       <Edit-accept>

       <Edit-end>
              The  filelist-bindings.tcl code will display a text-editing win-
              dow if the user clicks on a selected file/folder name.  See  the
              "Explorer" demos.

              %I     The item containing the edited text element

              %C     The column containing the edited text element

              %E     The name of the edited text element

              %t     The edited text

       <Header-invoke>
              Generated  whenever  the user clicks and releases the left mouse
              button in a column header if  the  column's  -button  option  is
              true. You can bind a script to this event to sort the list.

              %C     The column whose header was clicked

       The  library scripts provide an example of using a dynamic event called
       <Header-invoke>, which is generated when the mouse button  is  released
       over a column header.



treectrl                       2.3                             78





treectrl(n)                Tk Commands                treectrl(n)


       treectrl .t
                               puts "header %C clicked in treectrl %T"
       }
       proc ::TreeCtrl::Release1 {w x y} {
                               ...
                               $w notify generate <Header-invoke> [list C $Priv(column)] \
                               [list ::TreeCtrl::PercentsCmd $w]
                               ...
       }

       In the example a new treectrl widget is created and the <Header-invoke>
       event is installed. For convenience there is no  percentsCommand  argu-
       ment  to  notify install; instead the call to notify generate specifies
       the %-substitution command. A script is bound to the event with  notify
       bind which will print out the column number and widget name to the con-
       sole (in the demos, <Header-invoke> is used to sort the list  based  on
       the  column  that was clicked). The charMap argument to notify generate
       provides a list of %-substitution characters and values which  is  used
       by  ::TreeCtrl::PercentsCmd. In this example any %C in any script bound
       to  the  <Header-invoke>  event  will  be  replaced  by  the  value  of
       $Priv(column).

DEFAULT BINDINGS
       Tk  automatically creates class bindings for treectrl widgets that give
       them the following default behavior.

       [1]    Clicking mouse button 1 over an item positions the active cursor
              on the item, sets the input focus to this widget, and resets the
              selection of the widget to this item, if it is  not  already  in
              the selection.

       [2]    Clicking  mouse  button 1 with the Control key down will reposi-
              tion the active cursor and add the item to the selection without
              ever removing any items from the selection.

       [3]    If  the  mouse  is  dragged  out of the widget while button 1 is
              pressed, the treectrl will automatically  scroll  to  make  more
              items  visible  (if  there are more items off-screen on the side
              where the mouse left the window).

       [4]    The Left and Right keys move the active cursor one item  to  the
              left  or  right; for an hierarchical tree with vertical orienta-
              tion nothing will happen, since it has no two items in the  same
              row.   The selection is set to include only the active item.  If
              Left or Right is typed with the Shift key down, then the  active
              cursor  moves  and  the selection is extended to include the new
              item.

       [5]    The Up and Down keys move the active cursor one item up or down.
              The  selection is set to include only the active item.  If Up or
              Down is typed with the Shift key down, then  the  active  cursor
              moves and the selection is extended to include the new item.

       [6]    The  Next  and  Prior  keys  move  the  active cursor forward or



treectrl                       2.3                             79





treectrl(n)                Tk Commands                treectrl(n)


              backwards by one screenful, without affecting the selection.

       [7]    Control-Next and Control-Prior scroll the view right or left  by
              one  page  without  moving  the  active  cursor or affecting the
              selection.  Control-Left and Control-Right behave the same.

       [8]    The Home and End keys scroll to the left or  right  end  of  the
              widget  without moving the active cursor or affecting the selec-
              tion.

       [9]    The Control-Home and Control-End keys scroll to the top or  bot-
              tom  of  the  widget, they also activate and select the first or
              last item.  If also the Shift key is down, then the active  cur-
              sor moves and the selection is extended to include the new item.

       [10]   The Space and Select keys set the selection to the active  item.

       [11]   Control-/ selects the entire contents of the widget.

       [12]   Control-\\ clears any selection in the widget.

       [13]   The  + and - keys expand or collapse the active item, the Return
              key toggles the active item.

       [14]   The mousewheel scrolls the view of the widget four lines  up  or
              down  depending  on  the  direction,  the wheel was turned.  The
              active cursor or the selection is not affected.


GRADIENTS
       Color gradients are an easy way  to  give  your  lists  a  more  modern
       appearance.   Since  Tk  provides no support for drawing gradients, the
       TkPath extension was used as a guide  when  implementing  gradients  in
       TkTreeCtrl.  The current implementation has some limitations, however:

       [1]    Only linear gradients are supported.

       [2]    Gradients  can  only  be painted left-to-right or top-to-bottom,
              not at arbitrary angles.

       [3]    Gradients look bad on low-color displays.  Before  using  gradi-
              ents,  you  should  check  that  the display's color depth is at
              least 15 or 16 by calling the winfo depth command.

       [4]    Gradients are fully opaque when XFillRectangle() is used to draw
              them  (see  below).   This means the opacity value of each color
              stop is ignored.  Keep that  in  mind  if  your  application  is
              cross-platform.

       [5]    Rounded  rectangles cannot be filled or outlined with a gradient
              when XFillRectangle() is used to  draw  gradients  (see  below).
              Instead,  the  rounded  rectangle is painted with the gradient's
              first -stops color.




treectrl                       2.3                             80





treectrl(n)                Tk Commands                treectrl(n)


       Gradients may be used in the following places:

       [1]    The -fill and -outline options of rect elements.

       [2]    The -fill and -outline options of the marquee configure command.

       [3]    The -itembackground option of columns.


       On  Microsoft  Windows, GDI+ is used where it is available (gdiplus.dll
       is dynamically loaded at run-time).  On Mac OS X, CoreGraphics is  used
       to  draw  gradients.  With the Gtk+ build of treectrl, libcairo is used
       to draw gradients.  When native gradient support is available, all  the
       talk below about -steps can safely be ignored.

       When  no native support for gradients is available, gradients are drawn
       simply by filling sub-rectangles using XFillRectangle().  The number of
       sub-rectangles  drawn  and  number of colors that make up the displayed
       gradient are controlled by the gradient's -steps  and  -stops  options.
       The  number  of  sub-rectangles  is  equal  to the length of the -stops
       option multiplied by the value of the -steps option. For example:

       $T gradient create myGradient -stops {{0 white} {1 gray}} -steps 8

       This gradient will be drawn with 2x8=16 sub-rectangles of  color.   The
       higher  the  -steps  value, the smoother the color transitions will be,
       and the slower the gradient will be to draw.  For the best  appearance,
       make  the  number  of  sub-rectangles  drawn  less than or equal to the
       height or width of the gradient being drawn.  So if  you  have  a  rect
       element  18  pixels  tall,  use  a  vertical  gradient that has steps X
       stops=18.  Avoid using gradients with steps X stops  greater  than  the
       height  or width of the rectangle being drawn, because then colors will
       overlap.

GRADIENT COORDINATES
       By default, a gradient brush is exactly the same size as whatever rect-
       angle  is  being  painted.   For example, if a column's -itembackground
       option specifies a gradient name, then the background  of  an  item  is
       painted  with  all  the colors of the gradient.  So a vertical gradient
       from blue to green will start blue at the top and end with green at the
       bottom of every item.

       By  specifying  any  of  the  -bottom,  -left,  -right or -top gradient
       options the size of the gradient brush does not need to match  that  of
       the  rectangle being painted.  These options can be used to make a gra-
       dient appear to span across the entire width or height of the  treectrl
       window, or across the entire canvas, for example.

       There  is no point specifying -left or -right if the gradient is verti-
       cal, since the gradient's colors are constant horizontally, so changing
       the  horizontal  size  of  the brush won't change the appearance of the
       gradient.  The same reasoning applies for the -top and -bottom  options
       for a horizontal gradient.




treectrl                       2.3                             81





treectrl(n)                Tk Commands                treectrl(n)


       package require treectrl
       set T [treectrl .t -itemheight 20 -showheader no]
       $T gradient api 1.0
       $T gradient create G1 -orient vertical -top {0.0 canvas} -bottom {1.0 canvas} \
                               -stops {{0.0 blue} {0.5 green} {1.0 red}} -steps 25
       $T column create -expand yes -itembackground G1
       pack $T -expand yes -fill both


EXAMPLES
       Get the unique identifier for the leftmost visible column:

       set id [$T column index "first visible"]

       Delete the leftmost column:

       $T column delete "order 0"

       Take  the  visible  column  that is to the left of the last column, and
       move that column in front of the tail column:

       $T column move "last prev visible" tail

       Get the unique identifier for the first visible item:

       set id [$T item index "first visible"]

       Delete the parent of the item that is under the point x,y:

       $T item delete "nearest $x $y parent"

       Add the 10th child of the second child of the root item to  the  selec-
       tion:

       $T selection add "root firstchild nextsibling child 10"

       Move a column that the user drag-and-dropped:

       $T column dragconfigure -enable yes
       $T notify install <ColumnDrag-receive>
       $T notify bind MyTag <ColumnDrag-receive> {
                               %T column move %C %b
       }


SEE ALSO
       bind(n), bitmap(n), image(n), listbox(n), options(n)

KEYWORDS
       tree, widget







treectrl                       2.3                             82


