# iwidgets2.2.0 User Commands - tabnotebook

##

## NAME

         tabnotebook - create and manipulate tabnotebook widgets

## SYNOPSIS

         tabnotebook pathName? options?

## INHERITANCE

         itk::Widget <- tabnotebook

## STANDARD OPTIONS

         background      disabledForeground             foregroundscrollCommand
         cursor          font           height          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:           auto
         Class:          Auto
         Command-Line Switch:           -auto

              Specifies    whether    to    use     the     automatic
              packing/unpacking algorithm of the notebook. A value of
              true indicates that page frames will  be  unpacked  and
              packed  acoording  to  the  algorithm  described in the
              select command. A value of  false  leaves  the  current
              page  packed  and subsequent selects, next, or previous
              commands do not switch pages automatically.  In  either
              case   the  page's  associated  command  (see  the  add
              command's  description  of  the  command   option)   is
              invoked.  The  value may have any of the forms accepted
              by the Tcl_GetBoolean, such as true, false, 0, 1,  yes,
              or no.

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

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

         Name:           background
         Class:          Background
         Command-Line Switch:           -background

              Specifies a background color to use  for  displaying  a
              page  and its associated tab. This can be thought of as
              the selected tab background color, since the tab  asso-
              ciated with the selected page is the selected tab.

         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:           borderWidth
         Class:          BorderWidth
         Command-Line Switch:           -borderwidth

              Specifies the width of shadowed border to place  around
              the notebook area of the tabnotebook. The default value
              is 2.

         Name:           disabledForeground
         Class:          DisabledForeground
         Command-Line Switch:           -disabledforeground

              Specifies a foreground color to use  for  displaying  a
              tab's label when its state is disabled.

         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:           foreground
         Class:          Foreground
         Command-Line Switch:           -foreground

              Specifies a foreground color to use  for  displaying  a
              page  and its associated tab label. This can be thought
              of as the selected tab background color, since the  tab
              associated with the selected page is the selected tab.

         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:           -Bmargin

              Specifies the amount of space to place between the out-
              side  edge  of  the tabnotebook and the outside edge of
              its tabs. If tabPos is s, this is the amount  of  space
              between the bottom edge of the tabnotebook and the bot-
              tom edge of the set of tabs. If tabPos is  n,  this  is
              the  amount  of  space between the top edge of the tab-
              notebook 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 tabnotebook 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 tabnotebook 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 of  the  tabnotebook  than
              the  unselected  tabs.  A  value  of true says to raise
              selected tabs, a value of false turns this feature 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 tabnotebook and the starting edge of
              its tabs. For horizontally positioned tabs, this is the
              amount  of  space between the left edge of the notebook
              and the left edge of  the  first  tab.  For  vertically
              positioned  tabs,  this  is the amount of space between
              the top of the notebook 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  tabnotebook.  Specifying
              normal  allows  all  pages to be selectable. Specifying
              disabled disables the notebook causing all page tabs to
              be drawn in the disabledForeground color.

         Name:           tabBackground
         Class:          TabBackground
         Command-Line Switch:           -tabbackground

              Specifies a background color to use for displaying  tab
              backgrounds  when  they  are in their unselected state.
              This is the background  associated  with  tabs  on  all
              pages other than the selected page.

         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:           tabForeground
         Class:          TabForeground
         Command-Line Switch:           -tabforeground

              Specifies a foreground color to use for displaying  tab
              labels when they are in their unselected state. This is
              the foreground associated with tabs on all pages  other
              than the selected page.

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

              Specifies the location of the set of tabs  in  relation
              to  the  notebook area. Must be n, s, e, or w. Defaults
              to s.

##

## DESCRIPTION

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

         A tabnotebook is a widget that  contains  a  set  of  tabbed
         pages.  It  displays  one  page from the set as the selected
         page. A Tab displays the label for the page to which  it  is
         attached and serves as a page selector. When a page's tab is
         selected, the page's contents  are  displayed  in  the  page
         area.  The  selected  tab  has a three-dimensional effect to
         make it appear to float above the other tabs. The  tabs  are
         displayed  as  a group along either the left, top, right, or
         bottom edge. When first created a tabnotebook has no  pages.
         Pages   may  be  added  or  deleted  using  widget  commands
         described below.

         A special option may be provided  to  the  tabnotebook.  The
         -auto option specifies whether the tabnotebook will automat-
         ically handle the unpacking and packing of pages when  pages
         are  selected.  A  value of true signifies that the notebook
         will automatically manage it. This is the default  value.  A
         value  of  false  signifies  the  notebook  will not perform
         automatic switching of pages.

