2 '\" Copyright (c) 1998 Sun Microsystems, Inc.
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 Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
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 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.
59 .\" End of list of standard options for a Tk widget.
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.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
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.
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
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
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options
280 \fB#include <tk.h>\fR
283 \fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR
285 \fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR
288 \fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR
291 \fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR
293 \fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR
295 \fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR
298 \fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
301 \fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR
303 \fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR
306 \fBTk_Offset(\fItype, field\fB)\fR
308 .AS Tk_SavedOptions "*const objv[]" in/out
309 .AP Tcl_Interp *interp in
310 A Tcl interpreter. Most procedures use this only for returning error
311 messages; if it is NULL then no error messages are returned. For
312 \fBTk_CreateOptionTable\fR the value cannot be NULL; it gives the
313 interpreter in which the option table will be used.
314 .AP "const Tk_OptionSpec" *templatePtr in
315 Points to an array of static information that describes the configuration
316 options that are supported. Used to build a Tk_OptionTable. The information
317 pointed to by this argument must exist for the lifetime of the Tk_OptionTable.
318 .AP Tk_OptionTable optionTable in
319 Token for an option table. Must have been returned by a previous call
320 to \fBTk_CreateOptionTable\fR.
321 .AP char *recordPtr in/out
322 Points to structure in which values of configuration options are stored;
323 fields of this record are modified by procedures such as \fBTk_SetOptions\fR
324 and read by procedures such as \fBTk_GetOptionValue\fR.
325 .AP Tk_Window tkwin in
326 For options such as \fBTK_OPTION_COLOR\fR, this argument indicates
327 the window in which the option will be used. If \fIoptionTable\fR uses
328 no window-dependent options, then a NULL value may be supplied for
331 Number of values in \fIobjv\fR.
332 .AP Tcl_Obj "*const objv[]" in
333 Command-line arguments for setting configuring options.
334 .AP Tk_SavedOptions *savePtr out
335 If not NULL, the structure pointed to by this argument is filled
336 in with the old values of any options that were modified and old
337 values are restored automatically if an error occurs in \fBTk_SetOptions\fR.
339 If not NULL, the word pointed to by \fImaskPtr\fR is filled in with the
340 bit-wise OR of the \fItypeMask\fR fields for the options that
342 .AP Tk_SavedOptions *savedPtr in/out
343 Points to a structure previously filled in by \fBTk_SetOptions\fR with
344 old values of modified options.
345 .AP Tcl_Obj *namePtr in
346 The value of this object is the name of a particular option. If NULL
347 is passed to \fBTk_GetOptionInfo\fR then information is returned for
348 all options. Must not be NULL when \fBTk_GetOptionValue\fR is called.
349 .AP "type name" type in
350 The name of the type of a record.
351 .AP "field name" field in
352 The name of a field in records of type \fItype\fR.
356 These procedures handle most of the details of parsing configuration
357 options such as those for Tk widgets. Given a description of what
358 options are supported, these procedures handle all the details of
359 parsing options and storing their values into a C structure associated
360 with the widget or object. The procedures were designed primarily for
361 widgets in Tk, but they can also be used for other kinds of objects that
362 have configuration options. In the rest of this manual page
364 will be used to refer to the object whose options are being managed; in
365 practice the object may not actually be a widget. The term
367 is used to refer to the C-level structure in
368 which information about a particular widget or object is stored.
370 Note: the easiest way to learn how to use these procedures is to
371 look at a working example. In Tk, the simplest example is the code
372 that implements the button family of widgets, which is in \fBtkButton.c\fR.
373 Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR.
375 In order to use these procedures, the code that implements the widget
376 must contain a static array of Tk_OptionSpec structures. This is a
377 template that describes the various options supported by that class of
378 widget; there is a separate template for each kind of widget. The
379 template contains information such as the name of each option, its type,
380 its default value, and where the value of the option is stored in the
381 widget record. See TEMPLATES below for more detail.
383 In order to process configuration options efficiently, the static
384 template must be augmented with additional information that is available
385 only at runtime. The procedure \fBTk_CreateOptionTable\fR creates this
386 dynamic information from the template and returns a Tk_OptionTable token
387 that describes both the static and dynamic information. All of the
388 other procedures, such as \fBTk_SetOptions\fR, take a Tk_OptionTable
389 token as argument. Typically, \fBTk_CreateOptionTable\fR is called the
390 first time that a widget of a particular class is created and the
391 resulting Tk_OptionTable is used in the future for all widgets of that
392 class. A Tk_OptionTable may be used only in a single interpreter, given
393 by the \fIinterp\fR argument to \fBTk_CreateOptionTable\fR. When an
394 option table is no longer needed \fBTk_DeleteOptionTable\fR should be
395 called to free all of its resources. All of the option tables
396 for a Tcl interpreter are freed automatically if the interpreter is deleted.
398 \fBTk_InitOptions\fR is invoked when a new widget is created to set
399 the default values for all of the widget's configuration options.
400 \fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR)
401 and a pointer to a widget record (\fIrecordPtr\fR), which is the C
402 structure that holds information about this widget. \fBTk_InitOptions\fR
403 uses the information in the option table to
404 choose an appropriate default for each option, then it stores the default
405 value directly into the widget record, overwriting any information that
406 was already present in the widget record. \fBTk_InitOptions\fR normally
407 returns \fBTCL_OK\fR. If an error occurred while setting the default values
408 (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR is returned
409 and an error message is left in \fIinterp\fR's result if \fIinterp\fR
412 \fBTk_SetOptions\fR is invoked to modify configuration options based
413 on information specified in a Tcl command. The command might be one that
414 creates a new widget, or a command that modifies options on an existing
415 widget. The \fIobjc\fR and \fIobjv\fR arguments describe the
416 values of the arguments from the Tcl command. \fIObjv\fR must contain
417 an even number of objects: the first object of each pair gives the name of
418 an option and the second object gives the new value for that option.
419 \fBTk_SetOptions\fR looks up each name in \fIoptionTable\fR, checks that
420 the new value of the option conforms to the type in \fIoptionTable\fR,
421 and stores the value of the option into the widget record given by
422 \fIrecordPtr\fR. \fBTk_SetOptions\fR normally returns \fBTCL_OK\fR. If
423 an error occurred (such as an unknown option name or an illegal option
424 value) then \fBTCL_ERROR\fR is returned and an error message is left in
425 \fIinterp\fR's result if \fIinterp\fR is not NULL.
427 \fBTk_SetOptions\fR has two additional features. First, if the
428 \fImaskPtr\fR argument is not NULL then it points to an integer
429 value that is filled in with information about the options that were
430 modified. For each option in the template passed to
431 \fBTk_CreateOptionTable\fR there is a \fItypeMask\fR field. The
432 bits of this field are defined by the code that implements the widget;
433 for example, each bit might correspond to a particular configuration option.
434 Alternatively, bits might be used functionally. For example, one bit might
435 be used for redisplay: all options that affect the widget's display, such
436 that changing the option requires the widget to be redisplayed, might have
437 that bit set. Another bit might indicate that the geometry of the widget
438 must be recomputed, and so on. \fBTk_SetOptions\fR OR's together the
439 \fItypeMask\fR fields from all the options that were modified and returns
440 this value at *\fImaskPtr\fR; the caller can then use this information
441 to optimize itself so that, for example, it does not redisplay the widget
442 if the modified options do not affect the widget's appearance.
444 The second additional feature of \fBTk_SetOptions\fR has to do with error
445 recovery. If an error occurs while processing configuration options, this
446 feature makes it possible to restore all the configuration options to their
447 previous values. Errors can occur either while processing options in
448 \fBTk_SetOptions\fR or later in the caller. In many cases the caller does
449 additional processing after \fBTk_SetOptions\fR returns; for example, it
450 might use an option value to set a trace on a variable and may detect
451 an error if the variable is an array instead of a scalar. Error recovery
452 is enabled by passing in a non-NULL value for the \fIsavePtr\fR argument
453 to \fBTk_SetOptions\fR; this should be a pointer to an uninitialized
454 Tk_SavedOptions structure on the caller's stack. \fBTk_SetOptions\fR
455 overwrites the structure pointed to by \fIsavePtr\fR with information
456 about the old values of any options modified by the procedure.
457 If \fBTk_SetOptions\fR returns successfully, the
458 caller uses the structure in one of two ways. If the caller completes
459 its processing of the new options without any errors, then it must pass
460 the structure to \fBTk_FreeSavedOptions\fR so that the old values can be
461 freed. If the caller detects an error in its processing of the new
462 options, then it should pass the structure to \fBTk_RestoreSavedOptions\fR,
463 which will copy the old values back into the widget record and free
465 If \fBTk_SetOptions\fR detects an error then it automatically restores
466 any options that had already been modified and leaves *\fIsavePtr\fR in
467 an empty state: the caller need not call either \fBTk_FreeSavedOptions\fR or
468 \fBTk_RestoreSavedOptions\fR.
469 If the \fIsavePtr\fR argument to \fBTk_SetOptions\fR is NULL then
470 \fBTk_SetOptions\fR frees each old option value immediately when it sets a new
471 value for the option. In this case, if an error occurs in the third
472 option, the old values for the first two options cannot be restored.
474 \fBTk_GetOptionValue\fR returns the current value of a configuration option
475 for a particular widget. The \fInamePtr\fR argument contains the name of
476 an option; \fBTk_GetOptionValue\fR uses \fIoptionTable\fR
477 to lookup the option and extract its value from the widget record
478 pointed to by \fIrecordPtr\fR, then it returns an object containing
479 that value. If an error occurs (e.g., because \fInamePtr\fR contains an
480 unknown option name) then NULL is returned and an error message is left
481 in \fIinterp\fR's result unless \fIinterp\fR is NULL.
483 \fBTk_GetOptionInfo\fR returns information about configuration options in
484 a form suitable for \fBconfigure\fR widget commands. If the \fInamePtr\fR
485 argument is not NULL, it points to an object that gives the name of a
486 configuration option; \fBTk_GetOptionInfo\fR returns an object containing
487 a list with five elements, which are the name of the option, the name and
488 class used for the option in the option database, the default value for
489 the option, and the current value for the option. If the \fInamePtr\fR
490 argument is NULL, then \fBTk_GetOptionInfo\fR returns information about
491 all options in the form of a list of lists; each sublist describes one
492 option. Synonym options are handled differently depending on whether
493 \fInamePtr\fR is NULL: if \fInamePtr\fR is NULL then the sublist for
494 each synonym option has only two elements, which are the name of the
495 option and the name of the other option that it refers to; if \fInamePtr\fR
496 is non-NULL and names a synonym option then the object returned
497 is the five-element list
498 for the other option that the synonym refers to. If an error occurs
499 (e.g., because \fInamePtr\fR contains an unknown option name) then NULL
500 is returned and an error message is left in \fIinterp\fR's result unless
501 \fIinterp\fR is NULL.
503 \fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted.
504 It frees all of the resources associated with any of the configuration
505 options defined in \fIrecordPtr\fR by \fIoptionTable\fR.
507 The \fBTk_Offset\fR macro is provided as a safe way of generating the
508 \fIobjOffset\fR and \fIinternalOffset\fR values for entries in
509 Tk_OptionSpec structures. It takes two arguments: the name of a type
510 of record, and the name of a field in that record. It returns the byte
511 offset of the named field in records of the given type.
514 The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR
515 via its \fItemplatePtr\fR argument describes the configuration options
516 supported by a particular class of widgets. Each structure specifies
517 one configuration option and has the following fields:
520 Tk_OptionType \fItype\fR;
521 const char *\fIoptionName\fR;
522 const char *\fIdbName\fR;
523 const char *\fIdbClass\fR;
524 const char *\fIdefValue\fR;
526 int \fIinternalOffset\fR;
528 const void *\fIclientData\fR;
530 } \fBTk_OptionSpec\fR;
532 The \fItype\fR field indicates what kind of configuration option this is
533 (e.g. \fBTK_OPTION_COLOR\fR for a color value, or \fBTK_OPTION_INT\fR for
534 an integer value). \fIType\fR determines how the
535 value of the option is parsed (more on this below).
536 The \fIoptionName\fR field is a string such as \fB\-font\fR or \fB\-bg\fR;
537 it is the name used for the option in Tcl commands and passed to
538 procedures via the \fIobjc\fR or \fInamePtr\fR arguments.
539 The \fIdbName\fR and \fIdbClass\fR fields are used by \fBTk_InitOptions\fR
540 to look up a default value for this option in the option database; if
541 \fIdbName\fR is NULL then the option database is not used by
542 \fBTk_InitOptions\fR for this option. The \fIdefValue\fR field
543 specifies a default value for this configuration option if no
544 value is specified in the option database. The \fIobjOffset\fR and
545 \fIinternalOffset\fR fields indicate where to store the value of this
546 option in widget records (more on this below); values for the \fIobjOffset\fR
547 and \fIinternalOffset\fR fields should always be generated with the
548 \fBTk_Offset\fR macro.
549 The \fIflags\fR field contains additional information
550 to control the processing of this configuration option (see below
552 \fIClientData\fR provides additional type-specific data needed
553 by certain types. For instance, for \fBTK_OPTION_COLOR\fR types,
554 \fIclientData\fR is a string giving the default value to use on
555 monochrome displays. See the descriptions of the different types
557 The last field, \fItypeMask\fR, is used by \fBTk_SetOptions\fR to
558 return information about which options were modified; see the description
559 of \fBTk_SetOptions\fR above for details.
561 When \fBTk_InitOptions\fR and \fBTk_SetOptions\fR store the value of an
562 option into the widget record, they can do it in either of two ways.
563 If the \fIobjOffset\fR field of the Tk_OptionSpec is greater than
564 or equal to zero, then the value of the option is stored as a
565 (Tcl_Obj *) at the location in the widget record given by \fIobjOffset\fR.
566 If the \fIinternalOffset\fR field of the Tk_OptionSpec is
567 greater than or equal to zero, then the value of the option is stored
568 in a type-specific internal form at the location in the widget record
569 given by \fIinternalOffset\fR. For example, if the option's type is
570 \fBTK_OPTION_INT\fR then the internal form is an integer. If the
571 \fIobjOffset\fR or \fIinternalOffset\fR field is negative then the
572 value is not stored in that form. At least one of the offsets must be
573 greater than or equal to zero.
575 The \fIflags\fR field consists of one or more bits ORed together. At
576 present only a single flag is supported: \fBTK_OPTION_NULL_OK\fR. If
577 this bit is set for an option then an empty string will be accepted as
578 the value for the option and the resulting internal form will be a
579 NULL pointer, a zero value, or \fBNone\fR, depending on the type of
580 the option. If the flag is not set then empty strings will result
582 \fBTK_OPTION_NULL_OK\fR is typically used to allow a
583 feature to be turned off entirely, e.g. set a cursor value to
584 \fBNone\fR so that a window simply inherits its parent's cursor.
585 Not all option types support the \fBTK_OPTION_NULL_OK\fR
586 flag; for those that do, there is an explicit indication of that fact
587 in the descriptions below.
589 The \fItype\fR field of each Tk_OptionSpec structure determines
590 how to parse the value of that configuration option. The
591 legal value for \fItype\fR, and the corresponding actions, are
592 described below. If the type requires a \fItkwin\fR value to be
593 passed into procedures like \fBTk_SetOptions\fR, or if it uses
594 the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated
595 explicitly; if not mentioned, the type requires neither \fItkwin\fR
596 nor \fIclientData\fR.
598 \fBTK_OPTION_ANCHOR\fR
599 The value must be a standard anchor position such as \fBne\fR or
600 \fBcenter\fR. The internal form is a Tk_Anchor value like the ones
601 returned by \fBTk_GetAnchorFromObj\fR.
603 \fBTK_OPTION_BITMAP\fR
604 The value must be a standard Tk bitmap name. The internal form is a
605 Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR.
606 This option type requires \fItkwin\fR to be supplied to procedures
607 such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
609 \fBTK_OPTION_BOOLEAN\fR
610 The value must be a standard boolean value such as \fBtrue\fR or
611 \fBno\fR. The internal form is an integer with value 0 or 1.
613 \fBTK_OPTION_BORDER\fR
614 The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
615 The internal form is a Tk_3DBorder token like the ones returned
616 by \fBTk_Alloc3DBorderFromObj\fR.
617 This option type requires \fItkwin\fR to be supplied to procedures
618 such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
620 \fBTK_OPTION_COLOR\fR
621 The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR.
622 The internal form is an (XColor *) token like the ones returned by
623 \fBTk_AllocColorFromObj\fR.
624 This option type requires \fItkwin\fR to be supplied to procedures
625 such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
627 \fBTK_OPTION_CURSOR\fR
628 The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR.
629 The internal form is a Tk_Cursor token like the ones returned by
630 \fBTk_AllocCursorFromObj\fR.
631 This option type requires \fItkwin\fR to be supplied to procedures
632 such as \fBTk_SetOptions\fR, and when the option is set the cursor
633 for the window is changed by calling \fBXDefineCursor\fR. This
634 option type also supports the \fBTK_OPTION_NULL_OK\fR flag.
636 \fBTK_OPTION_CUSTOM\fR
637 This option allows applications to define new option types. The
638 clientData field of the entry points to a structure defining the new
639 option type. See the section \fBCUSTOM OPTION TYPES\fR below for details.
641 \fBTK_OPTION_DOUBLE\fR
642 The string value must be a floating-point number in
643 the format accepted by \fBstrtol\fR. The internal form is a C
644 \fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR
645 flag; if a NULL value is set, the internal representation is set to zero.
648 Marks the end of the template. There must be a Tk_OptionSpec structure
649 with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the
650 \fIclientData\fR field of this structure is not NULL, then it points to
651 an additional array of Tk_OptionSpec's, which is itself terminated by
652 another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily
653 deeply. This feature allows common options to be shared by several
657 The value must be a standard font name such as \fBTimes 16\fR.
658 The internal form is a Tk_Font handle like the ones returned by
659 \fBTk_AllocFontFromObj\fR.
660 This option type requires \fItkwin\fR to be supplied to procedures
661 such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag.
664 The string value must be an integer in the format accepted by
665 \fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to
666 specify octal or hexadecimal numbers, respectively). The internal
667 form is a C \fBint\fR value.
669 \fBTK_OPTION_JUSTIFY\fR
670 The value must be a standard justification value such as \fBleft\fR.
671 The internal form is a Tk_Justify like the values returned by
672 \fBTk_GetJustifyFromObj\fR.
674 \fBTK_OPTION_PIXELS\fR
675 The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR.
676 The internal form is an integer value giving a
677 distance in pixels, like the values returned by
678 \fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field is not
679 used then information about the original value of this option will be lost.
680 See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option
681 type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the
682 internal representation is set to zero.
684 \fBTK_OPTION_RELIEF\fR
685 The value must be standard relief such as \fBraised\fR.
686 The internal form is an integer relief value such as
687 \fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR
688 flag; if the empty string is specified as the value for the option,
689 the integer relief value is set to \fBTK_RELIEF_NULL\fR.
691 \fBTK_OPTION_STRING\fR
692 The value may be any string. The internal form is a (char *) pointer
693 that points to a dynamically allocated copy of the value.
694 This option type supports the \fBTK_OPTION_NULL_OK\fR flag.
696 \fBTK_OPTION_STRING_TABLE\fR
697 For this type, \fIclientData\fR is a pointer to an array of strings
698 suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must
699 be one of the strings in the table, or a unique abbreviation of
700 one of the strings. The internal form is an integer giving the index
701 into the table of the matching string, like the return value
702 from \fBTcl_GetStringFromObj\fR.
704 \fBTK_OPTION_SYNONYM\fR
705 This type is used to provide alternative names for an option (for
706 example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR).
707 The \fBclientData\fR field is a string that gives the name of another
708 option in the same table. Whenever the synonym option is used, the
709 information from the other option will be used instead.
711 \fBTK_OPTION_WINDOW\fR
712 The value must be a window path name. The internal form is a
713 \fBTk_Window\fR token for the window.
714 This option type requires \fItkwin\fR to be supplied to procedures
715 such as \fBTk_SetOptions\fR (in order to identify the application),
716 and it supports the \fBTK_OPTION_NULL_OK\fR flag.
717 .SH "STORAGE MANAGEMENT ISSUES"
719 If a field of a widget record has its offset stored in the \fIobjOffset\fR
720 or \fIinternalOffset\fR field of a Tk_OptionSpec structure then the
721 procedures described here will handle all of the storage allocation and
722 resource management issues associated with the field. When the value
723 of an option is changed, \fBTk_SetOptions\fR (or \fBTk_FreeSavedOptions\fR)
724 will automatically free any resources associated with the old value, such as
725 Tk_Fonts for \fBTK_OPTION_FONT\fR options or dynamically allocated memory for
726 \fBTK_OPTION_STRING\fR options. For an option stored as an object using the
727 \fIobjOffset\fR field of a Tk_OptionSpec, the widget record shares the
728 object pointed to by the \fIobjv\fR value from the call to
729 \fBTk_SetOptions\fR. The reference count for this object is incremented
730 when a pointer to it is stored in the widget record and decremented when
731 the option is modified. When the widget is deleted
732 \fBTk_FreeConfigOptions\fR should be invoked; it will free the resources
733 associated with all options and decrement reference counts for any
736 However, the widget code is responsible for storing NULL or \fBNone\fR in
737 all pointer and token fields before invoking \fBTk_InitOptions\fR.
738 This is needed to allow proper cleanup in the rare case where
739 an error occurs in \fBTk_InitOptions\fR.
740 .SH "OBJOFFSET VS. INTERNALOFFSET"
742 In most cases it is simplest to use the \fIinternalOffset\fR field of
743 a Tk_OptionSpec structure and not the \fIobjOffset\fR field. This
744 makes the internal form of the value immediately available to the
745 widget code so the value does not have to be extracted from an object
746 each time it is used. However, there are two cases where the
747 \fIobjOffset\fR field is useful. The first case is for
748 \fBTK_OPTION_PIXELS\fR options. In this case, the internal form is
749 an integer pixel value that is valid only for a particular screen.
750 If the value of the option is retrieved, it will be returned as a simple
751 number. For example, after the command \fB.b configure \-borderwidth 2m\fR,
752 the command \fB.b configure \-borderwidth\fR might return 7, which is the
753 integer pixel value corresponding to \fB2m\fR. Unfortunately, this loses
754 the original screen-independent value. Thus for \fBTK_OPTION_PIXELS\fR options
755 it is better to use the \fIobjOffset\fR field. In this case the original
756 value of the option is retained in the object and can be returned when
757 the option is retrieved. In most cases it is convenient to use the
758 \fIinternalOffset\fR field as well, so that the integer value is
759 immediately available for use in the widget code (alternatively,
760 \fBTk_GetPixelsFromObj\fR can be used to extract the integer value from
761 the object whenever it is needed). Note: the problem of losing information
762 on retrievals exists only for \fBTK_OPTION_PIXELS\fR options.
764 The second reason to use the \fIobjOffset\fR field is in order to
765 implement new types of options not supported by these procedures.
766 To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as
767 the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field
768 but not the \fIinternalOffset\fR field. Then, after calling
769 \fBTk_SetOptions\fR, convert the object to internal form yourself.
770 .SH "CUSTOM OPTION TYPES"
772 Applications can extend the built-in configuration types with
773 additional configuration types by writing procedures to parse, print,
774 free, and restore saved copies of the type and creating a structure
775 pointing to those procedures:
777 typedef struct Tk_ObjCustomOption {
779 Tk_CustomOptionSetProc *\fIsetProc\fR;
780 Tk_CustomOptionGetProc *\fIgetProc\fR;
781 Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
782 Tk_CustomOptionFreeProc *\fIfreeProc\fR;
783 ClientData \fIclientData\fR;
784 } \fBTk_ObjCustomOption\fR;
786 typedef int \fBTk_CustomOptionSetProc\fR(
787 ClientData \fIclientData\fR,
788 Tcl_Interp *\fIinterp\fR,
789 Tk_Window \fItkwin\fR,
790 Tcl_Obj **\fIvaluePtr\fR,
791 char *\fIrecordPtr\fR,
792 int \fIinternalOffset\fR,
793 char *\fIsaveInternalPtr\fR,
796 typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR(
797 ClientData \fIclientData\fR,
798 Tk_Window \fItkwin\fR,
799 char *\fIrecordPtr\fR,
800 int \fIinternalOffset\fR);
802 typedef void \fBTk_CustomOptionRestoreProc\fR(
803 ClientData \fIclientData\fR,
804 Tk_Window \fItkwin\fR,
805 char *\fIinternalPtr\fR,
806 char *\fIsaveInternalPtr\fR);
808 typedef void \fBTk_CustomOptionFreeProc\fR(
809 ClientData \fIclientData\fR,
810 Tk_Window \fItkwin\fR,
811 char *\fIinternalPtr\fR);
814 The Tk_ObjCustomOption structure contains six fields: a name
815 for the custom option type; pointers to the four procedures; and a
816 \fIclientData\fR value to be passed to those procedures when they are
817 invoked. The \fIclientData\fR value typically points to a structure
818 containing information that is needed by the procedures when they are
819 parsing and printing options. \fIRestoreProc\fR and \fIfreeProc\fR
820 may be NULL, indicating that no function should be called for those
823 The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to
824 convert a Tcl_Obj into an internal representation and store the
825 resulting value in the widget record. The arguments are:
829 A copy of the \fIclientData\fR field in the Tk_ObjCustomOption
833 A pointer to a Tcl interpreter, used for error reporting.
836 A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR
839 A pointer to a reference to a Tcl_Obj describing the new value for the
840 option; it could have been specified explicitly in the call to
841 \fBTk_SetOptions\fR or it could come from the option database or a
842 default. If the objOffset for the option is non-negative (the option
843 value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj
844 pointer referenced by \fIvaluePtr\fR is the pointer that will be
845 stored at the objOffset for the option. \fISetProc\fR may modify the
846 value if necessary; for example, \fIsetProc\fR may change the value to
847 NULL to support the \fBTK_OPTION_NULL_OK\fR flag.
850 A pointer to the start of the widget record to modify.
853 Offset in bytes from the start of the widget record to the location
854 where the internal representation of the option value is to be placed.
856 \fIsaveInternalPtr\fR
857 A pointer to storage allocated in a Tk_SavedOptions structure for the
858 internal representation of the original option value. Before setting
859 the option to its new value, \fIsetProc\fR should set the value
860 referenced by \fIsaveInternalPtr\fR to the original value of the
861 option in order to support \fBTk_RestoreSavedOptions\fR.
864 A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the
868 \fISetProc\fR returns a standard Tcl result: \fBTCL_OK\fR to indicate successful
869 processing, or \fBTCL_ERROR\fR to indicate a failure of any kind. An error
870 message may be left in the Tcl interpreter given by \fIinterp\fR in
871 the case of an error.
873 The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and
874 \fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the
875 internal representation of an option. The \fIclientData\fR argument
876 is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
877 structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
878 \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIRecordPtr\fR
879 is a pointer to the beginning of the widget record to query.
880 \fIInternalOffset\fR is the offset in bytes from the beginning of the
881 widget record to the location where the internal representation of the
882 option value is stored. \fIGetProc\fR must return a pointer to a
883 Tcl_Obj representing the value of the option.
885 The \fIrestoreProc\fR procedure is invoked by
886 \fBTk_RestoreSavedOptions\fR to restore a previously saved internal
887 representation of a custom option value. The \fIclientData\fR argument
888 is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
889 structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
890 \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
891 is a pointer to the location where internal representation of the
892 option value is stored.
893 \fISaveInternalPtr\fR is a pointer to the saved value.
894 \fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to
895 \fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not
896 free any memory associated with either \fIinternalPtr\fR or
897 \fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that
898 memory if necessary. \fIRestoreProc\fR has no return value.
900 The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and
901 \fBTk_FreeSavedOptions\fR to free any storage allocated for the
902 internal representation of a custom option. The \fIclientData\fR argument
903 is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
904 structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
905 \fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
906 is a pointer to the location where the internal representation of the
907 option value is stored. The \fIfreeProc\fR must free any storage
908 associated with the option. \fIFreeProc\fR has no return value.
910 anchor, bitmap, boolean, border, color, configuration option,
911 cursor, double, font, integer, justify,
912 pixels, relief, screen distance, synonym
OSDN Git Service
