iwidgets2.2.0 User Commands - tabnotebook






NAME

     tabnotebook - create and manipulate tabnotebook widgets


SYNOPSIS

     tabnotebook pathName? options?


INHERITANCE

     itk::Widget <- tabnotebook


STANDARD OPTIONS

     background      disabledForeground             foregroundscrollCommand
     cursor          font           height          width

     See the "options" manual entry for details on  the  standard
     options.


WIDGET-SPECIFIC OPTIONS

     Name:           angle
     Class:          Angle
     Command-Line Switch:           -angle

          Specifes the angle of slope from the inner edge to  the
          outer  edge  of the tab. An angle of 0 specifies square
          tabs. Valid ranges  are  0  to  45  degrees  inclusive.
          Default is 15 degrees. If tabPos is e or w, this option
          is ignored.

     Name:           auto
     Class:          Auto
     Command-Line Switch:           -auto

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

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

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

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

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

     Name:           bevelAmount
     Class:          BevelAmount
     Command-Line Switch:           -bevelamount

          Specifes the size of tab corners. A  value  of  0  with
          angle set to 0 results in square tabs. A bevelAmount of
          4, means that the tab will be drawn with angled corners
          that  cut  in  4  pixels  from the edge of the tab. The
          default is 0.

     Name:           borderWidth
     Class:          BorderWidth
     Command-Line Switch:           -borderwidth

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

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

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

     Name:           equalTabs
     Class:          EqualTabs
     Command-Line Switch:           -equaltabs

          Specifies whether to force tabs to be  equal  sized  or
          not.  A  value of true means constrain tabs to be equal
          sized. A value of false allows each tab to  size  based
          on  the  text label size. The value may have any of the
          forms accepted by the  Tcl_GetBoolean,  such  as  true,
          false, 0, 1, yes, or no.

          For horizontally positioned tabs (tabpos is either s or
          n),  true  forces all tabs to be equal width (the width
          being equal to the longest label plus any  padX  speci-
          fied). Horizontal tabs are always equal in height.

          For vertically positioned tabs (tabpos is either  w  or
          e), true forces all tabs to be equal height (the height
          being equal to the height of the label with the largest
          font).  Vertically  oriented  tabs  are always equal in
          width.

     Name:           foreground
     Class:          Foreground
     Command-Line Switch:           -foreground

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

     Name:           gap
     Class:          Gap
     Command-Line Switch:           -gap

          Specifies the amount of pixel space  to  place  between
          each tab. Value may be any pixel offset value. In addi-
          tion, a special keyword overlap  can  be  used  as  the
          value to achieve a standard overlap of tabs. This value
          may have any of the forms acceptable to Tk_GetPixels.

     Name:           margin
     Class:          Margin
     Command-Line Switch:           -Bmargin

          Specifies the amount of space to place between the out-
          side  edge  of  the tabnotebook and the outside edge of
          its tabs. If tabPos is s, this is the amount  of  space
          between the bottom edge of the tabnotebook and the bot-
          tom edge of the set of tabs. If tabPos is  n,  this  is
          the  amount  of  space between the top edge of the tab-
          notebook and the top edge of the set of tabs. If tabPos
          is  e,  this  is  the amount of space between the right
          edge of the tabnotebook and the right edge of  the  set
          of  tabs.  If  tabPos is w, this is the amount of space
          between the left edge of the tabnotebook and  the  left
          edge of the set of tabs. This value may have any of the
          forms acceptable to Tk_GetPixels.

     Name:           padX
     Class:          PadX
     Command-Line Switch:           -padx

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for a tab around its label in
          the X-direction. When computing how large a  window  it
          needs,  the  tab  will  add this amount to the width it
          would normally need The tab  will  end  up  with  extra
          internal space to the left and right of its text label.
          This value may have any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Name:           padY
     Class:          PadY
     Command-Line Switch:           -pady

          Specifies a  non-negative  value  indicating  how  much
          extra  space  to  request for a tab around its label in
          the Y-direction. When computing how large a  window  it
          needs,  the  tab  will add this amount to the height it
          would normally need The tab  will  end  up  with  extra
          internal space to the top and bottom of its text label.
          This value may have any  of  the  forms  acceptable  to
          Tk_GetPixels.

     Name:           raiseSelect
     Class:          RaiseSelect
     Command-Line Switch:           -raiseselect

          Specifes whether to slightly  raise  the  selected  tab
          from  the rest of the tabs. The selected tab is drawn 2
          pixels closer to the outside of  the  tabnotebook  than
          the  unselected  tabs.  A  value  of true says to raise
          selected tabs, a value of false turns this feature off.
          The  default  is  false.  The value may have any of the
          forms accepted by the  Tcl_GetBoolean,  such  as  true,
          false, 0, 1, yes, or no.

     Name:           start
     Class:          Start
     Command-Line Switch:           -start

          Specifies the amount of space to place between the left
          or top edge of the tabnotebook and the starting edge of
          its tabs. For horizontally positioned tabs, this is the
          amount  of  space between the left edge of the notebook
          and the left edge of  the  first  tab.  For  vertically
          positioned  tabs,  this  is the amount of space between
          the top of the notebook and the top of the  first  tab.
          This  value may change if the user performs a MButton-2
          scroll on the tabs. This value  may  have  any  of  the
          forms acceptable to Tk_GetPixels.

     Name:           state
     Class:          State
     Command-Line Switch:           -state

          Sets the active state of  the  tabnotebook.  Specifying
          normal  allows  all  pages to be selectable. Specifying
          disabled disables the notebook causing all page tabs to
          be drawn in the disabledForeground color.

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

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

     Name:           tabBorders
     Class:          TabBorders
     Command-Line Switch:           -tabborders

          Specifies whether to draw the borders of tabs that  are
          not selected. Specifying true (the default) draws these
          borders, specifying false draws only the border  around
          the  selected  tab. The value may have any of the forms
          accepted by the Tcl_GetBoolean, such as true, false, 0,
          1, yes, or no.

     Name:           tabForeground
     Class:          TabForeground
     Command-Line Switch:           -tabforeground

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

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

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