## NOTEBOOK PAGES

         A tabnotebook's pages area  contains  a  single  child  site
         frame.  When  a  new  page  is created it is a child of this
         frame. The page's child site frame serves as a geometry con-
         tainer  for  applications  to  pack widgets into. It is this
         frame that is automatically unpacked or packed when the auto
         option  is  true.  This creates the effect of one page being
         visible at a time. When a new page is selected,  the  previ-
         ously  selected  page's  child  site  frame is automatically
         unpacked from the tabnotebook's child  site  frame  and  the
         newly   selected  page's  child  site  is  packed  into  the
         tabnotebook's child site frame.

         However, sometimes it is desirable to handle page changes in
         a  different manner. By specifying the auto option as false,
         child site packing can be disabled and done differently. For
         example,  all  widgets might be packed into the first page's
         child site frame. Then when a  new  page  is  selected,  the
         application can reconfigure the widgets and give the appear-
         ance that the page was flipped.

         In both cases the command option for a page specifies a  Tcl
         Command to execute when the page is selected. In the case of
         auto being true, it is between the unpacking of  the  previ-
         ously  selected  page  and the packing of the newly selected
         page.

         Notebook pages can also be controlled with  scroll  bars  or
         other  widgets that obey the scrollcommand protocol. By giv-
         ing a scrollbar a -command to call the tabnotebook's  select
         method, the tabnotebook can be controlled with a scrollbar.

         The notebook area is  implemented  with  the  notebook  mega
         widget.

## TABS

         Tabs appear along the edge of the notebook  area.  Tabs  are
         drawn  to  appear  attached to their associated page. When a
         tab is clicked on, the associated page is selected  and  the
         tab  is  drawn as raised above all other tabs and as a seam-
         less part of its notebook page. Tabs can  be  controlled  in
         their  location  along  the  edges,  the angle tab sides are
         drawn with, gap  between  tabs,  starting  margin  of  tabs,
         internal  padding around text labels in a tab, the font, and
         its label.

         The Tab area is implemented with the tabset mega widget. See
         tabset(1).  Tabs  may  be  oriented  along either the north,
         south, east, or west sides with the tabPos option. North and
         south  tabs  may appear as angled, square, or bevelled. West
         and east tabs may appear as square or bevelled. By  changing
         tab  gaps,  tab  angles,  bevelling,  orientations,  colors,
         fonts, start locations, and margins; tabs may  appear  in  a
         wide  variety  of  styles.  For  example,  it is possible to
         implement Microsoft-style tabs, Borland property tab styles,
         or Borland Delphi style tabs all with the same tabnotebook.

