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

FreeBSD Manual Pages

  
 
  

home | help
iwidgets::hierarchy(1)		[incr Widgets]		iwidgets::hierarchy(1)

______________________________________________________________________________

NAME
       iwidgets::hierarchy - Create and	manipulate a hierarchy widget

SYNOPSIS
       iwidgets::hierarchy pathName ?options?

INHERITANCE
       itk::Widget  <-	iwidgets::Labeledwidget	<- iwidgets::Scrolledwidget <-
       iwidgets::Hierarchy

STANDARD OPTIONS
       activeBackground	   activeForeground    background	 borderWidth
       cursor		   disabledForeground  foreground	 highlightColor
       highlightThickness  relief	       selectBackground	 selectForeground

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

ASSOCIATED OPTIONS
       activeRelief    elementBorderWidth	      jumptroughColor

       See the "scrollbar" widget manual entry for details on the above	 asso-
       ciated options.

       spacing1	       spacing2	      spacing3	      tabs

       See  the	"text" widget manual entry for details on the above associated
       options.

INHERITED OPTIONS
       labelBitmap     labelFont      labelImage      labelMargin
       labelPos	       labelText      labelVariable   sticky

       See the "labeledwidget" class manual entry for details on the inherited
       options.

WIDGET-SPECIFIC	OPTIONS
       Name:	       alwaysQuery
       Class:	       AlwaysQuery
       Command-Line Switch:	      -alwaysquery

	      Boolean  flag  which  tells  the hierarchy widget	weather	or not
	      each refresh of the display should be via	a new query using  the
	      command value of the -querycommand option	or use the values pre-
	      vious found the last time	the query was made.   The  default  is
	      no.

       Name:	       closedIcon
       Class:	       Icon
       Command-Line Switch:	      -closedicon

	      Specifies	 the  name of an existing closed icon image to be used
	      in the hierarchy before those nodes that are collapsed.	Should
	      one  not	be  provided,  then  a	folder icon will be generated,
	      pixmap if	possible, bitmap otherwise.

       Name:	       dblClickCommand
       Class:	       Command
       Command-Line Switch:	      -dblclickcommand

	      Specifies	a command to be	executed upon user double clicking via
	      mouse  button one	of the text label of an	entry. If this command
	      contains "%n", it	is replaced with  the  name  of	 the  selected
	      node.  Should  it	 contain  "%s" then a boolean indicator	of the
	      node's current selection status is substituted.

       Name:	       expanded
       Class:	       Expanded
       Command-Line Switch:	      -expanded

	      When true, the hierarchy will be completely expanded when	it  is
	      first  displayed.	 A fresh display can be	triggered by resetting
	      the -querycommand	option.	 The default is	false.

       Name:	       filter
       Class:	       Filter
       Command-Line Switch:	      -filter

	      When true	only the branch	nodes  and  selected  items  are  dis-
	      played.	This gives a compact view of important items.  The de-
	      fault is false.

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

	      Specifies	the height of the hierarchy as an  entire  unit.   The
	      value may	be specified in	any of the forms acceptable to Tk_Get-
	      Pixels.  Any additional space needed to display the other	compo-
	      nents  such as labels, margins, and scrollbars force the hierar-
	      chy to be	compressed.  A value of	zero along with	the same value
	      for the width causes the value given for the visibleitems	option
	      to be applied which administers geometry constraints in  a  dif-
	      ferent manner.  The default height is zero.

       Name:	       iconCommand
       Class:	       Command
       Command-Line Switch:	      -iconcommand

	      Specifies	a command to be	executed upon user selection via mouse
	      button one of any	additional icons given in the values  returned
	      by  the  command	associated  with the -querycommand option.  If
	      this command contains "%n", it is	replaced with the name of  the
	      node  the	icon belongs to.  Should it contain "%i" then the icon
	      name is  substituted.

       Name:	       iconDblCommand
       Class:	       Command
       Command-Line Switch:	      -icondblcommand

	      Specifies	a command to be	executed upon user double clicking via
	      mouse  button  one of the	icon of	an entry. If this command con-
	      tains "%n", it is	replaced with the name of the  node  the  icon
	      belongs to. Should it contain "%i" then the icon name is substi-
	      tuted.

       Name:	       imageCommand
       Class:	       Command
       Command-Line Switch:	      -imagecommand

	      Specifies	a command to be	executed upon user selecting an	 image
	      of an entry.  If this command contains "%n", it is replaced with
	      the name of the selected node. Should it	contain	 "%s"  then  a
	      boolean indicator	of the node's current selection	status is sub-
	      stituted.

       Name:	       imageDblCommand
       Class:	       Command
       Command-Line Switch:	      -imagedblcommand

	      Specifies	a command to be	executed upon user double clicking via
	      mouse  button one	of the image of	an entry. If this command con-
	      tains "%n", it is	replaced with the name of the  node  the  icon
	      belongs to. Should it contain "%i" then the icon name is substi-
	      tuted.

       Name:	       imageMenuLoadCommand
       Class:	       Command
       Command-Line Switch:	      -imagemenuloadcommand

	      Specifies	a command to be	executed upon user selection via mouse
	      button  three,  on the image or icon, that will dynamically load
	      the itemMenu for the widget.

       Name:	       markBackground
       Class:	       Foreground
       Command-Line Switch:	      -markbackground

	      Specifies	the background color to	 use  when  displaying	marked
	      nodes.

       Name:	       markForeground
       Class:	       Background
       Command-Line Switch:	      -markforeground

	      Specifies	 the  foreground  color	 to use	when displaying	marked
	      nodes.

       Name:	       menuCursor
       Class:	       Cursor
       Command-Line Switch:	      -menucursor

	      Specifies	the mouse cursor to be used for	 the  item  and	 back-
	      ground  menus.   The value may have any of the forms accept able
	      to Tk_GetCursor.

       Name:	       nodeIcon
       Class:	       Icon
       Command-Line Switch:	      -nodeicon

	      Specifies	the name of an existing	node icon image	to be used  in
	      the hierarchy before those nodes that are	leafs.	Should one not
	      be provided, then	a  dog-eared  page  icon  will	be  generated,
	      pixmap if	possible, bitmap otherwise.

       Name:	       openIcon
       Class:	       Icon
       Command-Line Switch:	      -openicon

	      Specifies	 the name of an	existing open icon image to be used in
	      the hierarchy before those nodes that are	expanded.  Should  one
	      not  be  provided,  then	an open	folder icon will be generated,
	      pixmap if	possible, bitmap otherwise.

       Name:	       queryCommand
       Class:	       Command
       Command-Line Switch:	      -querycommand

	      Specifies	the command executed to	query  the  contents  of  each
	      node.   If  this	command	contains "%n", it is replaced with the
	      name of the desired node.	 In its	simpilest form it  should  re-
	      turn  the	children of the	given node as a	list which will	be de-
	      picted in	the display.  Since the	names of the children are used
	      as tags in the underlying	text widget, each child	must be	unique
	      in the hierarchy.	 Due to	 the  unique  requirement,  the	 nodes
	      shall  be	reffered to as uids or uid in the singular sense.  The
	      format of	returned list is

		{uid [uid ...]}

		where uid is a unique id and primary key for the hierarchy en-
	      try

	      Should  the unique requirement pose a problem, the list returned
	      can take on another more extended	form which enables the associ-
	      ation of text to be displayed with the uids.  The	uid must still
	      be unique, but the text does not have to obey the	 unique	 rule.
	      In  addition,  the format	also allows the	specification of addi-
	      tional tags to be	used on	the same entry in the hierarchy	as the
	      uid  and	additional icons to be displayed just before the node.
	      The tags and icons are considered	to be the property of the user
	      in  that	the  hierarchy	widget will not	depend on any of their
	      values.  The extended format is

		{{uid [text [tags [icons]]]} {uid [text	[tags [icons]]]} ...}

		where uid is a unique id and primary key for the hierarchy en-
	      try
		      text is the text to be displayed for this	uid
		      tags is a	list of	user tags to be	applied	to the entry
		      icons is a list of icons to be displayed in front	of the
	      text

	      The hierarchy widget does	a look ahead from each node to	deter-
	      mine  if the node	has a children.	 This can be cost some perfor-
	      mace with	large hierarchies.  User's can avoid this by providing
	      a	 hint in the user tags.	 A tag of "leaf" or "branch" tells the
	      hierarchy	widget the information it needs	to know	thereby	avoid-
	      ing the look ahead operation.

       Name:	       hscrollMode
       Class:	       ScrollMode
       Command-Line Switch:	      -hscrollmode

	      Specifies	 the  the  display  mode to be used for	the horizontal
	      scrollbar: static, dynamic, or none.  In static mode, the	scroll
	      bar is displayed at all times.  Dynamic mode displays the	scroll
	      bar as required, and none	disables the scroll bar	display.   The
	      default is static.

       Name:	       sbWidth
       Class:	       Width
       Command-Line Switch:	      -sbwidth

	      Specifies	the width of the scrollbar in any of the forms accept-
	      able to Tk_GetPixels.

       Name:	       scrollMargin
       Class:	       Margin
       Command-Line Switch:	      -scrollmargin

	      Specifies	the distance between the text portion of the hierarchy
	      and  the scrollbars in any of the	forms acceptable to Tk_GetPix-
	      els.  The	default	is 3 pixels.

       Name:	       selectCommand
       Class:	       Command
       Command-Line Switch:	      -selectcommand

	      Specifies	a Tcl command to be evaluated when you select  a  node
	      in  the  hierarchy via left mouse	click.	If "%n"	is included in
	      the command, it is substituted with the node  name.   Similarly,
	      "%s"  is substituted with	the node's current selection status: 1
	      for selected, 0 otherwise.

       Name:	       textBackground Class:	      Background  Command-Line
       Switch:		 -textbackground

	      Specifies	the background color for the text portion of the hier-
	      archy in any of the forms	acceptable to Tk_GetColor.

       Name:	       textFont
       Class:	       Font
       Command-Line Switch:	      -textfont

	      Specifies	the font to be used in the text	portion	of the hierar-
	      chy.

       Name:	       textMenuLoadCommand
       Class:	       Command
       Command-Line Switch:	      -textmenuloadcommand

	      Specifies	a command to be	executed upon user selection via mouse
	      button three, that will dynamically load the  itemMenu  for  the
	      widget.

       Name:	       visibleitems
       Class:	       VisibleItems
       Command-Line Switch:	      -visibleitems

	      Specifies	the widthxheight in characters and lines for the hier-
	      archy.  This option is only administered if the width and	height
	      options  are  both  set to zero, otherwise they take precedence.
	      The default value	is 80x24.  With	the  visibleitems  option  en-
	      gaged, geometry constraints are maintained only on the text por-
	      tion of the hierarchy.  The size of the other components such as
	      labels,  margins,	and scroll bars, are additive and independent,
	      effecting	the overall  size  of  the  hierarchy.	 In  contrast,
	      should  the  width and height options have non zero values, they
	      are applied to the hierarchy as a	whole.	The hierarchy is  com-
	      pressed or expanded to maintain the geometry constraints.

       Name:	       vscrollMode
       Class:	       ScrollMode
       Command-Line Switch:	      -vscrollmode

	      Specifies	 the  the  display  mode  to  be used for the vertical
	      scrollbar: static, dynamic, or none.  In static mode, the	scroll
	      bar is displayed at all times.  Dynamic mode displays the	scroll
	      bar as required, and none	disables the scroll bar	display.   The
	      default is static.

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

	      Specifies	 the  width  of	 the hierarchy as an entire unit.  The
	      value may	be specified in	any of the forms acceptable to Tk_Get-
	      Pixels.  Any additional space needed to display the other	compo-
	      nents such as labels, margins, and  scrollbars  force  the  text
	      portion  of  the	hierarchy  to  be compressed.  A value of zero
	      along with the same value	for the	height causes the value	 given
	      for  the visibleitems option to be applied which administers ge-
	      ometry constraints in a different	manner.	 The default width  is
	      zero.

