plucky (3) iwidgets_tabnotebook.3iwidget.gz

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