1 |
578 |
markom |
'\"
|
2 |
|
|
'\" Copyright (c) 1995 DSC Technologies Corporation
|
3 |
|
|
'\"
|
4 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
5 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
6 |
|
|
'\"
|
7 |
|
|
'\" @(#) notebook.n
|
8 |
|
|
'/"
|
9 |
|
|
.so man.macros
|
10 |
|
|
.HS notebook iwid
|
11 |
|
|
.BS
|
12 |
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
13 |
|
|
'\"
|
14 |
|
|
'\"
|
15 |
|
|
.SH NAME
|
16 |
|
|
notebook \- create and manipulate notebook widgets
|
17 |
|
|
.SH SYNOPSIS
|
18 |
|
|
\fBnotebook\fR \fIpathName\fR ?\fIoptions\fR?
|
19 |
|
|
.SH "INHERITANCE"
|
20 |
|
|
itk::Widget <- notebook
|
21 |
|
|
.SH "STANDARD OPTIONS"
|
22 |
|
|
.LP
|
23 |
|
|
.nf
|
24 |
|
|
.ta 4c 8c 12c
|
25 |
|
|
\fBbackground\fR \fBforeground\fR \fBscrollCommand\fR \fBwidth\fR
|
26 |
|
|
\fBcursor\fR \fBheight\fR
|
27 |
|
|
.fi
|
28 |
|
|
.LP
|
29 |
|
|
See the "options" manual entry for details on the standard options.
|
30 |
|
|
.SH "WIDGET-SPECIFIC OPTIONS"
|
31 |
|
|
.LP
|
32 |
|
|
.nf
|
33 |
|
|
Name: \fBauto\fR
|
34 |
|
|
Class: \fBAuto\fR
|
35 |
|
|
Command-Line Switch: \fB-auto\fR
|
36 |
|
|
.fi
|
37 |
|
|
.IP
|
38 |
|
|
Specifies whether to use the automatic packing/unpacking algorithm of the
|
39 |
|
|
notebook. A value of \fBtrue\fR indicates that page frames will be unpacked
|
40 |
|
|
and packed acoording to the algorithm described in the \fBselect\fR command.
|
41 |
|
|
A value of \fBfalse\fR leaves the current page packed and subsequent selects,
|
42 |
|
|
next, or previous commands do not switch pages automatically. In either
|
43 |
|
|
case the page's associated command (see the \fBadd\fR command's description
|
44 |
|
|
of the \fBcommand\fR option) is invoked. The value may have any of the
|
45 |
|
|
forms accepted by the \fBTcl_GetBoolean\fR, such as true, false, 0, 1, yes,
|
46 |
|
|
or no.
|
47 |
|
|
.IP
|
48 |
|
|
For example, if a series of pages in a notebook simply change certain display
|
49 |
|
|
configurations of a graphical display, the \fB-auto\fR flag could be used.
|
50 |
|
|
By setting it, the \fB-command\fR procs could do the appropriate reconfiguring
|
51 |
|
|
of the page when the page is switched.
|
52 |
|
|
.BE
|
53 |
|
|
.SH DESCRIPTION
|
54 |
|
|
.PP
|
55 |
|
|
The \fBnotebook\fR command creates a new window (given by the pathName
|
56 |
|
|
argument) and makes it into a notebook widget. Additional options, described
|
57 |
|
|
above may be specified on the command line or in the option database to
|
58 |
|
|
configure aspects of the notebook such as its colors, font, and text.
|
59 |
|
|
The \fBnotebook\fR command returns its \fIpathName\fR argument. At the time
|
60 |
|
|
this command is invoked, there must not exist a window named pathName, but
|
61 |
|
|
pathName's parent must exist.
|
62 |
|
|
|
63 |
|
|
A notebook is a widget that contains a set of pages. It displays one page from
|
64 |
|
|
the set as the selected page. When a page is selected, the page's contents are
|
65 |
|
|
displayed in the page area. When first created a notebook has no pages. Pages
|
66 |
|
|
may be added or deleted using widget commands described below.
|
67 |
|
|
|
68 |
|
|
.SH "NOTEBOOK PAGES"
|
69 |
|
|
.PP
|
70 |
|
|
A notebook's pages area contains a single child site \fBframe\fR. When a new
|
71 |
|
|
page is created it is a child of this frame. The page's child site frame
|
72 |
|
|
serves as a geometry container for applications to pack widgets into. It is
|
73 |
|
|
this frame that is automatically unpacked or packed when the \fBauto\fR
|
74 |
|
|
option is \fBtrue\fR. This creates the effect of one page being visible at
|
75 |
|
|
a time. When a new page is selected, the previously selected page's child
|
76 |
|
|
site frame is automatically unpacked from the notebook's child site frame
|
77 |
|
|
and the newly selected page's child site is packed into the notebook's
|
78 |
|
|
child site frame.
|
79 |
|
|
|
80 |
|
|
However, sometimes it is desirable to handle page changes in a different
|
81 |
|
|
manner. By specifying the \fBauto\fR option as \fBfalse\fR, child site
|
82 |
|
|
packing can be disabled and done differently. For example, all widgets might
|
83 |
|
|
be packed into the first page's child site frame. Then when a new page is
|
84 |
|
|
selected, the application can reconfigure the widgets and give the appearance
|
85 |
|
|
that the page was flipped.
|
86 |
|
|
|
87 |
|
|
In both cases the \fBcommand\fR option for a page specifies a Tcl Command to
|
88 |
|
|
execute when the page is selected. In the case of \fBauto\fR being \fBtrue\fR,
|
89 |
|
|
it is called between the unpacking of the previously selected page and the
|
90 |
|
|
packing of the newly selected page.
|
91 |
|
|
|
92 |
|
|
.SH "WIDGET-SPECIFIC METHODS"
|
93 |
|
|
.PP
|
94 |
|
|
The \fBnotebookfR command creates a new Tcl command whose name
|
95 |
|
|
is \fIpathName\fR. This command may be used to invoke various operations
|
96 |
|
|
on the widget. It has the following general form:
|
97 |
|
|
.DS C
|
98 |
|
|
\fIpathName option \fR?\fIarg arg ...\fR?
|
99 |
|
|
.DE
|
100 |
|
|
\fIoption\fR and the \fIarg\fRs
|
101 |
|
|
determine the exact behavior of the command.
|
102 |
|
|
.PP
|
103 |
|
|
Many of the widget commands for a notebook take as one argument an indicator
|
104 |
|
|
of which page of the notebook to operate on. These indicators are called
|
105 |
|
|
indexes and may be specified in any of the following forms:
|
106 |
|
|
.TP
|
107 |
|
|
\fInumber\fR
|
108 |
|
|
Specifies the index of the the component. For menus, 0 corresponds to the
|
109 |
|
|
left-most menu of the menu bar. For entries, 0 corresponds to the top-most
|
110 |
|
|
entry of the menu.
|
111 |
|
|
\fInumber\fR
|
112 |
|
|
Specifies the page numerically, where 0 corresponds to the first page in
|
113 |
|
|
the notebook, 1 to the second, and so on.
|
114 |
|
|
.TP
|
115 |
|
|
\fBselect\fR
|
116 |
|
|
Specifies the currently selected page's index. If no page is currently
|
117 |
|
|
selected, the value -1 is returned.
|
118 |
|
|
.TP
|
119 |
|
|
\fBend\fR
|
120 |
|
|
Specifes the last page in the notebooks's index. If the notebook is empty
|
121 |
|
|
this will return -1.
|
122 |
|
|
.TP
|
123 |
|
|
\fIpattern\fR
|
124 |
|
|
If the index doesn't satisfy the form of a number, then this form is used.
|
125 |
|
|
Pattern is pattern-matched against the \fBlabel\fR of each page in the
|
126 |
|
|
notebook, in order from the first to the last page, until a matching entry
|
127 |
|
|
is found. The rules of \fBTcl_StringMatch\fR are used.
|
128 |
|
|
.PP
|
129 |
|
|
'.............................................................................
|
130 |
|
|
The following commands are possible for notebook widgets:
|
131 |
|
|
.TP
|
132 |
|
|
\fIpathName\fR \fBadd\fR ?\fIoption value\fR?
|
133 |
|
|
Add a new page at the end of the notebook. A new child site frame is
|
134 |
|
|
created. Returns the child site pathName. If additional arguments are
|
135 |
|
|
present, they specify any of the following options:
|
136 |
|
|
.RS
|
137 |
|
|
.TP
|
138 |
|
|
\fB-background\fR \fIvalue\fR
|
139 |
|
|
Specifies a background color to use for displaying the child site frame
|
140 |
|
|
of this page. If this option is specified as an empty string (the default),
|
141 |
|
|
then the background option for the overall notebook is used.
|
142 |
|
|
.TP
|
143 |
|
|
\fB-command\fR \fIvalue\fR
|
144 |
|
|
Specifies a Tcl command to be executed when this page is selected. This
|
145 |
|
|
allows the programmer a hook to reconfigure this page's widgets or any other
|
146 |
|
|
page's widgets.
|
147 |
|
|
.IP
|
148 |
|
|
If the notebook has the auto option set to true, when a page is selected
|
149 |
|
|
this command will be called immediately after the previously selected page
|
150 |
|
|
is unpacked and immediately before this page is selected. The index value
|
151 |
|
|
select is valid during this Tcl command. `index select' will return this
|
152 |
|
|
page's page number.
|
153 |
|
|
.IP
|
154 |
|
|
If the auto option is set to false, when a page is selected the unpack and
|
155 |
|
|
pack calls are bypassed. This Tcl command is still called.
|
156 |
|
|
.TP
|
157 |
|
|
\fB-foreground\fR \fIvalue\fR
|
158 |
|
|
Specifies a foreground color to use for displaying tab labels when tabs are
|
159 |
|
|
in their normal unselected state. If this option is specified as an empty
|
160 |
|
|
string (the default), then the foreground option for the overall notebook
|
161 |
|
|
is used.
|
162 |
|
|
.TP
|
163 |
|
|
\fB-label\fR \fIvalue\fR
|
164 |
|
|
Specifies a string to associate with this page. This label serves as an
|
165 |
|
|
additional identifier used to reference the page. This label may be used
|
166 |
|
|
for the index value in widget commands.
|
167 |
|
|
.RE
|
168 |
|
|
.TP
|
169 |
|
|
\fIpathName\fR \fBchildSite\fR ?\fIindex\fR?
|
170 |
|
|
If passed no arguments, returns a list of pathNames for all the pages in
|
171 |
|
|
the notebook. If the notebook is empty, an empty list is returned
|
172 |
|
|
.IP
|
173 |
|
|
If index is passed, it returns the pathName for the page's child site
|
174 |
|
|
frame specified by index. Widgets that are created with this pathName will
|
175 |
|
|
be displayed when the associated page is selected. If index is not a valid
|
176 |
|
|
index, an empty string is returned.
|
177 |
|
|
.TP
|
178 |
|
|
\fIpathName\fR \fBcget\fR \fIoption\fR
|
179 |
|
|
Returns the current value of the configuration option given by \fIoption\fR.
|
180 |
|
|
.TP
|
181 |
|
|
\fIpathName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue\fR \fIoption\fR \fIvalue\fR ...?
|
182 |
|
|
Query or modify the configuration options of the widget. If no \fIoption\fR
|
183 |
|
|
is specified, returns a list describing all of the available options
|
184 |
|
|
for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for information on the
|
185 |
|
|
format of this list). If \fIoption\fR is specified with no \fIvalue\fR,
|
186 |
|
|
then the command returns a list describing the one named option (this
|
187 |
|
|
list will be identical to the corresponding sublist of the value returned
|
188 |
|
|
if no option is specified). If one or more option-value pairs are specified,
|
189 |
|
|
then the command modifies the given widget option(s) to have the given
|
190 |
|
|
value(s); in this case the command returns an empty string. \fIOption\fR
|
191 |
|
|
may have any of the values accepted by the \fBnotebook\fR command.
|
192 |
|
|
.TP
|
193 |
|
|
\fIpathName\fR \fBdelete\fR \fIindex1\fR ?i\fRndex2?
|
194 |
|
|
Delete all of the pages between \fIindex1\fR and \fIindex2\fR inclusive.
|
195 |
|
|
If \fIindex2\fR is omitted then it defaults to \fIindex1\fR. Returns an
|
196 |
|
|
empty string.
|
197 |
|
|
.TP
|
198 |
|
|
\fIpathName\fR \fBindex\fR \fIindex\fR
|
199 |
|
|
Returns the numerical index corresponding to \fIindex\fR.
|
200 |
|
|
.TP
|
201 |
|
|
\fBpathName\fR \fBinsert\fR \fIindex\fR ?\fIoption\fR \fIvalue\fR?
|
202 |
|
|
Insert a new page in the notebook before the page specified by \fIindex\fR.
|
203 |
|
|
A new child site \fBframe\fR is created. See the \fBadd\fR command for
|
204 |
|
|
valid options. Returns the child site pathName.
|
205 |
|
|
.TP
|
206 |
|
|
\fIpathName\fR \fBnext\fR
|
207 |
|
|
Advances the selected page to the next page (order is determined by insertion
|
208 |
|
|
order). If the currently selected page is the last page in the notebook,
|
209 |
|
|
the selection wraps around to the first page in the notebook.
|
210 |
|
|
.IP
|
211 |
|
|
For notebooks with auto set to true the current page's child site is
|
212 |
|
|
unpacked from the notebook's child site frame. Then the next page's child
|
213 |
|
|
site is packed into the notebooks child site frame. The Tcl command given
|
214 |
|
|
with the command option will be invoked between these two operations.
|
215 |
|
|
.IP
|
216 |
|
|
For notebooks with auto set to false the Tcl command given with the
|
217 |
|
|
command option will be invoked.
|
218 |
|
|
.TP
|
219 |
|
|
\fIpathName\fR \fBpagecget\fR \fIindex\fR ?\fIoption\fR?
|
220 |
|
|
Returns the current value of the configuration option given by \fIoption\fR
|
221 |
|
|
for the page specified by \fIindex\fR. The valid available options are the
|
222 |
|
|
same as available to the \fBadd\fR command.
|
223 |
|
|
.TP
|
224 |
|
|
\fIpathName\fR \fBpageconfigure\fR \fIindex\fR ?\fIoption\fR? ?\fIvalue\fR \fIoption\fR \fIvalue\fR ...?
|
225 |
|
|
This command is similar to the configure command, except that it applies to
|
226 |
|
|
the options for an individual page, whereas configure applies to the options
|
227 |
|
|
for the notebook. Options may have any of the values accepted by the add
|
228 |
|
|
widget command. If options are specified, options are modified as indicated
|
229 |
|
|
in the command and the command returns an empty string. If no options are
|
230 |
|
|
specified, returns a list describing the current options for
|
231 |
|
|
page \fIindex\fR (see \fBTk_ConfigureInfo\fR for information on the
|
232 |
|
|
format of this list).
|
233 |
|
|
.TP
|
234 |
|
|
\fIpathName\fR \fBprev\fR
|
235 |
|
|
Moves the selected page to the previous page (order is determined by
|
236 |
|
|
insertion order). If the currently selected page is the first page in the
|
237 |
|
|
notebook, the selection wraps around to the last page in the notebook.
|
238 |
|
|
.IP
|
239 |
|
|
For notebooks with \fBauto\fR set to \fBtrue\fR the current page's child
|
240 |
|
|
site is unpacked from the notebook's child site frame. Then the previous
|
241 |
|
|
page's child site is packed into the notebooks child site frame. The Tcl
|
242 |
|
|
command given with the command option will be invoked between these two
|
243 |
|
|
operations.
|
244 |
|
|
.IP
|
245 |
|
|
For notebooks with \fBauto\fR set to \fBfalse\fR the Tcl command given with
|
246 |
|
|
the command option will be invoked.
|
247 |
|
|
.TP
|
248 |
|
|
\fIpathName\fR \fBselect\fR \fIindex\fR
|
249 |
|
|
Selects the page specified by \fIindex\fR as the currently selected page.
|
250 |
|
|
.IP
|
251 |
|
|
For notebooks with \fBauto\fR set to \fBtrue\fR the current page's child
|
252 |
|
|
site is unpacked from the notebook's child site frame. Then the index page's
|
253 |
|
|
child site is packed into the notebooks child site frame. The Tcl command
|
254 |
|
|
given with the command option will be invoked between these two operations.
|
255 |
|
|
.IP
|
256 |
|
|
For notebooks with \fBauto\fR set to \fBfalse\fR the Tcl command given with
|
257 |
|
|
the command option will be invoked.
|
258 |
|
|
.TP
|
259 |
|
|
\fIpathName\fR \fBview\fR
|
260 |
|
|
Returns the currently selected page. This command is for compatibility
|
261 |
|
|
with the scrollbar widget.
|
262 |
|
|
.TP
|
263 |
|
|
\fIpathName\fR \fBview\fR \fIindex\fR
|
264 |
|
|
Selects the page specified by \fIindex\fR as the currently selected page.
|
265 |
|
|
This command is for compatibility with the scrollbar widget.
|
266 |
|
|
.TP
|
267 |
|
|
\fIpathName\fR \fBview\fR \fImoveto\fR \fIfraction\fR
|
268 |
|
|
Uses the fraction value to determine the corresponding page to move to.
|
269 |
|
|
This command is for compatibility with the scrollbar widget.
|
270 |
|
|
.TP
|
271 |
|
|
\fIpathName\fR \fBview\fR \fIscroll\fR \fInum\fR \fIwhat\fR
|
272 |
|
|
Uses the \fInum\fR value to determine how many pages to move forward or
|
273 |
|
|
backward (num can be negative or positive). The \fIwhat\fR argument is
|
274 |
|
|
ignored. This command is for compatibility with the scrollbar widget.
|
275 |
|
|
|
276 |
|
|
.SH EXAMPLE
|
277 |
|
|
.PP
|
278 |
|
|
Following is an example that creates a notebook with two pages. In this example, we use a scrollbar widget to control the notebook widget.
|
279 |
|
|
.nf
|
280 |
|
|
.IP
|
281 |
|
|
.ta 2c 8c 12c
|
282 |
|
|
# Create the notebook widget and pack it.
|
283 |
|
|
notebook .nb -width 100 -height 100
|
284 |
|
|
pack .nb -anchor nw \\
|
285 |
|
|
-fill both \\
|
286 |
|
|
-expand yes \\
|
287 |
|
|
-side left \\
|
288 |
|
|
-padx 10 \\
|
289 |
|
|
-pady 10
|
290 |
|
|
.IP
|
291 |
|
|
# Add two pages to the notebook, labelled
|
292 |
|
|
# "Page One" and "Page Two", respectively.
|
293 |
|
|
.nb add -label "Page One"
|
294 |
|
|
.nb add -label "Page Two"
|
295 |
|
|
.IP
|
296 |
|
|
# Get the child site frames of these two pages.
|
297 |
|
|
set page1CS [.nb childsite 0]
|
298 |
|
|
set page2CS [.nb childsite "Page Two"]
|
299 |
|
|
.IP
|
300 |
|
|
# Create buttons on each page of the notebook
|
301 |
|
|
button $page1CS.b -text "Button One"
|
302 |
|
|
pack $page1CS.b
|
303 |
|
|
button $page2CS.b -text "Button Two"
|
304 |
|
|
pack $page2CS.b
|
305 |
|
|
.IP
|
306 |
|
|
# Select the first page of the notebook
|
307 |
|
|
.nb select 0
|
308 |
|
|
.IP
|
309 |
|
|
# Create the scrollbar and associate teh scrollbar
|
310 |
|
|
# and the notebook together, then pack the scrollbar
|
311 |
|
|
ScrollBar .scroll -command ".nb view"
|
312 |
|
|
.nb configure -scrollcommand ".scroll set"
|
313 |
|
|
pack .scroll -fill y -expand yes -pady 10
|
314 |
|
|
.fi
|
315 |
|
|
.SH AUTHOR
|
316 |
|
|
Bill W. Scott
|
317 |
|
|
.SH KEYWORDS
|
318 |
|
|
notebook page
|