______________________________________________________________________________

DESCRIPTION
       The  iwidgets::hierarchy	 command creates a hierarchical	data view wid-
       get.  It	allows the graphical management	of a a list of nodes that  can
       be expanded or collapsed.  Individual nodes can be highlighted.	Click-
       ing with	the right mouse	button on any item brings up  a	 special  item
       menu.   Clicking	 on  the  background  area brings up a different popup
       menu.  Options exist to provide user control over the  loading  of  the
       nodes  and actions associated with node selection.  Since the hierarchy
       is based	on the scrolledtext widget, it includes	options	to control the
       method  in  which the scrollbars	are displayed, i.e. statically or  dy-
       namically.  Options also	exist for adding a label to the	hierarchy  and
       controlling its position.

METHODS
       The iwidgets::hierarchy command creates a new Tcl command whose name is
       pathName.  This command may be used to invoke various operations	on the
       widget.	 It  has  the following	general	form: pathName option ?arg arg
       ...?  Option and	the args determine the exact behavior of the  command.
       The following commands are possible for hierarchy widgets:

ASSOCIATED METHODS
       bbox	       compare	      debug	      delete
       dlineinfo       dump	      get	      index
       insert	       scan	      search	      see
       tag	       window	      xview	      yview

       See the "text" manual entry for details on the standard methods.

