# iwidgets2.2.0 User Commands - tabset

##

## NAME

         tabset - create and manipulate tabs as as set

## SYNOPSIS

         tabset pathName ?options?

## INHERITANCE

         itk::Widget <- tabset

## STANDARD OPTIONS

         background      font           selectBackgroundcursor
         foreground      selectForeground               disabledForegroundheight
         width

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

## WIDGET-SPECIFIC OPTIONS

         Name:           angle
         Class:          Angle
         Command-Line Switch:           -angle

              Specifes the angle of slope from the inner edge to  the
              outer  edge  of the tab. An angle of 0 specifies square
              tabs. Valid ranges  are  0  to  45  degrees  inclusive.
              Default is 15 degrees. If tabPos is e or w, this option
              is ignored.

         Name:           backdrop
         Class:          Backdrop
         Command-Line Switch:           -backdrop

              Specifies a background color to use when filling in the
              area behind the tabs.

         Name:           bevelAmount
         Class:          BevelAmount
         Command-Line Switch:           -bevelamount

              Specifes the size of tab corners. A  value  of  0  with
              angle set to 0 results in square tabs. A bevelAmount of
              4, means that the tab will be drawn with angled corners
              that  cut  in  4  pixels  from the edge of the tab. The
              default is 0.

         Name:           command
         Class:          Command
         Command-Line Switch:           -command
         Specifes the prefix of a Tcl command to invoke to change the view in the
         widget associated with the tabset. When a user selects a tab, a Tcl command
         is invoked. The actual command consists of this option followed by a space
         and a number. The number is the numerical index of the tab that has been
         selected.

         Name:           equalTabs
         Class:          EqualTabs
         Command-Line Switch:           -equaltabs

              Specifies whether to force tabs to be  equal  sized  or
              not.  A  value of true means constrain tabs to be equal
              sized. A value of false allows each tab to  size  based
              on  the  text label size. The value may have any of the
              forms accepted by the  Tcl_GetBoolean,  such  as  true,
              false, 0, 1, yes, or no.

              For horizontally positioned tabs (tabPos is either s or
              n),  true  forces all tabs to be equal width (the width
              being equal to the longest label plus any  padX  speci-
              fied). Horizontal tabs are always equal in height.

              For vertically positioned tabs (tabPos is either  w  or
              e), true forces all tabs to be equal height (the height
              being equal to the height of the label with the largest
              font).  Vertically  oriented  tabs  are always equal in
              width.

         Name:           gap
         Class:          Gap
         Command-Line Switch:           -gap

              Specifies the amount of pixel space  to  place  between
              each tab. Value may be any pixel offset value. In addi-
              tion, a special keyword overlap  can  be  used  as  the
              value to achieve a standard overlap of tabs. This value
              may have any of the forms acceptable to Tk_GetPixels.

         Name:           margin
         Class:          Margin
         Command-Line Switch:           -margin

              Specifies the amount of space to place between the out-
              side  edge  of  the  tabset and the outside edge of its
              tabs. If tabPos is s,  this  is  the  amount  of  space
              between  the  bottom  edge of the tabset and the bottom
              edge of the set of tabs. If tabPos is n,  this  is  the
              amount  of space between the top edge of the tabset and
              the top edge of the set of tabs. If tabPos is  e,  this
              is  the  amount  of space between the right edge of the
              tabset and the right edge of the set of tabs. If tabPos
              is w, this is the amount of space between the left edge
              of the tabset and the left edge of  the  set  of  tabs.
              This  value  may  have  any  of the forms acceptable to
              Tk_GetPixels.

         Name:           padX
         Class:          PadX
         Command-Line Switch:           -padx

              Specifies a  non-negative  value  indicating  how  much
              extra  space  to  request for a tab around its label in
              the X-direction. When computing how large a  window  it
              needs,  the  tab  will  add this amount to the width it
              would normally need The tab  will  end  up  with  extra
              internal space to the left and right of its text label.
              This value may have any  of  the  forms  acceptable  to
              Tk_GetPixels.

         Name:           padY
         Class:          PadY
         Command-Line Switch:           -pady

              Specifies a  non-negative  value  indicating  how  much
              extra  space  to  request for a tab around its label in
              the Y-direction. When computing how large a  window  it
              needs,  the  tab  will add this amount to the height it
              would normally need The tab  will  end  up  with  extra
              internal space to the top and bottom of its text label.
              This value may have any  of  the  forms  acceptable  to
              Tk_GetPixels.

         Name:           raiseSelect
         Class:          RaiseSelect
         Command-Line Switch:           -raiseselect

              Specifes whether to slightly  raise  the  selected  tab
              from  the rest of the tabs. The selected tab is drawn 2
              pixels closer to the outside edge of  the  tabset  than
              the  unselected  tabs.  A  value  of true says to raise
              selected tabs, a value of false  turns  this  off.  The
              default  is  false. The value may have any of the forms
              accepted by the Tcl_GetBoolean, such as true, false, 0,
              1, yes, or no.

         Name:           start
         Class:          Start
         Command-Line Switch:           -start

              Specifies the amount of space to place between the left
              or  top edge of the tabset and the starting edge of its
              tabs. For horizontally positioned  tabs,  this  is  the
              amount of space between the left edge of the tabset and
              the left edge of the first tab.  For  vertically  posi-
              tioned  tabs,  this  is the amount of space between the
              top of the tabset and the top of the  first  tab.  This
              value  may  change  if  the  user  performs a MButton-2
              scroll on the tabs. This value  may  have  any  of  the
              forms acceptable to Tk_GetPixels.

         Name:           state
         Class:          State
         Command-Line Switch:           -state

              Sets the active state of the tabset. Specifying  normal
              allows  all  tabs to be selectable. Specifying disabled
              disables the tabset causing all tabs to be drawn in the
              disabledForeground color.

         Name:           tabBorders
         Class:          TabBorders
         Command-Line Switch:           -tabborders

              Specifies whether to draw the borders of tabs that  are
              not selected. Specifying true (the default) draws these
              borders, specifying false draws only the border  around
              the  selected  tab. The value may have any of the forms
              accepted by the Tcl_GetBoolean, such as true, false, 0,
              1, yes, or no.

         Name:           tabPos
         Class:          TabPos
         Command-Line Switch:           -tabpos

              Specifies the location of the set of tabs  in  relation
              to  another  widget. Must be n, s, e, or w. Defaults to
              s. North tabs open downward, South  tabs  open  upward.
              West  tabs  open  to  the  right, east tabs open to the
              left.

