<!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>tabset(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
tabset - Create and manipulate tabset widgets
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>tabset</B> <I>pathName </I>?<I>options</I>?
<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
The <B>tabset</B> 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. <P>
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 "balloon
help".
<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
Notebooks are a popular graphical paradigm. They allow
you to organize many windows in a single widget. For example, you might
have an application the displays several X-Y graphs at the same time. Typically,
you can't pack the graphs into the same <B>frame</B> because they are too large.
The other alternative is to pack the graphs into several <B>toplevel</B> widgets,
allowing them to overlap on the screen. The problem is that all the different
toplevel windows clutter the screen and are difficult to manage. <P>
The <B>tabset</B>
widget lets organize your application by displaying each graph as a page
in a folder of a notebook. Only one page is visible at a time. When you
click on a tab, the folder (graph) corresponding to the tab is displayed
in the <B>tabset</B> widget. The tabset 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. <P>
A tabset may contain
an unlimited number of folders. If there are too many tabs to view, you
can arrange them as multiple tiers or scroll the tabs. The tabset uses the
conventional Tk scrollbar syntax, so you can attach a scrollbar too.
<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
You
create a tabset widget with the <B>tabset</B> command. <BR>
<CODE># Create a new tabset<BR>
tabset .ts -relief sunken -borderwidth 2 <BR>
</CODE><P>A new Tcl command <I>.ts</I> 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 <B>configure</B> operation.
<BR>
<CODE># Change the default font.<BR>
.ts configure -font "fixed"<BR>
</CODE><P>You can then add folders using the <B>insert</B> operation. <BR>
<CODE># Create a new folder "f1"<BR>
.ts insert 0 "f1"<BR>
</CODE><P>This inserts the new tab named "f1" into the tabset. The index <I>0</I> indicates
location to insert the new tab. You can also use the index <I>end</I> 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 <B>-text</B> option. <BR>
<CODE># Change the label of "f1"<BR>
.ts tab configure "f1" -label "Tab #1" <BR>
</CODE><P>The <B>insert</B> operation lets you add one or more folders at a time. <BR>
<CODE>.ts insert end "f2" -label "Tab #2" "f3" "f4" <BR>
</CODE><P>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 <B>tab configure</B> operation. <BR>
<CODE># Add an image to the label of "f1"<BR>
set image [image create photo -file stopsign.gif]<BR>
.ts tab configure "f1" -image $image<BR>
.ts tab configure "f2" -rotate 90<BR>
</CODE><P>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 <B>-window</B>
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.
<BR>
<CODE>graph .ts.graph<BR>
.ts tab configure "f1" -window ".ts.graph" \<BR>
-fill both -padx 0.25i -pady 0.25i<BR>
</CODE><P>The size of the folder is determined the sizes of the Tk widgets embedded
inside each folder. The folder will be as wide as the widest widget in
any folder. The tallest determines the height. You can use the tab's <B>-pagewidth</B>
and <B>-pageheight</B> options override this. <P>
Other options control how the widget
appears in the folder. The <B>-fill</B> option says that you wish to have the widget
stretch to fill the available space in the folder. <BR>
<CODE>.ts tab configure "f1" -fill both -padx 0.25i -pady 0.25i<BR>
<P>
</CODE><P>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 embedded widget will be moved
into a toplevel widget of its own. Clicking again on the right mouse button
puts it back into the folder. <P>
If you want to share a page between two different
folders, the <B>-command</B> option lets you specify a Tcl command to be invoked
whenever the folder is selected. You can reset the <B>-window</B> option for the
tab whenever it's clicked. <BR>
<CODE>.ts tab configure "f2" -command { <BR>
.ts tab configure "f2" -window ".ts.graph"<BR>
}<BR>
.ts tab configure "f1" -command { <BR>
.ts tab configure "f1" -window ".ts.graph"<BR>
}<BR>
</CODE><P>If you have many folders, you may wish to stack tabs in multiple tiers.
The tabset's <B>-tiers</B> option requests a maximum number of tiers. The default
is one tier. <BR>
<CODE>.ts configure -tiers 2<BR>
</CODE><P>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 number of tiers,
the tabset will automatically let you scroll the tabs. You can even attach
a scrollbar to the tabset. <BR>
<CODE>.ts configure -scrollcommand { .sbar set } -scrollincrement 20<BR>
.sbar configure -orient horizontal -command { .ts view }<BR>
</CODE><P>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 <B>-side</B> option. <BR>
<CODE># Arrange tabs along the right side of the tabset. <BR>
.ts configure -side right -rotate 270<BR>
<H2><A NAME="sect5" HREF="#toc5"></CODE><P>Syntax</A></H2>
The <B>tabset</B> command creates a new window using the <I>pathName</I> argument
and makes it into a tabset widget. <BR>
<P>
<CODE><B>tabset <I>pathName </I></B>?<I>option value</I>?...<BR>
</CODE><P>Additional 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 <B>tabset</B> command returns its <I>pathName</I> argument. At the time
this command is invoked, there must not exist a window named <I>pathName</I>,
but <I>pathName</I>'s parent must exist. <P>
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 <B>-scrollcommand</B> option.
They also support scanning (see the <B>scan</B> operation). Tabs may be arranged
along any side of the tabset window using the <B>-side</B> option. <P>
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 determines the height. If no folders
contain an embedded widget, the size is detemined solely by the size of
the tabs. <P>
You can override either dimension with the tabset's <B>-width</B> and
<B>-height</B> options.
<H2><A NAME="sect6" HREF="#toc6">Tabset Indices</A></H2>
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:
<DL>
<DT><I>number</I> </DT>
<DD>Unique node
id of the tab. </DD>
<DT><B>@<I>x<B>,<I>y</I></B></I></B> </DT>
<DD>Tab that covers the point in the tabset window specified
by <I>x</I> and <I>y</I> (in screen coordinates). If no tab covers that point, then the
index is ignored. </DD>
<DT><B>select</B> </DT>
<DD>The currently selected tab. The <B>select</B> index is
typically changed by either clicking on the tab with the left mouse button
or using the widget's <B>invoke</B> operation. </DD>
<DT><B>active</B> </DT>
<DD>The tab where the mouse pointer
is currently located. The label is drawn using its active colors (see
the <B>-activebackground</B> and <B>-activeforeground</B> options). The <B>active</B> index is
typically changed by moving the mouse pointer over a tab or using the widget's
<B>activate</B> 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. </DD>
<DT><B>focus</B>
</DT>
<DD>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 <B>focus</B> operation. If
no tab has focus, then the index is ignored. </DD>
<DT><B>down</B> </DT>
<DD>Tab immediately below
the tab that currently has focus, if there is one. If there is no tab below,
the current tab is returned. </DD>
<DT><B>left</B> </DT>
<DD>Tab immediately to the left the tab that
currently has focus, if there is one. If there is no tab to the left, the
current tab is returned. </DD>
<DT><B>right</B> </DT>
<DD>Tab immediately to the right the tab that
currently has focus, if there is one. If there is no tab to the right, the
current tab is returned. </DD>
<DT><B>up</B> </DT>
<DD>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. </DD>
<DT><B>end</B> </DT>
<DD>Last tab in the tabset. If there are no tabs in the
tabset then the index is ignored. </DD>
</DL>
<P>
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 operations this is harmless and ignored.
<H2><A NAME="sect7" HREF="#toc7">Tabset
Operations</A></H2>
All <B>tabset</B> operations are invoked by specifying the widget's pathname,
the operation, and any arguments that pertain to that operation. The general
form is: <P>
<BR>
<P>
<CODE><tt> </tt> <tt> </tt> <I>pathName operation </I>?<I>arg arg ...</I>?<BR>
<P>
</CODE><P><I>Operation</I> and the <I>arg</I>s determine the exact behavior of the command. The
following operations are available for tabset widgets:
<DL>
<DT><I>pathName <B>activate</B></I>
<I>index</I> </DT>
<DD>Sets the active tab to the one indicated by <I>index</I>. The active tab
is drawn with its <I>active</I> colors (see the <B>-activebackground</B> and <B>-activeforeground</B>
options) and may be retrieved with the index <B>active</B>. Only one tab may be
active at a time. If <I>index</I> is the empty string, then all tabs will be drawn
with their normal foreground and background colors. </DD>
<DT><I>pathName <B>bind</B></I> <I>tagName</I>
?<I>sequence</I>? ?<I>command</I>? </DT>
<DD>Associates <I>command</I> with <I>tagName</I> such that whenever
the event sequence given by <I>sequence</I> occurs for a tab with this tag, <I>command</I>
will be invoked. The syntax is similar to the <B>bind</B> command except that
it operates on tabs, rather than widgets. See the <B>bind</B> manual entry for
complete details on <I>sequence</I> and the substitutions performed on <I>command</I>.
<P>
If all arguments are specified then a new binding is created, replacing
any existing binding for the same <I>sequence</I> and <I>tagName</I>. If the first character
of <I>command</I> is <I>+</I> then <I>command</I> augments an existing binding rather than
replacing it. If no <I>command</I> argument is provided then the command currently
associated with <I>tagName</I> and <I>sequence</I> (it's an error occurs if there's no
such binding) is returned. If both <I>command</I> and <I>sequence</I> are missing then
a list of all the event sequences for which bindings have been defined
for <I>tagName</I>. </DD>
<DT><I>pathName <B>cget</B></I> <I>option</I> </DT>
<DD>Returns the current value of the configuration
option given by <I>option</I>. <I>Option</I> may have any of the values accepted by the
<B>configure</B> operation described below. </DD>
<DT><I>pathName <B>configure</B></I> ?<I>option</I>? ?<I>value
option value ...</I>? </DT>
<DD>Query or modify the configuration options of the widget.
If no <I>option</I> is specified, returns a list describing all the available
options for <I>pathName</I> (see <B>Tk_ConfigureInfo</B> for information on the format
of this list). If <I>option</I> is specified with no <I>value</I>, 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 <I>option</I> is specified).
If one or more <I>option-value</I> 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. <I>Option</I> and <I>value</I> are described below: <blockquote></DD>
<DT><B>-activebackground
<I>color</I></B> </DT>
<DD>Sets the default active background color for tabs. A tab is active
when the mouse is positioned over it or set by the <B>activate</B> operation.
Individual tabs may override this option by setting the tab's <B>-activebackground</B>
option. </DD>
<DT><B>-activeforeground <I>color</I></B> </DT>
<DD>Sets the default active foreground color
for tabs. A tab is active when the mouse is positioned over it or set by
the <B>activate</B> operation. Individual tabs may override this option by setting
the tab's <B>-activeforeground</B> option. </DD>
<DT><B>-background <I>color</I></B> </DT>
<DD>Sets the background color
of the tabset. </DD>
<DT><B>-borderwidth <I>pixels</I></B> </DT>
<DD>Sets the width of the 3-D border around
the outside edge of the widget. The <B>-relief</B> option determines how the border
is to be drawn. The default is <I>2</I>. </DD>
<DT><B>-cursor <I>cursor</I></B> </DT>
<DD>Specifies the widget's cursor.
The default cursor is <I>""</I>. </DD>
<DT><B>-dashes <I>dashList</I></B> </DT>
<DD>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 label. <I>DashList</I> 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 <I>dashList</I> is <I>""</I>, the outline will be
a solid line. The default value is <I>5 2</I>. </DD>
<DT><B>-font <I>fontName</I></B> </DT>
<DD>Sets the default
font for the text in tab labels. Individual tabs may override this by setting
the tab's <B>-font</B> option. The default value is <I>*-Helvetica-Bold-R-Normal-*-12-120-*</I>.
</DD>
<DT><B>-foreground <I>color</I></B> </DT>
<DD>Sets the default color of tab labels. Individual tabs
may override this option by setting the tab's <B>-foreground</B> option. The default
value is <I>black</I>. </DD>
<DT><B>-gap <I>size</I></B> </DT>
<DD>Sets the gap (in pixels) between tabs. The default
value is <I>2</I>. </DD>
<DT><B>-height <I>pixels</I></B> </DT>
<DD>Specifies the requested height of widget. If <I>pixels</I>
is 0, then the height of the widget will be calculated based on the size
the tabs and their pages. The default is <I>0</I>. </DD>
<DT><B>-highlightbackground <I>color</I></B> </DT>
<DD>Sets
the color to display in the traversal highlight region when the tabset
does not have the input focus. </DD>
<DT><B>-highlightcolor <I>color</I></B> </DT>
<DD>Sets the color to
use for the traversal highlight rectangle that is drawn around the widget
when it has the input focus. The default is <I>black</I>. </DD>
<DT><B>-highlightthickness <I>pixels</I></B>
</DT>
<DD>Sets the width of the highlight rectangle to draw around the outside of
the widget when it has the input focus. <I>Pixels</I> is a non-negative value
and may have any of the forms acceptable to <B>Tk_GetPixels</B>. If the value is
zero, no focus highlight is drawn around the widget. The default is <I>2</I>. </DD>
<DT><B>-pageheight
<I>pixels</I></B> </DT>
<DD>Sets the requested height of the page. The page is the area under
the tab used to display the page contents. If <I>pixels</I> is <I>0</I>, the maximum
height of all embedded tab windows is used. The default is <I>0</I>. </DD>
<DT><B>-pagewidth
<I>pixels</I></B> </DT>
<DD>Sets the requested width of the page. The page is the area under
the tab used to display the page contents. If <I>pixels</I> is <I>0</I>, the maximum
width of all embedded tab windows is used. The default is <I>0</I>. </DD>
<DT><B>-relief <I>relief</I></B>
</DT>
<DD>Specifies the 3-D effect for the tabset widget. <I>Relief</I> specifies how the
tabset should appear relative to widget that it is packed into; for example,
<I>raised</I> means the tabset should appear to protrude. The default is <I>sunken</I>.
</DD>
<DT><B>-rotate <I>theta</I></B> </DT>
<DD>Specifies the degrees to rotate text in tab labels. <I>Theta</I> is
a real value representing the number of degrees to rotate the tick labels.
The default is <I>0.0</I> degrees. </DD>
<DT><B>-samewidth <I>boolean</I></B> </DT>
<DD>Indicates if each tab should
be the same width. If true, each tab will be as wide as the widest tab.
The default is <I>no</I>. </DD>
<DT><B>-scrollcommand <I>string</I></B> </DT>
<DD>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 specified, then
no command will be executed. </DD>
<DT><B>-scrollincrement <I>pixels</I></B> </DT>
<DD>Sets the smallest number
of pixels to scroll the tabs. If <I>pixels</I> 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). </DD>
<DT><B>-selectbackground <I>color</I></B> </DT>
<DD>Sets the
color to use when displaying background of the selected tab. Individual
tabs can override this option by setting the tab's <B>-selectbackground</B> option.
</DD>
<DT><B>-selectborderwidth <I>pixels</I></B> </DT>
<DD>Sets the width of the raised 3-D border to draw
around the label of the selected tab. <I>Pixels</I> must be a non-negative value.
The default value is <I>1</I>. </DD>
<DT><B>-selectcommand <I>string</I></B> </DT>
<DD>Specifies a default Tcl script
to be associated with tabs. This command is typically invoked when left
mouse button is released over the tab. Individual tabs may override this
with the tab's <B>-command</B> option. The default value is <I>""</I>. </DD>
<DT><B>-selectforeground <I>color<B>
</B></I></B></DT>
<DD>Sets the default color of the selected tab's text label. Individual tabs
can override this option by setting the tab's <B>-selectforeground</B> option. The
default value is <I>black</I>. </DD>
<DT><B>-selectpad <I>pixels<B> </B></I></B></DT>
<DD>Specifies extra padding to be displayed
around the selected tab. The default value is <I>3</I>. </DD>
<DT><B>-side <I>side<B> </B></I></B></DT>
<DD>Specifies the
side of the widget to place tabs. The following values are valid for <I>side</I>.
The default value is <I>top</I>. <blockquote></DD>
<DT><I>top</I> </DT>
<DD>Tabs are drawn along the top. </DD>
<DT><I>left</I> </DT>
<DD>Tabs are
drawn along the left side. </DD>
<DT><I>right</I> </DT>
<DD>Tabs are drawn along the right side. </DD>
<DT><I>both</I>
</DT>
<DD>Tabs are drawn along the bottom side. </DD>
</DL>
</blockquote>
<DL>
<DT><B>-slant <I>slant</I></B> </DT>
<DD>Specifies if the tabs
should be slanted 45 degrees on the left and/or right sides. The following
values are valid for <I>slant</I>. The default is <I>none</I>. <blockquote></DD>
<DT><I>none</I> </DT>
<DD>Tabs are drawn as
a rectangle. </DD>
<DT><I>left</I> </DT>
<DD>The left side of the tab is slanted. </DD>
<DT><I>right</I> </DT>
<DD>The right
side of the tab is slanted. </DD>
<DT><I>both</I> </DT>
<DD>Boths sides of the tab are slanted. </DD>
</DL>
</blockquote>
<DL>
<DT><B>-tabbackground
<I>color</I></B> </DT>
<DD>Sets the default background color of tabs. Individual tabs can override
this option by setting the tab's <B>-background</B> option. </DD>
<DT><B>-tabborderwidth <I>pixels</I></B>
</DT>
<DD>Sets the width of the 3-D border around the outside edge of the tab. The
<B>-tabrelief</B> option determines how the border is to be drawn. The default
is <I>2</I>. </DD>
<DT><B>-tabforeground <I>color</I></B> </DT>
<DD>Specifies the color to use when displaying a tab's
label. Individual tabs can override this option by setting the tab's <B>-foreground</B>
option. </DD>
<DT><B>-tabrelief <I>relief</I></B> </DT>
<DD>Specifies the 3-D effect for both tabs and folders.
<I>Relief</I> specifies how the tabs should appear relative to background of
the widget; for example, <I>raised</I> means the tab should appear to protrude.
The default is <I>raised</I>. </DD>
<DT><B>-takefocus</B> <I>focus</I> </DT>
<DD>Provides information used when
moving the focus from window to window via keyboard traversal (e.g., Tab
and Shift-Tab). If <I>focus</I> is <I>0</I>, this means that this window should be skipped
entirely during keyboard traversal. <I>1</I> 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 <I>1</I>. </DD>
<DT><B>-textside
<I>side<B> </B></I></B></DT>
<DD>If both images and text are specified for a tab, this option determines
on which side of the tab the text is to be displayed. The valid sides are
<I>left</I>, <I>right</I>, <I>top</I>, and <I>bottom</I>. The default value is <I>left</I>. </DD>
<DT><B>-tiers <I>number<B> </B></I></B></DT>
<DD>Specifies
the maximum number of tiers to use to display the tabs. The default value
is <I>1</I>. </DD>
<DT><B>-tile <I>image</I></B> </DT>
<DD>Specifies a tiled background for the widget. If <I>image</I>
isn't <I>""</I>, the background is tiled using <I>image</I>. Otherwise, the normal background
color is drawn (see the <B>-background</B> option). <I>Image</I> must be an image created
using the Tk <B>image</B> command. The default is <I>""</I>. </DD>
<DT><B>-width <I>pixels</I></B> </DT>
<DD>Specifies the
requested width of the widget. If <I>pixels</I> is 0, then the width of the widget
will be calculated based on the size the tabs and their pages. The default
is <I>0</I>. </DD>
</DL>
</blockquote>
<DL>
<DT><I>pathName <B>delete <I>first </I></B></I>?<I>last</I>? </DT>
<DD>Deletes one or more tabs from the tabset.
<I>First</I> and <I>last</I> are the first and last indices, defining a range of tabs
to be deleted. If <I>last</I> isn't specified, then only the tab at <I>first</I> is
deleted. </DD>
<DT><I>pathName <B>focus <I>index</I></B></I> </DT>
<DD>Designates a tab to get the widget's focus.
This tab is displayed with a dashed line around its label. </DD>
<DT><I>pathName <B>get</B></I>
<I>index</I> </DT>
<DD>Returns the name of the tab. The value of <I>index</I> may be in any form
described in the section <FONT SIZE=-1><B>TABSET INDICES</B></FONT>
</DD>
<DT><I>pathName <B>index</B></I> ?<I>flag</I>? <I>string</I>
</DT>
<DD>Returns the node id of the tab specified by <I>string</I>. If <I>flag</I> is <B>-name</B>, then
<I>string</I> is the name of a tab. If <I>flag</I> is <B>-index</B>, <I>string</I> is an index such as
"active" or "focus". If <I>flag</I> isn't specified, it defaults to <B>-index</B>. </DD>
<DT><I>pathName
<B>insert</B></I> <I>position <I>name</I></I> ?<I>option value</I>?... </DT>
<DD>Inserts new tabs into the tabset. Tabs
are inserted just before the tab given by <I>position</I>. <I>Position</I> may be either
a number, indicating where in the list the new tab should be added, or
<B>end</B>, indicating that the new tab is to be added the end of the list. <I>Name</I>
is the symbolic name of the tab. <I>Be careful not to use a number. Otherwise
the tabset will confuse it with tab indices</I>. Returns a list of indices
for all the new tabs. </DD>
<DT><I>pathName <B>invoke <I>index</I></B></I> </DT>
<DD>Selects the tab given by <I>index</I>,
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 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 <B>-state</B>
option) is disabled. </DD>
<DT><I>pathName <B>move</B></I> <I>index</I> <B>before</B>|<B>after</B> <I>index</I> </DT>
<DD>Moves the tab
<I>index</I> to a new position in the tabset. </DD>
<DT><I>pathName <B>nearest</B></I> <I>x</I> <I>y</I> </DT>
<DD>Returns the
name of the tab nearest to given X-Y screen coordinate. </DD>
<DT><I>pathName <B>scan</B></I> <I>option
args</I> </DT>
<DD>This command implements scanning on tabsets. It has two forms, depending
on <I>option</I>: <blockquote></DD>
<DT><I>pathName <B>scan mark <I>x y</I></B></I> </DT>
<DD>Records <I>x</I> and <I>y</I> and the current view
in the tabset window; used with later <B>scan dragto</B> commands. Typically this
command is associated with a mouse button press in the widget. It returns
an empty string. </DD>
<DT><I>pathName <B>scan dragto <I>x y</I></B></I>. </DT>
<DD>This command computes the difference
between its <I>x</I> and <I>y</I> arguments and the <I>x</I> and <I>y</I> arguments to the last <B>scan
mark</B> 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. </DD>
</DL>
</blockquote>
<DL>
<DT><I>pathName
<B>see <I>index</I></B></I> </DT>
<DD>Scrolls the tabset so that the tab <I>index</I> is visible in the widget's
window. </DD>
<DT><I>pathName <B>size</B></I> </DT>
<DD>Returns the number of tabs in the tabset. </DD>
<DT><I>pathName
<B>tab <I>operation</I></B></I> ?<I>args</I>? </DT>
<DD>See the <FONT SIZE=-1><B>TAB OPERATIONS</B></FONT>
section below. </DD>
<DT><I>pathName <B>view
<I>args</I></B></I> </DT>
<DD>This command queries or changes the position of the tabset in the
widget's window. It can take any of the following forms: <blockquote></DD>
<DT><I>pathName <B>view</B></I>
</DT>
<DD>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 <I>view</I> 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 <B>-scrollcommand</B> option.
</DD>
<DT><I>pathName <B>view moveto<I> fraction</I></B></I> </DT>
<DD>Adjusts the view in the window so that <I>fraction</I>
of the total width of the tabset text is off-screen to the left. <I>fraction</I>
must be a number between 0.0 and 1.0. </DD>
<DT><I>pathName <B>view scroll <I>number what</I></B></I> </DT>
<DD>This
command shifts the view in the window (left/top or right/bottom) according
to <I>number</I> and <I>what</I>. <I>Number</I> must be an integer. <I>What</I> must be either <B>units</B>
or <B>pages</B> or an abbreviation of these. If <I>what</I> is <B>units</B>, the view adjusts
left or right by <I>number</I> scroll units (see the <B>-scrollincrement</B> option).
; if it is <B>pages</B> then the view adjusts by <I>number</I> widget windows. If <I>number</I>
is negative then tabs farther to the left become visible; if it is positive
then tabs farther to the right become visible. </DD>
</DL>
</blockquote>
<H2><A NAME="sect8" HREF="#toc8">Tab Operations</A></H2>
<DL>
<DT><I>pathName <B>tab
cget</B></I> <I>nameOrIndex</I> <I>option</I> </DT>
<DD>Returns the current value of the configuration
option given by <I>option</I>. <I>Option</I> may have any of the values accepted by the
<B>tab configure</B> operation described below. </DD>
<DT><I>pathName <B>tab configure</B></I> <I>nameOrIndex</I>
?<I>nameOrIndex</I>...? <I>option</I>? ?<I>value option value ...</I>? </DT>
<DD>Query or modify the configuration
options of one or more tabs. If no <I>option</I> is specified, this operation returns
a list describing all the available options for <I>nameOrIndex</I>. <I>NameOrIndex</I>
can be either the name of a tab or its index. Names of tabs take precedence
over their indices. That means a tab named <I>focus</I> is picked over the "focus"
tab. </DD>
</DL>
<P>
If <I>option</I> is specified, but not <I>value</I>, then a list describing the one
named option is returned. If one or more <I>option-value</I> pairs are specified,
then each named tab (specified by <I>nameOrIndex</I>) will have its configurations
option(s) set the given value(s). In this last case, the empty string is
returned. <I>Option</I> and <I>value</I> are described below: <blockquote>
<DL>
<DT><B>-activebackground <I>color</I></B> </DT>
<DD>Sets
the active background color for <I>nameOrIndex</I>. A tab is active when the mouse
is positioned over it or set by the <B>activate</B> operation. This overrides
the widget's <B>-activebackground</B> option. </DD>
<DT><B>-activeforeground <I>color</I></B> </DT>
<DD>Sets the default
active foreground color <I>nameOrIndex</I>. A tab is "active" when the mouse is
positioned over it or set by the <B>activate</B> operation. Individual tabs may
override this option by setting the tab's <B>-activeforeground</B> option. </DD>
<DT><B>-anchor
<I>anchor</I></B> </DT>
<DD>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 itself. <I>Anchor</I> specifies how
the widget will be positioned in the extra space. For example, if <I>anchor</I>
is <I>center</I> then the window is centered in the folder ; if <I>anchor</I> is <I>w</I> then
the window will be aligned with the leftmost edge of the folder. The default
value is <I>center</I>. </DD>
<DT><B>-background <I>color</I></B> </DT>
<DD>Sets the background color for <I>nameOrIndex</I>.
Setting this option overides the widget's <B>-tabbackground</B> option. </DD>
<DT><B>-bindtags
<I>tagList</I></B> </DT>
<DD>Specifies the binding tags for this tab. <I>TagList</I> 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 <I>all</I>. </DD>
<DT><B>-command <I>string</I></B>
</DT>
<DD>Specifies a Tcl script to be associated with <I>nameOrIndex</I>. This command
is typically invoked when left mouse button is released over the tab.
Setting this option overrides the widget's <B>-selectcommand</B> option. </DD>
<DT><B>-data <I>string</I></B>
</DT>
<DD>Specifies a string to be associated with <I>nameOrIndex</I>. 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 <I>""</I>.
</DD>
<DT><B>-fill <I>fill</I></B> </DT>
<DD>If the space in the folder surrounding the tab's embedded widget
is larger than the widget, then <I>fill</I> indicates if the embedded widget
should be stretched to occupy the extra space. <I>Fill</I> is either <I>none</I>, <I>x</I>,
<I>y</I>, <I>both</I>. For example, if <I>fill</I> is <I>x</I>, then the widget is stretched horizontally.
If <I>fill</I> is <I>y</I>, the widget is stretched vertically. The default is <I>none</I>.
</DD>
<DT><B>-font <I>fontName</I></B> </DT>
<DD>Sets the font for the text in tab labels. If <I>fontName</I> is
not the empty string, this overrides the tabset's <B>-font</B> option. The default
value is <I>""</I>. </DD>
<DT><B>-foreground <I>color</I></B> </DT>
<DD>Sets the color of the label for <I>nameOrIndex</I>.
If <I>color</I> is not the empty string, this overrides the widget's <B>-tabforeground</B>
option. The default value is <I>""</I>. </DD>
<DT><B>-image <I>imageName</I></B> </DT>
<DD>Specifies the image to
be drawn in label for <I>nameOrIndex</I>. If <I>image</I> is <I>""</I>, no image will be drawn.
Both text and images may be displayed at the same time in tab labels. The
default value is <I>""</I>. </DD>
<DT><B>-ipadx <I>pad</I></B> </DT>
<DD>Sets the padding to the left and right of
the label. <I>Pad</I> can be a list of one or two screen distances. If <I>pad</I> has
two elements, the left side of the label is padded by the first distance
and the right side by the second. If <I>pad</I> has just one distance, both the
left and right sides are padded evenly. The default value is <I>0</I>. </DD>
<DT><B>-ipady <I>pad</I></B>
</DT>
<DD>Sets the padding to the top and bottom of the label. <I>Pad</I> can be a list of
one or two screen distances. If <I>pad</I> has two elements, the top of the label
is padded by the first distance and the bottom by the second. If <I>pad</I> has
just one distance, both the top and bottom sides are padded evenly. The
default value is <I>0</I>. </DD>
<DT><B>-padx <I>pad</I></B> </DT>
<DD>Sets the padding around the left and right
of the embedded widget, if one exists. <I>Pad</I> can be a list of one or two
screen distances. If <I>pad</I> has two elements, the left side of the widget
is padded by the first distance and the right side by the second. If <I>pad</I>
has just one distance, both the left and right sides are padded evenly.
The default value is <I>0</I>. </DD>
<DT><B>-pady <I>pad</I></B> </DT>
<DD>Sets the padding around the top and bottom
of the embedded widget, if one exists. <I>Pad</I> can be a list of one or two screen
distances. If <I>pad</I> has two elements, the top of the widget is padded by
the first distance and the bottom by the second. If <I>pad</I> has just one distance,
both the top and bottom sides are padded evenly. The default value is <I>0</I>.
</DD>
<DT><B>-selectbackground <I>color</I></B> </DT>
<DD>Sets the color to use when displaying background
of the selected tab. If <I>color</I> is not the empty string, this overrides the
widget's <B>-selectbackground</B> option. The default value is <I>""</I>. </DD>
<DT><B>-shadow <I>color</I></B> </DT>
<DD>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 <I>color</I> is the empty string, no shadow is drawn. The default value is <I>""</I>.
</DD>
<DT><B>-state <I>state</I></B> </DT>
<DD>Sets the state of the tab. If <I>state</I> is <I>disable</I> the text of the
tab is drawn as engraved and operations on the tab (such as <B>invoke</B> and
<B>tab tearoff</B>) are ignored. The default is <I>normal</I>. </DD>
<DT><B>-stipple <I>bitmap</I></B> </DT>
<DD>Specifies
a stipple pattern to use for the background of the folder when the window
is torn off. <I>Bitmap</I> specifies a bitmap to use as the stipple pattern. The
default is <I>BLT</I>. </DD>
<DT><B>-text <I>text</I></B> </DT>
<DD>Specifies the text of the tab's label. The exact
way the text is drawn may be affected by other options such as <B>-state</B> or
<B>-rotate</B>. </DD>
<DT><B>-window <I>pathName</I></B> </DT>
<DD>Specifies the widget to be embedded into the tab.
<I>PathName</I> must be a child of the <B>tabset</B> widget. The tabset will "pack"
and manage the size and placement of <I>pathName</I>. The default value is <I>""</I>.
</DD>
<DT><B>-windowheight <I>pixels</I></B> </DT>
<DD>Sets the requested height of the page. The page is
the area under the tab used to display the page contents. If <I>pixels</I> is
<I>0</I>, the maximum height of all embedded tab windows is used. The default
is <I>0</I>. </DD>
<DT><B>-windowwidth <I>pixels</I></B> </DT>
<DD>Sets the requested width of the page. The page
is the area under the tab used to display the page contents. If <I>pixels</I>
is <I>0</I>, the maximum width of all embedded tab windows is used. The default
is <I>0</I>. </DD>
</DL>
</blockquote>
<DL>
<DT><I>pathName <B>tab names</B></I> ?<I>pattern</I>? </DT>
<DD>Returns the names of all the tabs matching
the given pattern. If no <I>pattern</I> argument is provided, then all tab names
are returned. </DD>
<DT><I>pathName <B>tab tearoff <I>index</I></B></I> ?<I>newName</I>? </DT>
<DD>Reparents the widget
embedded into <I>index</I>, placing it inside of <I>newName</I>. <I>NewName</I> is either the
name of an new widget that will contain the embedded widget or the name
of the <B>tabset</B> widget. It the last case, the embedded widget is put back
into the folder. <P>
If no <I>newName</I> argument is provided, then the name of the
current parent of the embedded widget is returned. </DD>
</DL>
<H2><A NAME="sect9" HREF="#toc9">Default Bindings</A></H2>
<P>
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 <I>Tabset</I>):
<DL>
<DT><B><ButtonPress-2></B></DT>
<DD></DD>
<DT><B><B2-Motion></B></DT>
<DD></DD>
<DT><B><ButtonRelease-2></B></DT>
<DD>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.
</DD>
<DT><B><KeyPress-Up></B></DT>
<DD></DD>
<DT><B><KeyPress-Down></B></DT>
<DD>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. </DD>
<DT><B><KeyPress-Left></B></DT>
<DD></DD>
<DT><B><KeyPress-Right></B></DT>
<DD>The
left and right arrow keys move the focus to the tab immediately to the
left or right of the current focus tab. The tab with focus is drawn with
the a dashed outline around the tab label. </DD>
<DT><B><KeyPress-space></B></DT>
<DD></DD>
<DT><B><KeyPress-Return></B></DT>
<DD>The
space and return keys select the current tab given focus. When a folder
is selected, it's command is invoked and the embedded widget is mapped.
</DD>
</DL>
<P>
Each tab, by default, also has a set of bindings (via the tag <I>all</I>). These
bindings may be reset using the tabset's <B>bind</B> operation.
<DL>
<DT><B><Enter></B></DT>
<DD></DD>
<DT><B><Leave></B></DT>
<DD>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.
</DD>
<DT><B><ButtonRelease-1></B></DT>
<DD>Clicking with the left mouse button on a tab causes the tab
to be selected and its Tcl script (see the <B>-command</B> or <B>-selectcommand</B> options)
to be invoked. The folder and any embedded widget (if one is specified)
is automatically mapped. </DD>
<DT><B><ButtonRelease-3></B></DT>
<DD></DD>
<DT><B><Control-ButtonRelease-1></B></DT>
<DD>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. </DD>
</DL>
<H2><A NAME="sect10" HREF="#toc10">Bind Tags</A></H2>
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 <B>Enter</B>, <B>Leave</B>, <B>ButtonPress</B>, <B>Motion</B>,
and <B>KeyPress</B>). <P>
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 <B>-bindtags</B>
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 invoked. 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. <P>
The <B>-bindtags</B> 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 <B>-bindtags</B> option doesn't change this.
<H2><A NAME="sect11" HREF="#toc11">Keywords</A></H2>
tabset,
widget <P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Syntax</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Tabset Indices</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Tabset Operations</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Tab Operations</A></LI>
<LI><A NAME="toc9" HREF="#sect9">Default Bindings</A></LI>
<LI><A NAME="toc10" HREF="#sect10">Bind Tags</A></LI>
<LI><A NAME="toc11" HREF="#sect11">Keywords</A></LI>
</UL>
</BODY></HTML>
