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

FreeBSD Manual Pages

  
 
  

home | help
tabset(n)		     BLT Built-In Commands		     tabset(n)

______________________________________________________________________________

NAME
       tabset -	Create and manipulate tabset widgets
_________________________________________________________________

SYNOPSIS
       tabset pathName ?options?

DESCRIPTION
       The  tabset  widget  displays a series of overlapping folders. Only the
       contents	of one folder at a time	is  displayed.	 By  clicking  on  the
       tab's of	a folder, you can view other folders.  Each folder may contain
       any Tk widget that can be automatically positioned and resized  in  the
       folder.

       There's	no  limit  to  the  number  of folders.	 Tabs can be tiered or
       scrolled.  Pages	(i.e. embedded widgets)	can be torn off	and  displayed
       in  another  toplevel  widget, and also restored.  A tabset can also be
       used as just a set of tabs, without a displaying	any  pages.   You  can
       bind events to individual tabs, so it's easy to add features like "bal-
       loon help".

INTRODUCTION
       Notebooks are a popular graphical paradigm.  They allow you to organize
       several	windows	 that are too big to display at	the same time as pages
       of a notebook.  For example, your application may display  several  X-Y
       graphs  at the same time.  The graphs are too big to pack into the same
       frame.  Managing	them in	several	toplevel widgets  is  also  cumbersome
       and  clutters  the  screen.   Instead,  the tabset widget organizes the
       graphs as folders in a notebook.

       Only one	page is	visible	at a time. When	you click on a tab, the	folder
       corresponding  to the tab is displayed in the  tabset widget.  The tab-
       set also	lets you temporarily tear pages	out of	the  notebook  into  a
       separate	 toplevel  widget, and put them	back in	the tabset later.  For
       example,	you could compare two graphs side-by-side by tearing them out,
       and then	replace	them when you are finished.

       A tabset	can contain any	number of folders.  If there are too many tabs
       to view,	you can	arrange	them as	multiple tiers or scroll the tabs. You
       can also	attach Tk scrollbars to	the tabset to scroll the tabs.

SYNTAX
       The tabset command creates a new	window using the pathName argument and
       makes it	into a tabset widget.  tabset pathName ?option value?...   Ad-
       ditional	 options may be	specified on the command line or in the	option
       database	to configure aspects of	the tabset such	as its	colors,	 font,
       text,  and  relief.   The tabset	command	returns	its pathName argument.
       At the time this	command	is invoked, there  must	 not  exist  a	window
       named pathName, but pathName's parent must exist.

       When  first  created, a new tabset contains no tabs.  Tabs are added or
       deleted using widget operations described below.	It  is	not  necessary
       for all the tabs	to be displayed	in the tabset window at	once; commands
       described below may be used to change the view in the window.   Tabsets
       allow  scrolling	 of  tabs  using the -scrollcommand option.  They also
       support scanning	(see the scan operation).  Tabs	may be arranged	 along
       any side	of the tabset window using the -side option.

       The size	of the tabset window is	determined the number of tiers of tabs
       and the sizes of	the Tk	widgets	 embedded  inside  each	 folder.   The
       widest  widget  determines  the width of	the folder. The	tallest	deter-
       mines the height.  If no	folders	contain	an embedded widget,  the  size
       is detemined solely by the size of the tabs.

       You  can	override either	dimension with the tabset's -width and -height
       options.

INDICES
       Indices refer to	individual tabs/folders	in the tabset.	 Many  of  the
       operations  for	tabset	widgets	take one or more indices as arguments.
       An index	may take several forms:

       number	   Unique index	offset of the tab.

       @x,y	   Tab that covers the point in	the tabset window specified by
		   x  and  y  (in  screen coordinates).	 If no tab covers that
		   point, then the index is ignored.

       select	   The currently selected tab.	The select index is  typically
		   changed  by	either clicking	on the tab with	the left mouse
		   button or using the widget's	invoke operation.

       active	   The tab where the mouse pointer is currently	located.   The
		   label  is  drawn  using its active colors (see the -active-
		   background and -activeforeground options).  The active  in-
		   dex is typically changed by moving the mouse	pointer	over a
		   tab or using	the widget's activate operation. There can  be
		   only	 one active tab	at a time.  If there is	no tab located
		   under the mouse pointer, the	index is ignored.

       begin	   First tab in	the tabset.  If	there are no tabs in the  tab-
		   set then the	index is ignored.

       current	   Tab	that  is  currently  being operated upon.  Used	within
		   bindings.

       focus	   Tab that currently has the widget's	focus.	 This  tab  is
		   displayed  with  a  dashed  line around its label.  You can
		   change this using the focus operation. If no	tab has	focus,
		   then	the index is ignored.

       down	   Tab	immediately below the tab that currently has focus, if
		   there is one. If there is no	tab below, the current tab  is
		   returned.

       left	   Tab	immediately to the left	the tab	that currently has fo-
		   cus,	if there is one.  If there is no tab to	the left,  the
		   current tab is returned.

       next	   The next tab.  Wraps	to the first tab if at end.

       prev	   The previous	tab.  Wraps to the last	tab if at start.

       right	   Tab immediately to the right	the tab	that currently has fo-
		   cus,	if there is one. If there is no	tab to the right,  the
		   current tab is returned.

       up	   Tab	immediately  above,  if	 there is one, to the tab that
		   currently has focus.	If there is no tab above, the  current
		   tab is returned.

       end	   Last	tab in the tabset.  If there are no tabs in the	tabset
		   then	the index is ignored.

       Some indices may	not always be available.  For example, if the mouse is
       not over	any tab, "active" does not have	an index.  For most tabset op-
       erations	this is	harmless and ignored.

