# iwidgets2.2.0 User Commands - notebook

##

## 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 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 reconfigur-
              ing of the page when the page is switched.

##

## DESCRIPTION

         The 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
         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 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 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  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 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 note-
                   book 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  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.

              -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  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 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 note-
              book.

              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 infor-
              mation 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.

              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  com-
              patibility 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