blt_hierbox man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

treeview(n)		     BLT Built-In Commands		   treeview(n)

______________________________________________________________________________

NAME
       treeview - Create and manipulate hierarchical table widgets
_________________________________________________________________

SYNOPSIS
       treeview pathName ?options?

DESCRIPTION
       The  treeview  widget  displays	a  tree of data.  It replaces both the
       hiertable and hierbox widgets.  The treeview is 100% syntax  compatible
       with  the hiertable widget.  The hiertable command is retained for sake
       of script-level compatibility.  This widget obsoletes the hierbox  wid‐
       get.   It does everything the old hierbox widget did, but also provides
       data sharing (via tree data objects) and the ability to tag nodes.

INTRODUCTION
       The treeview widget displays hierarchical data.	Data is represented as
       nodes  in  a  general-ordered  tree.   Each node may have sub-nodes and
       these nodes can in turn has their own children.

       A node is displayed as a row entry in the widget.   Each	 entry	has  a
       text label and icon.  When a node has children, its entry is drawn with
       a small button to the left of the label.	 Clicking the mouse over  this
       button opens or closes the node.	 When a node is open, its children are
       exposed.	 When it is closed, the children and their descedants are hid‐
       den.   The  button  is normally a + or - symbol (ala Windows Explorer),
       but can be replaced with a pair of Tk images (open and closed images).

       If the node has data associated with it, they can be displayed in  col‐
       umns  running  vertically on either side the tree.  You can control the
       color, font, etc of each entry.	Any entry label or data field  can  be
       edited in-place.

TREE DATA OBJECT
       The tree is not stored inside the widget but in a tree data object (see
       the tree command for a further explanation).  Tree data objects can  be
       shared  among  different clients, such as a treeview widget or the tree
       command.	 You can walk the tree and manage its data with the tree  com‐
       mand  tree, while displaying it with the treeview widget.  Whenever the
       tree is updated, the treeview widget is automatically redrawn.

       By default, the treeview widget creates its own tree object.  The  tree
       initially  contains  just  a root node.	But you can also display trees
       created by the tree  command  using  the	 -tree	configuration  option.
       Treeview	 widgets  can  share the same tree object, possibly displaying
       different views of the same data.

       A tree object has both a Tcl and C API.	You can insert or delete nodes
       using treeview widget or tree command operations, but also from C code.
       For example, you can load the tree from your C code while still	manag‐
       ing and displaying the tree from Tcl. The widget is automatically noti‐
       fied whenever the tree is modified via C or Tcl.

SYNTAX
       treeview pathName ?option value?...  The treeview command creates a new
       window  pathName and makes it into a treeview widget.  At the time this
       command is invoked, there must not exist a window named	pathName,  but
       pathName's  parent  must exist.	Additional options may be specified on
       the command line or in the option database to configure aspects of  the
       widget  such as its colors and font.  See the configure operation below
       for the exact details about what option and value pairs are valid.

       If successful, treeview returns the path name of the widget.   It  also
       creates	a  new Tcl command by the same name.  You can use this command
       to invoke various operations that query or modify the widget.  The gen‐
       eral form is: pathName operation ?arg?...  Both operation and its argu‐
       ments determine the exact behavior  of  the  command.   The  operations
       available are described in the TREEVIEW OPERATIONS section.

IDS AND TAGS
       Nodes can be inserted into a tree using the treeview widget

	      blt::treeview .t
	      set node [.t insert end root "one"]

       or tree command.

	      set tree [blt::tree create]
	      set node [$tree insert root "one"]

       In  both cases, a number identifying the node is returned (the value of
       $node).	This serial number or id uniquely identifies the node.	Please
       note that you can't infer a location or position of a node from its id.
       The only exception is that the root node is always id  0.  Since	 nodes
       may  have  the  same labels or be moved within the tree, ids provide an
       convenient way to identify nodes.  If a tree is shared, the ids will be
       the same regardless if you are using by the treeview widget or the tree
       command.	 Ids are recycled when the node deleted.

       A node may also have any number of tags associated with it.  A  tag  is
       just a string of characters, and it may take any form except that of an
       integer.	 For example, "x123" is valid, but "123" isn't.	 The same  tag
       may be associated with many different nodes.  This is typically done to
       associate a group of nodes.  Many operations  in	 the  treeview	widget
       take  either  node  ids or tag names as arguments.  Using a tag says to
       apply the operation to all nodes with that tag.

       The tag all is implicitly associated with every node in the  tree.   It
       may be used to invoke operations on all the nodes in the tree.

       Tags may be shared, just like trees, between clients.  For example, you
       can use the tags created by the tree command with treeview widgets.

SPECIAL NODE IDS
       There are also several special non-numeric  ids.	  Special  ids	differ
       from  tags  in that they are always translated to their numeric equiva‐
       lent.  They also take precedence over tags.  For example, you can't use
       a  tag  name that is a special id.  These ids are specific to the tree‐
       view widget.

       active	      The node where the mouse pointer is  currently  located.
		      When a node is active, it is drawn using its active icon
		      (see the -activeicon option).  The active id is  changed
		      automatically  by	 moving the mouse pointer over another
		      node or by using the entry activate operation. Note that
		      there can be only one active node at a time.

       anchor	      The  node	 representing  the  fixed  end	of the current
		      selection.  The anchor is set by	the  selection	anchor
		      operation.

       current	      The  node	 where the mouse pointer is currently located.
		      But unlike active, this id changes while	the  selection
		      is  dragged.   It	 is used to determine the current node
		      during button drags.

       down	      The next open node from the current focus. The  down  of
		      the last open node is the same.

       end	      The last open node (in depth-first order) on the tree.

       focus	      The  node	 that  currently  has  focus.  When a node has
		      focus, it receives key events.  To indicate  focus,  the
		      node  is drawn with a dotted line around its label.  You
		      can change the focus using the focus operation.

       last	      The last open node from the current  focus.  But	unlike
		      up,  when the focus is at root, last wraps around to the
		      last open node in the tree.

       mark	      The node representing the non-fixed end of  the  current
		      selection.  The mark is set by the selection mark opera‐
		      tion.

       next	      The next open node from the current focus.   But	unlike
		      down,  when  the	focus is on last open node, next wraps
		      around to the root node.

       nextsibling    The next sibling from the node with the  current	focus.
		      If  the  node is already the last sibling then it is the
		      nextsibling.

       parent	      The parent of the node with the current focus. The  par‐
		      ent of the root is also the root.

       prevsibling    The  previous  sibling  from  the	 node with the current
		      focus.  If the node is already the first sibling then it
		      is the prevsibling.

       root	      The  root	 node.	You  can also use id 0 to indicate the
		      root.

       up	      The last open node (in depth-first order) from the  cur‐
		      rent  focus.  The up of the root node (i.e. the root has
		      focus) is also the root.

       view.top	      First node that's current visible in the widget.

       view.bottom    Last node that's current visible in the widget.

       path	      Absolute path of a node.	Path names refer to  the  node
		      name,  not their entry labels. Paths don't have to start
		      with  a  separator  (see	the  -separator	 configuration
		      option),	but  component	names must be separated by the
		      designated separator.

       @x,y	      Indicates the node that covers the point in the treeview
		      window  specified by x and y (in pixel coordinates).  If
		      no part of the entryd covers that point, then the	 clos‐
		      est node to that point is used.

       A node may be specified as an id or tag. If the specifier is an integer
       then it is assumed to refer to the single node with that	 id.   If  the
       specifier  is  not an integer, it's checked to see if it's a special id
       (such as focus).	 Otherwise, it's assumed to be tag.   Some  operations
       only  operate  on a single node at a time; if a tag refers to more than
       one node, then an error is generated.