OPERATIONS
       All tabset operations are invoked by specifying the widget's  pathname,
       the  operation,	and any	arguments that pertain to that operation.  The
       general form is:

	    pathName operation ?arg arg	...?

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

       pathName	activate index
	      Sets  the	 active	tab to the one indicated by index.  The	active
	      tab is drawn with	its active colors (see	the  -activebackground
	      and -activeforeground options) and may be	retrieved with the in-
	      dex active.  Only	one tab	may be active at a time.  If index  is
	      the  empty string, then all tabs will be drawn with their	normal
	      foreground and background	colors.

       pathName	bind tagName ?sequence?	?command?
	      Associates command with tagName such that	whenever the event se-
	      quence given by sequence occurs for a tab	with this tag, command
	      will be invoked.	The syntax is similar to the bind command  ex-
	      cept that	it operates on tabs, rather than widgets.  The tagName
	      is one of	all, Perforation, Image, Leftimage, Startimage,	Endim-
	      age,  or the name	label used to create a Tab.  See the bind man-
	      ual entry	for complete details on	sequence and the substitutions
	      performed	on command.

	      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	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 in the	section	WIDGET OPTIONS below.

       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 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 op-
	      tion-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  de-
	      scribed in the section WIDGET OPTIONS below.

       pathName	coords element ?index?
	      Returns  the  screen coordinates for the given element, which is
	      one of: text, image, leftimage, startimage, endimage, or	perfo-
	      ration.	All except startimage and endimage must	also provide a
	      tab index.

       pathName	delete first ?last?
	      Deletes one or more tabs from the	tabset.	 First	and  last  are
	      the  first  and  last  indices,  defining	 a range of tabs to be
	      deleted.	If last	isn't specified, then only the tab at first is
	      deleted.

       pathName	focus index
	      Designates  a  tab  to get the widget's focus.  This tab is dis-
	      played with a dashed line	around its label.

       pathName	get index
	      Returns the name of the tab.  The	value of index may be  in  any
	      form described in	the section INDICES .

       pathName	hightlight index
	      Highlight	a tab.

       pathName	index ?flag? string
	      Returns  the  index  offset  of the tab specified	by string.  If
	      flag is -name, then string is the	name of	a  tab.	  If  flag  is
	      -index, string is	an index such as "active" or "focus".  If flag
	      is -both,	string is either.  If flag  isn't  specified,  it  de-
	      faults to	-index.

       pathName	insert position	?name ...? ?option value?...
	      Inserts new tabs into the	tabset.	 Tabs are inserted just	before
	      the tab given by position.  Position may be either a number, in-
	      dicating	where in the list the new tab should be	added, or end,
	      indicating that the new tab is to	be added the end of the	 list.
	      Name  is	the  symbolic name of the tab. Be careful not to use a
	      number. Otherwise	the tabset will	confuse	it with	 tab  indices.
	      Returns  a list of indices for all the new tabs.	If tab name is
	      an empty string, or ends in #auto, it  is	 generated  using  the
	      given prefix.  The list of created tab names is returned.

       pathName	invoke index
	      Selects  the tab given by	index, maps the	tab's embedded widget,
	      and invokes the Tcl command associated with the tab,  if	 there
	      is  one.	The return value is the	return value from the Tcl com-
	      mand, or an empty	string	if there  is  no  command   associated
	      with  the	tab.  This command is ignored if the  tab's state (see
	      the -state option) is disabled.

       pathName	move index before|after	index
	      Moves the	tab index to a new position in the tabset.

       pathName	nearest	x y ?varName? ?coordsVar?
	      Returns the name of the tab nearest to given X-Y screen  coordi-
	      nate.   If  the argument varName is present, this	is a Tcl vari-
	      able that	is set to either text, image,  leftimage,  startimage,
	      endimage,	perforation or the empty string	depending what part of
	      the tab the coordinate is	over.  If the  argument	 coordsVar  is
	      present, return the bounding box coordinates coordinates for the
	      matching item set	in varName.

       pathName	perforation operation ?args?
	      This operation controls the perforation on the tab label.

	      pathName perforation activate boolean
		     Set perforation active state to on	or off.

	      pathName perforation invoke
		     Invokes the command specified for perforations  (see  the
		     -perforationcommand  widget  option). Typically this com-
		     mand places the page into a top level widget. The name of
		     the  toplevel  is the concatonation of the	pathName, "-",
		     and the tabName.  The return value	is  the	 return	 value
		     from  the	Tcl  command, or an empty string  if there  is
		     no	 command  associated with the tab.   This  command  is
		     ignored  if  the	tab's state (see the -state option) is
		     disabled.

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

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

	      pathName scan dragto x y.
		     This command 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 wid-
		     get,  to  produce the effect of dragging the list at high
		     speed through the window.	The return value is  an	 empty
		     string.

       pathName	see index
	      Scrolls  the tabset so that the tab index	is visible in the wid-
	      get's window.

       pathName	select index
	      Select the tab.

       pathName	size
	      Returns the number of tabs in the	tabset.

       pathName	tab operation ?args?

	      pathName tab cget	nameOrIndex option
		     Returns the current value	of  the	 configuration	option
		     given  by	option.	 Option	may have any of	the values ac-
		     cepted by the tab configure operation  described  in  the
		     section TAB OPTIONS below.

	      pathName	tab  configure	nameOrIndex  ?nameOrIndex...?  option?
	      ?value option value ...?
		     Query or modify the configuration options of one or  more
		     tabs.   If	no option is specified,	this operation returns
		     a list describing all the	available  options  for	 name-
		     OrIndex.	NameOrIndex can	be either the name of a	tab or
		     its index.	 Names of tabs take precedence over their  in-
		     dices.   That  means a tab	named focus is picked over the
		     "focus" tab.

		     If	option is specified, but not value, then  a  list  de-
		     scribing  the  one	 named option is returned.  If	one or
		     more option-value pairs are specified,  then  each	 named
		     tab  (specified  by nameOrIndex) will have	its configura-
		     tions option(s) set the given  value(s).	In  this  last
		     case, the empty string is returned.  Option and value are
		     described in the section TAB OPTIONS below.

	      pathName tab dockall
		     Dock all tearoffs.

	      pathName tab names ?pattern?
		     Returns the names of all the tabs matching	the given pat-
		     tern.  If	no  pattern argument is	provided, then all tab
		     names are returned.

	      pathName tab pageheight

	      pathName tab pagewidth

	      pathName tab select nameOrindex
		     Select a tab by name or index, and	 cause	it  to	become
		     visible, selected,	activated, and receive focus.  This is
		     a shortform for using separate commands.

	      pathName tab tearoff ?index?
		     With no  ?index?, returns	list  of  all  torn-off	 tabs.
		     Otherwise,	return the window for the given	torn-off tab.

       pathName	tab tearoff ?index?
	      With no  ?index?,	returns	list of	all torn-off tabs.  Otherwise,
	      toggles the torn-off state of the	tab.

       pathName	view args
	      This command queries or changes the position of  the  tabset  in
	      the widget's window.  It can take	any of the following forms:

	      pathName view
		     Returns  a	 list  of two numbers between 0.0 and 1.0 that
		     describe the amount and position of the  tabset  that  is
		     visible  in  the  window.	 For  example, if view is "0.2
		     0.6", 20% of the tabset's text is off-screen to the left,
		     40%  is  visible  in the window, and 40% of the tabset is
		     off-screen	to the	right.	 These	are  the  same	values
		     passed to scrollbars via the -scrollcommand option.

	      pathName view moveto fraction
		     Adjusts  the  view	 in the	window so that fraction	of the
		     total width of the	tabset text is off-screen to the left.
		     fraction must be a	number between 0.0 and 1.0.

	      pathName view scroll number what
		     This  command  shifts the view in the window (left/top or
		     right/bottom) according to	number and what.  Number  must
		     be	 an  integer. What must	be either units	or pages or an
		     abbreviation of these.  If	what is	units,	the  view  ad-
		     justs  left  or  right  by	 number	 scroll	units (see the
		     -scrollincrement option).	; if it	is pages then the view
		     adjusts  by number	widget windows.	 If number is negative
		     then tabs farther to the left become visible;  if	it  is
		     positive then tabs	farther	to the right become visible.

