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)
