Provided by: iwidgets4-doc_4.1.0-1_all bug

NAME

       iwidgets::notebook - create and manipulate notebook widgets

SYNOPSIS

       iwidgets::notebook pathName ?options?

INHERITANCE

       itk::Widget <- iwidgets::Notebook

STANDARD OPTIONS

       background      foreground     scrollCommand   width
       cursor          height

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

WIDGET-SPECIFIC OPTIONS

       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.

              For  example,  if  a  series  of  pages in a notebook simply change certain display
              configurations of a graphical display, the -auto flag could be  used.   By  setting
              it,  the -command procs could do the appropriate reconfiguring of the page when the
              page is switched.
_________________________________________________________________________________________________

DESCRIPTION

       The iwidgets::notebook command creates a new window (given by the pathName  argument)  and
       makes  it  into a notebook widget. Additional options, described above may be specified on
       the command line or in the option database to configure aspects of the  notebook  such  as
       its colors, font, and text.  The iwidgets::notebook 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  notebook is a widget that contains a set of pages. It displays one page from the set as
       the selected page. When a page is selected, the page's contents are displayed in the  page
       area.  When  first  created  a  notebook has no pages. Pages may be added or deleted using
       widget commands described below.

NOTEBOOK PAGES

       A notebook'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 notebook's child site frame and the newly selected page's
       child site is packed into the notebook'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 called between the unpacking of
       the previously selected page and the packing of the newly selected page.

WIDGET-SPECIFIC METHODS

       The iwidgets::notebookfR 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 index of the the component. For menus, 0 corresponds to the left-most
              menu of the menu bar. For entries, 0 corresponds to the top-most entry of the menu.
              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 notebooks's index. If the notebook is empty this will
              return -1.

       pattern
              If the index doesn't satisfy the form of a number, 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 notebook widgets:

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

              -background value
                     Specifies  a  background color to use for displaying the child site frame of
                     this page. If this option is specified as an  empty  string  (the  default),
                     then the background option for the overall notebook is used.

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

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

              -label value
                     Specifies  a  string  to  associate  with this 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.

       pathName childSite ?index?
              If  passed  no  arguments,  returns  a  list  of pathNames for all the pages in the
              notebook. If the 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 cget option
              Returns the current value of the configuration option given by option.

       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::notebook 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?
              Insert a new page in the notebook before the page specified by index.  A new  child
              site  frame  is  created.  See the add command for valid options. 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.

              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
              notebooks 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 pagecget index ?option?
              Returns the current value of the configuration option given by option for the  page
              specified  by  index.  The valid available options are the same as available to the
              add command.

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

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

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

EXAMPLE

       Following  is an example that creates a notebook with two pages. In this example, we use a
       scrollbar widget to control the notebook widget.

              package require Iwidgets 4.0
              # Create the notebook widget and pack it.
                iwidgets::notebook .nb -width 100 -height 100
                pack .nb -anchor nw \
                      -fill both \
                      -expand yes \
                      -side left \
                      -padx 10 \
                      -pady 10

              # Add two pages to the notebook, labelled
              # "Page One" and "Page Two", respectively.
                .nb add -label "Page One"
                .nb add -label "Page Two"

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

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

              # Select the first page of the notebook
                .nb select 0

              # Create the scrollbar and associate teh scrollbar
              # and the notebook together, then pack the scrollbar
                scrollbar .scroll -command ".nb view"
                .nb configure -scrollcommand ".scroll set"
                pack .scroll -fill y -expand yes -pady 10

AUTHOR

       Bill W. Scott

KEYWORDS

       notebook page