WIDGET OPTIONS
       Widget  configuration options may be set	either by the configure	opera-
       tion or the Tk option command.  The resource class is Tabset.  The  re-
       source name is the name of the widget.

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

       The following widget options are	available:

       -activebackground color
	      Sets the default active background color for tabs.  A tab	is ac-
	      tive when	the mouse is positioned	over it	or set by the activate
	      operation.   Individual tabs may override	this option by setting
	      the tab's	-activebackground option.

       -activeforeground color
	      Sets the default active foreground color for tabs.  A tab	is ac-
	      tive when	the mouse is positioned	over it	or set by the activate
	      operation.  Individual tabs may override this option by  setting
	      the tab's	-activeforeground option.

       -anchor anchor
	      Anchors  the tab's text (and images) to a	particular edge	of the
	      tab.  The	default	value is center.

       -background color
	      Sets the background color	of the tabset.

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

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

       -dashes dashList
	      Sets the dash style of the focus outline.	 When a	 tab  has  the
	      widget's focus, it is drawn with a dashed	outline	around its la-
	      bel.  DashList is	a list of up to	11  numbers  that  alternately
	      represent	 the  lengths of the dashes and	gaps on	the cross hair
	      lines.  Each number must be between 1 and	255.  If  dashList  is
	      "", the outline will be a	solid line.  The default value is 5 2.

       -ellipsis string
	      String  to  append  to displayed labels that have	been truncated
	      due to exceeding -labelmax.  The default is ....

       -endimage imageName
	      Specify an image to be drawn after tabs (ie.  on	the  right  if
	      -side  =	top).	This is	used by	a binding looking for endimage
	      from the nearest subcommand.

       -fillwidth boolean
	      Indicates	if extra space should be allocated to tabs when	multi-
	      ple tiers	are displayed.	The default is yes.

       -font fontName
	      Sets  the	 default  font for the text in tab labels.  Individual
	      tabs may override	this by	setting	the tab's -font	 option.   The
	      default value is *-Helvetica-Bold-R-Normal-*-12-120-*.

       -foreground color
	      Sets the default color of	tab labels.  Individual	tabs may over-
	      ride this	option by setting the tab's -foreground	 option.   The
	      default value is black.

       -gap size
	      Sets the gap (in pixels) between tabs.  The default value	is 2.

       -gapleft	size
	      Sets a gap (in pixels) to	leave between the text and -leftimage.
	      The default value	is 2.

       -height pixels
	      Specifies	the requested height of	widget.	 If pixels is 0,  then
	      the  height  of  the widget will be calculated based on the size
	      the tabs and their pages.	 The default is	0.

       -highlightbackground  color
	      Sets the color to	display	in the traversal highlight region when
	      the tabset does not have the input focus.

       -highlightcolor color
	      Sets the color to	use for	the traversal highlight	rectangle that
	      is drawn around the widget when it has the input focus.  The de-
	      fault is black.

       -highlightthickness pixels
	      Sets  the	 width	of  the	highlight rectangle to draw around the
	      outside of the widget when it has	the input focus. Pixels	 is  a
	      non-negative  value  and may have	any of the forms acceptable to
	      Tk_GetPixels.  If	the value is zero, no focus highlight is drawn
	      around the widget.  The default is 2.

       -labelbackground	color
	      Sets a background	color for the label.  The default is ".

       -labelmax length
	      Length at	which to truncate displayed label text after appending
	      value of -ellipsis.  This	enables	a user implemention  of	 trun-
	      cating  labels  as  the  number of tabs increases.  Default is 0
	      meaning do no truncation.

       -outerpad pixels
	      Padding around the exterior of the tabset	and folder.

       -pageheight pixels
	      Sets the requested height	of the page.  The page is the area un-
	      der  the tab used	to display the page contents.  If pixels is 0,
	      the maximum height of all	embedded tab windows is	used.  The de-
	      fault is 0.

       -pagewidth pixels
	      Sets  the	requested width	of the page.  The page is the area un-
	      der the tab used to display the page contents.  If pixels	is  0,
	      the  maximum width of all	embedded tab windows is	used.  The de-
	      fault is 0.

       -perforationcommand string
	      Specifies	a Tcl script to	be invoked to  tear  off  the  current
	      page  in the tabset. This	command	is typically invoked when left
	      mouse button is released over the	tab perforation.  The  default
	      action  is to tear-off the page and place	it into	a new toplevel
	      window.

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

       -rotate theta
	      Specifies	 the degrees to	rotate text in tab labels.  Theta is a
	      real value representing the number of degrees to rotate the tick
	      labels.  The default is 0.0 degrees.

       -samewidth boolean
	      Indicates	 if  each tab should be	the same width.	 If true, each
	      tab will be as wide as the widest	tab.  The default is no.

       -scrollcommand string
	      Specifies	the  prefix  for  a  command  for  communicating  with
	      scrollbars.   Whenever  the view in the widget's window changes,
	      the widget will generate a  Tcl  command	by  concatenating  the
	      scroll  command  and  two	numbers.  If this option is not	speci-
	      fied, then no command will be executed.

       -scrollincrement	pixels
	      Sets the smallest	number of pixels to scroll the tabs.  If  pix-
	      els  is greater than 0, this sets	the units for scrolling	(e.g.,
	      when you the change the view by clicking on the left  and	 right
	      arrows of	a scrollbar).

       -selectbackground color
	      Sets the color to	use when displaying background of the selected
	      tab. Individual tabs can override	this  option  by  setting  the
	      tab's -selectbackground option.

       -selectcommand string
	      Specifies	 a  default Tcl	script to be invoked when tabs are se-
	      lected.  This command is typically invoked when left mouse  but-
	      ton  is pressed over the tab.  Individual	tabs may override this
	      with the tab's -command option.  Alternatively, the  <<TabsetSe-
	      lect>> virtual event may be bound	to instead.  The default value
	      is "".

       -selectforeground color
	      Sets the default color of	the selected tab's text	label.	 Indi-
	      vidual  tabs  can	override this option by	setting	the tab's -se-
	      lectforeground option. The default value is black.

       -selectpad pixels
	      Specifies	extra padding to be displayed around the selected tab.
	      The default value	is 3.

       -shadow colorAndOffset
	      Sets  the	 shadow	 color	for the	text in	all tab	labels.	 If an
	      offset isn't given, it defaults to 1.  Drop shadows  are	useful
	      when  both the foreground	and background of the tab have similar
	      color intensities.  If color is the empty	string,	no  shadow  is
	      drawn.  The default value	is "".

       -shadowcolor color
	      Sets the folder shadow color.

       -side side
	      Specifies	 the  side  of the widget to place tabs. The following
	      values are valid for side. The default value is top.

	      top	Tabs are drawn along the top.

	      left	Tabs are drawn along the left side.

	      right	Tabs are drawn along the right side.

	      both	Tabs are drawn along the bottom	side.

       -slant slant
	      Specifies	if the tabs should be slanted 45 degrees on  the  left
	      and/or  right  sides.  The following values are valid for	slant.
	      The default is none.

	      none	Tabs are drawn as a rectangle.

	      left	The left side of the tab is slanted.

	      right	The right side of the tab is slanted.

	      both	Boths sides of the tab are slanted.

       -startimage imageName
	      Specify an image to be drawn before tabs (ie.  on	 the  left  if
	      -side  = top).  This is used by a	binding	looking	for startimage
	      from the nearest subcommand.

       -tabbackground color
	      Sets the default background color	of tabs.  Individual tabs  can
	      override this option by setting the tab's	-background option.

       -tabborderwidth pixels
	      Sets  the	width of the 3-D border	around the outside edge	of the
	      tab.  The	-tabrelief option determines how the border is	to  be
	      drawn.  The default is 2.

       -tabforeground color
	      Specifies	the color to use when displaying a tab's label.	 Indi-
	      vidual tabs can override this option by setting the tab's	-fore-
	      ground option.

       -tabrelief relief
	      Specifies	 the  3-D  effect  for	both tabs and folders.	Relief
	      specifies	how the	tabs should appear relative to	background  of
	      the  widget;  for	example, raised	means the tab should appear to
	      protrude.	 The default is	raised.

       -tabtile	image
	      Specifies	tiled background for tabs.  The	default	is "".

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

       -tearoff	boolean
	      Display tearoff.

       -textside side
	      If both images and text are specified for	a tab, this option de-
	      termines	on  which side of the tab the text is to be displayed.
	      The valid	sides are left,	right, top, and	bottom.	  The  default
	      value is left.

       -tiers number
	      Specifies	 the  maximum  number  of  tiers to use	to display the
	      tabs.  The default value is 1.

       -tile image
	      Specifies	a tiled	background for the widget background excluding
	      the  tabs.  If image isn't "", the background is tiled using im-
	      age.  Otherwise, the normal background color is drawn  (see  the
	      -background  option).   Image must be an image created using the
	      Tk image command.	 The default is	"".  Specifies a  tiled	 back-
	      ground  image  for  the background of the	widget.	 This does not
	      include the tabs.

       -transient boolean
	      Tearoff window should be transient.

       -width pixels
	      Specifies	the requested width of the widget.  If	pixels	is  0,
	      then  the	 width	of  the	widget will be calculated based	on the
	      size the tabs and	their pages.  The default is 0.

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

	      option add *Tabset.Tab.Foreground	white
	      option add *Tabset.name.Background blue

       The following widget options are	available:

       -activebackground color
	      Sets the active background color for nameOrIndex.	 A tab is  ac-
	      tive when	the mouse is positioned	over it	or set by the activate
	      operation.  This overrides the  widget's	-activebackground  op-
	      tion.

       -activeforeground color
	      Sets  the	default	active foreground color	nameOrIndex.  A	tab is
	      "active" when the	mouse is positioned over it or set by the  ac-
	      tivate  operation.   Individual tabs may override	this option by
	      setting the tab's	-activeforeground option.

       -anchor anchor
	      Anchors the tab's	embedded widget	to a particular	 edge  of  the
	      folder.	This option has	effect only if the space in the	folder
	      surrounding the embedded widget is larger	than  the  widget  it-
	      self.  Anchor specifies how the widget will be positioned	in the
	      extra space.  For	example, if anchor is center then  the	window
	      is  centered in the folder ; if anchor is	w then the window will
	      be aligned with the leftmost edge	of  the	 folder.  The  default
	      value is center.

       -background color
	      Sets  the	background color for nameOrIndex.  Setting this	option
	      overides the widget's -tabbackground option.

       -bindtags tagList
	      Specifies	the binding tags for this tab.	TagList	is a  list  of
	      binding  tag names.  The tags and	their order will determine how
	      commands for events in tabs are invoked.	Each tag in  the  list
	      matching	the event sequence will	have its Tcl command executed.
	      Implicitly the name of the tab is	always the first  tag  in  the
	      list.  The default value is all.

       -command	string
	      Specifies	 a Tcl script to be associated with nameOrIndex.  This
	      command is typically invoked when	left mouse button  is  pressed
	      over  the	 tab.  Setting this option overrides the widget's -se-
	      lectcommand option.

       -data string
	      Specifies	a string to  be	 associated  with  nameOrIndex.	  This
	      value  isn't  used  in  the  widget code.	 It may	be used	in Tcl
	      bindings to associate extra data (other than the image or	 text)
	      with the tab. The	default	value is "".

       -fill fill
	      If the space in the folder surrounding the tab's embedded	widget
	      is larger	than the widget, then fill indicates if	 the  embedded
	      widget  should  be stretched to occupy the extra space.  Fill is
	      either none, x, y, both.	For example, if	fill is	 x,  then  the
	      widget  is  stretched horizontally.  If fill is y, the widget is
	      stretched	vertically.  The default is none.

       -font fontName
	      Sets the font for	the text in tab	labels.	 If  fontName  is  not
	      the empty	string,	this overrides the tabset's -font option.  The
	      default value is "".

       -foreground color
	      Sets the color of	the label for nameOrIndex.  If	color  is  not
	      the empty	string,	this overrides the widget's -tabforeground op-
	      tion.  The default value is "".

       -hidden bool
	      Hide the tab.  The default is 0.	The tab	should be  changed  to
	      not be the selected tab before setting it	to hidden.

       -image imageName
	      Specifies	 the  image  to	be drawn in label for nameOrIndex.  If
	      image is "", no image will be drawn.  Both text and  images  may
	      be  displayed at the same	time in	tab labels.  The default value
	      is "".

       -leftimage imageName
	      Specify a	second image to	be drawn to the	left before text/image
	      when  the	widgets	-textside = right.  This image might represent
	      a	close icon when	used with a binding that looks	for  leftimage
	      from the nearest subcommand.

       -ipadx pad
	      Sets the padding to the left and right of	the label.  Pad	can be
	      a	list of	one or two screen distances.  If pad has two elements,
	      the  left	 side of the label 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
	      value is 0.

       -ipady pad
	      Sets the padding to the top and bottom of	the label.  Pad	can be
	      a	list of	one or two screen distances.  If pad has two elements,
	      the top of the label is padded by	the  first  distance  and  the
	      bottom  by  the  second.	If pad has just	one distance, both the
	      top and bottom sides are padded evenly.  The default value is 0.

       -padx pad
	      Sets the padding around the left and right of the	embedded  wid-
	      get, if one exists.  Pad can be a	list of	one or two screen dis-
	      tances.  If pad has two elements,	the left side of the widget 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 value	is 0.

       -pady pad
	      Sets  the	padding	around the top and bottom of the embedded wid-
	      get, if one exists.  Pad can be a	list of	one or two screen dis-
	      tances.	If  pad	 has  two  elements,  the top of the widget is
	      padded by	the first distance and the bottom by the  second.   If
	      pad  has	just  one  distance, both the top and bottom sides are
	      padded evenly.  The default value	is 0.

       -selectbackground color
	      Sets the color to	use when displaying background of the selected
	      tab.  If	color is not the empty string, this overrides the wid-
	      get's -selectbackground option. The default value	is "".

       -shadow color
	      Sets the shadow color for	the text  in  the  tab's  label.  Drop
	      shadows  are  useful  when both the foreground and background of
	      the tab have similar color intensities.  If color	is  the	 empty
	      string, no shadow	is drawn.  The default value is	"".

       -state state
	      Sets  the	 state of the tab. If state is disable the text	of the
	      tab is drawn as engraved and operations on the tab (such as  in-
	      voke and tab tearoff) are	ignored.  The default is normal.

       -stipple	bitmap
	      Specifies	 a  stipple  pattern  to use for the background	of the
	      folder when the window is	torn off.  Bitmap specifies  a	bitmap
	      to use as	the stipple pattern. The default is BLT.

       -text text
	      Specifies	 the  text of the tab's	label.	The exact way the text
	      is drawn may be affected by other	options	such as	-state or -ro-
	      tate.

       -tornwindow text
	      Name of window that was torn off.

       -underline num
	      Character	to underline in	text.  Default is -1.

       -window pathName
	      Specifies	the widget to be embedded into the tab.	 PathName must
	      be a child of the	tabset widget.	The  tabset  will  "pack"  and
	      manage the size and placement of pathName.  The default value is
	      "".

       -windowheight pixels
	      Sets the requested height	of the page.  The page is the area un-
	      der  the tab used	to display the page contents.  If pixels is 0,
	      the maximum height of all	embedded tab windows is	used.  The de-
	      fault is 0.

       -windowwidth pixels
	      Sets  the	requested width	of the page.  The page is the area un-
	      der the tab used to display the page contents.  If pixels	is  0,
	      the  maximum width of all	embedded tab windows is	used.  The de-
	      fault is 0.