##

## DESCRIPTION

         The tabset command creates a new window (given by the  path-
         Name argument) and makes it into a tabset widget. Additional
         options, described above may be  specified  on  the  command
         line  or  in the option database to configure aspects of the
         tabset such as its colors, font, and text. The  tabset  com-
         mand 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.

         A tabset is a widget that contains a set of Tab buttons.  It
         displays  these tabs in a row or column depending on it tab-
         pos. When a tab is clicked on, it becomes the  only  tab  in
         the tab set that is selected. All other tabs are deselected.
         The Tcl command prefix associated with this tab (through the
         command  tab configure option) is invoked with the tab index
         number appended to its argument list. This allows the tabset
         to control another widget such as a Notebook.

## TABS

         Tabs are drawn to appear attached  to  another  widget.  The
         tabset  draws  an edge boundary along one of its edges. This
         edge is known as the attachment edge. This edge location  is
         dependent  on the value of tabPos. For example, if tabPos is
         s, the attachment edge wil be on the top side of the  tabset
         (in  order  to  attach  to  the  bottom or south side of its
         attached widget). The selected tab is draw with a 3d  relief
         to  appear  above  the other tabs. This selected tab "opens"
         toward attachment edge.

         Tabs can be controlled in their location  along  the  edges,
         the  angle  that tab sides are drawn with, gap between tabs,
         starting margin of tabs, internal padding around labels in a
         tab, the font, and its text or bitmap.

