util/X86LINUX64/man/mann/ttk_notebook.n

   1 '\"
   2 '\" Copyright (c) 2004 Joe English
   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 '\" RCS: @(#) $Id: ttk_notebook.n,v 1.12.2.1 2008/05/11 00:31:03 patthoyts Exp $
   8 '\"
   9 .\" The -*- nroff -*- definitions below are for supplemental macros used
  10 .\" in Tcl/Tk manual entries.
  11 .\"
  12 .\" .AP type name in/out ?indent?
  13 .\"     Start paragraph describing an argument to a library procedure.
  14 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  15 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  16 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  17 .\"     needed;  use .AS below instead)
  18 .\"
  19 .\" .AS ?type? ?name?
  20 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  21 .\"     name are examples of largest possible arguments that will be passed
  22 .\"     to .AP later.  If args are omitted, default tab stops are used.
  23 .\"
  24 .\" .BS
  25 .\"     Start box enclosure.  From here until next .BE, everything will be
  26 .\"     enclosed in one large box.
  27 .\"
  28 .\" .BE
  29 .\"     End of box enclosure.
  30 .\"
  31 .\" .CS
  32 .\"     Begin code excerpt.
  33 .\"
  34 .\" .CE
  35 .\"     End code excerpt.
  36 .\"
  37 .\" .VS ?version? ?br?
  38 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  39 .\"     of man pages.  The first argument is ignored and used for recording
  40 .\"     the version when the .VS was added, so that the sidebars can be
  41 .\"     found and removed when they reach a certain age.  If another argument
  42 .\"     is present, then a line break is forced before starting the sidebar.
  43 .\"
  44 .\" .VE
  45 .\"     End of vertical sidebar.
  46 .\"
  47 .\" .DS
  48 .\"     Begin an indented unfilled display.
  49 .\"
  50 .\" .DE
  51 .\"     End of indented unfilled display.
  52 .\"
  53 .\" .SO ?manpage?
  54 .\"     Start of list of standard options for a Tk widget. The manpage
  55 .\"     argument defines where to look up the standard options; if
  56 .\"     omitted, defaults to "options". The options follow on successive
  57 .\"     lines, in three columns separated by tabs.
  58 .\"
  59 .\" .SE
  60 .\"     End of list of standard options for a Tk widget.
  61 .\"
  62 .\" .OP cmdName dbName dbClass
  63 .\"     Start of description of a specific option.  cmdName gives the
  64 .\"     option's name as specified in the class command, dbName gives
  65 .\"     the option's name in the option database, and dbClass gives
  66 .\"     the option's class in the option database.
  67 .\"
  68 .\" .UL arg1 arg2
  69 .\"     Print arg1 underlined, then print arg2 normally.
  70 .\"
  71 .\" .QW arg1 ?arg2?
  72 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  73 .\"
  74 .\" .PQ arg1 ?arg2?
  75 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  76 .\"     (for trailing punctuation) and then a closing parenthesis.
  77 .\"
  78 .\" RCS: @(#) $Id: man.macros,v 1.9 2008/01/29 15:32:33 dkf Exp $
  79 .\"
  80 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  81 .if t .wh -1.3i ^B
  82 .nr ^l \n(.l
  83 .ad b
  84 .\"     # Start an argument description
  85 .de AP
  86 .ie !"\\$4"" .TP \\$4
  87 .el \{\
  88 .   ie !"\\$2"" .TP \\n()Cu
  89 .   el          .TP 15
  90 .\}
  91 .ta \\n()Au \\n()Bu
  92 .ie !"\\$3"" \{\
  93 \&\\$1 \\fI\\$2\\fP (\\$3)
  94 .\".b
  95 .\}
  96 .el \{\
  97 .br
  98 .ie !"\\$2"" \{\
  99 \&\\$1  \\fI\\$2\\fP
 100 .\}
 101 .el \{\
 102 \&\\fI\\$1\\fP
 103 .\}
 104 .\}
 105 ..
 106 .\"     # define tabbing values for .AP
 107 .de AS
 108 .nr )A 10n
 109 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 110 .nr )B \\n()Au+15n
 111 .\"
 112 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 113 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 114 ..
 115 .AS Tcl_Interp Tcl_CreateInterp in/out
 116 .\"     # BS - start boxed text
 117 .\"     # ^y = starting y location
 118 .\"     # ^b = 1
 119 .de BS
 120 .br
 121 .mk ^y
 122 .nr ^b 1u
 123 .if n .nf
 124 .if n .ti 0
 125 .if n \l'\\n(.lu\(ul'
 126 .if n .fi
 127 ..
 128 .\"     # BE - end boxed text (draw box now)
 129 .de BE
 130 .nf
 131 .ti 0
 132 .mk ^t
 133 .ie n \l'\\n(^lu\(ul'
 134 .el \{\
 135 .\"     Draw four-sided box normally, but don't draw top of
 136 .\"     box if the box started on an earlier page.
 137 .ie !\\n(^b-1 \{\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .el \}\
 141 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 142 .\}
 143 .\}
 144 .fi
 145 .br
 146 .nr ^b 0
 147 ..
 148 .\"     # VS - start vertical sidebar
 149 .\"     # ^Y = starting y location
 150 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 151 .de VS
 152 .if !"\\$2"" .br
 153 .mk ^Y
 154 .ie n 'mc \s12\(br\s0
 155 .el .nr ^v 1u
 156 ..
 157 .\"     # VE - end of vertical sidebar
 158 .de VE
 159 .ie n 'mc
 160 .el \{\
 161 .ev 2
 162 .nf
 163 .ti 0
 164 .mk ^t
 165 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 166 .sp -1
 167 .fi
 168 .ev
 169 .\}
 170 .nr ^v 0
 171 ..
 172 .\"     # Special macro to handle page bottom:  finish off current
 173 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 174 .\"     # page bottom macro.
 175 .de ^B
 176 .ev 2
 177 'ti 0
 178 'nf
 179 .mk ^t
 180 .if \\n(^b \{\
 181 .\"     Draw three-sided box if this is the box's first page,
 182 .\"     draw two sides but no top otherwise.
 183 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 185 .\}
 186 .if \\n(^v \{\
 187 .nr ^x \\n(^tu+1v-\\n(^Yu
 188 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 189 .\}
 190 .bp
 191 'fi
 192 .ev
 193 .if \\n(^b \{\
 194 .mk ^y
 195 .nr ^b 2
 196 .\}
 197 .if \\n(^v \{\
 198 .mk ^Y
 199 .\}
 200 ..
 201 .\"     # DS - begin display
 202 .de DS
 203 .RS
 204 .nf
 205 .sp
 206 ..
 207 .\"     # DE - end display
 208 .de DE
 209 .fi
 210 .RE
 211 .sp
 212 ..
 213 .\"     # SO - start of list of standard options
 214 .de SO
 215 'ie '\\$1'' .ds So \\fBoptions\\fR
 216 'el .ds So \\fB\\$1\\fR
 217 .SH "STANDARD OPTIONS"
 218 .LP
 219 .nf
 220 .ta 5.5c 11c
 221 .ft B
 222 ..
 223 .\"     # SE - end of list of standard options
 224 .de SE
 225 .fi
 226 .ft R
 227 .LP
 228 See the \\*(So manual entry for details on the standard options.
 229 ..
 230 .\"     # OP - start of full description for a single option
 231 .de OP
 232 .LP
 233 .nf
 234 .ta 4c
 235 Command-Line Name:      \\fB\\$1\\fR
 236 Database Name:  \\fB\\$2\\fR
 237 Database Class: \\fB\\$3\\fR
 238 .fi
 239 .IP
 240 ..
 241 .\"     # CS - begin code excerpt
 242 .de CS
 243 .RS
 244 .nf
 245 .ta .25i .5i .75i 1i
 246 ..
 247 .\"     # CE - end code excerpt
 248 .de CE
 249 .fi
 250 .RE
 251 ..
 252 .\"     # UL - underline word
 253 .de UL
 254 \\$1\l'|0\(ul'\\$2
 255 ..
 256 .\"     # QW - apply quotation marks to word
 257 .de QW
 258 .ie '\\*(lq'"' ``\\$1''\\$2
 259 .\"" fix emacs highlighting
 260 .el \\*(lq\\$1\\*(rq\\$2
 261 ..
 262 .\"     # PQ - apply parens and quotation marks to word
 263 .de PQ
 264 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 265 .\"" fix emacs highlighting
 266 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 267 ..
 268 .\"     # QR - quoted range
 269 .de QR
 270 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 271 .\"" fix emacs highlighting
 272 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 273 ..
 274 .\"     # MT - "empty" string
 275 .de MT
 276 .QW ""
 277 ..
 278 .TH ttk::notebook n 8.5 Tk "Tk Themed Widget"
 279 .BS
 280 .SH NAME
 281 ttk::notebook \- Multi-paned container widget
 282 .SH SYNOPSIS
 283 .nf
 284 \fBttk::notebook\fR \fIpathName \fR?\fIoptions...\fR?
 285 .br
 286 \fIpathName \fBadd\fR \fIwindow\fR ?\fIoptions...\fR?
 287 \fIpathName \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR?
 288 .fi
 289 .BE
 290 .SH DESCRIPTION
 291 A \fBttk::notebook\fR widget manages a collection of windows
 292 and displays a single one at a time.
 293 Each slave window is associated with a \fItab\fR,
 294 which the user may select to change the currently-displayed window.
 295 .SO ttk_widget
 296 \-class \-cursor        \-takefocus
 297 \-style
 298 .SE
 299 .SH "WIDGET-SPECIFIC OPTIONS"
 300 .OP \-height height Height
 301 If present and greater than zero,
 302 specifies the desired height of the pane area
 303 (not including internal padding or tabs).
 304 Otherwise, the maximum height of all panes is used.
 305 .OP \-padding padding Padding
 306 Specifies the amount of extra space to add around the outside
 307 of the notebook.
 308 The padding is a list of up to four length specifications
 309 \fIleft top right bottom\fR.
 310 If fewer than four elements are specified,
 311 \fIbottom\fR defaults to \fItop\fR,
 312 \fIright\fR defaults to \fIleft\fR, and
 313 \fItop\fR defaults to \fIleft\fR.
 314 .OP \-width width Width
 315 If present and greater than zero,
 316 specifies the desired width of the pane area
 317 (not including internal padding).
 318 Otherwise, the maximum width of all panes is used.
 319 .SH "TAB OPTIONS"
 320 The following options may be specified for individual notebook panes:
 321 .OP \-state state State
 322 Either \fBnormal\fR, \fBdisabled\fR or \fBhidden\fR.
 323 If \fBdisabled\fR, then the tab is not selectable.
 324 If \fBhidden\fR, then the tab is not shown.
 325 .OP \-sticky sticky Sticky
 326 Specifies how the slave window is positioned within the pane area.
 327 Value is a string containing zero or more of the characters
 328 \fBn, s, e,\fR or \fBw\fR.
 329 Each letter refers to a side (north, south, east, or west)
 330 that the slave window will
 331 .QW stick
 332 to, as per the \fBgrid\fR geometry manager.
 333 .OP \-padding padding Padding
 334 Specifies the amount of extra space to add between the notebook and this pane.
 335 Syntax is the same as for the widget \fB\-padding\fR option.
 336 .OP \-text text Text
 337 Specifies a string to be displayed in the tab.
 338 .OP \-image image Image
 339 Specifies an image to display in the tab.
 340 See \fIttk_widget(n)\fR for details.
 341 .OP \-compound compound Compound
 342 Specifies how to display the image relative to the text,
 343 in the case both \fB\-text\fR and \fB\-image\fR are present.
 344 See \fIlabel(n)\fR for legal values.
 345 .OP \-underline underline Underline
 346 Specifies the integer index (0-based) of a character to underline
 347 in the text string.
 348 The underlined character is used for mnemonic activation
 349 if \fBttk::notebook::enableTraversal\fR is called.
 350 .SH "TAB IDENTIFIERS"
 351 The \fItabid\fR argument to the following commands may take
 352 any of the following forms:
 353 .IP \(bu
 354 An integer between zero and the number of tabs;
 355 .IP \(bu
 356 The name of a slave window;
 357 .IP \(bu
 358 A positional specification of the form
 359 .QW @\fIx\fR,\fIy\fR ,
 360 which identifies the tab
 361 .IP \(bu
 362 The literal string
 363 .QW \fBcurrent\fR ,
 364 which identifies the currently-selected tab; or:
 365 .IP \(bu
 366 The literal string
 367 .QW \fBend\fR ,
 368 which returns the number of tabs
 369 (only valid for
 370 .QW "\fIpathname \fBindex\fR" ).
 371 .SH "WIDGET COMMAND"
 372 .TP
 373 \fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR?
 374 Adds a new tab to the notebook.
 375 See \fBTAB OPTIONS\fR for the list of available \fIoptions\fR.
 376 If \fIwindow\fR is currently managed by the notebook but hidden,
 377 it is restored to its previous position.
 378 .TP
 379 \fIpathname \fBconfigure\fR ?\fIoptions\fR?
 380 See \fIttk::widget(n)\fR.
 381 .TP
 382 \fIpathname \fBcget\fR \fIoption\fR
 383 See \fIttk::widget(n)\fR.
 384 .TP
 385 \fIpathname \fBforget\fR \fItabid\fR
 386 Removes the tab specified by \fItabid\fR,
 387 unmaps and unmanages the associated window.
 388 .TP
 389 \fIpathname \fBhide\fR \fItabid\fR
 390 Hides the tab specified by \fItabid\fR.
 391 The tab will not be displayed, but the associated window
 392 remains managed by the notebook and its configuration remembered.
 393 Hidden tabs may be restored with the \fBadd\fR command.
 394 .TP
 395 \fIpathName \fBidentify\fR \fIx y\fR
 396 Returns the name of the element at position \fIx\fR, \fIy\fR.
 397 See \fIttk::widget(n)\fR.
 398 .TP
 399 \fIpathname \fBindex\fR \fItabid\fR
 400 Returns the numeric index of the tab specified by \fItabid\fR,
 401 or the total number of tabs if \fItabid\fR is the string
 402 .QW \fBend\fR .
 403 .TP
 404 \fIpathname \fBinsert\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\fR
 405 Inserts a pane at the specified position.
 406 \fIpos\fR is either the string \fBend\fR, an integer index,
 407 or the name of a managed subwindow.
 408 If \fIsubwindow\fR is already managed by the notebook,
 409 moves it to the specified position.
 410 See \fBTAB OPTIONS\fR for the list of available options.
 411 .TP
 412 \fIpathname \fBinstate\fR \fIstatespec \fR?\fIscript...\fR?
 413 See \fIttk::widget(n)\fR.
 414 .TP
 415 \fIpathname \fBselect\fR ?\fItabid\fR?
 416 Selects the specified tab.
 417 The associated slave window will be displayed,
 418 and the previously-selected window (if different) is unmapped.
 419 If \fItabid\fR is omitted, returns the widget name of the
 420 currently selected pane.
 421 .TP
 422 \fIpathname \fBstate\fR ?\fIstatespec\fR?
 423 See \fIttk::widget(n)\fR.
 424 .TP
 425 \fIpathname \fBtab\fR \fItabid\fR ?\fI\-option \fR?\fIvalue ...\fR
 426 Query or modify the options of the specific tab.
 427 If no \fI\-option\fR is specified,
 428 returns a dictionary of the tab option values.
 429 If one \fI\-option\fR is specified,
 430 returns the value of that \fIoption\fR.
 431 Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs.
 432 See \fBTAB OPTIONS\fR for the available options.
 433 .TP
 434 \fIpathname \fBtabs\fR
 435 Returns the list of windows managed by the notebook.
 436 .SH "KEYBOARD TRAVERSAL"
 437 To enable keyboard traversal for a toplevel window
 438 containing a notebook widget \fI$nb\fR, call:
 439 .CS
 440 ttk::notebook::enableTraversal $nb
 441 .CE
 442 .PP
 443 This will extend the bindings for the toplevel window
 444 containing the notebook as follows:
 445 .IP \(bu
 446 \fBControl-Tab\fR selects the tab following the currently selected one.
 447 .IP \(bu
 448 \fBShift-Control-Tab\fR selects the tab preceding the currently selected one.
 449 .IP \(bu
 450 \fBAlt-K\fR, where \fBK\fR is the mnemonic (underlined) character
 451 of any tab, will select that tab.
 452 .PP
 453 Multiple notebooks in a single toplevel may be enabled for traversal,
 454 including nested notebooks.
 455 However, notebook traversal only works properly if all panes
 456 are direct children of the notebook.
 457 .SH "VIRTUAL EVENTS"
 458 The notebook widget generates a \fB<<NotebookTabChanged>>\fR
 459 virtual event after a new tab is selected.
 460 .SH "EXAMPLE"
 461 .CS
 462 pack [\fBttk::notebook\fR .nb]
 463 \.nb add [frame .nb.f1] \-text "First tab"
 464 \.nb add [frame .nb.f2] \-text "Second tab"
 465 \.nb select .nb.f2
 466 ttk::notebook::enableTraversal .nb
 467 .CE
 468 .SH "SEE ALSO"
 469 ttk::widget(n), grid(n)
 470 .SH "KEYWORDS"
 471 pane, tab