DEFAULT	BINDINGS
       BLT automatically generates class bindings that	supply	tabsets	 their
       default behaviors. The following	event sequences	are set	by default for
       tabsets (via the	class bind tag Tabset):

       <ButtonPress-2>

       <B2-Motion>

       <ButtonRelease-2>
	      Mouse button 2 may be used for scanning.	If it is  pressed  and
	      dragged over the tabset, the contents of the tabset drag at high
	      speed in the direction the mouse moves.

       <KeyPress-Up>

       <KeyPress-Down>
	      The up and down arrow keys move the focus	to the tab immediately
	      above  or	 below	the  current focus tab.	 The tab with focus is
	      drawn with the a dashed outline around the tab label.

       <KeyPress-Left>

       <KeyPress-Right>
	      The left and right arrow keys move the focus to the tab  immedi-
	      ately  to	 the  left or right of the current focus tab.  The tab
	      with focus is drawn with the a dashed outline around the tab la-
	      bel.

       <KeyPress-space>

       <KeyPress-Return>
	      The  space  and  return keys select the current tab given	focus.
	      When a folder is selected, it's command is invoked and  the  em-
	      bedded widget is mapped.

       Each  tab,  by  default,	 also has a set	of bindings (via the tag all).
       These bindings may be reset using the tabset's bind operation.

       <Enter>

       <Leave>
	      When the mouse pointer enters a tab, it is activated (i.e. drawn
	      in its active colors) and	when the pointer leaves, it is redrawn
	      in its normal colors.

       <ButtonRelease-1>
	      Clicking with the	left mouse button on a tab causes the  tab  to
	      be  selected and its Tcl script (see the -command	or -selectcom-
	      mand options) to be invoked.  The	folder and any embedded	widget
	      (if one is specified) is automatically mapped.

       <ButtonRelease-3>

       <Control-ButtonRelease-1>
	      Clicking	on  the	 right	mouse button (or the left mouse	button
	      with the Control key held	down) tears off	the current page  into
	      its own toplevel widget. The embedded widget is re-packed	into a
	      new toplevel and an outline  of  the  widget  is	drawn  in  the
	      folder.	Clicking  again	(toggling) will	reverse	this operation
	      and replace the page back	in the folder.