## WIDGET-SPECIFIC METHODS

         The tabset command creates a new Tcl command whose  name  is
         pathName.  This command may be used to invoke various opera-
         tions on the widget. It has the following general form:

              pathName option ?arg arg ...?

         option and the args determine the exact behavior of the com-
         mand.

         Many of the widget commands for a tabset take as  one  argu-
         ment  an indicator of which tab of the tabset to operate on.
         These indicators are called indexes and may be specified  in
         any of the following forms:

         number
              Specifies the tab numerically, where 0  corresponds  to
              the  first  tab in the tab set, 1 to the second, and so
              on.

         select
              Specifies the currently selected tab's index. If no tab
              is currently selected, the value -1 is returned.

         end  Specifes the last tab in the  tabset's  index.  If  the
              tabset is empty this will return -1.

         pattern
              If the index doesn't satisfy any of  the  above  forms,
              then  this  form  is  used.  Pattern is pattern-matched
              against the label of each tab in the tabset,  in  order
              from  the first to the last tab, until a matching entry
              is found. The rules of Tcl_StringMatch are used.

         The following commands are possible for tabset widgets:

              pathName add ?option value option value ...?
                   Add a new tab at the end of  the  tabset.  Returns
                   the  child  site pathName. If additional arguments
                   are present, they specify  any  of  the  following
                   options:

                   -angle value
                        Specifes the angle of slope  from  the  inner
                        edge  to  the outer edge of the tab. An angle
                        of 0 specifies square tabs. Valid ranges  are
                        0  to  45  degrees  inclusive.  Default is 15
                        degrees. If this option is  specified  as  an
                        empty  string  (the  default), then the angle
                        option for the overall tabset is used.

                   -background value
                        Specifies  a  background  color  to  use  for
                        displaying tabs when they are in their normal
                        state (unselected). If this option is  speci-
                        fied  as  an empty string (the default), then
                        the background option for the overall  tabset
                        is used.

                   -bevelamount value
                        Specifes the size of tab corners. A value  of
                        0 with angle set to 0 results in square tabs.
                        A bevelAmount of 4, means that the  tab  will
                        be  drawn  with  angled corners that cut in 4
                        pixels from the edge of the tab. The  default
                        is  0. This is generally only set at the tab-
                        set configuration level. Tabs  normally  will
                        want to share the same bevelAmount.

                   -bitmap value
                        If label is a non-empty string,  specifies  a
                        bitmap  to  display in the tab. Bitmap may be
                        of any of the forms accepted by Tk_GetBitmap.

                   -disabledforeground value
                        Specifies  a  foreground  color  to  use  for
                        displaying  tab labels when tabs are in their
                        disable state. If this option is specified as
                        an empty string (the default), then the disa-
                        bledforeground option for the overall  tabset
                        is used.

                   -font value
                        Specifies the font to use  when  drawing  the
                        label  on  a tab. If this option is specified
                        as an empty string then the font  option  for
                        the overall tabset is used.

                   -foreground value
                        Specifies  a  foreground  color  to  use  for
                        displaying  tab labels when tabs are in their
                        normal unselected state. If  this  option  is
                        specified  as  an empty string (the default),
                        then the foreground option  for  the  overall
                        tabset is used.

                   -image value
                        If label is a non-empty string, specifies  an
                        image  to display in the tab. Image must have
                        been created with the image  create  command.
                        Typically,  if  the image option is specified
                        then it overrides other options that  specify
                        a  bitmap  or textual value to display in the
                        widget; the image option may be reset  to  an
                        empty  string  to  re-enable a bitmap or text
                        display.

                   -label value
                        Specifies a text string to be placed  in  the
                        tabs  label. If this value is set, the bitmap
                        option is overridden and this option is  used
                        instead.  This  label serves as an additional
                        identifier used to reference  the  tab.  This
                        label  may  be  used  for  the index value in
                        widget commands.

                   -selectbackground value
                        Specifies  a  background  color  to  use  for
                        displaying  the  selected tab. If this option
                        is  specified  as  an   empty   string   (the
                        default),  then  the  selectBackground option
                        for the overall tabset is used.

                   -selectforeground value
                        Specifies  a  foreground  color  to  use  for
                        displaying  the  selected tab. If this option
                        is  specified  as  an   empty   string   (the
                        default),  then  the  selectForeground option
                        for the overall tabset is used.

                   -padx value
                        Specifies a non-negative value indicating how
                        much  extra space to request for a tab around
                        its label in the X-direction. When  computing
                        how large a window it needs, the tab will add
                        this amount to the width  it  would  normally
                        need  The tab will end up with extra internal
                        space to the  left  and  right  of  its  text
                        label.  This  value may have any of the forms
                        acceptable to Tk_GetPixels. If this option is
                        specified  as  an empty string (the default),
                        then the padX option for the  overall  tabset
                        is used

                   -pady value
                        Specifies a non-negative value indicating how
                        much  extra space to request for a tab around
                        its label in the Y-direction. When  computing
                        how large a window it needs, the tab will add
                        this amount to the height it  would  normally
                        need  The tab will end up with extra internal
                        space to the  top  and  bottom  of  its  text
                        label.  This  value may have any of the forms
                        acceptable to Tk_GetPixels. If this option is
                        specified  as  an empty string (the default),
                        then the padY option for the  overall  tabset
                        is used

                   -state value
                        Sets the state of the tab. Specifying  normal
                        allows  this tab to be selectable. Specifying
                        disabled disables the this  tab  causing  its
                        tab  label  to  be drawn in the disabledFore-
                        ground color. The tab  will  not  respond  to
                        events until the state is set back to normal.

              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 available options for  path-
                   Name  (see Tk_ConfigureInfo for information on the
                   format of this list). If option is specified  with
                   no value, then the command returns a list describ-
                   ing the one named option (this list will be ident-
                   ical  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 tabset command.

              pathName delete index1 ?index2?
                   Delete all of the tabs between index1  and  index2
                   inclusive.  If  index2 is omitted then it defaults
                   to index1. Returns an empty string.

              pathName index index
                   Returns  the  numerical  index  corresponding   to
                   index.

              pathName insert index ?option value option value ...?
                   Insert a new tab in  the  tabset  before  the  tab
                   specified  by  index. The additional arguments are
                   the same as for the add command. Returns the tab's
                   pathName.

              pathName next
                   Advances the selected tab to the next  tab  (order
                   is   determined   by   insertion  order).  If  the
                   currently selected tab is the last tab in the tab-
                   set,  the selection wraps around to the first tab.
                   It behaves as if the user selected the next tab.

              pathName tabconfigure index ?option? ?value?
                   This command is similar to the configure  command,
                   except that it applies to the options for an indi-
                   vidual  tab,  whereas  configure  applies  to  the
                   options  for  the  tabset  as a whole. Options may
                   have any of the values accepted by the add  widget
                   command.  If  options  are  specified, options are
                   modified as indicated in the command and the  com-
                   mand  returns  an  empty string. If no options are
                   specified, returns a list describing  the  current
                   options  for  tab  index (see Tk_ConfigureInfo for
                   information on the format of this list).

              pathName prev
                   Moves the selected tab to the previous tab  (order
                   is   determined   by   insertion  order).  If  the
                   currently selected tab is the  first  tab  in  the
                   tabset, the selection wraps around to the last tab
                   in the tabset. It behaves as if the user  selected
                   the previous tab.

              pathName select index
                   Selects  the  tab  specified  by  index   as   the
                   currently  selected tab. It behaves as if the user
                   selected the new tab.

## EXAMPLE

         Following is an example that creates a tabset with two  tabs
         and a list box that the tabset controls. In addition select-
         ing an item from the list  also  selects  the  corresponding
         tab.

              # Define a proc that knows how to select an item
              # from a list given an index from the tabset -command callback.
                proc selectItem { item } {
                  .l selection clear [.l curselection]
                  .l selection set $item
                  .l see $item

              }

              # Define a proc that knows how to select a tab
              # given a y pixel coordinate from the list..
                proc selectTab { y } {
                  set whichItem [.l nearest $y]
                  .ts select $whichItem
              }

              # Create a listbox with two items (one and two)
              # and bind button 1 press to the selectTab procedure.
                listbox .l -selectmode single -exportselection false
                .l insert end one
                .l insert end two
                .l selection set 0
                pack .l
                bind .l <ButtonPress-1> { selectTab %y }

              # Create a tabset, set its -command to call selectItem
              # Add two labels to the tabset (one and two).
                tabset .ts -command selectItem
                .ts add -label 1
                .ts add -label 2
                .ts select 0
                pack .ts -fill x -expand no

## AUTHOR

         Bill W. Scott

## KEYWORDS

         tab tabset notebook tabnotebook