DATA FIELDS
       A node in the tree can have data fields.	 A data field is a  name-value
       pair,  used to represent arbitrary data in the node.  Nodes can contain
       different fields (they aren't required to  contain  the	same  fields).
       You  can optionally display these fields in the treeview widget in col‐
       umns running on either side of the displayed tree.  A node's value  for
       the  field is drawn in the column along side its node in the hierarchy.
       Any node that doesn't have a specific field is left blank.  Columns can
       be interactively resized, hidden, or, moved.

ENTRY BINDINGS
       You  can	 bind  Tcl  commands  to be invoked when events occur on nodes
       (much like Tk canvas items).  You can bind a node using its id  or  its
       bindtags.   Bindtags are simply names that associate a binding with one
       or more nodes.  There is a built-in tag all that all node entries auto‐
       matically have.

TREEVIEW OPERATIONS
       The  treeview  operations  are  the  invoked by specifying the widget's
       pathname, the operation, and any arguments that pertain to that	opera‐
       tion.  The general form is:

	      pathName operation ?arg arg ...?

       Operation  and  the  args  determine the exact behavior of the command.
       The following operation are available for treeview widgets:

       pathName bbox ?-screen? tagOrId...
	      Returns a list of 4 numbers,  representing  a  bounding  box  of
	      around  the  specified  entries.	The entries is given by one or
	      more tagOrId arguments.  If the -screen flag is given, then  the
	      x-y coordinates of the bounding box are returned as screen coor‐
	      dinates, not virtual coordinates. Virtual coordinates start from
	      0	 from the root node.  The returned list contains the following
	      values.

	      x		  X-coordinate of the upper-left corner of the	bound‐
			  ing box.

	      y		  Y-coordinate	of the upper-left corner of the bound‐
			  ing box.

	      width	  Width of the bounding box.

	      height	  Height of the bounding box.

       pathName bind tagName ?sequence command?
	      Associates command with tagName such  that  whenever  the	 event
	      sequence given by sequence occurs for a node with this tag, com‐
	      mand will be invoked.  The syntax is similar to the bind command
	      except  that  it	operates on treeview entries, rather than wid‐
	      gets. See the bind manual entry for complete details on sequence
	      and the substitutions performed on command before invoking it.

	      If  all  arguments  are specified then a new binding is created,
	      replacing any existing binding for the same  sequence  and  tag‐
	      Name.   If the first character of command is + then command aug‐
	      ments an existing binding rather than replacing it.  If no  com‐
	      mand  argument is provided then the command currently associated
	      with tagName and sequence (it's an error occurs  if  there's  no
	      such  binding)  is  returned.   If both command and sequence are
	      missing then a list of all the event sequences for  which	 bind‐
	      ings have been defined for tagName.

       pathName button operation ?args?
	      This  command  is	 used to control the button selectors within a
	      treeview widget.	It has several forms, depending on operation:

	      pathName button activate tagOrId
		     Designates the node given by tagOrId as active.   When  a
		     node  is active it's entry is drawn using its active icon
		     (see the -activeicon option).  Note  that	there  can  be
		     only  one	active entry at a time.	 The special id active
		     indicates the currently active node.

	      pathName button bind tagName ?sequence command?
		     Associates command with tagName such  that	 whenever  the
		     event  sequence given by sequence occurs for an button of
		     a node entry with this tag, command will be invoked.  The
		     syntax  is	 similar  to  the  bind command except that it
		     operates on treeview buttons, rather  than	 widgets.  See
		     the  bind	manual	entry for complete details on sequence
		     and the substitutions performed on command before	invok‐
		     ing it.

		     If all arguments are specified then a new binding is cre‐
		     ated,  replacing  any  existing  binding  for  the	  same
		     sequence  and tagName.  If the first character of command
		     is + then command augments	 an  existing  binding	rather
		     than  replacing  it.   If no command argument is provided
		     then the command currently associated  with  tagName  and
		     sequence  (it's  an error occurs if there's no such bind‐
		     ing) is returned.	If both command and sequence are miss‐
		     ing  then	a  list	 of  all the event sequences for which
		     bindings have been defined for tagName.

	      pathName button cget option
		     Returns the current value	of  the	 configuration	option
		     given  by	option.	  Option  may  have  any of the values
		     accepted by the configure operation described below.

	      pathName button 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 available options for pathName (see	 Tk_Configure‐
		     Info  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  and  value are described in the section
		     BUTTON OPTIONS below.

       pathName cget option
	      Returns the current value of the configuration option  given  by
	      option.	Option may have any of the values accepted by the con‐
	      figure operation described below.

       pathName close ?-recurse? tagOrId...
	      Closes the node specified by tagOrId.  In	 addition,  if	a  Tcl
	      script was specified by the -closecommand option, it is invoked.
	      If the node is already closed, this command has no  effect.   If
	      the  -recurse  flag  is  present, each child node is recursively
	      closed.

       pathName column operation ?args?
	      The following operations are available for treeview columns.

	      pathName column activate column
		     Sets the active column to column.	Column is the name  of
		     a	column	in  the widget.	 When a column is active, it's
		     drawn using its -activetitlebackground and	 -activetitle‐
		     foreground	 options.  If column is the "", then no column
		     will be active.  If no column argument is provided,  then
		     the name of the currently active column is returned.

	      pathName column cget name option
		     Returns  the  current  value  of the column configuration
		     option given by option for name.  Name  is	 the  name  of
		     column that corresponds to a data field.  Option may have
		     any of the values accepted	 by  the  configure  operation
		     described below.

	      pathName column configure name ?option? ?value option value ...?
		     Query  or	modify the configuration options of the column
		     designated by name. Name is the name of the column corre‐
		     sponding  to  a  data  field.  If no option is specified,
		     returns a list describing all of  the  available  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	corre‐
		     sponding  sublist	of  the value returned if no option is
		     specified).  If one or more option-value pairs are speci‐
		     fied,   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 and value are
		     described in the section COLUMN OPTIONS below.

	      pathName column delete field ?field...?
		     Deletes one of more columns designated  by	 field.	  Note
		     that this does not delete the data fields themselves.

	      pathName column insert position field ?options...?
		     Inserts  one of more columns designated by field.	A col‐
		     umn displays each node's data field by the same name.  If
		     the  node	doesn't have the given field, the cell is left
		     blank.  Position indicates where in the list  of  columns
		     to add the new column.  It may be either a number or end.

	      pathName column invoke field
		     Invokes the Tcl command associated with the column field,
		     if there is one (using  the  column's  -command  option).
		     The  command is ignored if the column's -state option set
		     to disabled.

	      pathName column move name dest
		     Moves the column name to the destination position.	  Dest
		     is the name of another column or a screen position in the
		     form @x,y.

	      pathName column names
		     Returns a list of the names of all columns in the widget.
		     The  list	is ordered as the columns are drawn from left-
		     to-right.

	      pathName column nearest x ?y?
		     Returns the name of the column closest to the  given  X-Y
		     screen  coordinate.   If  you  provide a y argument (it's
		     optional), a name is returned only when if the  point  is
		     over a column's title.

       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 and value  are
	      described in the section TREEVIEW OPTIONS below.

       pathName curselection
	      Returns a list containing the ids of all of the entries that are
	      currently selected.  If there are no entries selected, then  the
	      empty string is returned.

       pathName delete tagOrId...
	      Deletes one or more entries given by tagOrId and its children.

       pathName entry operation ?args?
	      The following operations are available for treeview entries.

	      pathName entry activate tagOrId
		     Sets  the	active	entry to the one specified by tagOrId.
		     When an entry is active it is drawn using its active icon
		     (see  the	-activeicon  option).	Note that there can be
		     only one active node at a time.  The special  id  of  the
		     currently active node is active.

	      pathName entry cget option
		     Returns  the  current  value  of the configuration option
		     given by option.  Option  may  have  any  of  the	values
		     accepted by the configure operation described below.

	      pathName entry children tagOrId  ?first? ?last?
		     Returns  a list of ids for the given range of children of
		     tagOrId.  TagOrId is the id or tag	 of  the  node	to  be
		     examined.	 If only a first argument is present, then the
		     id	 of  the  that	child  at  that	 numeric  position  is
		     returned.	 If  both  first and last arguments are given,
		     then the ids of  all  the	children  in  that  range  are
		     returned.	  Otherwise   the  ids	of  all	 children  are
		     returned.

	      pathName entry 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 available options for pathName (see	 Tk_Configure‐
		     Info  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 and value are described below:

	      pathName entry delete tagOrId ?first ?last?
		     Deletes  the  one	or  more  children nodes of the parent
		     tagOrId.  If first and last arguments are	present,  they
		     are positions designating a range of children nodes to be
		     deleted.

	      pathName entry isbefore tagOrId1 tagOrId2
		     Returns 1 if tagOrId1 is before tagOrId2 and 0 otherwise.

	      pathName entry ishidden tagOrId
		     Returns 1 if the node is currently hidden	and  0	other‐
		     wise.  A node is also hidden if any of its ancestor nodes
		     are closed or hidden.

	      pathName entry isopen tagOrId
		     Returns 1 if the node is currently open and 0 otherwise.

	      pathName entry size -recurse tagOrId
		     Returns the number of children for parent	node  tagOrId.
		     If	 the  -recurse	flag  is  set,	the  number of all its
		     descendants is returned.  The node itself is not counted.

       pathName find ?flags? first last
	      Finds for all entries matching the criteria given by  flags.   A
	      list  of	ids for all matching nodes is returned. First and last
	      are ids designating the  range  of  the  search  in  depth-first
	      order.  If  last	is  before  first,  then nodes are searched in
	      reverse order.  The valid flags are:

	      -name pattern
			  Specifies pattern to match against node names.

	      -full pattern
			  Specifies pattern to match against node pathnames.

	      -option pattern
			  Specifies pattern to match against the node  entry's
			  configuration option.

	      -exact	  Patterns must match exactly.	The is the default.

	      -glob	  Use  global pattern matching.	 Matching is done in a
			  fashion similar to that used by  the	C-shell.   For
			  the	two  strings  to match, their contents must be
			  identical  except  that  the	  following    special
			  sequences  may appear in pattern:

			  *    Matches	  any	sequence   of	characters  in
			       string, including a null string.

			  ?    Matches any single character in string.

			  [chars]
			       Matches any  character  in  the	set  given  by
			       chars. If a sequence of the form x-y appears in
			       chars, then any	character  between  x  and  y,
			       inclusive, will match.

			  \x   Matches	 the  single  character	 x.  This pro‐
			       vides a way of  avoiding	 the   special	inter‐
			       pretation  of  the characters *?[]\ in the pat‐
			       tern.

	      -regexp	  Use regular expression pattern  matching  (i.e.  the
			  same as implemented by the regexp command).

	      -nonmatching
			  Pick entries that don't match.

	      -exec string
			  Specifies a Tcl script to be invoked for each match‐
			  ing node.  Percent substitutions  are	 performed  on
			  string before it is executed.	 The following substi‐
			  tutions are valid:

			  %W   The pathname of the widget.

			  %p   The name of the node.

			  %P   The full pathname of the node.

			  %#   The id of the node.

			  %%   Translates to a single percent.

	      -count number
			  Stop searching after number matches.

	      --	  Indicates the end of flags.

       pathName focus  tagOrId
	      Sets the focus to the node given by tagOrId.  When  a  node  has
	      focus,  it  can  receive	keyboard events.  The special id focus
	      designates the node that currently has focus.

       pathName get ?-full? tagOrId tagOrId...
	      Translates one or more  ids  to  their  node  entry  names.   It
	      returns a list of names for all the ids specified.  If the -full
	      flag is set, then the full pathnames are returned.

       pathName hide ?flags? tagOrId...
	      Hides all nodes matching	the  criteria  given  by  flags.   The
	      search  is performed recursively for each node given by tagOrId.
	      The valid flags are described below:

	      -name pattern
			  Specifies pattern to match against node names.

	      -full pattern
			  Specifies pattern to match against node pathnames.

	      -option pattern
			  Specifies pattern to match against the node  entry's
			  configuration option.

	      -exact	  Match patterns exactly.  The is the default.

	      -glob	  Use  global pattern matching.	 Matching is done in a
			  fashion similar to that used by  the	C-shell.   For
			  the	two  strings  to match, their contents must be
			  identical  except  that  the	  following    special
			  sequences  may appear in pattern:

			  *    Matches	  any	sequence   of	characters  in
			       string, including a null string.

			  ?    Matches any single character in string.

			  [chars]
			       Matches any  character  in  the	set  given  by
			       chars. If a sequence of the form x-y appears in
			       chars, then any	character  between  x  and  y,
			       inclusive, will match.

			  \x   Matches	 the  single  character	 x.  This pro‐
			       vides a way of  avoiding	 the   special	inter‐
			       pretation  of  the characters *?[]\ in the pat‐
			       tern.

	      -regexp	  Use regular expression pattern  matching  (i.e.  the
			  same as implemented by the regexp command).

	      -nonmatching
			  Hide nodes that don't match.

	      --	  Indicates the end of flags.

       pathName index ?-at tagOrId? string
	      Returns the id of the node specified by string.  String may be a
	      tag or node id.  Some special ids are normally relative  to  the
	      node that has focus.  The -at flag lets you select another node.

       pathName	  insert  ?-at	tagOrId?  position  path  ?options...?	?path?
       ?options...?
	      Inserts one or more nodes at position.  Position is the location
	      (number  or  end)	 where	the  new nodes are added to the parent
	      node.  Path is the pathname of the new node.  Pathnames  can  be
	      formated either as a Tcl list (each element is a path component)
	      or as a string separated by a special character sequence	(using
	      the  -separator  option).	  Pathnames are normally absolute, but
	      the -at switch lets you select a relative starting  point.   Its
	      value is the id of the starting node.

	      All  ancestors  of  the  new node must already exist, unless the
	      -autocreate option is set.  It  is  also	an  error  if  a  node
	      already exists, unless the -allowduplicates option is set.

	      Option  and  value  may  have  any of the values accepted by the
	      entry configure operation described in the ENTRY OPERATIONS sec‐
	      tion  below.   This command returns a list of the ids of the new
	      entries.

       pathName move tagOrId how destId
	      Moves the node given by tagOrId to the  destination  node.   The
	      node  can	 not be an ancestor of the destination.	 DestId is the
	      id of the destination node and can not be the root of the	 tree.
	      In conjunction with how, it describes how the move is performed.

	      before  Moves the node before the destination node.

	      after   Moves the node after the destination node.

	      into    Moves  the  node to the end of the destination's list of
		      children.

       pathName nearest x y ?varName?
	      Returns the id of the node entry closest to the given X-Y screen
	      coordinate.   The optional argument varName is the name of vari‐
	      able which is set to either button or select  to	indicate  over
	      what part of the node the coordinate lies.  If the coordinate is
	      not directly over any node, then varName will contain the	 empty
	      string.

       pathName open ?-recurse? tagOrId...
	      Opens  the one or more nodes specified by tagOrId.  If a node is
	      not already open, the Tcl script specified by  the  -opencommand
	      option  is  invoked.  If the -recurse flag is present, then each
	      descendant is recursively opened.

       pathName range ?-open? first last
	      Returns the ids in depth-first order of the  nodes  between  the
	      first  and last ids.  If the -open flag is present, it indicates
	      to consider only open nodes.  If last is before first, then  the
	      ids are returned in reverse order.

       pathName scan option args
	      This  command  implements scanning.  It has two forms, depending
	      on option:

	      pathName scan mark x y
		     Records x and y and the current view in the treeview win‐
		     dow;   used  in  conjunction  with later scan dragto com‐
		     mands.  Typically this command is associated with a mouse
		     button press in the widget.  It returns an empty string.

	      pathName scan dragto x y.
		     Computes the difference between its x and y arguments and
		     the x and y arguments to the last scan mark  command  for
		     the  widget.   It	then  adjusts the view by 10 times the
		     difference in coordinates.	  This	command	 is  typically
		     associated	 with  mouse  motion  events in the widget, to
		     produce the effect of dragging the	 list  at  high	 speed
		     through the window.  The return value is an empty string.

       pathName see ?-anchor anchor? tagOrId
	      Adjusts the view of entries so that the node given by tagOrId is
	      visible in the widget window.  It is an error if	tagOrId	 is  a
	      tag  that	 refers	 to more than one node.	 By default the node's
	      entry is displayed in  the  middle  of  the  window.   This  can
	      changed  using the -anchor flag.	Its value is a Tk anchor posi‐
	      tion.

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

	      pathName selection anchor tagOrId
		     Sets  the	selection anchor to the node given by tagOrId.
		     If tagOrId refers to a non-existent node, then the	 clos‐
		     est node is used.	The selection anchor is the end of the
		     selection that is fixed while dragging  out  a  selection
		     with  the	mouse.	 The  special id anchor may be used to
		     refer to the anchor node.

	      pathName selection cancel
		     Clears the temporary selection of	entries	 back  to  the
		     current  anchor.  Temporary selections are created by the
		     selection mark operation.

	      pathName selection clear first ?last?
		     Removes the entries between first	and  last  (inclusive)
		     from  the	selection.  Both first and last are ids repre‐
		     senting a range of entries.  If last  isn't  given,  then
		     only  first is deselected.	 Entries outside the selection
		     are not affected.

	      pathName selection clearall
		     Clears the entire selection.

	      pathName selection mark tagOrId
		     Sets the selection mark to the  node  given  by  tagOrId.
		     This  causes  the range of entries between the anchor and
		     the mark to be temporarily added to the  selection.   The
		     selection	mark is the end of the selection that is fixed
		     while dragging out a selection with the mouse.  The  spe‐
		     cial  id  mark  may  be used to refer to the current mark
		     node.  If tagOrId refers to a non-existent node, then the
		     mark  is  ignored.	  Resetting the mark will unselect the
		     previous range.  Setting the anchor finalizes the range.

	      pathName selection includes tagOrId
		     Returns 1 if the  node  given  by	tagOrId	 is  currently
		     selected, 0 if it isn't.

	      pathName selection present
		     Returns  1 if any nodes are currently selected and 0 oth‐
		     erwise.

	      pathName selection set first ?last?
		     Selects all of the nodes in the range between  first  and
		     last, inclusive, without affecting the selection state of
		     nodes outside that range.

	      pathName selection toggle first ?last?
		     Selects/deselects nodes in the range  between  first  and
		     last,  inclusive,	from the selection.  If a node is cur‐
		     rently selected, it becomes deselected, and visa versa.

       pathName show ?flags? tagOrId...
	      Exposes all nodes matching the criteria given by flags.  This is
	      the  inverse  of	the  hide  operation.  The search is performed
	      recursively for each node given by tagOrId.  The valid flags are
	      described below:

	      -name pattern
			  Specifies pattern to match against node names.

	      -full pattern
			  Specifies pattern to match against node pathnames.

	      -option pattern
			  Specifies  pattern to match against the entry's con‐
			  figuration option.

	      -exact	  Match patterns exactly.  The is the default.

	      -glob	  -glob Use global pattern matching.  Matching is done
			  in  a	 fashion  similar to that used by the C-shell.
			  For  the  two strings	 to match, their contents must
			  be  identical	 except	 that  the  following  special
			  sequences  may appear in pattern:

			  *    Matches	 any   sequence	  of   characters   in
			       string, including a null string.

			  ?    Matches any single character in string.

			  [chars]
			       Matches	any  character	in  the	 set  given by
			       chars. If a sequence of the form x-y appears in
			       chars,  then  any  character  between  x and y,
			       inclusive, will match.

			  \x   Matches	the  single  character	x.  This  pro‐
			       vides  a	 way of	 avoiding  the	special inter‐
			       pretation of the characters *?[]\ in  the  pat‐
			       tern.

	      -regexp	  Use  regular	expression  pattern matching (i.e. the
			  same as implemented by the regexp command).

	      -nonmatching
			  Expose nodes that don't match.

	      --	  Indicates the end of flags.

       pathName sort ?operation? args...

	      pathName sort auto ?boolean
		     Turns on/off automatic sorting of node entries.  If bool‐
		     ean is true, entries will be automatically sorted as they
		     are opened, closed, inserted, or deleted.	If no  boolean
		     argument is provided, the current state is returned.

	      pathName sort cget option
		     Returns  the  current  value  of the configuration option
		     given by option.  Option  may  have  any  of  the	values
		     accepted by the configure operation described below.

	      pathName sort configure ?option? ?value option value ...?
		     Query  or modify the sorting configuration options of the
		     widget.  If  no  option  is  specified,  returns  a  list
		     describing all of the available 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 com‐
		     mand modifies the given sorting  option(s)	 to  have  the
		     given  value(s);	in  this  case	the command returns an
		     empty string.  Option and value are described below:

		     -column string
			    Specifies the column to sort. Entries in the  wid‐
			    get	 are  rearranged according to this column.  If
			    column is "" then no sort is performed.

		     -command string
			    Specifies a Tcl procedure to be called when	 sort‐
			    ing	 nodes.	  The  procedure  is called with three
			    arguments: the pathname  of	 the  widget  and  the
			    fields of two entries.  The procedure returns 1 if
			    the first node is greater than the second,	-1  is
			    the second is greater, and 0 if equal.

		     -decreasing boolean
			    Indicates  to  sort in ascending/descending order.
			    If	boolean	 is  true,  then  the  entries	as  in
			    descending order. The default is no.

		     -mode string
			    Specifies  how  to	compare	 entries when sorting.
			    String may be one of the following:

			    ascii	   Use string  comparison  based  upon
					   the ASCII collation order.

			    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  embedded numbers, the num‐
					   bers compare as integers, not char‐
					   acters.    For   example,  "bigBoy"
					   sorts between "bigbang"  and	 "big‐
					   boy",   and	"x10y"	sorts  between
					   "x9y" and "x11y".

			    integer	   Compares fields as integers.

			    real	   Compares fields as  floating	 point
					   numbers.

			    command	   Use	the  Tcl proc specified by the
					   -command option to compare  entries
					   when	 sorting.    If	 no command is
					   specified,  the  sort  reverts   to
					   ascii sorting.

	      pathName sort once ?flags? tagOrId...
		     Sorts the children for each entries specified by tagOrId.
		     By default, entries are sorted by name, but you can spec‐
		     ify a Tcl proc to do your own comparisons.

		     -recurse	    Recursively	 sort  the  entire branch, not
				    just the children.

       pathName tag operation args
	      Tags are a general means of selecting and marking nodes  in  the
	      tree.  A tag is just a string of characters, and it may take any
	      form except that of an integer.  The same tag may be  associated
	      with many different nodes.

	      Both operation and its arguments determine the exact behavior of
	      the command.  The	 operations  available	for  tags  are	listed
	      below.

	      pathName tag add string id...
		     Adds the tag string to one of more entries.

	      pathName tag delete string id...
		     Deletes the tag string from one or more entries.

	      pathName tag forget string
		     Removes  the  tag	string	from all entries.  It's not an
		     error if no entries are tagged as string.

	      pathName tag names ?id?
		     Returns a list of	tags  used.   If  an  id  argument  is
		     present,  only  those tags used by the node designated by
		     id are returned.

	      pathName tag nodes string
		     Returns a list of ids that have the tag  string.	If  no
		     node  is  tagged  as  string,  then  an  empty  string is
		     returned.

       pathName text operation ?args?
	      This operation is used to provide text editing for  cells	 (data
	      fields  in  a  column)  or  entry labels.	 It has several forms,
	      depending on operation:

	      pathName text apply
		     Applies the edited buffer, replacing the entry  label  or
		     data field. The edit window is hidden.

	      pathName text cancel
		     Cancels  the editing operation, reverting the entry label
		     or data value back to the previous value. The edit window
		     is hidden.

	      pathName text cget value
		     Returns  the  current  value  of the configuration option
		     given by option.  Option  may  have  any  of  the	values
		     accepted by the configure operation described below.

	      pathName text configure ?option value?
		     Query  or	modify	the  configuration options of the edit
		     window.  If  no  option  is  specified,  returns  a  list
		     describing	 all  of the available 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 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 and value are described  in  the  section
		     TEXT EDITING OPTIONS below.

       pathName text delete first last
	      Deletes  the characters in the edit buffer between the two given
	      character positions.

       pathName text get ?-root? x y

       pathName text icursor index

       pathName text index index
	      Returns the text index of given index.

       pathName text insert index string
	      Insert the text string string into the edit buffer at the	 index
	      index.  For example, the index 0 will prepend the buffer.

       pathName text selection args
	      This  operation  controls	 the  selection of the editing window.
	      Note that this differs from the selection of  entries.   It  has
	      the following forms:

	      pathName text selection adjust index
		     Adjusts either the first or last index of the selection.

	      pathName text selection clear
		     Clears the selection.

	      pathName text selection from index
		     Sets the anchor of the selection.

	      pathName text selection present
		     Indicates if a selection is present.

	      pathName text selection range start end
		     Sets both the anchor and mark of the selection.

	      pathName text selection to index
		     Sets the unanchored end (mark) of the selection.

       pathName toggle tagOrId
	      Opens or closes the node given by tagOrId.  If the corresponding
	      -opencommand or -closecommand option is set, then	 that  command
	      is also invoked.

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

	      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 treeview widget's text is off-
		     screen to the left, the middle 40% is visible in the win‐
		     dow,  and	40%  of	 the  text is off-screen to the right.
		     These are the same values passed to  scrollbars  via  the
		     -xscrollcommand option.

	      pathName xview tagOrId
		     Adjusts  the  view	 in  the  window so that the character
		     position given by tagOrId is displayed at the  left  edge
		     of	 the  window.	Character positions are defined by the
		     width of the character 0.

	      pathName xview moveto fraction
		     Adjusts the view in the window so that  fraction  of  the
		     total  width  of the treeview widget's text is off-screen
		     to the left.  fraction must be a fraction between	0  and
		     1.

	      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 by number character units (the width of the 0 char‐
		     acter) on the display;  if it  is	pages  then  the  view
		     adjusts by number screenfuls.  If number is negative then
		     characters farther to the left become visible;  if it  is
		     positive then characters farther to the right become vis‐
		     ible.

       pathName yview ?args?
	      This command is used to query and change the  vertical  position
	      of the text in the widget's window.  It can take any of the fol‐
	      lowing forms:

	      pathName yview
		     Returns a list containing two elements, both of which are
		     real  fractions between 0 and 1.  The first element gives
		     the position of the node at the top of the window,	 rela‐
		     tive  to  the  widget as a whole (0.5 means it is halfway
		     through the treeview window, for  example).   The	second
		     element  gives  the  position  of the node just after the
		     last one in the window,  relative	to  the	 widget	 as  a
		     whole.   These  are  the same values passed to scrollbars
		     via the -yscrollcommand option.

	      pathName yview tagOrId
		     Adjusts the view in the window so that the node given  by
		     tagOrId is displayed at the top of the window.

	      pathName yview moveto fraction
		     Adjusts  the view in the window so that the node given by
		     fraction appears at the top of the window.	 Fraction is a
		     fraction  between	0  and 1;  0 indicates the first node,
		     0.33 indicates the node one-third	the  way  through  the
		     treeview widget, and so on.

	      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,
		     the view adjusts up or down by number lines;   if	it  is
		     pages  then  the  view  adjusts by number screenfuls.  If
		     number is negative then earlier nodes become visible;  if
		     it is positive then later nodes become visible.

TREEVIEW OPTIONS
       In  addition  to	 the configure operation, widget configuration options
       may also be set by the Tk option command.  The class resource  name  is
       TreeView.

	      option add *TreeView.Foreground white
	      option add *TreeView.Background blue

       The following widget options are available:

       -activebackground color
	      Sets  the background color for active entries.  A node is active
	      when the mouse passes over it's  entry  or  using	 the  activate
	      operation.

       -activeforeground color
	      Sets  the foreground color of the active node.  A node is active
	      when the mouse passes over it's  entry  or  using	 the  activate
	      operation.

       -activeicons images
	      Specifies	 images to be displayed for an entry's icon when it is
	      active. Images is a list of two Tk images: the  first  image  is
	      displayed when the node is open, the second when it is closed.

       -autocreate boolean
	      If  boolean is true, automatically create missing ancestor nodes
	      when inserting new nodes. Otherwise flag an error.  The  default
	      is no.

       -allowduplicates boolean
	      If  boolean  is  true, allow nodes with duplicate pathnames when
	      inserting new nodes.  Otherwise flag an error.  The  default  is
	      no.

       -background color
	      Sets the background color of the widget.	The default is white.

       -borderwidth pixels
	      Sets  the width of the 3-D border around the outside edge of the
	      widget.  The -relief option determines if the border  is	to  be
	      drawn.  The default is 2.

       -closecommand string
	      Specifies a Tcl script to be invoked when a node is closed.  You
	      can overrider this for  individual  entries  using  the  entry's
	      -closecommand  option. The default is "".	 Percent substitutions
	      are performed on string before it is  executed.	The  following
	      substitutions are valid:

	      %W   The pathname of the widget.

	      %p   The name of the node.

	      %P   The full pathname of the node.

	      %#   The id of the node.

	      %%   Translates to a single percent.

       -cursor cursor
	      Specifies the widget's cursor.  The default cursor is "".

       -dashes number
	      Sets  the	 dash style of the horizontal and vertical lines drawn
	      connecting entries. Number is the length in pixels of the dashes
	      and gaps in the line. If number is 0, solid lines will be drawn.
	      The default is 1 (dotted).

       -exportselection boolean
	      Indicates if the	selection  is  exported.   If  the  widget  is
	      exporting	 its  selection	 then it will observe the standard X11
	      protocols for handling the selection.  Selections are  available
	      as  type STRING; the value of the selection will be the label of
	      the selected nodes, separated by newlines.  The default is no.

       -flat boolean
	      Indicates whether to display the tree as a flattened  list.   If
	      boolean is true, then the hierarchy will be a list of full paths
	      for the nodes.  This option also has affect on sorting.  See the
	      SORT  OPERATIONS	section	 for more information.	The default is
	      no.

       -focusdashes dashList
	      Sets the dash style of the outline rectangle  drawn  around  the
	      entry  label  of	the node that current has focus. Number is the
	      length in pixels of the dashes and gaps in the line.  If	number
	      is 0, a solid line will be drawn. The default is 1.

       -focusforeground color
	      Sets the color of the focus rectangle.  The default is black.

       -font fontName
	      Specifies	 the font for entry labels.  You can override this for
	      individual entries with the entry's -font configuration  option.
	      The default is *-Helvetica-Bold-R-Normal-*-12-120-*.

       -foreground color
	      Sets  the text color of entry labels.  You can override this for
	      individual entries with the  entry's  -foreground	 configuration
	      option.  The default is black.

       -height pixels
	      Specifies the requested height of widget.	 The default is 400.

       -hideroot boolean
	      If boolean is true, it indicates that no entry for the root node
	      should be displayed.  The default is no.

       -highlightbackground  color
	      Specifies the normal color of  the  traversal  highlight	region
	      when the widget does not have the input focus.

       -highlightcolor color
	      Specifies	 the  color  of the traversal highlight rectangle when
	      the widget has the input focus.  The default is black.

       -highlightthickness pixels
	      Specifies the width of the highlight rectangle  indicating  when
	      the  widget has input focus. The value may have any of the forms
	      acceptable to Tk_GetPixels.  If the  value  is  zero,  no	 focus
	      highlight will be displayed.  The default is 2.

       -icons images
	      Specifies	 images for the entry's icon.  Images is a list of two
	      Tk images: the first image is displayed when the node  is	 open,
	      the second when it is closed.

       -linecolor color
	      Sets  the	 color	of the connecting lines drawn between entries.
	      The default is black.

       -linespacing pixels
	      Sets the number of pixels spacing between entries.  The  default
	      is 0.

       -linewidth pixels
	      Set  the width of the lines drawn connecting entries.  If pixels
	      is 0, no vertical or horizontal lines are drawn.	The default is
	      1.

       -opencommand string
	      Specifies	 a  Tcl script to be invoked when a node is open.  You
	      can override this for individual entries with the entry's -open‐
	      command  configuration option.  The default is "".  Percent sub‐
	      stitutions are performed on string before it is  executed.   The
	      following substitutions are valid:

	      %W   The pathname of the widget.

	      %p   The name of the node.

	      %P   The full pathname of the node.

	      %#   The id of the node.

	      %%   Translates to a single percent.

       -relief relief
	      Specifies	 the  3-D effect for the widget.  Relief specifies how
	      the treeview widget should  appear  relative  to	widget	it  is
	      packed  into;  for  example,  raised  means  the treeview widget
	      should appear to protrude.  The default is sunken.

       -scrollmode mode
	      Specifies the style of scrolling	to  be	used.	The  following
	      styles are valid.	 This is the default is hierbox.

	      listbox	  Like	the  listbox widget, the last entry can always
			  be scrolled to the top of the widget	window.	  This
			  allows  the  scrollbar  thumb	 to shrink as the last
			  entry is scrolled upward.

	      hierbox	  Like the hierbox widget, the last entry can only  be
			  viewed  at  the  bottom  of  the widget window.  The
			  scrollbar stays a constant size.

	      canvas	  Like the canvas widget, the entries are bound within
			  the scrolling area.

       -selectbackground color
	      Sets the background color selected node entries.	The default is
	      #ffffea.

       -selectborderwidth pixels
	      Sets the width of the raised 3-D border drawn around the	labels
	      of  selected  entries.  The default is 0.	 -selectcommand string
	      Specifies a Tcl script to invoked when the set of selected nodes
	      changes.	The default is "".

       -selectforeground color
	      Sets  the	 color	of  the	 labels of selected node entries.  The
	      default is black.

       -selectmode mode
	      Specifies the selection mode. If mode is single, only  one  node
	      can  be  selected at a time.  If multiple more than one node can
	      be selected.  The default is single.

       -separator string
	      Specifies the character sequence to use when spliting  the  path
	      components.   The separator may be several characters wide (such
	      as "::") Consecutive separators in a  pathname  are  treated  as
	      one.   If	 string	 is  the  empty	 string, the pathnames are Tcl
	      lists.  Each element is a path component.	  The default is "".

       -showtitles boolean
	      If boolean is false, column titles are not  be  displayed.   The
	      default is yes.

       -sortselection boolean
	      If  boolean  is true, nodes in the selection are ordered as they
	      are currently displayed (depth-first  or	sorted),  not  in  the
	      order they were selected. The default is no.

       -takefocus focus
	      Provides	information  used when moving the focus from window to
	      window via keyboard traversal (e.g.,  Tab	 and  Shift-Tab).   If
	      focus  is	 0,  this  means  that	this  window should be skipped
	      entirely during keyboard traversal.  1 means that the this  win‐
	      dow should always receive the input focus.  An empty value means
	      that the traversal scripts make the decision whether to focus on
	      the window.  The default is "1".

       -trim string
	      Specifies	 a  string leading characters to trim from entry path‐
	      names before parsing.  This only makes sense if  the  -separator
	      is also set.  The default is "".

       -width pixels
	      Sets  the	 requested  width of the widget.  If pixels is 0, then
	      the with is computed from the contents of the  treeview  widget.
	      The default is 200.

       -xscrollcommand string
	      Specifies the prefix for a command used to communicate with hor‐
	      izontal scrollbars.  Whenever the horizontal view	 in  the  wid‐
	      get's  window changes, the widget will generate a Tcl command by
	      concatenating the scroll	command	 and  two  numbers.   If  this
	      option is not specified, then no command will be executed.

       -xscrollincrement pixels
	      Sets  the	 horizontal scrolling distance. The default is 20 pix‐
	      els.

       -yscrollcommand string
	      Specifies the prefix for a command used to communicate with ver‐
	      tical  scrollbars.    Whenever the vertical view in the widget's
	      window changes, the widget will generate a Tcl command  by  con‐
	      catenating  the  scroll command and two numbers.	If this option
	      is not specified, then no command will be executed.

       -yscrollincrement pixels
	      Sets the vertical scrolling distance. The default is 20 pixels.

ENTRY OPTIONS
       Many widget configuration options have counterparts  in	entries.   For
       example,	 there is a -closecommand configuration option for both widget
       itself and for individual entries.  Options set at the widget level are
       global for all entries.	If the entry configuration option is set, then
       it overrides the widget option.	This is done to avoid  wasting	memory
       by replicated options.  Most entries will have redundant options.

       There is no resource class or name for entries.

       -activeicons images
	      Specifies	 images to be displayed as the entry's icon when it is
	      active. This overrides  the  global  -activeicons	 configuration
	      option  for  the	specific  entry.   Images  is a list of two Tk
	      images: the first image is displayed when the node is open,  the
	      second when it is closed.

       -bindtags tagList
	      Specifies	 the  binding  tags  for  nodes.  TagList is a list of
	      binding tag names.  The tags and their order will determine  how
	      events are handled for nodes.  Each tag in the list matching the
	      current event sequence will have its Tcl command executed.   The
	      default value is all.

       -button string
	      Indicates	 whether a button should be displayed on the left side
	      of the node entry.  String can be yes, no, or  auto.   If	 auto,
	      then  a  button is automatically displayed if the node has chil‐
	      dren.  This is the default.

       -closecommand string
	      Specifies a Tcl script to be invoked when the  node  is  closed.
	      This  overrides  the global -closecommand option for this entry.
	      The default is  "".   Percent  substitutions  are	 performed  on
	      string  before  it is executed.  The following substitutions are
	      valid:

	      %W   The pathname of the widget.

	      %p   The name of the node.

	      %P   The full pathname of the node.

	      %#   The id of the node.

	      %%   Translates to a single percent.

       -data string
	      Sets data fields for the node.  String is a list	of  name-value
	      pairs to be set. The default is "".

       -font fontName
	      Sets  the	 font  for  entry labels.  This overrides the widget's
	      -font option for this node.  The default is  *-Helvetica-Bold-R-
	      Normal-*-12-120-*.

       -foreground color
	      Sets the text color of the entry label.  This overrides the wid‐
	      get's -foreground configuration option.  The default is "".

       -icons images
	      Specifies images to be displayed for  the	 entry's  icon.	  This
	      overrides	 the  global -icons configuration option.  Images is a
	      list of two Tk images: the first image  is  displayed  when  the
	      node is open, the second when it is closed.

       -label string
	      Sets  the text for the entry's label.  If not set, this defaults
	      to the name of the node. The default is "".

       -opencommand string
	      Specifies a Tcl script to be invoked when the entry  is  opened.
	      This  overrides  the widget's -opencommand option for this node.
	      The default is  "".   Percent  substitutions  are	 performed  on
	      string  before  it is executed.  The following substitutions are
	      valid:

	      %W   The pathname of the widget.

	      %p   The name of the node.

	      %P   The full pathname of the node.

	      %#   The id of the node.

	      %%   Translates to a single percent.

BUTTON OPTIONS
       Button configuration options may also be set  by	 the  option  command.
       The resource subclass is Button.	  The resource name is always button.

	      option add *TreeView.Button.Foreground white
	      option add *TreeView.button.Background blue

       The following are the configuration options available for buttons.

       -activebackground color
	      Sets  the	 background color of active buttons.  A button is made
	      active when the mouse passes over it or by the  button  activate
	      operation.

       -activeforeground color
	      Sets  the	 foreground color of active buttons.  A button is made
	      active when the mouse passes over it or by the  button  activate
	      operation.

       -background color
	      Sets the background of the button.  The default is white.

       -borderwidth pixels
	      Sets the width of the 3-D border around the button.  The -relief
	      option determines if a border is to be drawn.  The default is 1.

       -closerelief relief
	      Specifies the 3-D effect for the closed  button.	 Relief	 indi‐
	      cates  how  the button should appear relative to the widget; for
	      example, raised means the button should appear to protrude.  The
	      default is solid.

       -cursor cursor
	      Sets the widget's cursor.	 The default cursor is "".

       -foreground color
	      Sets the foreground color of buttons.  The default is black.

       -images images
	      Specifies	 images	 to  be displayed for the button.  Images is a
	      list of two Tk images: the first image  is  displayed  when  the
	      button  is open, the second when it is closed.  If the images is
	      the empty string,	 then  a  plus/minus  gadget  is  drawn.   The
	      default is "".

       -openrelief relief
	      Specifies	 the  3-D effect of the open button.  Relief indicates
	      how the button should appear relative to the widget;  for	 exam‐
	      ple,  raised  means  the	button should appear to protrude.  The
	      default is flat.

       -size pixels
	      Sets the requested size of the button.  The default is 0.

COLUMN OPTIONS
       Column configuration options may also be set  by	 the  option  command.
       The resource subclass is Column.	  The resource name is the name of the
       column.

	      option add *TreeView.Column.Foreground white
	      option add *TreeView.treeView.Background blue

       The following configuration options are available for columns.

       -background color
	      Sets the background color of the	column.	  This	overrides  the
	      widget's -background option. The default is white.

       -borderwidth pixels
	      Sets  the	 width	of  the 3-D border of the column.  The -relief
	      option determines if a border is to be drawn.  The default is 0.

       -edit boolean
	      Indicates if the column's data fields can be edited. If  boolean
	      is  false, the data fields in the column may not be edited.  The
	      default is yes.

       -foreground color
	      Specifies the foreground color of the column.  You can  override
	      this for individual entries with the entry's -foreground option.
	      The default is black.

       -font fontName
	      Sets the font for a column.  You can override this for  individ‐
	      ual  entries  with  the  entry's	-font  option.	The default is
	      *-Helvetica-Bold-R-Normal-*-12-120-*.

       -hide boolean
	      If boolean is true, the column is not displayed.	The default is
	      yes.

       -justify justify
	      Specifies	 how  the column data fields title should be justified
	      within the column.  This matters only when the column  is	 wider
	      than the data field to be display.  Justify must be left, right,
	      or center.  The default is left.

       -pad pad
	      Specifies how much padding for the left and right sides  of  the
	      column.	Pad  is a list of one or two screen distances.	If pad
	      has two elements, the left side of the column is padded  by  the
	      first  distance  and  the	 right side by the second.  If pad has
	      just one distance, both the left	and  right  sides  are	padded
	      evenly.  The default is 2.

       -relief relief
	      Specifies	 the  3-D  effect of the column.  Relief specifies how
	      the column should appear relative to the	widget;	 for  example,
	      raised  means the column should appear to protrude.  The default
	      is flat.

       -state state
	      Sets the state of the column. If state is disable then the  col‐
	      umn title can not be activated nor invoked.  The default is nor‐
	      mal.

       -text string
	      Sets the title for the column.  The default is "".

       -titleforeground color
	      Sets the foreground color of the column title.  The  default  is
	      black.

       -titleshadow color
	      Sets  the	 color	of  the	 drop shadow of the column title.  The
	      default is "".

       -width pixels
	      Sets the requested width of the column.  This overrides the com‐
	      puted with of the column.	 If pixels is 0, the width is computed
	      as from the contents of the column. The default is 0.

TEXT EDITING OPTIONS
       Text edit window configuration options may also be set  by  the	option
       command.	 The  resource	class is TreeViewEditor.  The resource name is
       always edit.

	      option add *TreeViewEditor.Foreground white
	      option add *edit.Background blue

       The following are the configuration  options  available	for  the  text
       editing window.

       -background color
	      Sets  the	 background  of	 the text edit window.	The default is
	      white.

       -borderwidth pixels
	      Sets the width of the 3-D border around the  edit	 window.   The
	      -relief  option  determines  if  a  border  is to be drawn.  The
	      default is 1.

       -exportselection boolean
	      Indicates if the text selection is exported.  If the edit window
	      is exporting its selection then it will observe the standard X11
	      protocols for handling the selection.  Selections are  available
	      as type STRING.  The default is no.

       -relief relief
	      Specifies	 the  3-D effect of the edit window.  Relief indicates
	      how the background should appear relative to  the	 edit  window;
	      for  example,  raised means the background should appear to pro‐
	      trude.  The default is solid.

       -selectbackground color
	      Sets the background of the selected text	in  the	 edit  window.
	      The default is white.

       -selectborderwidth pixels
	      Sets the width of the 3-D border around the selected text in the
	      edit window.  The -selectrelief option determines if a border is
	      to be drawn.  The default is 1.

       -selectforeground color
	      Sets  the	 foreground  of	 the selected text in the edit window.
	      The default is white.

       -selectrelief relief
	      Specifies the 3-D effect of the selected text in the  edit  win‐
	      dow.   Relief  indicates	how the text should appear relative to
	      the edit window; for  example,  raised  means  the  text	should
	      appear to protrude.  The default is flat.

DEFAULT BINDINGS
       Tk  automatically  creates  class bindings for treeviews that give them
       Motif-like behavior.  Much of the behavior  of  a  treeview  widget  is
       determined  by its -selectmode option, which selects one of two ways of
       dealing with the selection.

       If the selection mode is single, only one node can  be  selected	 at  a
       time.   Clicking button 1 on an node selects it and deselects any other
       selected item.

       If the selection mode  is  multiple,  any  number  of  entries  may  be
       selected	 at  once,  including discontiguous ranges.  Clicking Control-
       Button-1 on a node entry toggles its selection state without  affecting
       any other entries.  Pressing Shift-Button-1 on a node entry selects it,
       extends the selection.

       [1]    In extended mode, the selected range can be adjusted by pressing
	      button  1	 with the Shift key down:  this modifies the selection
	      to consist of the entries between the anchor and the entry under
	      the mouse, inclusive.  The un-anchored end of this new selection
	      can also be dragged with the button down.

       [2]    In extended mode, pressing button 1 with the  Control  key  down
	      starts  a toggle operation: the anchor is set to the entry under
	      the mouse, and its selection state is reversed.	The  selection
	      state  of	 other entries isn't changed.  If the mouse is dragged
	      with button 1 down, then the  selection  state  of  all  entries
	      between the anchor and the entry under the mouse is set to match
	      that of the anchor entry;	 the  selection	 state	of  all	 other
	      entries remains what it was before the toggle operation began.

       [3]    If  the mouse leaves the treeview window with button 1 down, the
	      window scrolls away from the mouse, making  information  visible
	      that  used  to  be  off-screen  on  the  side of the mouse.  The
	      scrolling continues until the mouse re-enters  the  window,  the
	      button is released, or the end of the hierarchy is reached.

       [4]    Mouse  button  2 may be used for scanning.  If it is pressed and
	      dragged over the treeview widget, the contents of the  hierarchy
	      drag at high speed in the direction the mouse moves.

       [5]    If  the  Up  or Down key is pressed, the location cursor (active
	      entry) moves up or down one entry.  If  the  selection  mode  is
	      browse  or  extended  then the new active entry is also selected
	      and all other entries are deselected.  In extended mode the  new
	      active entry becomes the selection anchor.

       [6]    In extended mode, Shift-Up and Shift-Down move the location cur‐
	      sor (active entry) up or down one	 entry	and  also  extend  the
	      selection	 to  that  entry in a fashion similar to dragging with
	      mouse button 1.

       [7]    The Left and Right keys scroll the treeview widget view left and
	      right  by	 the  width of the character 0.	 Control-Left and Con‐
	      trol-Right scroll the treeview widget view left and right by the
	      width of the window.  Control-Prior and Control-Next also scroll
	      left and right by the width of the window.

       [8]    The Prior and Next keys scroll the treeview widget view  up  and
	      down by one page (the height of the window).

       [9]    The Home and End keys scroll the treeview widget horizontally to
	      the left and right edges, respectively.

       [10]   Control-Home sets the location cursor to the  the	 first	entry,
	      selects that entry, and deselects everything else in the widget.

       [11]   Control-End  sets	 the  location	cursor	to the the last entry,
	      selects that entry, and deselects everything else in the widget.

       [12]   In extended mode, Control-Shift-Home extends  the	 selection  to
	      the  first  entry and Control-Shift-End extends the selection to
	      the last entry.

       [13]   In multiple mode, Control-Shift-Home moves the  location	cursor
	      to the first entry and Control-Shift-End moves the location cur‐
	      sor to the last entry.

       [14]   The space and Select keys make a selection at the location  cur‐
	      sor  (active  entry)  just as if mouse button 1 had been pressed
	      over this entry.

       [15]   In extended mode, Control-Shift-space  and  Shift-Select	extend
	      the  selection  to the active entry just as if button 1 had been
	      pressed with the Shift key down.

       [16]   In extended mode, the Escape key cancels the most recent	selec‐
	      tion and restores all the entries in the selected range to their
	      previous selection state.

       [17]   Control-slash selects everything in the widget, except in single
	      and  browse modes, in which case it selects the active entry and
	      deselects everything else.

       [18]   Control-backslash deselects everything in the widget, except  in
	      browse mode where it has no effect.

       [19]   The  F16	key (labelled Copy on many Sun workstations) or Meta-w
	      copies the selection in the widget to the clipboard, if there is
	      a selection.

       The  behavior  of treeview widgets can be changed by defining new bind‐
       ings for individual widgets or by redefining the class bindings.

   WIDGET BINDINGS
       In addition to the above behavior, the following additional behavior is
       defined by the default widget class (TreeView) bindings.

       <ButtonPress-2>
	      Starts scanning.

       <B2-Motion>
	      Adjusts the scan.

       <ButtonRelease-2>
	      Stops scanning.

       <B1-Leave>
	      Starts auto-scrolling.

       <B1-Enter>
	      Starts auto-scrolling

       <KeyPress-Up>
	      Moves the focus to the previous entry.

       <KeyPress-Down>
	      Moves the focus to the next entry.

       <Shift-KeyPress-Up>
	      Moves the focus to the previous sibling.

       <Shift-KeyPress-Down>
	      Moves the focus to the next sibling.

       <KeyPress-Prior>
	      Moves  the  focus	 to first entry.  Closed or hidden entries are
	      ignored.

       <KeyPress-Next>
	      Move the focus to the last entry. Closed or hidden  entries  are
	      ignored.

       <KeyPress-Left>
	      Closes  the entry.  It is not an error if the entry has no chil‐
	      dren.

       <KeyPress-Right>
	      Opens the entry, displaying its children.	 It is not an error if
	      the entry has no children.

       <KeyPress-space>
	      In  "single"  select mode this selects the entry.	 In "multiple"
	      mode, it toggles the entry (if it was previous selected,	it  is
	      not deselected).

       <KeyRelease-space>
	      Turns off select mode.

       <KeyPress-Return>
	      Sets the focus to the current entry.

       <KeyRelease-Return>
	      Turns off select mode.

       <KeyPress>
	      Moves  to	 the  next  entry  whose  label starts with the letter
	      typed.

       <KeyPress-Home>
	      Moves the focus to first entry.  Closed or  hidden  entries  are
	      ignored.

       <KeyPress-End>
	      Move  the	 focus to the last entry. Closed or hidden entries are
	      ignored.

       <KeyPress-F1>
	      Opens all entries.

       <KeyPress-F2>
	      Closes all entries (except root).

   BUTTON BINDINGS
       Buttons have bindings.  There are associated  with  the	"all"  bindtag
       (see  the  entry's -bindtag option).  You can use the bind operation to
       change them.

       <Enter>
	      Highlights the button of the current entry.

       <Leave>
	      Returns the button back to its normal state.

       <ButtonRelease-1>
	      Adjust the view so that the current entry is visible.

   ENTRY BINDINGS
       Entries have default bindings.  There are  associated  with  the	 "all"
       bindtag (see the entry's -bindtag option).  You can use the bind opera‐
       tion to modify them.

       <Enter>
	      Highlights the current entry.

       <Leave>
	      Returns the entry back to its normal state.

       <ButtonPress-1>
	      Sets the selection anchor the current entry.

       <Double-ButtonPress-1>
	      Toggles the selection of the current entry.

       <B1-Motion>
	      For "multiple" mode only.	 Saves the  current  location  of  the
	      pointer for auto-scrolling.  Resets the selection mark.

       <ButtonRelease-1>
	      For "multiple" mode only.	 Sets the selection anchor to the cur‐
	      rent entry.

       <Shift-ButtonPress-1>
	      For "multiple" mode only. Extends the selection.

       <Shift-Double-ButtonPress-1>
	      Place holder. Does nothing.

       <Shift-B1-Motion>
	      Place holder. Does nothing.

       <Shift-ButtonRelease-1>
	      Stop auto-scrolling.

       <Control-ButtonPress-1>
	      For "multiple" mode only.	 Toggles and extends the selection.

       <Control-Double-ButtonPress-1>
	      Place holder. Does nothing.

       <Control-B1-Motion>
	      Place holder. Does nothing.

       <Control-ButtonRelease-1>
	      Stops auto-scrolling.

       <Control-Shift-ButtonPress-1>
	      ???

       <Control-Shift-Double-ButtonPress-1>
	      Place holder. Does nothing.

       <Control-Shift-B1-Motion>
	      Place holder. Does nothing.

   COLUMN BINDINGS
       Columns have bindings too.  They are associated with the column's "all"
       bindtag	(see the column -bindtag option).  You can use the column bind
       operation to change them.

       <Enter>
	      Highlights the current column title.

       <Leave>
	      Returns the column back to its normal state.

       <ButtonRelease-1>
	      Invokes the command (see the column's -command option) if one if
	      specified.

   COLUMN RULE BINDINGS
       <Enter>
	      Highlights the current and activates the ruler.

       <Leave>
	      Returns  the  column  back  to its normal state. Deactivates the
	      ruler.

       <ButtonPress-1>
	      Sets the resize anchor for the column.

       <B1-Motion>
	      Sets the resize mark for the column.

       <ButtonRelease-1>
	      Adjust the size of the column, based upon the resize anchor  and
	      mark positions.

EXAMPLE
       The treeview command creates a new widget.

	      treeview .h -bg white

       A  new  Tcl  command  .h	 is also created.  This command can be used to
       query and modify the treeview widget.  For example, to change the back‐
       ground  color  of the table to "green", you use the new command and the
       widget's configure operation.

	      # Change the background color.
	      .h configure -background "green"

       By default, the treeview widget will automatically create  a  new  tree
       object  to  contain the data.  The name of the new tree is the pathname
       of the widget.  Above, the new tree object name is ".h".	 But  you  can
       use the -tree option to specify the name of another tree.

	      # View the tree "myTree".
	      .h configure -tree "myTree"

       When  a new tree is created, it contains only a root node.  The node is
       automatically opened.  The id of the root node is always 0 (you can use
       also use the special id root). The insert operation lets you insert one
       or more new entries into the tree.  The last  argument  is  the	node's
       pathname.

	      # Create a new entry named "myEntry"
	      set id [.h insert end "myEntry"]

       This  appends  a	 new  node named "myEntry".  It will positioned as the
       last child of the root of the tree (using the position "end").  You can
       supply another position to order the node within its siblings.

	      # Prepend "fred".
	      set id [.h insert 0 "fred"]

       Entry  names do not need to be unique.  By default, the node's label is
       its name.  To supply a different text label, add the -label option.

	      # Create a new node named "fred"
	      set id [.h insert end "fred" -label "Fred Flintstone"]

       The insert operation returns the id of the new node.  You can also  use
       the index operation to get this information.

	      # Get the id of "fred"
	      .h index "fred"

       To  insert  a  node  somewhere other than root, use the -at switch.  It
       takes the id of the node where the new child will be added.

	      # Create a new node "barney" in "fred".
	      .h insert -at $id end "barney"

       A pathname describes the path to an entry in  the  hierarchy.   It's  a
       list  of entry names that compose the path in the tree.	Therefore, you
       can also add "barney" to "fred" as follows.

	      # Create a new sub-entry of "fred"
	      .h insert end "fred barney"

       Every name in the list is ancestor of the  next.	  All  ancestors  must
       already exist.  That means that an entry "fred" is an ancestor of "bar‐
       ney" and must already exist.  But you can use the -autocreate  configu‐
       ration option to force the creation of ancestor nodes.

	      # Force the creation of ancestors.
	      .h configure -autocreate yes
	      .h insert end "fred barney wilma betty"

       Sometimes  the  pathname	 is  already separated by a character sequence
       rather than formed as a list.  A file name is a good example  of	 this.
       You  can	 use  the  -separator  option to specify a separator string to
       split the path into its components.  Each pathname inserted is automat‐
       ically split using the separator string as a separator.	Multiple sepa‐
       rators are treated as one.

	      .h configure -separator /
	      .h insert end "/usr/local/tcl/bin"

       If the path is prefixed by extraneous characters, you can automatically
       trim  it	 off  using  the -trim option.	It removed the string from the
       path before it is parsed.

	      .h configure -trim C:/windows -separator /
	      .h insert end "C:/window/system"

       You can insert more than one entry at a time with the insert operation.
       This can be much faster than looping over a list of names.

	      # The slow way
	      foreach f [glob $dir/*] {
		  .h insert end $f
	      }
	      # The fast way
	      eval .h insert end [glob $dir/*]

       In this case, the insert operation will return a list of ids of the new
       entries.

       You can delete entries with the delete operation.  It takes one or more
       tags of ids as its argument. It deletes the entry and all its children.

	      .h delete $id

       Entries	have  several configuration options.  They control the appear‐
       ance of the entry's icon and label.  We have already  seen  the	-label
       option  that  sets the entry's text label.   The entry configure opera‐
       tion lets you set or modify an entry's configuration options.

	      .h entry configure $id -color red -font fixed

       You can hide an entry and its children using the -hide option.

	      .h entry configure $id -hide yes

       More that one entry can be configured at once.  All  entries  specified
       are configured with the same options.

	      .h entry configure $i1 $i2 $i3 $i4 -color brown

       An icon is displayed for each entry.  It's a Tk image drawn to the left
       of the label.  You can set the icon with the entry's -icons option.  It
       takes  a	 list  of  two	image  names: one to represent the open entry,
       another when it is closed.

	      set im1 [image create photo -file openfolder.gif]
	      set im2 [image create photo -file closefolder.gif]
	      .h entry configure $id -icons "$im1 $im2"

       If -icons is set to the empty string, no icons are display.

       If an entry has children, a button is displayed	to  the	 left  of  the
       icon. Clicking the mouse on this button opens or closes the sub-hierar‐
       chy.  The button is normally a + or - symbol, but can be configured  in
       a  variety  of ways using the button configure operation.  For example,
       the + and - symbols can be replaced with Tk images.

	      set im1 [image create photo -file closefolder.gif]
	      set im2 [image create photo -file downarrow.gif]
	      .h button configure $id -images "$im1 $im2" \
		  -openrelief raised -closerelief raised

       Entries can contain an arbitrary number of data	fields.	  Data	fields
       are  name-value	pairs.	 Both  the  value  and	name are strings.  The
       entry's -data option lets you set data fields.

	      .h entry configure $id -data {mode 0666 group users}

       The -data takes a list of name-value pairs.

       You can display these data fields as columns in	the  treeview  widget.
       You  can	 create	 and configure columns with the column operation.  For
       example, to add a new column to the widget, use the column insert oper‐
       ation.	The  last argument is the name of the data field that you want
       to display.

	      .h column insert end "mode"

       The column title is displayed at the top of the	column.	  By  default,
       it's is the field name.	You can override this using the column's -text
       option.

	      .h column insert end "mode" -text "File Permissions"

       Columns have several configuration options.  The column configure oper‐
       ation lets you query or modify column options.

	      .h column configure "mode" -justify left

       The  -justify  option says how the data is justified within in the col‐
       umn.  The -hide option indicates whether the column is displayed.

	      .h column configure "mode" -hide yes

       Entries can be selected by clicking on the mouse.  Selected entries are
       drawn  using the colors specified by the -selectforeground and -select‐
       background configuration options.  The selection itself is  managed  by
       the selection operation.

	      # Clear all selections
	      .h selection clear 0 end
	      # Select the root node
	      .h selection set 0

       The  curselection  operation  returns a list of ids of all the selected
       entries.

	      set ids [.h curselection]

       You can use the get operation to convert the ids to their pathnames.

	      set names [eval .h get -full $ids]

       If a treeview is exporting its selection	 (using	 the  -exportselection
       option),	 then  it will observe the standard X11 protocols for handling
       the selection.  Treeview selections are available as type  STRING;  the
       value  of  the selection will be the pathnames of the selected entries,
       separated by newlines.

       The treeview supports two modes of selection: single and multiple.   In
       single  select  mode,  only  one entry can be selected at a time, while
       multiple select mode allows several entries to be selected.   The  mode
       is set by the widget's -selectmode option.

	      .h configure -selectmode "multiple"

       You  can	 be  notified  when the list of selected entries changes.  The
       widget's -selectcommand specifies a Tcl procedure that is called	 when‐
       ever the selection changes.

	      proc SelectNotify { widget } {
		 set ids [$widget curselection]
	      }
	      .h configure -selectcommand "SelectNotify .h"

       The  widget supports the standard Tk scrolling and scanning operations.
       The treeview can be both horizontally and vertically.  You  can	attach
       scrollbars  to  the treeview the same way as the listbox or canvas wid‐
       gets.

	      scrollbar .xbar -orient horizontal -command ".h xview"
	      scrollbar .ybar -orient vertical -command ".h yview"
	      .h configure -xscrollcommand ".xbar set" \
		  -yscrollcommand ".ybar set"

       There are three different modes	of  scrolling:	listbox,  canvas,  and
       hierbox.	 In listbox mode, the last entry can always be scrolled to the
       top of the widget.  In hierbox mode, the last entry is always drawn  at
       the  bottom  of	the  widget.   The  scroll mode is set by the widget's
       -selectmode option.

	      .h configure -scrollmode "listbox"

       Entries can be programmatically opened or closed	 using	the  open  and
       close operations respectively.

	      .h open $id
	      .h close $id

       When  an entry is opened, a Tcl procedure can be automatically invoked.
       The -opencommand option specifies this procedure.  This	procedure  can
       lazily insert entries as needed.

	      proc AddEntries { dir } {
		 eval .h insert end [glob -nocomplain $dir/*]
	      }
	      .h configure -opencommand "AddEntries %P"

       Now  when  an  entry  is opened, the procedure AddEntries is called and
       adds children to the entry.  Before the command is invoked, special "%"
       substitutions (like bind) are performed. Above, %P is translated to the
       pathname of the entry.

       The same feature exists when an entry  is  closed.   The	 -closecommand
       option specifies the procedure.

	      proc DeleteEntries { id } {
		 .h entry delete $id 0 end
	      }
	      .h configure -closecommand "DeleteEntries %#"

       When  an	 entry	is  closed,  the procedure DeleteEntries is called and
       deletes the entry's children using the entry delete  operation  (%#  is
       the id of entry).

KEYWORDS
       treeview, widget

BLT				      2.4			   treeview(n)
[top]

List of man pages available for SuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net