BIND TAGS
       You can bind commands to	tabs that  are	triggered  when	 a  particular
       event  sequence	occurs	in them, much like canvas items	in Tk's	canvas
       widget.	Not all	event sequences	are valid.  The	 only  binding	events
       that may	be specified are those related to the mouse and	keyboard (such
       as Enter, Leave,	ButtonPress, Motion, and KeyPress).

       It is possible for multiple bindings to match a particular event.  This
       could  occur,  for  example,  if	one binding is associated with the tab
       name and	another	is associated with the tab's tags (see	the  -bindtags
       option).	  When	this occurs, all the matching bindings are invoked.  A
       binding associated with the tab name is invoked first, followed by  one
       binding for each	of the tab's bindtags.	If there are multiple matching
       bindings	for a single tag, then only the	most specific binding  is  in-
       voked.	A continue command in a	binding	script terminates that script,
       and a break command terminates that  script  and	 skips	any  remaining
       scripts for the event, just as for the bind command.

       The  -bindtags  option for tabs controls	addition tag names that	can be
       matched.	 Implicitly the	first tag for each tab is its  name.   Setting
       the value of the	-bindtags option doesn't change	this.

       Note  that the <<TabsetTearoff>>	virtual	event is generated on tearoff.
       and the <<TabsetSelect>>	virtual	event is generated on selection.

