2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
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)
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.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
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.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
281 \fB#include <tk.h>\fR
284 \fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
287 \fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
290 \fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
292 \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
294 .AS char *widgRec in/out
295 .AP Tcl_Interp *interp in
296 Interpreter to use for returning error messages.
297 .AP Tk_Window tkwin in
298 Window used to represent widget (needed to set up X resources).
299 .AP "const Tk_ConfigSpec" *specs in
300 Pointer to table specifying legal configuration options for this
303 Number of arguments in \fIargv\fR.
304 .AP "const char" **argv in
305 Command-line options for configuring widget.
306 .AP char *widgRec in/out
307 Points to widget record structure. Fields in this structure get
308 modified by \fBTk_ConfigureWidget\fR to hold configuration information.
310 If non-zero, then it specifies an OR-ed combination of flags that
311 control the processing of configuration information.
312 \fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be
313 ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to
314 selectively disable entries in \fIspecs\fR.
315 .AP "type name" type in
316 The name of the type of a widget record.
317 .AP "field name" field in
318 The name of a field in records of type \fItype\fR.
319 .AP "const char" *argvName in
320 The name used on Tcl command lines to refer to a particular option
321 (e.g. when creating a widget or invoking the \fBconfigure\fR widget
322 command). If non-NULL, then information is returned only for this
323 option. If NULL, then information is returned for all available
325 .AP Display *display in
326 Display containing widget whose record is being freed; needed in
327 order to free up resources.
331 Note: \fBTk_ConfigureWidget\fR should be replaced with the new
332 \fBTcl_Obj\fR based API \fBTk_SetOptions\fR. The old interface is
333 retained for backward compatibility.
335 \fBTk_ConfigureWidget\fR is called to configure various aspects of a
336 widget, such as colors, fonts, border width, etc.
337 It is intended as a convenience procedure to reduce the amount
338 of code that must be written in individual widget managers to
339 handle configuration information.
341 invoked when widgets are created, and again when the \fBconfigure\fR
342 command is invoked for a widget.
343 Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
344 can be used in other situations where \fIargc-argv\fR information
345 is to be used to fill in a record structure, such as configuring
346 graphical elements for a canvas widget or entries of a menu.
348 \fBTk_ConfigureWidget\fR processes
349 a table specifying the configuration options that are supported
350 (\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
351 \fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
352 It uses the option database and defaults specified in \fIspecs\fR
353 to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
354 \fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
355 case it does not modify \fIinterp\fR.
357 occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
358 leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
360 In the event of an error return, some of the fields of \fIwidgRec\fR
361 could already have been set, if configuration information for them
362 was successfully processed before the error occurred.
363 The other fields will be set to reasonable initial values so that
364 \fBTk_FreeOptions\fR can be called for cleanup.
366 The \fIspecs\fR array specifies the kinds of configuration options
367 expected by the widget. Each of its entries specifies one configuration
368 option and has the following structure:
372 const char *\fIargvName\fR;
373 const char *\fIdbName\fR;
374 const char *\fIdbClass\fR;
375 const char *\fIdefValue\fR;
378 const Tk_CustomOption *\fIcustomPtr\fR;
379 } \fBTk_ConfigSpec\fR;
381 The \fItype\fR field indicates what type of configuration option this is
382 (e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
383 an integer value). The \fItype\fR field indicates how to use the
384 value of the option (more on this below).
385 The \fIargvName\fR field is a string such as
389 which is compared with the values in \fIargv\fR (if \fIargvName\fR is
390 NULL it means this is a grouped entry; see \fBGROUPED ENTRIES\fR below). The
391 \fIdbName\fR and \fIdbClass\fR fields are used to look up a value
392 for this option in the option database. The \fIdefValue\fR field
393 specifies a default value for this configuration option if no
394 value is specified in either \fIargv\fR or the option database.
395 \fIOffset\fR indicates where in \fIwidgRec\fR to store information
396 about this option, and \fIspecFlags\fR contains additional information
397 to control the processing of this configuration option (see FLAGS
399 The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
400 \fBTK_CONFIG_CUSTOM\fR; see CUSTOM OPTION TYPES below.
402 \fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
403 (if any) configuration options are specified there. \fIArgv\fR
404 must contain an even number of fields; the first of each pair
405 of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
406 (unique abbreviations are acceptable),
407 and the second field of the pair contains the value for that
408 configuration option. If there are entries in \fIspec\fR for which
409 there were no matching entries in \fIargv\fR,
410 \fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
411 fields of the \fIspecs\fR entry to probe the option database; if
412 a value is found, then it is used as the value for the option.
413 Finally, if no entry is found in the option database, the
414 \fIdefValue\fR field of the \fIspecs\fR entry is used as the
415 value for the configuration option. If the \fIdefValue\fR is
416 NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
417 \fIflags\fR, then there is no default value and this \fIspecs\fR entry
418 will be ignored if no value is specified in \fIargv\fR or the
421 Once a string value has been determined for a configuration option,
422 \fBTk_ConfigureWidget\fR translates the string value into a more useful
423 form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
424 if \fItype\fR is \fBTK_CONFIG_INT\fR. This value is then stored in the
425 record pointed to by \fIwidgRec\fR. This record is assumed to
426 contain information relevant to the manager of the widget; its exact
427 type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field
428 of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store
429 the information about this configuration option. You should use the
430 \fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
431 a description of \fBTk_Offset\fR). The location indicated by
432 \fIwidgRec\fR and \fIoffset\fR will be referred to as the
434 in the descriptions below.
436 The \fItype\fR field of each entry in \fIspecs\fR determines what
437 to do with the string value of that configuration option. The
438 legal values for \fItype\fR, and the corresponding actions, are:
440 \fBTK_CONFIG_ACTIVE_CURSOR\fR
442 must be an ASCII string identifying a cursor in a form
443 suitable for passing to \fBTk_GetCursor\fR.
444 The value is converted to a \fBTk_Cursor\fR by calling
445 \fBTk_GetCursor\fR and the result is stored in the target.
446 In addition, the resulting cursor is made the active cursor
447 for \fItkwin\fR by calling \fBXDefineCursor\fR.
448 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
449 may be an empty string, in which case the target and \fItkwin\fR's
450 active cursor will be set to \fBNone\fR.
451 If the previous value of the target
452 was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
454 \fBTK_CONFIG_ANCHOR\fR
455 The value must be an ASCII string identifying an anchor point in one of the ways
456 accepted by \fBTk_GetAnchor\fR.
457 The string is converted to a \fBTk_Anchor\fR by calling
458 \fBTk_GetAnchor\fR and the result is stored in the target.
460 \fBTK_CONFIG_BITMAP\fR
461 The value must be an ASCII string identifying a bitmap in a form
462 suitable for passing to \fBTk_GetBitmap\fR. The value is converted
463 to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
464 is stored in the target.
465 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
466 may be an empty string, in which case the target is set to \fBNone\fR.
467 If the previous value of the target
468 was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
470 \fBTK_CONFIG_BOOLEAN\fR
471 The value must be an ASCII string specifying a boolean value. Any
478 or an abbreviation of one of these values, means true;
485 or an abbreviation of one of these values, means false.
486 The target is expected to be an integer; for true values it will
487 be set to 1 and for false values it will be set to 0.
489 \fBTK_CONFIG_BORDER\fR
490 The value must be an ASCII string identifying a border color in a form
491 suitable for passing to \fBTk_Get3DBorder\fR. The value is converted
492 to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
493 is stored in the target.
494 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
495 may be an empty string, in which case the target will be set to NULL.
496 If the previous value of the target
497 was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
499 \fBTK_CONFIG_CAP_STYLE\fR
501 an ASCII string identifying a cap style in one of the ways
502 accepted by \fBTk_GetCapStyle\fR.
503 The string is converted to an integer value corresponding
504 to the cap style by calling
505 \fBTk_GetCapStyle\fR and the result is stored in the target.
507 \fBTK_CONFIG_COLOR\fR
508 The value must be an ASCII string identifying a color in a form
509 suitable for passing to \fBTk_GetColor\fR. The value is converted
510 to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
511 is stored in the target.
512 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
513 may be an empty string, in which case the target will be set to \fBNone\fR.
514 If the previous value of the target
515 was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
517 \fBTK_CONFIG_CURSOR\fR
518 This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
519 that the new cursor is not made the active one for \fItkwin\fR.
521 \fBTK_CONFIG_CUSTOM\fR
522 This option allows applications to define new option types.
523 The \fIcustomPtr\fR field of the entry points to a structure
524 defining the new option type.
525 See the section \fBCUSTOM OPTION TYPES\fR below for details.
527 \fBTK_CONFIG_DOUBLE\fR
528 The value must be an ASCII floating-point number in
529 the format accepted by \fBstrtol\fR. The string is converted
530 to a \fBdouble\fR value, and the value is stored in the
534 Marks the end of the table. The last entry in \fIspecs\fR
535 must have this type; all of its other fields are ignored and it
536 will never match any arguments.
539 The value must be an ASCII string identifying a font in a form
540 suitable for passing to \fBTk_GetFont\fR. The value is converted
541 to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
542 is stored in the target.
543 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
544 may be an empty string, in which case the target will be set to NULL.
545 If the previous value of the target
546 was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
549 The value must be an ASCII integer string
550 in the format accepted by \fBstrtol\fR (e.g.
554 prefixes may be used to specify octal or hexadecimal
555 numbers, respectively). The string is converted to an integer
556 value and the integer is stored in the target.
558 \fBTK_CONFIG_JOIN_STYLE\fR
560 an ASCII string identifying a join style in one of the ways
561 accepted by \fBTk_GetJoinStyle\fR.
562 The string is converted to an integer value corresponding
563 to the join style by calling
564 \fBTk_GetJoinStyle\fR and the result is stored in the target.
566 \fBTK_CONFIG_JUSTIFY\fR
568 an ASCII string identifying a justification method in one of the
569 ways accepted by \fBTk_GetJustify\fR.
570 The string is converted to a \fBTk_Justify\fR by calling
571 \fBTk_GetJustify\fR and the result is stored in the target.
574 The value must specify a screen distance in one of the forms acceptable
575 to \fBTk_GetScreenMM\fR.
576 The string is converted to double-precision floating-point distance
577 in millimeters and the value is stored in the target.
579 \fBTK_CONFIG_PIXELS\fR
580 The value must specify screen units in one of the forms acceptable
581 to \fBTk_GetPixels\fR.
582 The string is converted to an integer distance in pixels and the
583 value is stored in the target.
585 \fBTK_CONFIG_RELIEF\fR
586 The value must be an ASCII string identifying a relief in a form
587 suitable for passing to \fBTk_GetRelief\fR. The value is converted
588 to an integer relief value by calling \fBTk_GetRelief\fR and the result
589 is stored in the target.
591 \fBTK_CONFIG_STRING\fR
593 of the value is made by allocating memory space with
594 \fBTcl_Alloc\fR and copying the value into the dynamically-allocated
595 space. A pointer to the new string is stored in the target.
596 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
597 may be an empty string, in which case the target will be set to NULL.
598 If the previous value of the target was not NULL, then it is
599 freed by passing it to \fBTcl_Free\fR.
601 \fBTK_CONFIG_SYNONYM\fR
602 This \fItype\fR value identifies special entries in \fIspecs\fR that
603 are synonyms for other entries. If an \fIargv\fR value matches the
604 \fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
605 directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
606 for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
607 field in the \fBTK_CONFIG_SYNONYM\fR entry; this new entry is used just
608 as if its \fIargvName\fR had matched the \fIargv\fR value. The
609 synonym mechanism allows multiple \fIargv\fR values to be used for
610 a single configuration option, such as
616 The value is translated to a \fBTk_Uid\fR
617 (by passing it to \fBTk_GetUid\fR). The resulting value
618 is stored in the target.
619 If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value
620 is an empty string then the target will be set to NULL.
622 \fBTK_CONFIG_WINDOW\fR
623 The value must be a window path name. It is translated to a
624 \fBTk_Window\fR token and the token is stored in the target.
625 .SH "GROUPED ENTRIES"
627 In some cases it is useful to generate multiple resources from
628 a single configuration value. For example, a color name might
629 be used both to generate the background color for a widget (using
630 \fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the
631 widget (using \fBTK_CONFIG_BORDER\fR). In cases like this it is possible
632 to specify that several consecutive entries in \fIspecs\fR are to
633 be treated as a group. The first entry is used to determine a value
634 (using its \fIargvName\fR, \fIdbName\fR,
635 \fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed
636 several times (one for each entry in the group), generating multiple
637 different resources and modifying multiple targets within \fIwidgRec\fR.
638 Each of the entries after the first must have a NULL value in its
639 \fIargvName\fR field; this indicates that the entry is to be grouped
640 with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR
641 fields are used from these follow-on entries.
644 The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
645 in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
646 to provide additional control over the processing of configuration
647 options. These values are used in three different ways as
650 First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
651 the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),
652 then the option database and
653 \fIdefValue\fR fields are not used. In this case, if an entry in
654 \fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
655 the corresponding target is not modified. This feature is useful
656 when the goal is to modify certain configuration options while
657 leaving others in their current state, such as when a \fBconfigure\fR
658 widget command is being processed.
660 Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
661 to control the processing of that entry. Each \fIspecFlags\fR
662 field may consists of an OR-ed combination of the following values:
664 \fBTK_CONFIG_COLOR_ONLY\fR
665 If this bit is set then the entry will only be considered if the
666 display for \fItkwin\fR has more than one bit plane. If the display
667 is monochromatic then this \fIspecs\fR entry will be ignored.
669 \fBTK_CONFIG_MONO_ONLY\fR
670 If this bit is set then the entry will only be considered if the
671 display for \fItkwin\fR has exactly one bit plane. If the display
672 is not monochromatic then this \fIspecs\fR entry will be ignored.
674 \fBTK_CONFIG_NULL_OK\fR
675 This bit is only relevant for some types of entries (see the
676 descriptions of the various entry types above).
677 If this bit is set, it indicates that an empty string value
678 for the field is acceptable and if it occurs then the
679 target should be set to NULL or \fBNone\fR, depending
680 on the type of the target.
681 This flag is typically used to allow a
682 feature to be turned off entirely, e.g. set a cursor value to
683 \fBNone\fR so that a window simply inherits its parent's cursor.
684 If this bit is not set then empty strings are processed as strings,
685 which generally results in an error.
687 \fBTK_CONFIG_DONT_SET_DEFAULT\fR
688 If this bit is one, it means that the \fIdefValue\fR field of the
689 entry should only be used for returning the default value in
690 \fBTk_ConfigureInfo\fR.
691 In calls to \fBTk_ConfigureWidget\fR no default will be supplied
692 for entries with this flag set; it is assumed that the
693 caller has already supplied a default value in the target location.
694 This flag provides a performance optimization where it is expensive
695 to process the default string: the client can compute the default
696 once, save the value, and provide it before calling
697 \fBTk_ConfigureWidget\fR.
699 \fBTK_CONFIG_OPTION_SPECIFIED\fR
701 deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
702 so that callers could detect what entries were specified in
703 \fIargv\fR, but it was removed because it was inherently
704 thread-unsafe. Code that wishes to detect what options were specified
705 should use \fBTk_SetOptions\fR instead.
707 The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
708 used to specify different default values for
709 monochrome and color displays. This is done by creating two
710 entries in \fIspecs\fR that are identical except for their
711 \fIdefValue\fR and \fIspecFlags\fR fields. One entry should have
712 the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the
713 default value for monochrome displays in its \fIdefValue\fR; the
714 other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in
715 its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
718 Third, it is possible to use \fIflags\fR and \fIspecFlags\fR
719 together to selectively disable some entries. This feature is
720 not needed very often. It is useful in cases where several
721 similar kinds of widgets are implemented in one place. It allows
722 a single \fIspecs\fR table to be created with all the configuration
723 options for all the widget types. When processing a particular
724 widget type, only entries relevant to that type will be used. This
725 effect is achieved by setting the high-order bits (those in positions
726 equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR
727 values or in \fIflags\fR. In order for a particular entry in
728 \fIspecs\fR to be used, its high-order bits must match exactly
729 the high-order bits of the \fIflags\fR value passed to
730 \fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used
731 for N different widget types, then N of the high-order bits will
732 be used. Each \fIspecs\fR entry will have one of more of those
733 bits set in its \fIspecFlags\fR field to indicate the widget types
734 for which this entry is valid. When calling \fBTk_ConfigureWidget\fR,
735 \fIflags\fR will have a single one of these bits set to select the
736 entries for the desired widget type. For a working example of
737 this feature, see the code in tkButton.c.
740 The \fBTk_Offset\fR macro is provided as a safe way of generating
741 the \fIoffset\fR values for entries in Tk_ConfigSpec structures.
742 It takes two arguments: the name of a type of record, and the
743 name of a field in that record. It returns the byte offset of
744 the named field in records of the given type.
747 The \fBTk_ConfigureInfo\fR procedure may be used to obtain
748 information about one or all of the options for a given widget.
749 Given a token for a window (\fItkwin\fR), a table describing the
750 configuration options for a class of widgets (\fIspecs\fR), a
751 pointer to a widget record containing the current information for
752 a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
753 \fBTk_ConfigureInfo\fR generates a string describing all of the
754 configuration options for the window. The string is placed
755 in interpreter \fIinterp\fR's result. Under normal circumstances
756 it returns \fBTCL_OK\fR; if an error occurs then it returns \fBTCL_ERROR\fR
757 and the interpreter's result will contain an error message.
759 If \fIargvName\fR is NULL, then the value left in
760 the interpreter's result by \fBTk_ConfigureInfo\fR
761 consists of a list of one or more entries, each of which describes
762 one configuration option (i.e. one entry in \fIspecs\fR). Each
763 entry in the list will contain either two or five values. If the
764 corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then
765 the list will contain two values: the \fIargvName\fR for the entry
766 and the \fIdbName\fR (synonym name). Otherwise the list will contain
767 five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
768 and current value. The current value is computed from the appropriate
769 field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR.
771 If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
772 then it indicates a single option, and information is returned only
773 for that option. The string placed in the interpreter's result will be
774 a list containing two or five values as described above; this will
775 be identical to the corresponding sublist that would have been returned
776 if \fIargvName\fR had been NULL.
778 The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
779 the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
780 .SH TK_CONFIGUREVALUE
782 \fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR;
783 instead of returning a list of values, it just returns the current value
784 of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL).
785 The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is
786 normally returned as the procedure's result.
787 If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is
788 not a valid option name), \fBTCL_ERROR\fR is returned and an error message
789 is left in the interpreter's result.
790 This procedure is typically called to implement \fBcget\fR widget
794 The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
795 to release all of the resources associated with configuration options.
796 It scans through \fIspecs\fR and for each entry corresponding to a
797 resource that must be explicitly freed (e.g. those with
798 type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record.
799 If the field in the widget record does not refer to a resource (e.g.
800 it contains a null pointer) then no resource is freed for that
802 After freeing a resource, \fBTk_FreeOptions\fR sets the
803 corresponding field of the widget record to null.
804 .SH "CUSTOM OPTION TYPES"
806 Applications can extend the built-in configuration types with additional
807 configuration types by writing procedures to parse and print options
808 of the a type and creating a structure pointing to those procedures:
810 typedef struct Tk_CustomOption {
811 Tk_OptionParseProc *\fIparseProc\fR;
812 Tk_OptionPrintProc *\fIprintProc\fR;
813 ClientData \fIclientData\fR;
814 } \fBTk_CustomOption\fR;
816 typedef int \fBTk_OptionParseProc\fR(
817 ClientData \fIclientData\fR,
818 Tcl_Interp *\fIinterp\fR,
819 Tk_Window \fItkwin\fR,
824 typedef const char *\fBTk_OptionPrintProc\fR(
825 ClientData \fIclientData\fR,
826 Tk_Window \fItkwin\fR,
829 Tcl_FreeProc **\fIfreeProcPtr\fR);
831 The Tk_CustomOption structure contains three fields, which are pointers
832 to the two procedures and a \fIclientData\fR value to be passed to those
833 procedures when they are invoked. The \fIclientData\fR value typically
834 points to a structure containing information that is needed by the
835 procedures when they are parsing and printing options.
837 The \fIparseProc\fR procedure is invoked by
838 \fBTk_ConfigureWidget\fR to parse a string and store the resulting
839 value in the widget record.
840 The \fIclientData\fR argument is a copy of the \fIclientData\fR
841 field in the Tk_CustomOption structure.
842 The \fIinterp\fR argument points to a Tcl interpreter used for
843 error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument
844 to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string
845 describing the value for the option; it could have been specified
846 explicitly in the call to \fBTk_ConfigureWidget\fR or it could
847 come from the option database or a default.
848 \fIValue\fR will never be a null pointer but it may point to
850 \fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to
851 \fBTk_ConfigureWidget\fR; it points to the start of the widget
853 The last argument, \fIoffset\fR, gives the offset in bytes from the start
854 of the widget record to the location where the option value is to
855 be placed. The procedure should translate the string to whatever
856 form is appropriate for the option and store the value in the widget
857 record. It should normally return \fBTCL_OK\fR, but if an error occurs
858 in translating the string to a value then it should return \fBTCL_ERROR\fR
859 and store an error message in interpreter \fIinterp\fR's result.
861 The \fIprintProc\fR procedure is called
862 by \fBTk_ConfigureInfo\fR to produce a string value describing an
864 Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR
865 arguments all have the same meaning as for Tk_OptionParseProc
867 The \fIprintProc\fR procedure should examine the option whose value
868 is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing
869 that option, and return a pointer to the string.
870 If the string is stored in dynamically-allocated memory, then
871 the procedure must set \fI*freeProcPtr\fR to the address of
872 a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR
873 will call this procedure when it is finished with the string.
874 If the result string is stored in static memory then \fIprintProc\fR
875 need not do anything with the \fIfreeProcPtr\fR argument.
877 Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
878 Tk_CustomOption structure has been created for them, options of this
879 new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
880 fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point
881 to the Tk_CustomOption structure.
884 Although the explanation of \fBTk_ConfigureWidget\fR is fairly
885 complicated, its actual use is pretty straightforward.
886 The easiest way to get started is to copy the code
887 from an existing widget.
888 The library implementation of frames
889 (tkFrame.c) has a simple configuration table, and the library
890 implementation of buttons (tkButton.c) has a much more complex
891 table that uses many of the fancy \fIspecFlags\fR mechanisms.
895 anchor, bitmap, boolean, border, cap style, color, configuration options,
896 cursor, custom, double, font, integer, join style, justify, millimeters,
897 pixels, relief, synonym, uid
OSDN Git Service
