[incr Widgets] - tabnotebook manpage





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   pack­
              ing/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  automati­
              cally. 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.

       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 bevelAm­
              ount 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_Get­
              Boolean, 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
              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 tab­
              notebook 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 win­
              dow  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

       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 win­
              dow 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  tab­
              notebook  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_Get­
              Boolean, 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  start­
              ing  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. Specify­
              ing normal allows all pages to be selectable. Spec­
              ifying  disabled  disables the notebook causing all
              page tabs to be  drawn  in  the  disabledForeground
              color.

       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_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  rela­
              tion  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 argu­
       ment. 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
       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 auto­
       matically 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 auto­
       matically 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 differ­
       ently.  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
       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 bev­
       elled.  West  and  east  tabs may appear as square or bev­
       elled. By changing tab gaps, tab angles, bevelling, orien­
       tations, 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 prop­
       erty 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 vari­
       ous 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 note­
              book, in order from the first  to  the  last  page,
              until  a  matching  entry  is  found.  The rules of

       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 tabnote­
                     book level. Tabs normally will want to share
                     the same angle value.

              -background value
                     Specifies a background color to use for dis­
                     playing 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 pro­
                     grammer 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  com­
                     mand  will  be  called immediately after the
                     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 dis­
                     playing 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 dis­
                     playing  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 identi­
                     fying 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 dis­
                     playing 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 dis­
                     playing the tab's text label when it is  not
                     selected.  If this option is specified as an
                     empty string (the default),  then  the  tab­
                     Foreground  option  for the overall tabnote­
                     book is used.

                     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 unse­
                     lected tabs are displayed using the tabfore­
                     ground  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 accord­
                     ing 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 dis­
              played when the associated  page  is  selected.  If

       pathName configure ?option? ?value option value ...?
              Query or modify the configuration  options  of  the
              widget.  If  no option is specified, returns a list
              describing all of the available options  for  path­
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list). If option is  specified  with
              no  value, then the command returns a list describ­
              ing the one named option (this list will be identi­
              cal  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 path­
              Name.

       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  com­
              mand given with the command option will be invoked.

       pathName pageconfigure index ?option? ?value option value
       ...?
              vidual  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 mod­
              ified  as  indicated in the command and the command
              returns an empty string. If no options  are  speci­
              fied, returns a list describing the current options
              for page index (see Tk_ConfigureInfo  for  informa­
              tion 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 opera­
              tions.

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

       pathName select index
              Selects the page specified by  index  as  the  cur­
              rently  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 com­
              mand 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  cur­
              rently selected page.  This command is for compati­
              bility with the scrollbar widget.
              Uses the fraction value  to  determine  the  corre­
              sponding page to move to.  This command is for com­
              patibility 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  com­
              mand  is  for compatibility with the scrollbar wid­
              get.


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 compo­
              nent.

              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  tabnote­
              book.

              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.
                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,
                .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

































Man(1) output converted with man2html