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