WIDGET-SPECIFIC	METHODS
       pathName	cget option
	      Returns  the  current value of the configuration option given by
	      option.  Option may have any of the values accepted by the iwid-
	      gets::hierarchy command.

       pathName	clear
	      Removes  all items from the hierarchy display including all tags
	      and icons.  The display will remain empty	until the  -filter  or
	      -querycommand options are	set.

       pathName	collapse uid
	      Collapses	 the  hierarchy	 beneath  the  node with the specified
	      unique id	by one level.  Since this can take a moment for	 large
	      hierarchies,  the	 cursor	 will be changed to a watch during the
	      collapse.	 Also, if any of the nodes beneath the node being col-
	      lapsed are selected, their status	is changed to unselected.

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

       pathName	current
	      Returns the tags for the node that was most recently selected by
	      the right	mouse button when the item menu	was  posted.   Usually
	      used by the code in the item menu	to figure out what item	is be-
	      ing manipulated.

       pathName	draw ?when?
	      Performs a complete redraw of the	entire hierarchy.  When	may be
	      either  -now  or -eventually where the latter means the draw can
	      be performed after idle.

       pathName	expand uid
	      Expands the hierarchy beneath the	node with the specified	unique
	      id by one	level.	Since this can take a moment for large hierar-
	      chies, the cursor	will be	changed	to a watch during  the	expan-
	      sion.

       pathName	expanded uid
	      Returns  the  current  state  of expansion for the node with the
	      specified	unique id.

       pathName	expState
	      Returns a	list of	all expanded nodes in the tree.

       pathName	mark option ?arg arg ...?
	      This command is used to manipulate marks which is	quite  similar
	      to  selection, adding a secondary	means of hilighting an item in
	      the hierarchy.  The exact	behavior of the	command	depends	on the
	      option  argument	that follows the mark argument.	 The following
	      forms of the command are currently supported:

	      pathName mark clear
		     Clears all	the currently marked nodes in the hierarchy.

	      pathName mark add	uid ?uid uid ...?
		     Marks the nodes with the specified	uids in	the  hierarchy
		     using the -markbackground and -markforeground options and
		     without affecting the mark	state of any other nodes  that
		     were already marked.

	      pathName mark remove uid ?uid uid	...?
		     Unmarks  the nodes	with the specified uids	in the hierar-
		     chy without affecting the mark state of any  other	 nodes
		     that were already marked.

	      pathName mark get
		     Returns  a	 list  of  the	unique	ids that are currently
		     marked.

       pathName	refresh	uid
	      Performs a redraw	of a specific node that	has the	given uid.  If
	      the  node	 is  not  currently  visible or	in other words already
	      drawn on the text, then no action	is taken.

       pathName	prune uid
	      Removes the node specified by the	given uid from the  hierarchy.
	      Should  the node have children, then all of its children will be
	      removed as well.

       pathName	selection option ?arg arg ...?
	      This command is used to manipulate the selection of nodes	in the
	      hierarchy.  The exact behavior of	the command depends on the op-
	      tion argument that follows the selection argument.  The  follow-
	      ing forms	of the command are currently supported:

	      pathName selection clear
		     Clears all	the currently selected nodes in	the hierarchy.

	      pathName selection add uid ?uid uid ...?
		     Selects  the nodes	with the specified uids	in the hierar-
		     chy using the  -selectionbackground  and  -selectionfore-
		     ground  options and without affecting the selection state
		     of	any other nodes	that were already selected.

	      pathName selection remove	uid ?uid uid ...?
		     Deselects the nodes with the specified uids in the	 hier-
		     archy  without affecting the selection state of any other
		     nodes that	were already selected.

	      pathName selection get
		     Returns a list of the unique ids that are	currently  se-
		     lected.
       A  nodes	 selection status is also dependent on it being	visible.  If a
       node is selected	and its	parent is then collapsed making	 the  selected
       node not	visible, then its selection status is changed to unselected.

       pathName	toggle uid
	      Toggles the hierarchy beneath the	node with the specified	unique
	      id.  If the hierarchy is currently expanded,  then  it  is  col-
	      lapsed, and vice-versa.