## WIDGET-SPECIFIC METHODS

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

              pathName option ?arg arg ...?

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

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

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

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

         end  Specifes the last page in the tabnotebook's  index.  If
              the notebook 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  page  in  the  notebook,  in
              order from the first to the last page, until a matching
              entry is found. The rules of Tcl_StringMatch are  used.
              The  following  commands  are  possible for tabnotebook
              widgets:

         pathName add ?option value option value ...?
              Add a new page at the end of  the  tabnotebook.  A  new
              child  site  frame  is  created. 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 tabnotebook
                   is used. This is generally only set  at  the  tab-
                   notebook  level.  Tabs normally will want to share
                   the same angle value.

              -background value
                   Specifies a background color to use for displaying
                   tabs when they are selected and for displaying the
                   current page. If this option is  specified  as  an
                   empty  string  (the  default), then the background
                   option for the overall tabnotebook 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  gen-
                   erally  only  set  at  the tabnotebook 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  this page's tab. Bitmap may be of
                   any of the forms accepted by Tk_GetPixmap.

              -command value
                   Specifies a Tcl command to be executed  when  this
                   page  is  selected.  This  allows the programmer a
                   hook to reconfigure this  page's  widgets  or  any
                   other page's widgets.

                   If the tabnotebook has  the  auto  option  set  to
                   true, when a page is selected this command will be
                   called immediately after the  previously  selected
                   page  is unpacked and immediately before this page
                   is selected. The index value select is valid  dur-
                   ing  this  Tcl command. `index select' will return
                   this page's page number.

                   If the auto option is set to false, when a page is
                   selected  the  unpack and pack calls are bypassed.
                   This Tcl command is still called.

              -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 disabledforeground option
                   for the overall tabnotebook is used.

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

              -foreground value
                   Specifies a foreground color to use for displaying
                   tab  labels when they are selected. If this option
                   is specified as an  empty  string  (the  default),
                   then  the  foreground  option for the overall tab-
                   notebook is used.

              -label value
                   Specifies a string to display  as  an  identifying
                   label for a notebook page. This label serves as an
                   additional identifier used to reference the  page.
                   This  label  may  be  used  for the index value in
                   widget commands.

              -tabbackground value
                   Specifies a background color to use for displaying
                   a  tab  when  it is not elected. If this option is
                   specified as an empty string (the  default),  then
                   the  tabBackground option for the overall tabnote-
                   book is used.

              -tabforeground value
                   Specifies a foreground color to use for displaying
                   the  tab's  text label when it is not selected. If
                   this option is specified as an empty  string  (the
                   default),  then  the  tabForeground option for the
                   overall tabnotebook 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 tabnotebook
                   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 tabnotebook
                   is used

              -state value
                   Specifies one of two states for the  page:  normal
                   or  disabled.  In normal state unselected tabs are
                   displayed using  the  tabforeground  and  tabback-
                   ground  option  from  the tabnotebook or the page.
                   Selected tabs and pages are  displayed  using  the
                   foreground and background option from the tabnote-
                   book or the page. The disabled  state  means  that
                   the  page  and  its tab is insensitive: it doesn't
                   respond to mouse button presses  or  releases.  In
                   this state the entry is displayed according to its
                   disabledForeground option for the tabnotebook  and
                   the  background/tabbackground option from the page
                   or the tabnotebook.

         pathName childSite ?index?
              If passed no arguments, returns a list of pathNames for
              all  the  pages in the tabnotebook. If the tab notebook
              is empty, an empty list is returned

              If index is passed, it returns  the  pathName  for  the
              page's  child  site  frame  specified by index. Widgets
              that are created with this pathName will  be  displayed
              when the associated page is selected. If index is not a
              valid index, an empty string is returned.

         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  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  correspond-
              ing  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 tabnotebook command.

         pathName delete index1 ?index2?
              Delete all of  the  pages  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 page in the tabnotebook  before  the  page
              specified  by index. A new child site frame is created.
              The additional arguments are the same as  for  the  add
              command. Returns the child site pathName.

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

              For notebooks with auto set to true the current  page's
              child  site  is unpacked from the notebook's child site
              frame. Then the next page's child site is  packed  into
              the  notebook's child site frame. The Tcl command given
              with the command option will be invoked  between  these
              two operations.

              For notebooks with auto set to false  the  Tcl  command
              given with the command option will be invoked.

         pathName pageconfigure index ?option? ?value option value ...?
              This  command  is  similar  to  the  configure command,
              except that it applies to the options for an individual
              page,  whereas configure applies to the options for the
              tabnotebook 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 command returns an empty string. If no
              options are specified, returns a  list  describing  the
              current  options  for  page index (see Tk_ConfigureInfo
              for information on the format of this list).

         pathName prev
              Moves the selected page to the previous page (order  is
              determined   by  insertion  order).  If  the  currently
              selected page is the first page in  the  notebook,  the
              selection  wraps  around  to the last page in the note-
              book. It behaves as if the user selected the new page.

              For notebooks with auto set to true the current  page's
              child  site  is unpacked from the notebook's child site
              frame. Then the previous page's child  site  is  packed
              into  the  notebook's child site frame. The Tcl command
              given with the command option will be  invoked  between
              these two operations.

              For notebooks with auto set to false  the  Tcl  command
              given with the command option will be invoked.

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

              For notebooks with auto set to true the current  page's
              child  site  is unpacked from the notebook's child site
              frame. Then the index page's child site is packed  into
              the  notebook's child site frame. The Tcl command given
              with the command option will be invoked  between  these
              two operations.

              For notebooks with auto set to false  the  Tcl  command
              given with the command option will be invoked.

         pathName view
              Returns the currently selected page.  This  command  is
              for compatibility with the scrollbar widget.

         pathName view index
              Selects the page specified by index  as  the  currently
              selected  page.  This command is for compatibility with
              the scrollbar widget.

         pathName view moveto fraction
              Uses the fraction value to determine the  corresponding
              page to move to. This command is for compatibility with
              the scrollbar widget.

         pathName view scroll num what
              Uses the num value to determine how many pages to  move
              forward  or backward (num can be negative or positive).
              The what argument is ignored. This command is for  com-
              patibility with the scrollbar widget.

## COMPONENTS

         Generally all behavior of the  internal  components,  tabset
         and  notebook  are  controlled via the pageconfigure method.
         The following section documents these two components.

         Name:   tabset
         Class:  Tabset

              This is the tabset component. It  implements  the  tabs
              that are associated with the notebook component.

              See the "Tabset" widget manual entry for details on the
              tabset component item.

         Name:   notebook
         Class:  Notebook

              This is the notebook component. It implements the note-
              book that contains the pages of the tabnotebook.

              See the "Notebook" widget manual entry for  details  on
              the notebook component item.

## EXAMPLE

         Following is an example that creates a tabnotebook with  two
         pages.

              # Create the tabnotebook widget and pack it.
                tabnotebook .tn -width 100 -height 100
                pack .tn \
                      -anchor nw \
                      -fill both \
                      -expand yes \
                      -side left \
                      -padx 10 \
                      -pady 10

              # Add two pages to the tabnotebook,
              # labelled "Page One" and "Page Two"
                .tn add -label "Page One"
                .tn add -label "Page Two"

              # Get the child site frames of these two pages.
                set page1CS [.tn childsite 0]
                set page2CS [.tn childsite "Page Two"]

              # Create buttons on each page of the tabnotebook.
                button $page1CS.b -text "Button One"
                pack $page1CS.b
                button $page2CS.b -text "Button Two"
                pack $page2CS.b

              # Select the first page of the tabnotebook.
                .tn select 0

## AUTHOR

         Bill W. Scott

## KEYWORDS

         tab tabset notebook tabnotebook page