Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ttk::treeview(n)	       Tk Themed Widget		      ttk::treeview(n)


       ttk::treeview - hierarchical multicolumn	data display widget

       ttk::treeview pathname ?options?

       The  ttk::treeview  widget displays a hierarchical collection of	items.
       Each item has a textual label, an optional image, and an	optional  list
       of  data	 values.   The data values are displayed in successive columns
       after the tree label.

       The order in which data values are displayed may	be controlled by  set-
       ting  the -displaycolumns widget	option.	 The tree widget can also dis-
       play column headings.  Columns may be accessed by number	or by symbolic
       names listed in the -columns widget option; see COLUMN IDENTIFIERS.

       Each  item  is  identified  by a	unique name.  The widget will generate
       item IDs	if they	are not	supplied by the	caller.	 There	is  a  distin-
       guished	root  item,  named {}.	The root item itself is	not displayed;
       its children appear at the top level of the hierarchy.

       Each item also has a list of tags, which	can be used to associate event
       bindings	with individual	items and control the appearance of the	item.

       Treeview	 widgets  support  horizontal  and vertical scrolling with the
       standard	-[xy]scrollcommand options and [xy]view	widget commands.

       -class		     -cursor		  -takefocus
       -style		     -xscrollcommand	  -yscrollcommand

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

       Command-Line Name:-columns
       Database	Name:  columns
       Database	Class: Columns

	      A	list of	column identifiers, specifying the number  of  columns
	      and their	names.

       Command-Line Name:-displaycolumns
       Database	Name:  displayColumns
       Database	Class: DisplayColumns

	      A	 list  of column identifiers (either symbolic names or integer
	      indices) specifying which	data columns are displayed and the or-
	      der  in  which  they appear, or the string #all.	If set to #all
	      (the default), all columns are shown in the order	given.

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

	      Specifies	the number of rows which should	be visible.  Note: the
	      requested	width is determined from the sum of the	column widths.

       Command-Line Name:-padding
       Database	Name:  padding
       Database	Class: Padding

	      Specifies	the internal padding for the widget.  The padding is a
	      list of up to four length	specifications;	see Ttk_GetPaddingFro-
	      mObj() for details.

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

	      Controls	how  the built-in class	bindings manage	the selection.
	      One of extended, browse, or none.

	      If set to	extended (the default),	 multiple  items  may  be  se-
	      lected.	If  browse,  only  a single item will be selected at a
	      time.  If	none, the selection will not be	changed.

	      Note that	application code and tag bindings can set  the	selec-
	      tion however they	wish, regardless of the	value of -selectmode.

       Command-Line Name:-show
       Database	Name:  show
       Database	Class: Show

	      A	list containing	zero or	more of	the following values, specify-
	      ing which	elements of the	tree to	display.

	      tree   Display tree labels in column #0.

		     Display the heading row.

	      The default is tree headings, i.e., show all elements.

	      NOTE: Column #0 always refers to the tree	column,	even if	 -show
	      tree is not specified.

       pathname	bbox item ?column?
	      Returns the bounding box (relative to the	treeview widget's win-
	      dow) of the specified item in the	form x	y  width  height.   If
	      column  is specified, returns the	bounding box of	that cell.  If
	      the item is not visible (i.e., if	it is a	descendant of a	closed
	      item or is scrolled offscreen), returns the empty	list.

       pathname	cget option
	      Returns the current value	of the specified option; see ttk::wid-

       pathname	children item ?newchildren?
	      If newchildren is	not specified, returns the  list  of  children
	      belonging	to item.

	      If  newchildren  is  specified,  replaces	item's child list with
	      newchildren.  Items in the old child list	not present in the new
	      child  list  are	detached  from the tree.  None of the items in
	      newchildren may be an ancestor of	item.

       pathname	column column ?-option ?value -option value...?
	      Query or modify the options for the  specified  column.	If  no
	      -option  is  specified,  returns	a  dictionary  of option/value
	      pairs.  If a single -option is specified,	returns	the  value  of
	      that option.  Otherwise, the options are updated with the	speci-
	      fied values.  The	following options may be set on	each column:

	      -id name
		     The column	name.  This is a read-only option.  For	 exam-
		     ple,  [$pathname  column  #n -id] returns the data	column
		     associated	with display column #n.

		     Specifies how the text in this column should  be  aligned
		     with  respect to the cell.	One of n, ne, e, se, s,	sw, w,
		     nw, or center.

		     The minimum width of the column in	pixels.	 The  treeview
		     widget  will  not	make the column	any smaller than -min-
		     width when	the widget is resized or the user drags	a col-
		     umn separator.

		     Specifies whether or not the column's width should	be ad-
		     justed when the widget is resized.

	      -width w
		     The width of the column in	pixels.	 Default is  something
		     reasonable, probably 200 or so.

	      Use pathname column #0 to	configure the tree column.

       pathname	configure ?option? ?value option value ...?
	      Modify or	query widget options; see ttk::widget(n).

       pathname	delete itemList
	      Deletes  each  of	the items in itemList and all of their descen-
	      dants.  The root item may	not be deleted.	 See also: detach.

       pathname	detach itemList
	      Unlinks all of the specified items in itemList  from  the	 tree.
	      The items	and all	of their descendants are still present and may
	      be reinserted at another point in	the tree with the move	opera-
	      tion,  but  will	not be displayed until that is done.  The root
	      item may not be detached.	 See also: delete.

       pathname	exists item
	      Returns 1	if the specified item is present in the	tree, 0	other-

       pathname	focus ?item?
	      If  item	is specified, sets the focus item to item.  Otherwise,
	      returns the current focus	item, or {} if there is	none.

       pathname	heading	column ?-option	?value -option value...?
	      Query or modify the heading options for  the  specified  column.
	      Valid options are:

	      -text text
		     The text to display in the	column heading.

	      -image imageName
		     Specifies	an image to display to the right of the	column

	      -anchor anchor
		     Specifies how the heading text should be aligned.	One of
		     the standard Tk anchor values.

	      -command script
		     A script to evaluate when the heading label is pressed.

	      Use pathname heading #0 to configure the tree column heading.

       pathname	identify component x y
	      Returns a	description of the specified component under the point
	      given by x and y,	or the empty string if no  such	 component  is
	      present  at  that	 position.  The	following subcommands are sup-

	      pathname identify	region x y
		     Returns one of:

			    Tree heading area; use [pathname identify column x
			    y] to determine the	heading	number.

			    Space between two column headings; [pathname iden-
			    tify column	x y] will return  the  display	column
			    identifier	of  the	heading	to left	of the separa-

		     tree   The	tree area.

		     cell   A data cell.
	      pathname identify	item x y Returns the item ID of	 the  item  at
	      position y.

	      pathname identify	column x y
		     Returns  the  data	column identifier of the cell at posi-
		     tion x.  The tree column has ID #0.

	      pathname identify	element	x y
		     The element at position x,y.

	      pathname identify	row x y
		     Obsolescent synonym for pathname identify item.

	      See COLUMN IDENTIFIERS for a discussion of display  columns  and
	      data columns.

       pathname	index item
	      Returns  the  integer  index of item within its parent's list of

       pathname	insert parent index ?-id id? options...
	      Creates a	new item.  parent is the item ID of the	 parent	 item,
	      or the empty string {} to	create a new top-level item.  index is
	      an integer, or the value end, specifying where in	 the  list  of
	      parent's children	to insert the new item.	 If index is less than
	      or equal to zero,	the new	node is	inserted at the	beginning;  if
	      index  is	 greater  than or equal	to the current number of chil-
	      dren, it is inserted at the end.	If -id	is  specified,	it  is
	      used  as	the  item identifier; id must not already exist	in the
	      tree.  Otherwise,	a new unique identifier	is generated.

	      pathname insert returns the item identifier of the newly created
	      item.  See ITEM OPTIONS for the list of available	options.

       pathname	instate	statespec ?script?
	      Test the widget state; see ttk::widget(n).

       pathname	item item ?-option ?value -option value...?
	      Query  or	modify the options for the specified item.  If no -op-
	      tion is specified, returns a dictionary of  option/value	pairs.
	      If  a single -option is specified, returns the value of that op-
	      tion.  Otherwise,	the item's options are updated with the	speci-
	      fied  values.   See  ITEM	 OPTIONS for the list of available op-

       pathname	move item parent index
	      Moves item to position index in parent's list of	children.   It
	      is illegal to move an item under one of its descendants.

	      If index is less than or equal to	zero, item is moved to the be-
	      ginning; if greater than or equal	to the number of children,  it
	      is moved to the end.

       pathname	next item
	      Returns  the identifier of item's	next sibling, or {} if item is
	      the last child of	its parent.

       pathname	parent item
	      Returns the ID of	the parent of item, or {} if item  is  at  the
	      top level	of the hierarchy.

       pathname	prev item
	      Returns the identifier of	item's previous	sibling, or {} if item
	      is the first child of its	parent.

       pathname	see item
	      Ensure that item is visible: sets	all  of	 item's	 ancestors  to
	      -open  true, and scrolls the widget if necessary so that item is
	      within the visible portion of the	tree.

       pathname	selection ?selop itemList?
	      If selop is not specified, returns the list of  selected	items.
	      Otherwise, selop is one of the following:

	      pathname selection set itemList
		     itemList becomes the new selection.

	      pathname selection add itemList
		     Add itemList to the selection

	      pathname selection remove	itemList
		     Remove itemList from the selection

	      pathname selection toggle	itemList
		     Toggle the	selection state	of each	item in	itemList.

       pathname	set item ?column? ?value?
	      With  one	 argument,  returns a dictionary of column/value pairs
	      for the specified	item.  With two	arguments, returns the current
	      value  of	 the specified column.	With three arguments, sets the
	      value of column column in	item item to the specified value.  See

       pathname	state ?stateSpec?
	      Modify or	query the widget state;	see ttk::widget(n).

       pathName	tag args...

	      pathName tag bind	tagName	?sequence? ?script?
		     Add  a  Tk	binding	script for the event sequence sequence
		     to	the tag	tagName.  When an X event is delivered	to  an
		     item,  binding  scripts  for each of the item's -tags are
		     evaluated in order	as per bindtags(n).

		     <KeyPress>, <KeyRelease>, and virtual events are sent  to
		     the focus item.  <ButtonPress>, <ButtonRelease>, and <Mo-
		     tion> events  are	sent  to  the  item  under  the	 mouse
		     pointer.  No other	event types are	supported.

		     The binding script	undergoes %-substitutions before eval-
		     uation; see bind(n) for details.

	      pathName tag configure tagName ?option? ?value option value...?
		     Query or modify the options for  the  specified  tagName.
		     If	one or more option/value pairs are specified, sets the
		     value of those options for	the specified tag.  If a  sin-
		     gle option	is specified, returns the value	of that	option
		     (or the empty string if the option	has not	been specified
		     for  tagName).   With  no additional arguments, returns a
		     dictionary	of the option settings for tagName.   See  TAG
		     OPTIONS for the list of available options.

	      pathName tag has tagName ?item?
		     If	item is	specified, returns 1 or	0 depending on whether
		     the specified item	has the	named tag.  Otherwise, returns
		     a list of all items which have the	specified tag.

	      pathName tag names
		     Returns a list of all tags	used by	the widget.

	      pathName tag add tag items
		     Adds  the	specified tag to each of the listed items.  If
		     tag is already present for	a particular  item,  then  the
		     -tags for that item are unchanged.

	      pathName tag remove tag ?items?
		     Removes  the specified tag	from each of the listed	items.
		     If	items is omitted, removes tag from each	 item  in  the
		     tree.   If	tag is not present for a particular item, then
		     the -tags for that	item are unchanged.

       pathName	xview args
	      Standard command for horizontal scrolling; see widget(n).

       pathName	yview args
	      Standard command for vertical scrolling; see ttk::widget(n).

       The following item options may be specified for items in	the insert and
       item widget commands.

       Command-Line Name:-text
       Database	Name:  text
       Database	Class: Text

	      The textual label	to display for the item.

       Command-Line Name:-image
       Database	Name:  image
       Database	Class: Image

	      A	Tk image, displayed to the left	of the label.

       Command-Line Name:-values
       Database	Name:  values
       Database	Class: Values

	      The list of values associated with the item.

	      Each  item should	have the same number of	values as the -columns
	      widget option.  If there are fewer values	than columns, the  re-
	      maining values are assumed empty.	 If there are more values than
	      columns, the extra values	are ignored.

       Command-Line Name:-open
       Database	Name:  open
       Database	Class: Open

	      A	boolean	value indicating whether the item's children should be
	      displayed	(-open true) or	hidden (-open false).

       Command-Line Name:-tags
       Database	Name:  tags
       Database	Class: Tags

	      A	list of	tags associated	with this item.

       The following options may be specified on tags:

	      Specifies	the text foreground color.

	      Specifies	the cell or item background color.

       -font  Specifies	the font to use	when drawing text.

       -image Specifies	 the  item  image, in case the item's -image option is

       Column identifiers take any of the following forms:

       o      A	symbolic name from the list of -columns.

       o      An integer n, specifying the nth data column.

       o      A	string of the form #n, where n is an integer,  specifying  the
	      nth display column.

       NOTE: Item -values may be displayed in a	different order	than the order
       in which	they are stored.

       NOTE: Column #0 always refers to	the tree column, even if -show tree is
       not specified.

       A data column number is an index	into an	item's -values list; a display
       column number is	the column number in the tree  where  the  values  are
       displayed.  Tree	labels are displayed in	column #0.  If -displaycolumns
       is not set, then	data column n is displayed  in	display	 column	 #n+1.
       Again, column #0	always refers to the tree column.

       The treeview widget generates the following virtual events.

	      Generated	whenever the selection changes.

	      Generated	just before setting the	focus item to -open true.

	      Generated	just after setting the focus item to -open false.

       The  focus  and	selection widget commands can be used to determine the
       affected	item or	items.

       ttk::widget(n), listbox(n), image(n), bind(n)

Tk				     8.5.9		      ttk::treeview(n)


Want to link to this manual page? Use this URL:

home | help