EXAMPLE
       You create a tabset widget with the tabset command.

	      #	Create a new tabset
	      tabset .ts -relief sunken	-borderwidth 2

       A new Tcl command .ts is	also created.  This command  can  be  used  to
       query  and  modify the tabset.  For example, to change the default font
       used by all the tab labels, you use the new command  and	 the  tabset's
       configure operation.

	      #	Change the default font.
	      .ts configure -font "fixed"

       You can then add	folders	using the insert operation.

	      #	Create a new folder "f1"
	      .ts insert 0 "f1"

       This inserts the	new tab	named "f1" into	the tabset.  The index 0 indi-
       cates location to insert	the new	tab.  You can also use the  index  end
       to  append a tab	to the end of the tabset.  By default, the text	of the
       tab is the name of the tab.  You	can change  this  by  configuring  the
       -text option.

	      #	Change the label of "f1"
	      .ts tab configure	"f1" -text "Tab	#1"

       The insert operation lets you add one or	more folders at	a time.

	      .ts insert end "f2" -text	"Tab #2" "f3" "f4"

       The  tab	 on each folder	contains a label.  A label may display both an
       image and a text	string.	 You  can  reconfigure	the  tab's  attributes
       (foreground/background  colors, font, rotation, etc) using the tab con-
       figure operation.

	      #	Add an image to	the label of "f1"
	      set image	[image create photo -file stopsign.gif]
	      .ts tab configure	"f1" -image $image
	      .ts tab configure	"f2" -rotate 90

       Each folder may contain an embedded widget to represent	its  contents.
       The  widget to be embedded must be a child of the tabset	widget.	 Using
       the -window option, you specify the name	of widget to be	embedded.  But
       don't  pack  the	widget,	the tabset takes care of placing and arranging
       the widget for you.

	      graph .ts.graph
	      .ts tab configure	"f1" -window ".ts.graph" \
		  -fill	both -padx 0.25i -pady 0.25i

       The size	of the folder is determined the	sizes of the Tk	widgets	embed-
       ded  inside each	folder.	 The folder will be as wide as the widest wid-
       get in any folder. The tallest determines the height.  You can use  the
       tab's -pagewidth	and -pageheight	options	override this.

       Other  options control how the widget appears in	the folder.  The -fill
       option says that	you wish to have the widget stretch to fill the	avail-
       able space in the folder.

	      .ts tab configure	"f1" -fill both	-padx 0.25i -pady 0.25i

       Now  when  you  click  the left mouse button on "f1", the graph will be
       displayed in the	folder.	 It will be automatically hidden when  another
       folder is selected.  If you click on the	right mouse button, the	embed-
       ded widget will be moved	into a toplevel	widget of its  own.   Clicking
       again on	the right mouse	button puts it back into the folder.

       If you want to share a page between two different folders, the -command
       option lets you specify a Tcl command to	be invoked whenever the	folder
       is  selected.   You  can	 reset the -window option for the tab whenever
       it's clicked.

	      .ts tab configure	"f2" -command {
		  .ts tab configure "f2" -window ".ts.graph"
	      }
	      .ts tab configure	"f1" -command {
		  .ts tab configure "f1" -window ".ts.graph"
	      }

       If you have many	folders, you may wish to stack tabs in multiple	tiers.
       The  tabset's  -tiers  option requests a	maximum	number of tiers.   The
       default is one tier.

	      .ts configure -tiers 2

       If the tabs can fit in less tiers,  the	widget	will  use  that	 many.
       Whenever	 there are more	tabs than can be displayed in the maximum num-
       ber of tiers, the tabset	will automatically let you  scroll  the	 tabs.
       You can even attach a scrollbar to the tabset.

	      .ts configure -scrollcommand { .sbar set }  -scrollincrement 20
	      .sbar configure -orient horizontal -command { .ts	view }

       By  default  tabs  are  along the top of	the tabset from	left to	right.
       But tabs	can be placed on any side of the tabset	using  the  -side  op-
       tion.

	      #	Arrange	tabs along the right side of the tabset.
	      .ts configure -side right	-rotate	270

KEYWORDS
       tabset, widget

BLT				      2.5			     tabset(n)

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION | SYNTAX | INDICES | OPERATIONS | WIDGET OPTIONS | TAB OPTIONS | DEFAULT BINDINGS | BIND TAGS | EXAMPLE | KEYWORDS

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

home | help