| 1 | '\" |
| 2 | '\" Copyright (c) 1998 Sun Microsystems, Inc. |
| 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: SetOptions.3,v 1.8 2000/10/01 21:31:35 ericm Exp $ |
| 8 | '\" |
| 9 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 10 | '\" 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 |
| 54 | '\" Start of list of standard options for a Tk widget. The |
| 55 | '\" options follow on successive lines, in four columns separated |
| 56 | '\" 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 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 71 | '\" |
| 72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 73 | .if t .wh -1.3i ^B |
| 74 | .nr ^l \n(.l |
| 75 | .ad b |
| 76 | '\" # Start an argument description |
| 77 | .de AP |
| 78 | .ie !"\\$4"" .TP \\$4 |
| 79 | .el \{\ |
| 80 | . ie !"\\$2"" .TP \\n()Cu |
| 81 | . el .TP 15 |
| 82 | .\} |
| 83 | .ta \\n()Au \\n()Bu |
| 84 | .ie !"\\$3"" \{\ |
| 85 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 86 | .\".b |
| 87 | .\} |
| 88 | .el \{\ |
| 89 | .br |
| 90 | .ie !"\\$2"" \{\ |
| 91 | \&\\$1 \\fI\\$2\\fP |
| 92 | .\} |
| 93 | .el \{\ |
| 94 | \&\\fI\\$1\\fP |
| 95 | .\} |
| 96 | .\} |
| 97 | .. |
| 98 | '\" # define tabbing values for .AP |
| 99 | .de AS |
| 100 | .nr )A 10n |
| 101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 102 | .nr )B \\n()Au+15n |
| 103 | .\" |
| 104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 106 | .. |
| 107 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 108 | '\" # BS - start boxed text |
| 109 | '\" # ^y = starting y location |
| 110 | '\" # ^b = 1 |
| 111 | .de BS |
| 112 | .br |
| 113 | .mk ^y |
| 114 | .nr ^b 1u |
| 115 | .if n .nf |
| 116 | .if n .ti 0 |
| 117 | .if n \l'\\n(.lu\(ul' |
| 118 | .if n .fi |
| 119 | .. |
| 120 | '\" # BE - end boxed text (draw box now) |
| 121 | .de BE |
| 122 | .nf |
| 123 | .ti 0 |
| 124 | .mk ^t |
| 125 | .ie n \l'\\n(^lu\(ul' |
| 126 | .el \{\ |
| 127 | .\" Draw four-sided box normally, but don't draw top of |
| 128 | .\" box if the box started on an earlier page. |
| 129 | .ie !\\n(^b-1 \{\ |
| 130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 131 | .\} |
| 132 | .el \}\ |
| 133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 134 | .\} |
| 135 | .\} |
| 136 | .fi |
| 137 | .br |
| 138 | .nr ^b 0 |
| 139 | .. |
| 140 | '\" # VS - start vertical sidebar |
| 141 | '\" # ^Y = starting y location |
| 142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 143 | .de VS |
| 144 | .if !"\\$2"" .br |
| 145 | .mk ^Y |
| 146 | .ie n 'mc \s12\(br\s0 |
| 147 | .el .nr ^v 1u |
| 148 | .. |
| 149 | '\" # VE - end of vertical sidebar |
| 150 | .de VE |
| 151 | .ie n 'mc |
| 152 | .el \{\ |
| 153 | .ev 2 |
| 154 | .nf |
| 155 | .ti 0 |
| 156 | .mk ^t |
| 157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 158 | .sp -1 |
| 159 | .fi |
| 160 | .ev |
| 161 | .\} |
| 162 | .nr ^v 0 |
| 163 | .. |
| 164 | '\" # Special macro to handle page bottom: finish off current |
| 165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 166 | '\" # page bottom macro. |
| 167 | .de ^B |
| 168 | .ev 2 |
| 169 | 'ti 0 |
| 170 | 'nf |
| 171 | .mk ^t |
| 172 | .if \\n(^b \{\ |
| 173 | .\" Draw three-sided box if this is the box's first page, |
| 174 | .\" draw two sides but no top otherwise. |
| 175 | .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 |
| 176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 177 | .\} |
| 178 | .if \\n(^v \{\ |
| 179 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 181 | .\} |
| 182 | .bp |
| 183 | 'fi |
| 184 | .ev |
| 185 | .if \\n(^b \{\ |
| 186 | .mk ^y |
| 187 | .nr ^b 2 |
| 188 | .\} |
| 189 | .if \\n(^v \{\ |
| 190 | .mk ^Y |
| 191 | .\} |
| 192 | .. |
| 193 | '\" # DS - begin display |
| 194 | .de DS |
| 195 | .RS |
| 196 | .nf |
| 197 | .sp |
| 198 | .. |
| 199 | '\" # DE - end display |
| 200 | .de DE |
| 201 | .fi |
| 202 | .RE |
| 203 | .sp |
| 204 | .. |
| 205 | '\" # SO - start of list of standard options |
| 206 | .de SO |
| 207 | .SH "STANDARD OPTIONS" |
| 208 | .LP |
| 209 | .nf |
| 210 | .ta 5.5c 11c |
| 211 | .ft B |
| 212 | .. |
| 213 | '\" # SE - end of list of standard options |
| 214 | .de SE |
| 215 | .fi |
| 216 | .ft R |
| 217 | .LP |
| 218 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 219 | .. |
| 220 | '\" # OP - start of full description for a single option |
| 221 | .de OP |
| 222 | .LP |
| 223 | .nf |
| 224 | .ta 4c |
| 225 | Command-Line Name: \\fB\\$1\\fR |
| 226 | Database Name: \\fB\\$2\\fR |
| 227 | Database Class: \\fB\\$3\\fR |
| 228 | .fi |
| 229 | .IP |
| 230 | .. |
| 231 | '\" # CS - begin code excerpt |
| 232 | .de CS |
| 233 | .RS |
| 234 | .nf |
| 235 | .ta .25i .5i .75i 1i |
| 236 | .. |
| 237 | '\" # CE - end code excerpt |
| 238 | .de CE |
| 239 | .fi |
| 240 | .RE |
| 241 | .. |
| 242 | .de UL |
| 243 | \\$1\l'|0\(ul'\\$2 |
| 244 | .. |
| 245 | .TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures" |
| 246 | .BS |
| 247 | .SH NAME |
| 248 | Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options |
| 249 | .SH SYNOPSIS |
| 250 | .nf |
| 251 | \fB#include <tk.h>\fR |
| 252 | .sp |
| 253 | Tk_OptionTable |
| 254 | \fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR |
| 255 | .sp |
| 256 | \fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR |
| 257 | .sp |
| 258 | int |
| 259 | \fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR |
| 260 | .sp |
| 261 | int |
| 262 | \fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR |
| 263 | .sp |
| 264 | \fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR |
| 265 | .sp |
| 266 | \fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR |
| 267 | .sp |
| 268 | Tcl_Obj * |
| 269 | \fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR |
| 270 | .sp |
| 271 | Tcl_Obj * |
| 272 | \fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR |
| 273 | .sp |
| 274 | \fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR |
| 275 | .sp |
| 276 | int |
| 277 | \fBTk_Offset(\fItype, field\fB)\fR |
| 278 | .SH ARGUMENTS |
| 279 | .AS Tk_SavedOptions "*CONST objv[]" in/out |
| 280 | .AP Tcl_Interp *interp in |
| 281 | A Tcl interpreter. Most procedures use this only for returning error |
| 282 | messages; if it is NULL then no error messages are returned. For |
| 283 | \fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the |
| 284 | interpreter in which the option table will be used. |
| 285 | .AP Tk_OptionSpec *templatePtr in |
| 286 | Points to an array of static information that describes the configuration |
| 287 | options that are supported. Used to build a Tk_OptionTable. The information |
| 288 | pointed to by this argument must exist for the lifetime of the Tk_OptionTable. |
| 289 | .AP Tk_OptionTable optionTable in |
| 290 | Token for an option table. Must have been returned by a previous call |
| 291 | to \fBTk_CreateOptionTable\fR. |
| 292 | .AP char *recordPtr in/out |
| 293 | Points to structure in which values of configuration options are stored; |
| 294 | fields of this record are modified by procedures such as \fBTk_SetOptions\fR |
| 295 | and read by procedures such as \fBTk_GetOptionValue\fR. |
| 296 | .AP Tk_Window tkwin in |
| 297 | For options such as TK_OPTION_COLOR, this argument indicates |
| 298 | the window in which the option will be used. If \fIoptionTable\fR uses |
| 299 | no window-dependent options, then a NULL value may be supplied for |
| 300 | this argument. |
| 301 | .AP int objc in |
| 302 | Number of values in \fIobjv\fR. |
| 303 | .AP Tcl_Obj "*CONST objv[]" in |
| 304 | Command-line arguments for setting configuring options. |
| 305 | .AP Tk_SavedOptions *savePtr out |
| 306 | If not NULL, the structure pointed to by this argument is filled |
| 307 | in with the old values of any options that were modified and old |
| 308 | values are restored automatically if an error occurs in \fBTk_SetOptions\fR. |
| 309 | .AP int *maskPtr out |
| 310 | If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the |
| 311 | bit-wise OR of the \fItypeMask\fR fields for the options that |
| 312 | were modified. |
| 313 | .AP Tk_SavedOptions *savedPtr in/out |
| 314 | Points to a structure previously filled in by \fBTk_SetOptions\fR with |
| 315 | old values of modified options. |
| 316 | .AP Tcl_Obj *namePtr in |
| 317 | The value of this object is the name of a particular option. If NULL |
| 318 | is passed to \fBTk_GetOptionInfo\fR then information is returned for |
| 319 | all options. Must not be NULL when \fBTk_GetOptionValue\fR is called. |
| 320 | .AP "type name" type in |
| 321 | The name of the type of a record. |
| 322 | .AP "field name" field in |
| 323 | The name of a field in records of type \fItype\fR. |
| 324 | .BE |
| 325 | .SH DESCRIPTION |
| 326 | .PP |
| 327 | These procedures handle most of the details of parsing configuration |
| 328 | options such as those for Tk widgets. Given a description of what |
| 329 | options are supported, these procedures handle all the details of |
| 330 | parsing options and storing their values into a C structure associated |
| 331 | with the widget or object. The procedures were designed primarily for |
| 332 | widgets in Tk, but they can also be used for other kinds of objects that |
| 333 | have configuration options. In the rest of this manual page ``widget'' will |
| 334 | be used to refer to the object whose options are being managed; in |
| 335 | practice the object may not actually be a widget. The term ``widget |
| 336 | record'' is used to refer to the C-level structure in |
| 337 | which information about a particular widget or object is stored. |
| 338 | .PP |
| 339 | Note: the easiest way to learn how to use these procedures is to |
| 340 | look at a working example. In Tk, the simplest example is the code |
| 341 | that implements the button family of widgets, which is an \fBtkButton.c\fR. |
| 342 | Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. |
| 343 | .PP |
| 344 | In order to use these procedures, the code that implements the widget |
| 345 | must contain a static array of Tk_OptionSpec structures. This is a |
| 346 | template that describes the various options supported by that class of |
| 347 | widget; there is a separate template for each kind of widget. The |
| 348 | template contains information such as the name of each option, its type, |
| 349 | its default value, and where the value of the option is stored in the |
| 350 | widget record. See TEMPLATES below for more detail. |
| 351 | .PP |
| 352 | In order to process configuration options efficiently, the static |
| 353 | template must be augmented with additional information that is available |
| 354 | only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this |
| 355 | dynamic information from the template and returns a Tk_OptionTable token |
| 356 | that describes both the static and dynamic information. All of the |
| 357 | other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable |
| 358 | token as argument. Typically, \fBTk_CreateOptionTable\fR is called the |
| 359 | first time that a widget of a particular class is created and the |
| 360 | resulting Tk_OptionTable is used in the future for all widgets of that |
| 361 | class. A Tk_OptionTable may be used only in a single interpreter, given |
| 362 | by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an |
| 363 | option table is no longer needed \fBTk_DeleteOptionTable\fR should be |
| 364 | called to free all of its resources. All of the option tables |
| 365 | for a Tcl interpreter are freed automatically if the interpreter is deleted. |
| 366 | .PP |
| 367 | \fBTk_InitOptions\fR is invoked when a new widget is created to set |
| 368 | the default values for all of the widget's configuration options. |
| 369 | \fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR) |
| 370 | and a pointer to a widget record (\fIrecordPtr\fR), which is the C |
| 371 | structure that holds information about this widget. \fBTk_InitOptions\fR |
| 372 | uses the information in the option table to |
| 373 | choose an appropriate default for each option, then it stores the default |
| 374 | value directly into the widget record, overwriting any information that |
| 375 | was already present in the widget record. \fBTk_InitOptions\fR normally |
| 376 | returns TCL_OK. If an error occurred while setting the default values |
| 377 | (e.g., because a default value was erroneous) then TCL_ERROR is returned |
| 378 | and an error message is left in \fIinterp\fR's result if \fIinterp\fR |
| 379 | isn't NULL. |
| 380 | .PP |
| 381 | \fBTk_SetOptions\fR is invoked to modify configuration options based |
| 382 | on information specified in a Tcl command. The command might be one that |
| 383 | creates a new widget, or a command that modifies options on an existing |
| 384 | widget. The \fIobjc\fR and \fIobjv\fR arguments describe the |
| 385 | values of the arguments from the Tcl command. \fIObjv\fR must contain |
| 386 | an even number of objects: the first object of each pair gives the name of |
| 387 | an option and the second object gives the new value for that option. |
| 388 | \fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that |
| 389 | the new value of the option conforms to the type in \fIoptionTable\fR, |
| 390 | and stores the value of the option into the widget record given by |
| 391 | \fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns TCL_OK. If |
| 392 | an error occurred (such as an unknown option name or an illegal option |
| 393 | value) then TCL_ERROR is returned and an error message is left in |
| 394 | \fIinterp\fR's result if \fIinterp\fR isn't NULL. |
| 395 | .PP |
| 396 | \fBTk_SetOptions\fR has two additional features. First, if the |
| 397 | \fImaskPtr\fR argument isn't NULL then it points to an integer |
| 398 | value that is filled in with information about the options that were |
| 399 | modified. For each option in the template passed to |
| 400 | \fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The |
| 401 | bits of this field are defined by the code that implements the widget; |
| 402 | for example, each bit might correspond to a particular configuration option. |
| 403 | Alternatively, bits might be used functionally. For example, one bit might |
| 404 | be used for redisplay: all options that affect the widget's display, such |
| 405 | that changing the option requires the widget to be redisplayed, might have |
| 406 | that bit set. Another bit might indicate that the geometry of the widget |
| 407 | must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the |
| 408 | \fItypeMask\fR fields from all the options that were modified and returns |
| 409 | this value at *\fImaskPtr\fR; the caller can then use this information |
| 410 | to optimize itself so that, for example, it doesn't redisplay the widget |
| 411 | if the modified options don't affect the widget's appearance. |
| 412 | .PP |
| 413 | The second additional feature of \fBTk_SetOptions\fR has to do with error |
| 414 | recovery. If an error occurs while processing configuration options, this |
| 415 | feature makes it possible to restore all the configuration options to their |
| 416 | previous values. Errors can occur either while processing options in |
| 417 | \fBTk_SetOptions\fR or later in the caller. In many cases the caller does |
| 418 | additional processing after \fBTk_SetOptions\fR returns; for example, it |
| 419 | might use an option value to set a trace on a variable and may detect |
| 420 | an error if the variable is an array instead of a scalar. Error recovery |
| 421 | is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument |
| 422 | to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized |
| 423 | Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR |
| 424 | overwrites the structure pointed to by \fIsavePtr\fR with information |
| 425 | about the old values of any options modified by the procedure. |
| 426 | If \fBTk_SetOptions\fR returns successfully, the |
| 427 | caller uses the structure in one of two ways. If the caller completes |
| 428 | its processing of the new options without any errors, then it must pass |
| 429 | the structure to \fBTk_FreeSavedOptions\fR so that the old values can be |
| 430 | freed. If the caller detects an error in its processing of the new |
| 431 | options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR, |
| 432 | which will copy the old values back into the widget record and free |
| 433 | the new values. |
| 434 | If \fBTk_SetOptions\fR detects an error then it automatically restores |
| 435 | any options that had already been modified and leaves *\fIsavePtr\fR in |
| 436 | an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or |
| 437 | \fBTk_RestoreSavedOptions\fR. |
| 438 | If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then |
| 439 | \fBTk_SetOptions\fR frees each old option value immediately when it sets a new |
| 440 | value for the option. In this case, if an error occurs in the third |
| 441 | option, the old values for the first two options cannot be restored. |
| 442 | .PP |
| 443 | \fBTk_GetOptionValue\fR returns the current value of a configuration option |
| 444 | for a particular widget. The \fInamePtr\fR argument contains the name of |
| 445 | an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR |
| 446 | to lookup the option and extract its value from the widget record |
| 447 | pointed to by \fIrecordPtr\fR, then it returns an object containing |
| 448 | that value. If an error occurs (e.g., because \fInamePtr\fR contains an |
| 449 | unknown option name) then NULL is returned and an error message is left |
| 450 | in \fIinterp\fR's result unless \fIinterp\fR is NULL. |
| 451 | .PP |
| 452 | \fBTk_GetOptionInfo\fR returns information about configuration options in |
| 453 | a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR |
| 454 | argument is not NULL, it points to an object that gives the name of a |
| 455 | configuration option; \fBTk_GetOptionInfo\fR returns an object containing |
| 456 | a list with five elements, which are the name of the option, the name and |
| 457 | class used for the option in the option database, the default value for |
| 458 | the option, and the current value for the option. If the \fInamePtr\fR |
| 459 | argument is NULL, then \fBTk_GetOptionInfo\fR returns information about |
| 460 | all options in the form of a list of lists; each sublist describes one |
| 461 | option. Synonym options are handled differently depending on whether |
| 462 | \fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for |
| 463 | each synonym option has only two elements, which are the name of the |
| 464 | option and the name of the other option that it refers to; if \fInamePtr\fR |
| 465 | is non-NULL and names a synonym option then the object returned |
| 466 | is the five-element list |
| 467 | for the other option that the synonym refers to. If an error occurs |
| 468 | (e.g., because \fInamePtr\fR contains an unknown option name) then NULL |
| 469 | is returned and an error message is left in \fIinterp\fR's result unless |
| 470 | \fIinterp\fR is NULL. |
| 471 | .PP |
| 472 | \fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. |
| 473 | It frees all of the resources associated with any of the configuration |
| 474 | options defined in \fIrecordPtr\fR by \fIoptionTable\fR. |
| 475 | .PP |
| 476 | The \fBTk_Offset\fR macro is provided as a safe way of generating the |
| 477 | \fIobjOffset\fR and \fIinternalOffset\fR values for entries in |
| 478 | Tk_OptionSpec structures. It takes two arguments: the name of a type |
| 479 | of record, and the name of a field in that record. It returns the byte |
| 480 | offset of the named field in records of the given type. |
| 481 | |
| 482 | .SH "TEMPLATES" |
| 483 | .PP |
| 484 | The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR |
| 485 | via its \fItemplatePtr\fR argument describes the configuration options |
| 486 | supported by a particular class of widgets. Each structure specifies |
| 487 | one configuration option and has the following fields: |
| 488 | .CS |
| 489 | typedef struct { |
| 490 | Tk_OptionType \fItype\fR; |
| 491 | char *\fIoptionName\fR; |
| 492 | char *\fIdbName\fR; |
| 493 | char *\fIdbClass\fR; |
| 494 | char *\fIdefValue\fR; |
| 495 | int \fIobjOffset\fR; |
| 496 | int \fIinternalOffset\fR; |
| 497 | int \fIflags\fR; |
| 498 | ClientData \fIclientData\fR; |
| 499 | int \fItypeMask\fR; |
| 500 | } Tk_OptionSpec; |
| 501 | .CE |
| 502 | The \fItype\fR field indicates what kind of configuration option this is |
| 503 | (e.g. TK_OPTION_COLOR for a color value, or TK_OPTION_INT for |
| 504 | an integer value). \fIType\fR determines how the |
| 505 | value of the option is parsed (more on this below). |
| 506 | The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR; |
| 507 | it is the name used for the option in Tcl commands and passed to |
| 508 | procedures via the \fIobjc\fR or \fInamePtr\fR arguments. |
| 509 | The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR |
| 510 | to look up a default value for this option in the option database; if |
| 511 | \fIdbName\fR is NULL then the option database is not used by |
| 512 | \fBTk_InitOptions\fR for this option. The \fIdefValue\fR field |
| 513 | specifies a default value for this configuration option if no |
| 514 | value is specified in the option database. The \fIobjOffset\fR and |
| 515 | \fIinternalOffset\fR fields indicate where to store the value of this |
| 516 | option in widget records (more on this below); values for the \fIobjOffset\fR |
| 517 | and \fIinternalOffset\fR fields should always be generated with the |
| 518 | \fBTk_Offset\fR macro. |
| 519 | The \fIflags\fR field contains additional information |
| 520 | to control the processing of this configuration option (see below |
| 521 | for details). |
| 522 | \fIClientData\fR provides additional type-specific data needed |
| 523 | by certain types. For instance, for TK_OPTION_COLOR types, |
| 524 | \fIclientData\fR is a string giving the default value to use on |
| 525 | monochrome displays. See the descriptions of the different types |
| 526 | below for details. |
| 527 | The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to |
| 528 | return information about which options were modified; see the description |
| 529 | of \fBTk_SetOptions\fR above for details. |
| 530 | .PP |
| 531 | When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an |
| 532 | option into the widget record, they can do it in either of two ways. |
| 533 | If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than |
| 534 | or equal to zero, then the value of the option is stored as a |
| 535 | (Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR. |
| 536 | If the \fIinternalOffset\fR field of the Tk_OptionSpec is |
| 537 | greater than or equal to zero, then the value of the option is stored |
| 538 | in a type-specific internal form at the location in the widget record |
| 539 | given by \fIinternalOffset\fR. For example, if the option's type is |
| 540 | TK_OPTION_INT then the internal form is an integer. If the |
| 541 | \fIobjOffset\fR or \fIinternalOffset\fR field is negative then the |
| 542 | value is not stored in that form. At least one of the offsets must be |
| 543 | greater than or equal to zero. |
| 544 | .PP |
| 545 | The \fIflags\fR field consists of one or more bits ORed together. At |
| 546 | present only a single flag is supported: TK_OPTION_NULL_OK. If |
| 547 | this bit is set for an option then an empty string will be accepted as |
| 548 | the value for the option and the resulting internal form will be a |
| 549 | NULL pointer, a zero value, or \fBNone\fR, depending on the type of |
| 550 | the option. If the flag is not set then empty strings will result |
| 551 | in errors. |
| 552 | TK_OPTION_NULL_OK is typically used to allow a |
| 553 | feature to be turned off entirely, e.g. set a cursor value to |
| 554 | \fBNone\fR so that a window simply inherits its parent's cursor. |
| 555 | Not all option types support the TK_OPTION_NULL_OK |
| 556 | flag; for those that do, there is an explicit indication of that fact |
| 557 | in the descriptions below. |
| 558 | .PP |
| 559 | The \fItype\fR field of each Tk_OptionSpec structure determines |
| 560 | how to parse the value of that configuration option. The |
| 561 | legal value for \fItype\fR, and the corresponding actions, are |
| 562 | described below. If the type requires a \fItkwin\fR value to be |
| 563 | passed into procedures like \fBTk_SetOptions\fR, or if it uses |
| 564 | the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated |
| 565 | explicitly; if not mentioned, the type requires neither \fItkwin\fR |
| 566 | nor \fIclientData\fR. |
| 567 | .TP |
| 568 | \fBTK_OPTION_ANCHOR\fR |
| 569 | The value must be a standard anchor position such as \fBne\fR or |
| 570 | \fBcenter\fR. The internal form is a Tk_Anchor value like the ones |
| 571 | returned by \fBTk_GetAnchorFromObj\fR. |
| 572 | .TP |
| 573 | \fBTK_OPTION_BITMAP\fR |
| 574 | The value must be a standard Tk bitmap name. The internal form is a |
| 575 | Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. |
| 576 | This option type requires \fItkwin\fR to be supplied to procedures |
| 577 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. |
| 578 | .TP |
| 579 | \fBTK_OPTION_BOOLEAN\fR |
| 580 | The value must be a standard boolean value such as \fBtrue\fR or |
| 581 | \fBno\fR. The internal form is an integer with value 0 or 1. |
| 582 | .TP |
| 583 | \fBTK_OPTION_BORDER\fR |
| 584 | The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. |
| 585 | The internal form is a Tk_3DBorder token like the ones returned |
| 586 | by \fBTk_Alloc3DBorderFromObj\fR. |
| 587 | This option type requires \fItkwin\fR to be supplied to procedures |
| 588 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. |
| 589 | .TP |
| 590 | \fBTK_OPTION_COLOR\fR |
| 591 | The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. |
| 592 | The internal form is an (XColor *) token like the ones returned by |
| 593 | \fBTk_AllocColorFromObj\fR. |
| 594 | This option type requires \fItkwin\fR to be supplied to procedures |
| 595 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. |
| 596 | .TP |
| 597 | \fBTK_OPTION_CURSOR\fR |
| 598 | The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. |
| 599 | The internal form is a Tk_Cursor token like the ones returned by |
| 600 | \fBTk_AllocCursorFromObj\fR. |
| 601 | This option type requires \fItkwin\fR to be supplied to procedures |
| 602 | such as \fBTk_SetOptions\fR, and when the option is set the cursor |
| 603 | for the window is changed by calling \fBXDefineCursor\fR. This |
| 604 | option type also supports the TK_OPTION_NULL_OK flag. |
| 605 | .TP |
| 606 | \fBTK_OPTION_CUSTOM\fR |
| 607 | This option allows applications to define new option types. The |
| 608 | clientData field of the entry points to a structure defining the new |
| 609 | option type. See the section CUSTOM OPTION TYPES below for details. |
| 610 | .TP |
| 611 | \fBTK_OPTION_DOUBLE\fR |
| 612 | The string value must be a floating-point number in |
| 613 | the format accepted by \fBstrtol\fR. The internal form is a C |
| 614 | \fBdouble\fR value. This option type supports the TK_OPTION_NULL_OK |
| 615 | flag; if a NULL value is set, the internal representation is set to zero. |
| 616 | .TP |
| 617 | \fBTK_OPTION_END\fR |
| 618 | Marks the end of the template. There must be a Tk_OptionSpec structure |
| 619 | with \fItype\fR TK_OPTION_END at the end of each template. If the |
| 620 | \fIclientData\fR field of this structure isn't NULL, then it points to |
| 621 | an additional array of Tk_OptionSpec's, which is itself terminated by |
| 622 | another TK_OPTION_END entry. Templates may be chained arbitrarily |
| 623 | deeply. This feature allows common options to be shared by several |
| 624 | widget classes. |
| 625 | .TP |
| 626 | \fBTK_OPTION_FONT\fR |
| 627 | The value must be a standard font name such as \fBTimes 16\fR. |
| 628 | The internal form is a Tk_Font handle like the ones returned by |
| 629 | \fBTk_AllocFontFromObj\fR. |
| 630 | This option type requires \fItkwin\fR to be supplied to procedures |
| 631 | such as \fBTk_SetOptions\fR, and it supports the TK_OPTION_NULL_OK flag. |
| 632 | .TP |
| 633 | \fBTK_OPTION_INT\fR |
| 634 | The string value must be an integer in the format accepted by |
| 635 | \fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to |
| 636 | specify octal or hexadecimal numbers, respectively). The internal |
| 637 | form is a C \fBint\fR value. |
| 638 | .TP |
| 639 | \fBTK_OPTION_JUSTIFY\fR |
| 640 | The value must be a standard justification value such as \fBleft\fR. |
| 641 | The internal form is a Tk_Justify like the values returned by |
| 642 | \fBTk_GetJustifyFromObj\fR. |
| 643 | .TP |
| 644 | \fBTK_OPTION_PIXELS\fR |
| 645 | The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. |
| 646 | The internal form is an integer value giving a |
| 647 | distance in pixels, like the values returned by |
| 648 | \fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field isn't |
| 649 | used then information about the original value of this option will be lost. |
| 650 | See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option |
| 651 | type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the |
| 652 | internal representation is set to zero. |
| 653 | .TP |
| 654 | \fBTK_OPTION_RELIEF\fR |
| 655 | The value must be standard relief such as \fBraised\fR. |
| 656 | The internal form is an integer relief value such as |
| 657 | TK_RELIEF_RAISED. This option type supports the TK_OPTION_NULL_OK |
| 658 | flag; if the empty string is specified as the value for the option, |
| 659 | the integer relief value is set to TK_RELIEF_NULL. |
| 660 | .TP |
| 661 | \fBTK_OPTION_STRING\fR |
| 662 | The value may be any string. The internal form is a (char *) pointer |
| 663 | that points to a dynamically allocated copy of the value. |
| 664 | This option type supports the TK_OPTION_NULL_OK flag. |
| 665 | .TP |
| 666 | \fBTK_OPTION_STRING_TABLE\fR |
| 667 | For this type, \fIclientData\fR is a pointer to an array of strings |
| 668 | suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must |
| 669 | be one of the strings in the table, or a unique abbreviation of |
| 670 | one of the strings. The internal form is an integer giving the index |
| 671 | into the table of the matching string, like the return value |
| 672 | from \fBTcl_GetStringFromObj\fR. |
| 673 | .TP |
| 674 | \fBTK_OPTION_SYNONYM\fR |
| 675 | This type is used to provide alternative names for an option (for |
| 676 | example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). |
| 677 | The \fBclientData\fR field is a (char *) pointer that gives |
| 678 | the name of another option in the same table. Whenever the |
| 679 | synonym option is used, the information from the other option |
| 680 | will be used instead. |
| 681 | .TP |
| 682 | \fBTK_OPTION_WINDOW\fR |
| 683 | The value must be a window path name. The internal form is a |
| 684 | \fBTk_Window\fR token for the window. |
| 685 | This option type requires \fItkwin\fR to be supplied to procedures |
| 686 | such as \fBTk_SetOptions\fR (in order to identify the application), |
| 687 | and it supports the TK_OPTION_NULL_OK flag. |
| 688 | |
| 689 | .SH "STORAGE MANAGEMENT ISSUES" |
| 690 | .PP |
| 691 | If a field of a widget record has its offset stored in the \fIobjOffset\fR |
| 692 | or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the |
| 693 | procedures described here will handle all of the storage allocation and |
| 694 | resource management issues associated with the field. When the value |
| 695 | of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR) |
| 696 | will automatically free any resources associated with the old value, such as |
| 697 | Tk_Fonts for TK_OPTION_FONT options or dynamically allocated memory for |
| 698 | TK_OPTION_STRING options. For an option stored as an object using the |
| 699 | \fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the |
| 700 | object pointed to by the \fIobjv\fR value from the call to |
| 701 | \fBTk_SetOptions\fR. The reference count for this object is incremented |
| 702 | when a pointer to it is stored in the widget record and decremented when |
| 703 | the option is modified. When the widget is deleted |
| 704 | \fBTk_FreeConfigOptions\fR should be invoked; it will free the resources |
| 705 | associated with all options and decrement reference counts for any |
| 706 | objects. |
| 707 | .PP |
| 708 | However, the widget code is responsible for storing NULL or \fBNone\fR in |
| 709 | all pointer and token fields before invoking \fBTk_InitOptions\fR. |
| 710 | This is needed to allow proper cleanup in the rare case where |
| 711 | an error occurs in \fBTk_InitOptions\fR. |
| 712 | |
| 713 | .SH "OBJOFFSET VS. INTERNALOFFSET" |
| 714 | .PP |
| 715 | In most cases it is simplest to use the \fIinternalOffset\fR field of |
| 716 | a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This |
| 717 | makes the internal form of the value immediately available to the |
| 718 | widget code so the value doesn't have to be extracted from an object |
| 719 | each time it is used. However, there are two cases where the |
| 720 | \fIobjOffset\fR field is useful. The first case is for |
| 721 | TK_OPTION_PIXELS options. In this case, the internal form is |
| 722 | an integer pixel value that is valid only for a particular screen. |
| 723 | If the value of the option is retrieved, it will be returned as a simple |
| 724 | number. For example, after the command \fB.b configure \-borderwidth 2m\fR, |
| 725 | the command \fB.b configure \-borderwidth\fR might return 7, which is the |
| 726 | integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses |
| 727 | the original screen-independent value. Thus for TK_OPTION_PIXELS options |
| 728 | it is better to use the \fIobjOffset\fR field. In this case the original |
| 729 | value of the option is retained in the object and can be returned when |
| 730 | the option is retrieved. In most cases it is convenient to use the |
| 731 | \fIinternalOffset\fR field field as well, so that the integer value is |
| 732 | immediately available for use in the widget code (alternatively, |
| 733 | \fBTk_GetPixelsFromObj\fR can be used to extract the integer value from |
| 734 | the object whenever it is needed). Note: the problem of losing information |
| 735 | on retrievals exists only for TK_OPTION_PIXELS options. |
| 736 | .PP |
| 737 | The second reason to use the \fIobjOffset\fR field is in order to |
| 738 | implement new types of options not supported by these procedures. |
| 739 | To implement a new type of option, you can use TK_OPTION_STRING as |
| 740 | the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field |
| 741 | but not the \fIinternalOffset\fR field. Then, after calling |
| 742 | \fBTk_SetOptions\fR, convert the object to internal form yourself. |
| 743 | |
| 744 | .SH "CUSTOM OPTION TYPES" |
| 745 | .PP |
| 746 | Applications can extend the built-in configuration types with |
| 747 | additional configuration types by writing procedures to parse, print, |
| 748 | free, and restore saved copies of the type and creating a structure |
| 749 | pointing to those procedures: |
| 750 | .CS |
| 751 | typedef struct Tk_ObjCustomOption { |
| 752 | char *name; |
| 753 | Tk_CustomOptionSetProc *\fIsetProc\fR; |
| 754 | Tk_CustomOptionGetProc *\fIgetProc\fR; |
| 755 | Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; |
| 756 | Tk_CustomOptionFreeProc *\fIfreeProc\fR; |
| 757 | ClientData \fIclientData\fR; |
| 758 | } Tk_ObjCustomOption; |
| 759 | |
| 760 | typedef int Tk_CustomOptionSetProc( |
| 761 | ClientData \fIclientData\fR, |
| 762 | Tcl_Interp *\fIinterp\fR, |
| 763 | Tk_Window \fItkwin\fR, |
| 764 | Tcl_Obj **\fIvaluePtr\fR, |
| 765 | char *\fIrecordPtr\fR, |
| 766 | int \fIinternalOffset\fR, |
| 767 | char *\fIsaveInternalPtr\fR, |
| 768 | int \fIflags\fR); |
| 769 | |
| 770 | typedef Tcl_Obj *Tk_CustomOptionGetProc( |
| 771 | ClientData \fIclientData\fR, |
| 772 | Tk_Window \fItkwin\fR, |
| 773 | char *\fIrecordPtr\fR, |
| 774 | int \fIinternalOffset\fR); |
| 775 | |
| 776 | typedef void Tk_CustomOptionRestoreProc( |
| 777 | ClientData \fIclientData\fR, |
| 778 | Tk_Window \fItkwin\fR, |
| 779 | char *\fIinternalPtr\fR, |
| 780 | char *\fIsaveInternalPtr\fR); |
| 781 | |
| 782 | typedef void Tk_CustomOptionFreeProc( |
| 783 | ClientData \fIclientData\fR, |
| 784 | Tk_Window \fItkwin\fR, |
| 785 | char *\fIinternalPtr\fR); |
| 786 | .CE |
| 787 | .PP |
| 788 | The Tk_ObjCustomOption structure contains six fields: a name |
| 789 | for the custom option type; pointers to the four procedures; and a |
| 790 | \fIclientData\fR value to be passed to those procedures when they are |
| 791 | invoked. The \fIclientData\fR value typically points to a structure |
| 792 | containing information that is needed by the procedures when they are |
| 793 | parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR |
| 794 | may be NULL, indicating that no function should be called for those |
| 795 | operations. |
| 796 | .PP |
| 797 | The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to |
| 798 | convert a Tcl_Obj into an internal representation and store the |
| 799 | resulting value in the widget record. The arguments are: |
| 800 | .RS |
| 801 | .TP |
| 802 | \fIclientData\fR |
| 803 | A copy of the \fIclientData\fR field in the Tk_ObjCustomOption |
| 804 | structure. |
| 805 | .TP |
| 806 | \fIinterp\fR |
| 807 | A pointer to a Tcl interpreter, used for error reporting. |
| 808 | .TP |
| 809 | \fITkwin\fR |
| 810 | A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR |
| 811 | .TP |
| 812 | \fIvaluePtr\fR |
| 813 | A pointer to a reference to a Tcl_Obj describing the new value for the |
| 814 | option; it could have been specified explicitly in the call to |
| 815 | \fBTk_SetOptions\fR or it could come from the option database or a |
| 816 | default. If the objOffset for the option is non-negative (the option |
| 817 | value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj |
| 818 | pointer referenced by \fIvaluePtr\fR is the pointer that will be |
| 819 | stored at the objOffset for the option. \fISetProc\fR may modify the |
| 820 | value if necessary; for example, \fIsetProc\fR may change the value to |
| 821 | NULL to support the TK_OPTION_NULL_OK flag. |
| 822 | .TP |
| 823 | \fIrecordPtr\fR |
| 824 | A pointer to the start of the widget record to modify. |
| 825 | .TP |
| 826 | \fIinternalOffset\fR |
| 827 | Offset in bytes from the start of the widget record to the location |
| 828 | where the internal representation of the option value is to be placed. |
| 829 | .TP |
| 830 | \fIsaveInternalPtr\fR |
| 831 | A pointer to storage allocated in a Tk_SavedOptions structure for the |
| 832 | internal representation of the original option value. Before setting |
| 833 | the option to its new value, \fIsetProc\fR should set the value |
| 834 | referenced by \fIsaveInternalPtr\fR to the original value of the |
| 835 | option in order to support \fBTk_RestoreSavedOptions\fR. |
| 836 | .TP |
| 837 | \fIflags\fR |
| 838 | A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the |
| 839 | option |
| 840 | .RE |
| 841 | .PP |
| 842 | \fISetProc\fR returns a standard Tcl result: TCL_OK to indicate successful |
| 843 | processing, or TCL_ERROR to indicate a failure of any kind. An error |
| 844 | message may be left in the Tcl interpreter given by \fIinterp\fR in |
| 845 | the case of an error. |
| 846 | .PP |
| 847 | The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and |
| 848 | \fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the |
| 849 | internal representation of an option. The \fIclientData\fR argument |
| 850 | is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption |
| 851 | structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to |
| 852 | \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR |
| 853 | is a pointer to the beginning of the widget record to query. |
| 854 | \fIInternalOffset\fR is the offset in bytes from the beginning of the |
| 855 | widget record to the location where the internal representation of the |
| 856 | option value is stored. \fIGetProc\fR must return a pointer to a |
| 857 | Tcl_Obj representing the value of the option. |
| 858 | .PP |
| 859 | The \fIrestoreProc\fR procedure is invoked by |
| 860 | \fBTk_RestoreSavedOptions\fR to restore a previously saved internal |
| 861 | representation of a custom option value. The \fIclientData\fR argument |
| 862 | is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption |
| 863 | structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to |
| 864 | \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR |
| 865 | is a pointer to the location where internal representation of the |
| 866 | option value is stored. |
| 867 | \fISaveInternalPtr\fR is a pointer to the saved value. |
| 868 | \fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to |
| 869 | \fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not |
| 870 | free any memory associated with either \fIinternalPtr\fR or |
| 871 | \fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that |
| 872 | memory if necessary. \fIRestoreProc\fR has no return value. |
| 873 | .PP |
| 874 | The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and |
| 875 | \fBTk_FreeSavedOptions\fR to free any storage allocated for the |
| 876 | internal representation of a custom option. The \fIclientData\fR argument |
| 877 | is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption |
| 878 | structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to |
| 879 | \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR |
| 880 | is a pointer to the location where the internal representation of the |
| 881 | option value is stored. The \fIfreeProc\fR must free any storage |
| 882 | associated with the option. \fIFreeProc\fR has no return value. |
| 883 | |
| 884 | |
| 885 | .SH KEYWORDS |
| 886 | anchor, bitmap, boolean, border, color, configuration option, |
| 887 | cursor, double, font, integer, justify, |
| 888 | pixels, relief, screen distance, synonym |