ABCDEFGHIJKLMNOPQRSTUVWXYZ

tabnotebook

tabnotebook(1)                  [incr Widgets]                  tabnotebook(1)



______________________________________________________________________________

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  algo-
              rithm  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  associated  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 note-
              book 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  specified).  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 ori-
              ented 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 addition, a special key-
              word  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 outside 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 bottom 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 tab-
              notebook 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 tab-
              notebook 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 accept-
              able 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 disabled-
              Foreground color.

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

              Specifies a background color to use  for  displaying  tab  back-
              grounds  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_Get-
              Boolean, 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 dis-
       plays 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 selec-
       tor. 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 automatically handle the unpack-
       ing  and packing of pages when pages are selected. A value of true sig-
       nifies 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 container 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 vis-
       ible  at  a  time. When a new page is selected, the previously selected
       page's child site frame is automatically  unpacked  from  the  tabnote-
       book'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  differ-
       ent  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
       appearance 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 previously selected page and the pack-
       ing of the newly selected page.

       Notebook pages can also be controlled with scroll bars or other widgets
       that  obey the scrollcommand protocol. By giving a scrollbar a -command
       to call the tabnotebook's select method, the tabnotebook  can  be  con-
       trolled 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 seamless 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 tab-
       set(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 path-
       Name. This command may be used to invoke various operations on the wid-
       get. It has the following general form:

              pathName option ?arg arg ...?

       option and the args determine the exact behavior of the command.

       Many  of  the  widget  commands  for a notebook take as one argument 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 note-
              book 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_String-
              Match are used.  The following commands are  possible  for  tab-
              notebook 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 over-
                     all  tabnotebook  is  used. This is generally only set at
                     the tabnotebook 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 tab-
                     notebook 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 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 reconfig-
                     ure 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 immedi-
                     ately after the previously selected page is unpacked  and
                     immediately before this page is selected. The index value
                     select is valid during 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 speci-
                     fied as an empty string (the  default),  then  the  fore-
                     ground option for the overall tabnotebook is used.

              -label value
                     Specifies a string to display as an identifying label for
                     a notebook page. This label serves as an additional iden-
                     tifier 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 tabnotebook 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  nor-
                     mally  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  nor-
                     mally  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 dis-
                     abled. In normal  state  unselected  tabs  are  displayed
                     using the tabforeground and tabbackground option from the
                     tabnotebook or the page. Selected tabs and pages are dis-
                     played  using  the  foreground and background option from
                     the tabnotebook 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 disabled-
                     Foreground option  for  the  tabnotebook  and  the  back-
                     ground/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 avail-
              able options for pathName (see Tk_ConfigureInfo for  information
              on  the  format  of  this  list). If option is specified with no
              value, then the command returns a list describing the one  named
              option (this list will be identical to the corresponding sublist
              of the value returned if no option is specified). If one or more
              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 notebook. 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  deter-
              mined 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 notebook. 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 compat-
              ibility 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 wid-
              get.

       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 compatibility 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 notebook that
              contains the pages of the tabnotebook.

              See the "Notebook" widget manual entry for details on the  note-
              book 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



Tk                                                              tabnotebook(1)