2 '\" Copyright (c) 2008 Arnulf Wiedemann
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH option n 4.0 itcl "[incr\ Tcl]"
8 '\" The definitions below are for supplemental macros used in Tcl/Tk
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)
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.
24 '\" Start box enclosure. From here until next .BE, everything will be
25 '\" enclosed in one large box.
28 '\" End of box enclosure.
31 '\" Begin code excerpt.
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.
44 '\" End of vertical sidebar.
47 '\" Begin an indented unfilled display.
50 '\" End of indented unfilled display.
53 '\" Start of list of standard options for a Tk widget. The
54 '\" options follow on successive lines, in four columns separated
58 '\" End of list of standard options for a Tk widget.
60 '\" .OP cmdName dbName dbClass
61 '\" Start of description of a specific option. cmdName gives the
62 '\" option's name as specified in the class command, dbName gives
63 '\" the option's name in the option database, and dbClass gives
64 '\" the option's class in the option database.
67 '\" Print arg1 underlined, then print arg2 normally.
69 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
71 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
75 '\" # Start an argument description
79 . ie !"\\$2"" .TP \\n()Cu
84 \&\\$1 \\fI\\$2\\fP (\\$3)
97 '\" # define tabbing values for .AP
100 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
103 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
104 .nr )C \\n()Bu+\\w'(in/out)'u+2n
106 .AS Tcl_Interp Tcl_CreateInterp in/out
107 '\" # BS - start boxed text
108 '\" # ^y = starting y location
116 .if n \l'\\n(.lu\(ul'
119 '\" # BE - end boxed text (draw box now)
124 .ie n \l'\\n(^lu\(ul'
126 .\" Draw four-sided box normally, but don't draw top of
127 .\" box if the box started on an earlier page.
129 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
132 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 '\" # VS - start vertical sidebar
140 '\" # ^Y = starting y location
141 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
145 .ie n 'mc \s12\(br\s0
148 '\" # VE - end of vertical sidebar
156 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
163 '\" # Special macro to handle page bottom: finish off current
164 '\" # box/sidebar if in box/sidebar mode, then invoked standard
165 '\" # page bottom macro.
172 .\" Draw three-sided box if this is the box's first page,
173 .\" draw two sides but no top otherwise.
174 .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
175 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
178 .nr ^x \\n(^tu+1v-\\n(^Yu
179 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
192 '\" # DS - begin display
198 '\" # DE - end display
204 '\" # SO - start of list of standard options
206 .SH "STANDARD OPTIONS"
212 '\" # SE - end of list of standard options
217 See the \\fBoptions\\fR manual entry for details on the standard options.
219 '\" # OP - start of full description for a single option
224 Command-Line Name: \\fB\\$1\\fR
225 Database Name: \\fB\\$2\\fR
226 Database Class: \\fB\\$3\\fR
230 '\" # CS - begin code excerpt
236 '\" # CE - end code excerpt
245 '\" Note: do not modify the .SH NAME line immediately below!
247 itcl::option \- define options for extendedclass, widget or widgetadaptor
249 Parts of this description are "borrowed" from Tcl extension [snit], as the functionality is mostly identical.
251 This is new functionality in [incr Tcl] where the API can still change!!
254 \fBoption \fIoptionSpec\fR ?\fIdefaultValue\fR?
255 \fBoption \fIoptionSpec\fR ?\fIoptions\fR?
261 The \fBoption\fR command is used inside an \fB[incr\ Tcl]\fR
262 extendedclass/widget/widgetadaptor definition to define options.
264 In the first form defines an option for instances of this type, and optionally
265 gives it an initial value. The initial value defaults to the empty string if
266 no defaultValue is specified.
268 An option defined in this way is said to be locally defined.
269 The optionSpec is a list defining the option's name, resource name, and class
273 option {-font font Font} {Courier 12}
276 The option name must begin with a hyphen, and must not contain any upper case
277 letters. The resource name and class name are optional; if not specified,
278 the resource name defaults to the option name, minus the hyphen, and the class
279 name defaults to the resource name with the first letter capitalized. Thus, the
280 following statement is equivalent to the previous example:
283 option -font {Courier 12}
286 See The Tk Option Database for more information about resource and class names.
288 Options are normally set and retrieved using the standard instance methods
289 configure and cget; within instance code (method bodies, etc.), option values
290 are available through the options array:
293 set myfont $itcl_options(-font)
296 In the second form you can define option handlers (e.g., -configuremethod),
297 then it should probably use configure and cget to access its options to avoid
300 The option statement may include the following options:
302 \fB-default\fI defvalue\fR
304 Defines the option's default value; the option's default value will be ""
309 The option is handled read-only -- it can only be set using configure at
310 creation time, i.e., in the type's constructor.
312 \fB-cgetmethod\fI methodName\fR
314 Every locally-defined option may define a -cgetmethod; it is called when the
315 option's value is retrieved using the cget method. Whatever the method's body
316 returns will be the return value of the call to cget.
319 The named method must take one argument, the option name. For example, this
320 code is equivalent to (though slower than) Itcl's default handling of cget:
323 option -font -cgetmethod GetOption
324 method GetOption {option} {
325 return $itcl_options($option)
329 Note that it's possible for any number of options to share a -cgetmethod.
332 \fB-cgetmethodvar\fI varName\fR
334 That is very similar to -cgetmethod, the only difference is, one can define
335 a variable, where to find the cgetmethod during runtime.
337 \fB-configuremethod\fI methodName\fR
339 Every locally-defined option may define a -configuremethod; it is called
340 when the option's value is set using the configure or configurelist
341 methods. It is the named method's responsibility to save the option's
342 value; in other words, the value will not be saved to the itcl_options()
343 array unless the method saves it there.
346 The named method must take two arguments, the option name and its new value.
347 For example, this code is equivalent to (though slower than) Itcl's default
348 handling of configure:
351 option -font -configuremethod SetOption
352 method SetOption {option value} {
353 set itcl_options($option) $value
357 Note that it's possible for any number of options to share a single -configuremethod.
360 \fB-configuremethodvar\fI varName\fR
362 That is very similar to -configuremethod, the only difference is, one can define
363 a variable, where to find the configuremethod during runtime.
365 \fB-validatemethod\fI methodName\fR
367 Every locally-defined option may define a -validatemethod; it is called when
368 the option's value is set using the configure or configurelist methods, just
369 before the -configuremethod (if any). It is the named method's responsibility
370 to validate the option's new value, and to throw an error if the value is
374 The named method must take two arguments, the option name and its new value.
375 For example, this code verifies that -flag's value is a valid Boolean value:
378 option -font -validatemethod CheckBoolean
379 method CheckBoolean {option value} {
380 if {![string is boolean -strict $value]} {
381 error "option $option must have a boolean value."
386 Note that it's possible for any number of options to share a single -validatemethod.
389 \fB-validatemethodvar\fI varName\fR
391 That is very similar to -validatemethod, the only difference is, one can define
392 a variable, where to find the validatemethod during runtime.
395 option, widget, widgetadaptor, extendedclass