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