[incr Widgets] - notebook manpage





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   pack­
              ing/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  automati­
              cally. 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  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.
       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  auto­
       matically  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 differ­
       ently. 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 unpack­
       ing 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 vari­
       ous 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
              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 dis­
                     playing  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 pro­
                     grammer 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 previ­
                     ously selected page is unpacked and  immedi­
                     ately  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
                     Specifies a foreground color to use for dis­
                     playing 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  dis­
              played  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  path­
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list). If option is  specified  with
              no  value, then the command returns a list describ­
              ing the one named option (this list will be identi­
              cal  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
              Insert a new page in the notebook before  the  page
              specified by index.  A new child site frame is cre­
              ated.  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  com­
              mand 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 indi­
              vidual  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
              be invoked between these two operations.

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

       pathName select index
              Selects  the  page  specified  by index as the cur­
              rently 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 com­
              mand 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  cur­
              rently selected page.  This command is for compati­
              bility with the scrollbar widget.

       pathName view moveto fraction
              Uses the fraction value  to  determine  the  corre­
              sponding page to move to.  This command is for com­
              patibility 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  com­
              mand  is  for compatibility with the scrollbar wid­
              get.



EXAMPLE

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


              # Create the notebook widget and pack it.
                iwidgets::notebook .nb -width 100 -height 100
                pack .nb -anchor nw \
                      -fill both \
                      -expand yes \
                      -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





















Man(1) output converted with man2html