1<TITLE>notebook - create and manipulate notebook widgets</TITLE> 2<H1>notebook - create and manipulate notebook widgets</H1> 3 4</pre><H2>SYNOPSIS</H2> 5<B>notebook</B> <I>pathName</I> ?<I>options</I>? 6</pre><H2>INHERITANCE</H2> 7itk::Widget <- notebook 8</pre><H2>STANDARD OPTIONS</H2> 9<P> 10<table cellpadding=5> 11<td valign=top> 12<B>background</B><br> 13<B>cursor</B><br> 14</td> 15<td valign=top> 16<B>foreground</B><br> 17<B>height</B><br> 18</td> 19<td valign=top> 20<B>scrollCommand</B><br> 21</td> 22<td valign=top> 23<B>width</B><br> 24</td> 25</table> 26<P> 27See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/options.n.html"> "options" </A> manual entry for details on the standard options. 28</pre><H2>WIDGET-SPECIFIC OPTIONS</H2> 29<P> 30<pre> 31Name: <B>auto</B> 32Class: <B>Auto</B> 33Command-Line Switch: <B>-auto</B> 34</pre> 35<UL> 36Specifies whether to use the automatic packing/unpacking algorithm of the 37notebook. A value of <B>true</B> indicates that page frames will be unpacked 38and packed acoording to the algorithm described in the <B>select</B> command. 39A value of <B>false</B> leaves the current page packed and subsequent selects, 40next, or previous commands do not switch pages automatically. In either 41case the page's associated command (see the <B>add</B> command's description 42of the <B>command</B> option) is invoked. The value may have any of the 43forms accepted by the <B>Tcl_GetBoolean</B>, such as true, false, 0, 1, yes, 44or no. 45</UL> 46<UL> 47For example, if a series of pages in a notebook simply change certain display 48configurations of a graphical display, the <B>-auto</B> flag could be used. 49By setting it, the <B>-command</B> procs could do the appropriate reconfiguring 50of the page when the page is switched. 51</UL> 52</pre><HR> 53</pre><H2>DESCRIPTION</H2> 54<P> 55The <B>notebook</B> command creates a new window (given by the pathName 56argument) and makes it into a notebook widget. Additional options, described 57above may be specified on the command line or in the option database to 58configure aspects of the notebook such as its colors, font, and text. 59The <B>notebook</B> command returns its <I>pathName</I> argument. At the time 60this command is invoked, there must not exist a window named pathName, but 61pathName's parent must exist. 62 63A notebook is a widget that contains a set of pages. It displays one page from 64the set as the selected page. When a page is selected, the page's contents are 65displayed in the page area. When first created a notebook has no pages. Pages 66may be added or deleted using widget commands described below. 67 68</pre><H2>NOTEBOOK PAGES</H2> 69<P> 70A notebook's pages area contains a single child site <B>frame</B>. When a new 71page is created it is a child of this frame. The page's child site frame 72serves as a geometry container for applications to pack widgets into. It is 73this frame that is automatically unpacked or packed when the <B>auto</B> 74option is <B>true</B>. This creates the effect of one page being visible at 75a time. When a new page is selected, the previously selected page's child 76site frame is automatically unpacked from the notebook's child site frame 77and the newly selected page's child site is packed into the notebook's 78child site frame. 79 80However, sometimes it is desirable to handle page changes in a different 81manner. By specifying the <B>auto</B> option as <B>false</B>, child site 82packing can be disabled and done differently. For example, all widgets might 83be packed into the first page's child site frame. Then when a new page is 84selected, the application can reconfigure the widgets and give the appearance 85that the page was flipped. 86 87In both cases the <B>command</B> option for a page specifies a Tcl Command to 88execute when the page is selected. In the case of <B>auto</B> being <B>true</B>, 89it is called between the unpacking of the previously selected page and the 90packing of the newly selected page. 91 92</pre><H2>WIDGET-SPECIFIC METHODS</H2> 93<P> 94The <B>notebookfR command creates a new Tcl command whose name 95is <I>pathName</I>. This command may be used to invoke various operations 96on the widget. It has the following general form: 97<pre> 98<I>pathName option </I>?<I>arg arg ...</I>? 99</pre> 100<I>option</I> and the <I>arg</I>s 101determine the exact behavior of the command. 102<P> 103Many of the widget commands for a notebook take as one argument an indicator 104of which page of the notebook to operate on. These indicators are called 105indexes and may be specified in any of the following forms: 106<DL> 107<DT> <I>number</I> 108</I></B> 109<DD> Specifies the index of the the component. For menus, 0 corresponds to the 110left-most menu of the menu bar. For entries, 0 corresponds to the top-most 111entry of the menu. 112<I>number</I> 113Specifies the page numerically, where 0 corresponds to the first page in 114the notebook, 1 to the second, and so on. 115</DL> 116<DL> 117<DT> <B>select</B> 118</I></B> 119<DD> Specifies the currently selected page's index. If no page is currently 120selected, the value -1 is returned. 121</DL> 122<DL> 123<DT> <B>end</B> 124</I></B> 125<DD> Specifes the last page in the notebooks's index. If the notebook is empty 126this will return -1. 127</DL> 128<DL> 129<DT> <I>pattern</I> 130</I></B> 131<DD> If the index doesn't satisfy the form of a number, then this form is used. 132Pattern is pattern-matched against the <B>label</B> of each page in the 133notebook, in order from the first to the last page, until a matching entry 134is found. The rules of <B>Tcl_StringMatch</B> are used. 135</DL> 136<P> 137'............................................................................. 138The following commands are possible for notebook widgets: 139<DL> 140<DT> <I>pathName</I> <B>add</B> ?<I>option value</I>? 141</I></B> 142<DD> Add a new page at the end of the notebook. A new child site frame is 143created. Returns the child site pathName. If additional arguments are 144present, they specify any of the following options: 145</DL> 146<UL> 147<DL> 148<DT> <B>-background</B> <I>value</I> 149</I></B> 150<DD> Specifies a background color to use for displaying the child site frame 151of this page. If this option is specified as an empty string (the default), 152then the background option for the overall notebook is used. 153</DL> 154<DL> 155<DT> <B>-command</B> <I>value</I> 156</I></B> 157<DD> Specifies a Tcl command to be executed when this page is selected. This 158allows the programmer a hook to reconfigure this page's widgets or any other 159page's widgets. 160<UL> 161If the notebook has the auto option set to true, when a page is selected 162this command will be called immediately after the previously selected page 163is unpacked and immediately before this page is selected. The index value 164select is valid during this Tcl command. `index select' will return this 165page's page number. 166</UL> 167<UL> 168If the auto option is set to false, when a page is selected the unpack and 169pack calls are bypassed. This Tcl command is still called. 170</UL> 171</DL> 172<DL> 173<DT> <B>-foreground</B> <I>value</I> 174</I></B> 175<DD> Specifies a foreground color to use for displaying tab labels when tabs are 176in their normal unselected state. If this option is specified as an empty 177string (the default), then the foreground option for the overall notebook 178is used. 179</DL> 180<DL> 181<DT> <B>-label</B> <I>value</I> 182</I></B> 183<DD> Specifies a string to associate with this page. This label serves as an 184additional identifier used to reference the page. This label may be used 185for the index value in widget commands. 186</DL> 187</UL> 188<DL> 189<DT> <I>pathName</I> <B>childSite</B> ?<I>index</I>? 190</I></B> 191<DD> If passed no arguments, returns a list of pathNames for all the pages in 192the notebook. If the notebook is empty, an empty list is returned 193<UL> 194If index is passed, it returns the pathName for the page's child site 195frame specified by index. Widgets that are created with this pathName will 196be displayed when the associated page is selected. If index is not a valid 197index, an empty string is returned. 198</UL> 199</DL> 200<DL> 201<DT> <I>pathName</I> <B>cget</B> <I>option</I> 202</I></B> 203<DD> Returns the current value of the configuration option given by <I>option</I>. 204</DL> 205<DL> 206<DT> <I>pathName</I> <B>configure</B> ?<I>option</I>? ?<I>value</I> <I>option</I> <I>value</I> ...? 207</I></B> 208<DD> Query or modify the configuration options of the widget. If no <I>option</I> 209is specified, returns a list describing all of the available options 210for <I>pathName</I> (see <B>Tk_ConfigureInfo</B> for information on the 211format of this list). If <I>option</I> is specified with no <I>value</I>, 212then the command returns a list describing the one named option (this 213list will be identical to the corresponding sublist of the value returned 214if no option is specified). If one or more option-value pairs are specified, 215then the command modifies the given widget option(s) to have the given 216value(s); in this case the command returns an empty string. <I>Option</I> 217may have any of the values accepted by the <B>notebook</B> command. 218</DL> 219<DL> 220<DT> <I>pathName</I> <B>delete</B> <I>index1</I> ?i</B></I>ndex2? 221</I></B> 222<DD> Delete all of the pages between <I>index1</I> and <I>index2</I> inclusive. 223If <I>index2</I> is omitted then it defaults to <I>index1</I>. Returns an 224empty string. 225</DL> 226<DL> 227<DT> <I>pathName</I> <B>index</B> <I>index</I> 228</I></B> 229<DD> Returns the numerical index corresponding to <I>index</I>. 230</DL> 231<DL> 232<DT> <B>pathName</B> <B>insert</B> <I>index</I> ?<I>option</I> <I>value</I>? 233</I></B> 234<DD> Insert a new page in the notebook before the page specified by <I>index</I>. 235A new child site <B>frame</B> is created. See the <B>add</B> command for 236valid options. Returns the child site pathName. 237</DL> 238<DL> 239<DT> <I>pathName</I> <B>next</B> 240</I></B> 241<DD> Advances the selected page to the next page (order is determined by insertion 242order). If the currently selected page is the last page in the notebook, 243the selection wraps around to the first page in the notebook. 244<UL> 245For notebooks with auto set to true the current page's child site is 246unpacked from the notebook's child site frame. Then the next page's child 247site is packed into the notebooks child site frame. The Tcl command given 248with the command option will be invoked between these two operations. 249</UL> 250<UL> 251For notebooks with auto set to false the Tcl command given with the 252command option will be invoked. 253</UL> 254</DL> 255<DL> 256<DT> <I>pathName</I> <B>pagecget</B> <I>index</I> ?<I>option</I>? 257</I></B> 258<DD> Returns the current value of the configuration option given by <I>option</I> 259for the page specified by <I>index</I>. The valid available options are the 260same as available to the <B>add</B> command. 261</DL> 262<DL> 263<DT> <I>pathName</I> <B>pageconfigure</B> <I>index</I> ?<I>option</I>? ?<I>value</I> <I>option</I> <I>value</I> ...? 264</I></B> 265<DD> This command is similar to the configure command, except that it applies to 266the options for an individual page, whereas configure applies to the options 267for the notebook. Options may have any of the values accepted by the add 268widget command. If options are specified, options are modified as indicated 269in the command and the command returns an empty string. If no options are 270specified, returns a list describing the current options for 271page <I>index</I> (see <B>Tk_ConfigureInfo</B> for information on the 272format of this list). 273</DL> 274<DL> 275<DT> <I>pathName</I> <B>prev</B> 276</I></B> 277<DD> Moves the selected page to the previous page (order is determined by 278insertion order). If the currently selected page is the first page in the 279notebook, the selection wraps around to the last page in the notebook. 280<UL> 281For notebooks with <B>auto</B> set to <B>true</B> the current page's child 282site is unpacked from the notebook's child site frame. Then the previous 283page's child site is packed into the notebooks child site frame. The Tcl 284command given with the command option will be invoked between these two 285operations. 286</UL> 287<UL> 288For notebooks with <B>auto</B> set to <B>false</B> the Tcl command given with 289the command option will be invoked. 290</UL> 291</DL> 292<DL> 293<DT> <I>pathName</I> <B>select</B> <I>index</I> 294</I></B> 295<DD> Selects the page specified by <I>index</I> as the currently selected page. 296<UL> 297For notebooks with <B>auto</B> set to <B>true</B> the current page's child 298site is unpacked from the notebook's child site frame. Then the index page's 299child site is packed into the notebooks child site frame. The Tcl command 300given with the command option will be invoked between these two operations. 301</UL> 302<UL> 303For notebooks with <B>auto</B> set to <B>false</B> the Tcl command given with 304the command option will be invoked. 305</UL> 306</DL> 307<DL> 308<DT> <I>pathName</I> <B>view</B> 309</I></B> 310<DD> Returns the currently selected page. This command is for compatibility 311with the scrollbar widget. 312</DL> 313<DL> 314<DT> <I>pathName</I> <B>view</B> <I>index</I> 315</I></B> 316<DD> Selects the page specified by <I>index</I> as the currently selected page. 317This command is for compatibility with the scrollbar widget. 318</DL> 319<DL> 320<DT> <I>pathName</I> <B>view</B> <I>moveto</I> <I>fraction</I> 321</I></B> 322<DD> Uses the fraction value to determine the corresponding page to move to. 323This command is for compatibility with the scrollbar widget. 324</DL> 325<DL> 326<DT> <I>pathName</I> <B>view</B> <I>scroll</I> <I>num</I> <I>what</I> 327</I></B> 328<DD> Uses the <I>num</I> value to determine how many pages to move forward or 329backward (num can be negative or positive). The <I>what</I> argument is 330ignored. This command is for compatibility with the scrollbar widget. 331 332</DL> 333</pre><H2>EXAMPLE</H2> 334<P> 335Following is an example that creates a notebook with two pages. In this example, we use a scrollbar widget to control the notebook widget. 336<table cellpadding=5> 337<td valign=top> 338<UL><br> 339the<br> 340pack<br> 341-width<br> 342pack<br> 343\\<br> 344-expand<br> 345left<br> 346\\<br> 347#<br> 348to<br> 349#<br> 350"Page<br> 351add<br> 352.nb<br> 353Two"<br> 354Get<br> 355frames<br> 356pages.<br> 357childsite<br> 358[.nb<br> 359</UL><br> 360buttons<br> 361of<br> 362$page1CS.b<br> 363pack<br> 364-text<br> 365$page2CS.b<br> 366Select<br> 367of<br> 368select<br> 369#<br> 370and<br> 371#<br> 372together,<br> 373scrollbar<br> 374".nb<br> 375-scrollcommand<br> 376.scroll<br> 377yes<br> 378</td> 379<td valign=top> 380</UL><br> 381notebook<br> 382it.<br> 383100<br> 384.nb<br> 385-fill<br> 386yes<br> 387\\<br> 388-pady<br> 389Add<br> 390the<br> 391"Page<br> 392Two",<br> 393-label<br> 394add<br> 395</UL><br> 396the<br> 397of<br> 398set<br> 3990]<br> 400childsite<br> 401<UL><br> 402on<br> 403the<br> 404-text<br> 405$page1CS.b<br> 406"Button<br> 407</UL><br> 408the<br> 409the<br> 4100<br> 411Create<br> 412associate<br> 413and<br> 414then<br> 415ScrollBar<br> 416view"<br> 417".scroll<br> 418-fill<br> 419-pady<br> 420</td> 421<td valign=top> 422#<br> 423widget<br> 424notebook<br> 425-height<br> 426-anchor<br> 427both<br> 428\\<br> 429-padx<br> 43010<br> 431two<br> 432notebook,<br> 433One"<br> 434respectively.<br> 435"Page<br> 436-label<br> 437<UL><br> 438child<br> 439these<br> 440page1CS<br> 441set<br> 442"Page<br> 443#<br> 444each<br> 445notebook<br> 446"Button<br> 447button<br> 448Two"<br> 449<UL><br> 450first<br> 451notebook<br> 452</UL><br> 453the<br> 454teh<br> 455the<br> 456pack<br> 457.scroll<br> 458.nb<br> 459set"<br> 460y<br> 46110<br> 462</td> 463<td valign=top> 464Create<br> 465and<br> 466.nb<br> 467100<br> 468nw<br> 469\\<br> 470-side<br> 47110<br> 472<UL><br> 473pages<br> 474labelled<br> 475and<br> 476.nb<br> 477One"<br> 478"Page<br> 479#<br> 480site<br> 481two<br> 482[.nb<br> 483page2CS<br> 484Two"]<br> 485Create<br> 486page<br> 487button<br> 488One"<br> 489$page2CS.b<br> 490pack<br> 491#<br> 492page<br> 493.nb<br> 494<UL><br> 495scrollbar<br> 496scrollbar<br> 497notebook<br> 498the<br> 499-command<br> 500configure<br> 501pack<br> 502-expand<br> 503</UL><br> 504</td> 505</table> 506</pre><H2>AUTHOR</H2> 507Bill W. Scott 508</pre><H2>KEYWORDS</H2> 509notebook page 510