DESCRIPTION

     The tabnotebook command creates a new window (given  by  the
     pathName  argument)  and makes it into a tabnotebook widget.
     Additional options, described above may be specified on  the
     command  line or in the option database to configure aspects
     of the tabnotebook such as its colors, font, and  text.  The
     tabnotebook  command  returns  its pathName argument. At the
     time this command is invoked, there must not exist a  window
     named pathName, but pathName's parent must exist.

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

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


NOTEBOOK PAGES

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

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

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

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

     The notebook area is  implemented  with  the  notebook  mega
     widget.



TABS

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

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


WIDGET-SPECIFIC METHODS

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

          pathName option ?arg arg ...?

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

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

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

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

     end  Specifes the last page in the tabnotebook's  index.  If
          the notebook is empty this will return -1.

     pattern
          If the index doesn't satisfy any of  the  above  forms,
          then  this  form  is  used.  Pattern is pattern-matched
          against the label of each  page  in  the  notebook,  in
          order from the first to the last page, until a matching
          entry is found. The rules of Tcl_StringMatch are  used.
          The  following  commands  are  possible for tabnotebook
          widgets:

     pathName add ?option value option value ...?
          Add a new page at the end of  the  tabnotebook.  A  new
          child  site  frame  is  created. Returns the child site
          pathName. If additional  arguments  are  present,  they
          specify any of the following options:

          -angle value
               Specifes the angle of slope from the inner edge to
               the outer edge of the tab. An angle of 0 specifies
               square tabs. Valid ranges  are  0  to  45  degrees
               inclusive.  Default  is 15 degrees. If this option
               is specified as an  empty  string  (the  default),
               then  the angle option for the overall tabnotebook
               is used. This is generally only set  at  the  tab-
               notebook  level.  Tabs normally will want to share
               the same angle value.

          -background value
               Specifies a background color to use for displaying
               tabs when they are selected and for displaying the
               current page. If this option is  specified  as  an
               empty  string  (the  default), then the background
               option for the overall tabnotebook is used.

          -bevelamount value
               Specifes the size of tab corners.  A  value  of  0
               with  angle  set  to  0  results in square tabs. A
               bevelAmount of 4, means that the tab will be drawn
               with  angled corners that cut in 4 pixels from the
               edge of the tab. The default is 0.  This  is  gen-
               erally  only  set  at  the tabnotebook level. Tabs
               normally will want to share the same bevelAmount.

          -bitmap value
               If label is a non-empty string, specifies a bitmap
               to  display  in  this page's tab. Bitmap may be of
               any of the forms accepted by Tk_GetPixmap.

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

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

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

          -disabledforeground value
               Specifies a foreground color to use for displaying
               tab  labels  when tabs are in their disable state.
               If this option is specified  as  an  empty  string
               (the  default), then the disabledforeground option
               for the overall tabnotebook is used.

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

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

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

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

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

          -padx value
               Specifies a non-negative value indicating how much
               extra  space to request for a tab around its label
               in the X-direction. When  computing  how  large  a
               window  it  needs, the tab will add this amount to
               the width it would normally need The tab will  end
               up with extra internal space to the left and right
               of its text label. This value may have any of  the
               forms  acceptable  to Tk_GetPixels. If this option
               is specified as an  empty  string  (the  default),
               then  the  padX option for the overall tabnotebook
               is used

          -pady value
               Specifies a non-negative value indicating how much
               extra  space to request for a tab around its label
               in the Y-direction. When  computing  how  large  a
               window  it  needs, the tab will add this amount to
               the height it would normally need The tab will end
               up with extra internal space to the top and bottom
               of its text label. This value may have any of  the
               forms  acceptable  to Tk_GetPixels. If this option
               is specified as an  empty  string  (the  default),
               then  the  padY option for the overall tabnotebook
               is used

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

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

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

     pathName configure ?option? ?value option value ...?
          Query  or  modify  the  configuration  options  of  the
          widget.  If  no  option  is  specified,  returns a list
          describing all of the available  options  for  pathName
          (see  Tk_ConfigureInfo for information on the format of
          this list). If option is specified with no value,  then
          the  command  returns  a  list describing the one named
          option (this list will be identical to the  correspond-
          ing  sublist  of  the  value  returned  if no option is
          specified). If  one  or  more  option-value  pairs  are
          specified,  then  the command modifies the given widget
          option(s) to have the given value(s); in this case  the
          command returns an empty string. Option may have any of
          the values accepted by the tabnotebook command.

     pathName delete index1 ?index2?
          Delete all of  the  pages  between  index1  and  index2
          inclusive.  If  index2  is  omitted then it defaults to
          index1. Returns an empty string.

     pathName index index
          Returns the numerical index corresponding to index.

     pathName insert index ?option value option value ...?
          Insert a new page in the tabnotebook  before  the  page
          specified  by index. A new child site frame is created.
          The additional arguments are the same as  for  the  add
          command. Returns the child site pathName.

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

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

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

     pathName pageconfigure index ?option? ?value option value ...?
          This  command  is  similar  to  the  configure command,
          except that it applies to the options for an individual
          page,  whereas configure applies to the options for the
          tabnotebook as a whole. Options may  have  any  of  the
          values  accepted  by the add widget command. If options
          are specified, options are modified as indicated in the
          command  and the command returns an empty string. If no
          options are specified, returns a  list  describing  the
          current  options  for  page index (see Tk_ConfigureInfo
          for information on the format of this list).

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

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

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

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

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

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

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

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

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

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


COMPONENTS

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

     Name:   tabset
     Class:  Tabset

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

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

     Name:   notebook
     Class:  Notebook

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

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


EXAMPLE

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

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

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

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

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

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


AUTHOR

     Bill W. Scott


KEYWORDS

     tab tabset notebook tabnotebook page