util/X86LINUX64/man/mann/option.n

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH option n "" Tk "Tk Built-In Commands"
   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 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  79 .if t .wh -1.3i ^B
  80 .nr ^l \n(.l
  81 .ad b
  82 .\"     # Start an argument description
  83 .de AP
  84 .ie !"\\$4"" .TP \\$4
  85 .el \{\
  86 .   ie !"\\$2"" .TP \\n()Cu
  87 .   el          .TP 15
  88 .\}
  89 .ta \\n()Au \\n()Bu
  90 .ie !"\\$3"" \{\
  91 \&\\$1 \\fI\\$2\\fP (\\$3)
  92 .\".b
  93 .\}
  94 .el \{\
  95 .br
  96 .ie !"\\$2"" \{\
  97 \&\\$1  \\fI\\$2\\fP
  98 .\}
  99 .el \{\
 100 \&\\fI\\$1\\fP
 101 .\}
 102 .\}
 103 ..
 104 .\"     # define tabbing values for .AP
 105 .de AS
 106 .nr )A 10n
 107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 108 .nr )B \\n()Au+15n
 109 .\"
 110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 112 ..
 113 .AS Tcl_Interp Tcl_CreateInterp in/out
 114 .\"     # BS - start boxed text
 115 .\"     # ^y = starting y location
 116 .\"     # ^b = 1
 117 .de BS
 118 .br
 119 .mk ^y
 120 .nr ^b 1u
 121 .if n .nf
 122 .if n .ti 0
 123 .if n \l'\\n(.lu\(ul'
 124 .if n .fi
 125 ..
 126 .\"     # BE - end boxed text (draw box now)
 127 .de BE
 128 .nf
 129 .ti 0
 130 .mk ^t
 131 .ie n \l'\\n(^lu\(ul'
 132 .el \{\
 133 .\"     Draw four-sided box normally, but don't draw top of
 134 .\"     box if the box started on an earlier page.
 135 .ie !\\n(^b-1 \{\
 136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 137 .\}
 138 .el \}\
 139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 140 .\}
 141 .\}
 142 .fi
 143 .br
 144 .nr ^b 0
 145 ..
 146 .\"     # VS - start vertical sidebar
 147 .\"     # ^Y = starting y location
 148 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 149 .de VS
 150 .if !"\\$2"" .br
 151 .mk ^Y
 152 .ie n 'mc \s12\(br\s0
 153 .el .nr ^v 1u
 154 ..
 155 .\"     # VE - end of vertical sidebar
 156 .de VE
 157 .ie n 'mc
 158 .el \{\
 159 .ev 2
 160 .nf
 161 .ti 0
 162 .mk ^t
 163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 164 .sp -1
 165 .fi
 166 .ev
 167 .\}
 168 .nr ^v 0
 169 ..
 170 .\"     # Special macro to handle page bottom:  finish off current
 171 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 172 .\"     # page bottom macro.
 173 .de ^B
 174 .ev 2
 175 'ti 0
 176 'nf
 177 .mk ^t
 178 .if \\n(^b \{\
 179 .\"     Draw three-sided box if this is the box's first page,
 180 .\"     draw two sides but no top otherwise.
 181 .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
 182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .\}
 184 .if \\n(^v \{\
 185 .nr ^x \\n(^tu+1v-\\n(^Yu
 186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 187 .\}
 188 .bp
 189 'fi
 190 .ev
 191 .if \\n(^b \{\
 192 .mk ^y
 193 .nr ^b 2
 194 .\}
 195 .if \\n(^v \{\
 196 .mk ^Y
 197 .\}
 198 ..
 199 .\"     # DS - begin display
 200 .de DS
 201 .RS
 202 .nf
 203 .sp
 204 ..
 205 .\"     # DE - end display
 206 .de DE
 207 .fi
 208 .RE
 209 .sp
 210 ..
 211 .\"     # SO - start of list of standard options
 212 .de SO
 213 'ie '\\$1'' .ds So \\fBoptions\\fR
 214 'el .ds So \\fB\\$1\\fR
 215 .SH "STANDARD OPTIONS"
 216 .LP
 217 .nf
 218 .ta 5.5c 11c
 219 .ft B
 220 ..
 221 .\"     # SE - end of list of standard options
 222 .de SE
 223 .fi
 224 .ft R
 225 .LP
 226 See the \\*(So manual entry for details on the standard options.
 227 ..
 228 .\"     # OP - start of full description for a single option
 229 .de OP
 230 .LP
 231 .nf
 232 .ta 4c
 233 Command-Line Name:      \\fB\\$1\\fR
 234 Database Name:  \\fB\\$2\\fR
 235 Database Class: \\fB\\$3\\fR
 236 .fi
 237 .IP
 238 ..
 239 .\"     # CS - begin code excerpt
 240 .de CS
 241 .RS
 242 .nf
 243 .ta .25i .5i .75i 1i
 244 ..
 245 .\"     # CE - end code excerpt
 246 .de CE
 247 .fi
 248 .RE
 249 ..
 250 .\"     # UL - underline word
 251 .de UL
 252 \\$1\l'|0\(ul'\\$2
 253 ..
 254 .\"     # QW - apply quotation marks to word
 255 .de QW
 256 .ie '\\*(lq'"' ``\\$1''\\$2
 257 .\"" fix emacs highlighting
 258 .el \\*(lq\\$1\\*(rq\\$2
 259 ..
 260 .\"     # PQ - apply parens and quotation marks to word
 261 .de PQ
 262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 263 .\"" fix emacs highlighting
 264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 265 ..
 266 .\"     # QR - quoted range
 267 .de QR
 268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 269 .\"" fix emacs highlighting
 270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 271 ..
 272 .\"     # MT - "empty" string
 273 .de MT
 274 .QW ""
 275 ..
 276 .BS
 277 '\" Note:  do not modify the .SH NAME line immediately below!
 278 .SH NAME
 279 option \- Add/retrieve window options to/from the option database
 280 .SH SYNOPSIS
 281 .nf
 282 \fBoption add \fIpattern value \fR?\fIpriority\fR?
 283 \fBoption clear\fR
 284 \fBoption get \fIwindow name class\fR
 285 \fBoption readfile \fIfileName \fR?\fIpriority\fR?
 286 .fi
 287 .BE
 288 .SH DESCRIPTION
 289 .PP
 290 The \fBoption\fR command allows you to add entries to the Tk option
 291 database or to retrieve options from the database.  The \fBadd\fR
 292 form of the command adds a new option to the database.
 293 \fIPattern\fR contains
 294 the option being specified, and consists of names and/or classes
 295 separated by asterisks or dots, in the usual X format (see
 296 \fBPATTERN FORMAT\fR).  \fIValue\fR
 297 contains a text string to associate with \fIpattern\fR;  this is the
 298 value that will be returned in calls to \fBTk_GetOption\fR or by
 299 invocations of the \fBoption get\fR command.  If \fIpriority\fR
 300 is specified, it indicates the priority level for this option (see
 301 below for legal values);  it defaults to \fBinteractive\fR.
 302 This command always returns an empty string.
 303 .PP
 304 The \fBoption clear\fR command clears the option database.  Default
 305 options (from the
 306 \fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR
 307 file) will be reloaded automatically the next time an
 308 option is added to the database or removed from it.  This command
 309 always returns an empty string.
 310 .PP
 311 The \fBoption get\fR command returns the value of the option
 312 specified for \fIwindow\fR
 313 under \fIname\fR and \fIclass\fR.  If several entries in the option
 314 database match \fIwindow\fR, \fIname\fR, and \fIclass\fR, then
 315 the command returns whichever was created with highest
 316 \fIpriority\fR level.  If there are several matching
 317 entries at the same priority level, then it returns whichever entry
 318 was most recently entered into the option database.  If there are
 319 no matching entries, then the empty string is returned.
 320 .PP
 321 The \fBreadfile\fR form of the command reads \fIfileName\fR,
 322 which should have the standard format for an
 323 X resource database such as \fB.Xdefaults\fR, and adds all the
 324 options specified in that file to the option database.  If \fIpriority\fR
 325 is specified, it indicates the priority level at which to enter the
 326 options;  \fIpriority\fR defaults to \fBinteractive\fR.
 327 .PP
 328 The \fIpriority\fR arguments to the \fBoption\fR command are
 329 normally specified symbolically using one of the following values:
 330 .TP
 331 \fBwidgetDefault\fR
 332 Level 20.  Used for default values hard-coded into widgets.
 333 .TP
 334 \fBstartupFile\fR
 335 Level 40.  Used for options specified in application-specific
 336 startup files.
 337 .TP
 338 \fBuserDefault\fR
 339 Level 60.  Used for options specified in user-specific defaults
 340 files, such as \fB.Xdefaults\fR, resource databases loaded into
 341 the X server, or user-specific startup files.
 342 .TP
 343 \fBinteractive\fR
 344 Level 80.  Used for options specified interactively after the application
 345 starts running.  If \fIpriority\fR is not specified, it defaults to
 346 this level.
 347 .PP
 348 Any of the above keywords may be abbreviated.  In addition, priorities
 349 may be specified numerically using integers between 0 and 100,
 350 inclusive.  The numeric form is probably a bad idea except for new priority
 351 levels other than the ones given above.
 352 .SH "PATTERN FORMAT"
 353 .PP
 354 Patterns consist of a sequence of words separated by either periods,
 355 .QW . ,
 356 or asterisks
 357 .QW * .
 358 The overall pattern may also be optionally preceded by an asterisk.
 359 .PP
 360 Each word in the pattern conventionally starts with either an upper-case
 361 letter (in which case it denotes the class of either a widget or an option) or
 362 any other character, when it denotes the name of a widget or option. The last
 363 word in the pattern always indicates the option; the preceding ones constrain
 364 which widgets that option will be looked for in.
 365 .PP
 366 When two words are separated by a period, the latter widget must be a direct
 367 child of the former (or the option must apply to only the indicated widgets).
 368 When two words are separated by an asterisk, any depth of widgets may lie
 369 between the former and latter widgets (and the option applies to all widgets
 370 that are children of the former widget).
 371 .PP
 372 If the overall pattern is preceded by an asterisk, then the overall pattern
 373 applies anywhere it can throughout the whole widget hierarchy. Otherwise the
 374 first word of the pattern is matched against the name and class of the
 375 .QW \fB.\fR
 376 \fBtoplevel\fR, which are usually set by options to \fBwish\fR.
 377 .SH EXAMPLES
 378 .PP
 379 Instruct every button in the application to have red text on it unless
 380 explicitly overridden, by setting the \fBforeground\fR for the \fBButton\fR
 381 class (note that on some platforms the option is ignored):
 382 .CS
 383 \fBoption add\fR *Button.foreground red startupFile
 384 .CE
 385 .PP
 386 Allow users to control what happens in an entry widget when the Return
 387 key is pressed by specifying a script in the option database and add a
 388 default option for that which rings the bell:
 389 .CS
 390 entry .e
 391 bind .e <Return> [\fBoption get\fR .e returnCommand Command]
 392 \fBoption add\fR *.e.returnCommand bell widgetDefault
 393 .CE
 394 .SH "SEE ALSO"
 395 options(n), wish(1)
 396 .SH KEYWORDS
 397 database, option, priority, retrieve
 398 '\" Local Variables:
 399 '\" mode: nroff
 400 '\" End: