Provided by: iwidgets4-doc_4.1.1-2.1_all bug

NAME

       iwidgets::tabnotebook - create and manipulate tabnotebook widgets

SYNOPSIS

       iwidgets::tabnotebook pathName? options?

INHERITANCE

       itk::Widget <- iwidgets::Tabnotebook

STANDARD OPTIONS

       background  disabledForeground  foreground  scrollCommand
       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
              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  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
              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 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 addition, 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 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 tabnotebook
              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 iwidgets::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 iwidgets::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 automatically 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  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 visible  at
       a  time.  When  a new page is selected, the previously 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 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 packing 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 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 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  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 iwidgets::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 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 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 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
                     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 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 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  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 specified as an empty string (the default), then
                     the foreground 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 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 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 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
                     tabbackground option from the tabnotebook or the  page.  Selected  tabs  and
                     pages  are  displayed  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 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  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 iwidgets::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  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 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  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
              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 notebook component item.

EXAMPLE

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

              package require Iwidgets 4.0
              # Create the tabnotebook widget and pack it.
                iwidgets::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