COMPONENTS
       Name:	       list
       Class:	       Text

	      The  list	component is the text widget in	which the hierarchy is
	      displayed.  See the "text" widget	manual entry  for  details  on
	      the text component item.

       Name:	       bgMenu
       Class:	       Menu

	      The  bgMenu  component is	the popup menu which is	displayed upon
	      pressing the right mouse button in the background, i.e. not over
	      a	 specific node.	 Menu items can	be added along with their com-
	      mands via	the component command.	See the	"menu"	widget	manual
	      entry for	details	on the bgMenu component	item.

       Name:	       horizsb
       Class:	       Scrollbar

	      The  horizsb  component  is  the horizontal scroll bar.  See the
	      "scrollbar" widget manual	entry for details on the horizsb  com-
	      ponent item.

       Name:	       itemMenu
       Class:	       Menu

	      The itemMenu component is	the popup menu which is	displayed upon
	      selection	of a hierarchy node with the right mouse button.  Menu
	      items  can  be added along with their commands via the component
	      command.	See the	"menu" widget manual entry for details on  the
	      itemMenu component item.

       Name:	       vertsb
       Class:	       Scrollbar

	      The  vertsb  component  is  the  vertical	 scroll	 bar.  See the
	      "scrollbar" widget manual	entry for details on the vertsb	compo-
	      nent item.

EXAMPLE
       package require Iwidgets	4.0 proc get_files {file} {
	   global env

	   if {$file ==	""} {
	       set dir $env(HOME)
	   } else {
	       set dir $file
	   }

	   if {[catch {cd $dir}] != 0} {
	       return ""
	   }

	   set rlist ""

	   foreach file	[lsort [glob -nocomplain *]] {
	       lappend rlist [list [file join $dir $file] $file]
	   }

	   return $rlist }

       iwidgets::hierarchy .h -querycommand "get_files %n" -visibleitems 30x15
       -labeltext $env(HOME) pack .h -side left	-expand	yes -fill both

AUTHOR
       Mark L. Ulferts Michael J. McLennan

KEYWORDS
       hierarchy, text,	widget

Tk							iwidgets::hierarchy(1)

NAME | SYNOPSIS | INHERITANCE | STANDARD OPTIONS | ASSOCIATED OPTIONS | INHERITED OPTIONS | WIDGET-SPECIFIC OPTIONS | DESCRIPTION | METHODS | ASSOCIATED METHODS | WIDGET-SPECIFIC METHODS | COMPONENTS | EXAMPLE | AUTHOR | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=iwidgets_hierarchy&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help