ABCDEFGHIJKLMNOPQRSTUVWXYZ

notebook

notebook(1)                     [incr Widgets]                     notebook(1)



______________________________________________________________________________

NAME
       notebook - create and manipulate notebook widgets

SYNOPSIS
       notebook pathName ?options?

INHERITANCE
       itk::Widget <- 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 algo-
              rithm 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 notebook command creates a new window (given by the pathName  argu-
       ment)  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 notebook command returns its pathName argument.  At  the
       time this command is invoked, there must not exist a window named path-
       Name, 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 com-
       mands 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  differ-
       ent  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 notebookfR command creates a new Tcl command whose  name  is  path-
       Name. This command may be used to invoke various operations on the wid-
       get. 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  corre-
              sponds  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_String-
              Match 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  speci-
                     fied  as  an  empty  string (the default), then the back-
                     ground 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  wid-
                     gets.

                     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 imme-
                     diately 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 refer-
                     ence 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 avail-
              able 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 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 speci-
              fied, 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  deter-
              mined 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 compat-
              ibility 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.

              # Create the notebook widget and pack it.
                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



Tk                                                                 notebook(1)