| '\" |
| '\" Copyright (c) 1990-1994 The Regents of the University of California. |
| '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
| '\" |
| '\" See the file "license.terms" for information on usage and redistribution |
| '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
| '\" |
| '\" RCS: @(#) $Id: ConfigWidg.3,v 1.8 2002/08/05 04:30:38 dgp Exp $ |
| '\" |
| '\" The definitions below are for supplemental macros used in Tcl/Tk |
| '\" manual entries. |
| '\" |
| '\" .AP type name in/out ?indent? |
| '\" Start paragraph describing an argument to a library procedure. |
| '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| '\" or "in/out" to describe whether procedure reads or modifies arg, |
| '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| '\" needed; use .AS below instead) |
| '\" |
| '\" .AS ?type? ?name? |
| '\" Give maximum sizes of arguments for setting tab stops. Type and |
| '\" name are examples of largest possible arguments that will be passed |
| '\" to .AP later. If args are omitted, default tab stops are used. |
| '\" |
| '\" .BS |
| '\" Start box enclosure. From here until next .BE, everything will be |
| '\" enclosed in one large box. |
| '\" |
| '\" .BE |
| '\" End of box enclosure. |
| '\" |
| '\" .CS |
| '\" Begin code excerpt. |
| '\" |
| '\" .CE |
| '\" End code excerpt. |
| '\" |
| '\" .VS ?version? ?br? |
| '\" Begin vertical sidebar, for use in marking newly-changed parts |
| '\" of man pages. The first argument is ignored and used for recording |
| '\" the version when the .VS was added, so that the sidebars can be |
| '\" found and removed when they reach a certain age. If another argument |
| '\" is present, then a line break is forced before starting the sidebar. |
| '\" |
| '\" .VE |
| '\" End of vertical sidebar. |
| '\" |
| '\" .DS |
| '\" Begin an indented unfilled display. |
| '\" |
| '\" .DE |
| '\" End of indented unfilled display. |
| '\" |
| '\" .SO |
| '\" Start of list of standard options for a Tk widget. The |
| '\" options follow on successive lines, in four columns separated |
| '\" by tabs. |
| '\" |
| '\" .SE |
| '\" End of list of standard options for a Tk widget. |
| '\" |
| '\" .OP cmdName dbName dbClass |
| '\" Start of description of a specific option. cmdName gives the |
| '\" option's name as specified in the class command, dbName gives |
| '\" the option's name in the option database, and dbClass gives |
| '\" the option's class in the option database. |
| '\" |
| '\" .UL arg1 arg2 |
| '\" Print arg1 underlined, then print arg2 normally. |
| '\" |
| '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| '\" |
| '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| .if t .wh -1.3i ^B |
| .nr ^l \n(.l |
| .ad b |
| '\" # Start an argument description |
| .de AP |
| .ie !"\\$4"" .TP \\$4 |
| .el \{\ |
| . ie !"\\$2"" .TP \\n()Cu |
| . el .TP 15 |
| .\} |
| .ta \\n()Au \\n()Bu |
| .ie !"\\$3"" \{\ |
| \&\\$1 \\fI\\$2\\fP (\\$3) |
| .\".b |
| .\} |
| .el \{\ |
| .br |
| .ie !"\\$2"" \{\ |
| \&\\$1 \\fI\\$2\\fP |
| .\} |
| .el \{\ |
| \&\\fI\\$1\\fP |
| .\} |
| .\} |
| .. |
| '\" # define tabbing values for .AP |
| .de AS |
| .nr )A 10n |
| .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| .nr )B \\n()Au+15n |
| .\" |
| .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| .. |
| .AS Tcl_Interp Tcl_CreateInterp in/out |
| '\" # BS - start boxed text |
| '\" # ^y = starting y location |
| '\" # ^b = 1 |
| .de BS |
| .br |
| .mk ^y |
| .nr ^b 1u |
| .if n .nf |
| .if n .ti 0 |
| .if n \l'\\n(.lu\(ul' |
| .if n .fi |
| .. |
| '\" # BE - end boxed text (draw box now) |
| .de BE |
| .nf |
| .ti 0 |
| .mk ^t |
| .ie n \l'\\n(^lu\(ul' |
| .el \{\ |
| .\" Draw four-sided box normally, but don't draw top of |
| .\" box if the box started on an earlier page. |
| .ie !\\n(^b-1 \{\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .el \}\ |
| \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| .\} |
| .\} |
| .fi |
| .br |
| .nr ^b 0 |
| .. |
| '\" # VS - start vertical sidebar |
| '\" # ^Y = starting y location |
| '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| .de VS |
| .if !"\\$2"" .br |
| .mk ^Y |
| .ie n 'mc \s12\(br\s0 |
| .el .nr ^v 1u |
| .. |
| '\" # VE - end of vertical sidebar |
| .de VE |
| .ie n 'mc |
| .el \{\ |
| .ev 2 |
| .nf |
| .ti 0 |
| .mk ^t |
| \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| .sp -1 |
| .fi |
| .ev |
| .\} |
| .nr ^v 0 |
| .. |
| '\" # Special macro to handle page bottom: finish off current |
| '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| '\" # page bottom macro. |
| .de ^B |
| .ev 2 |
| 'ti 0 |
| 'nf |
| .mk ^t |
| .if \\n(^b \{\ |
| .\" Draw three-sided box if this is the box's first page, |
| .\" draw two sides but no top otherwise. |
| .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 |
| .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| .\} |
| .if \\n(^v \{\ |
| .nr ^x \\n(^tu+1v-\\n(^Yu |
| \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| .\} |
| .bp |
| 'fi |
| .ev |
| .if \\n(^b \{\ |
| .mk ^y |
| .nr ^b 2 |
| .\} |
| .if \\n(^v \{\ |
| .mk ^Y |
| .\} |
| .. |
| '\" # DS - begin display |
| .de DS |
| .RS |
| .nf |
| .sp |
| .. |
| '\" # DE - end display |
| .de DE |
| .fi |
| .RE |
| .sp |
| .. |
| '\" # SO - start of list of standard options |
| .de SO |
| .SH "STANDARD OPTIONS" |
| .LP |
| .nf |
| .ta 5.5c 11c |
| .ft B |
| .. |
| '\" # SE - end of list of standard options |
| .de SE |
| .fi |
| .ft R |
| .LP |
| See the \\fBoptions\\fR manual entry for details on the standard options. |
| .. |
| '\" # OP - start of full description for a single option |
| .de OP |
| .LP |
| .nf |
| .ta 4c |
| Command-Line Name: \\fB\\$1\\fR |
| Database Name: \\fB\\$2\\fR |
| Database Class: \\fB\\$3\\fR |
| .fi |
| .IP |
| .. |
| '\" # CS - begin code excerpt |
| .de CS |
| .RS |
| .nf |
| .ta .25i .5i .75i 1i |
| .. |
| '\" # CE - end code excerpt |
| .de CE |
| .fi |
| .RE |
| .. |
| .de UL |
| \\$1\l'|0\(ul'\\$2 |
| .. |
| .TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures" |
| .BS |
| .SH NAME |
| Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets |
| .SH SYNOPSIS |
| .nf |
| \fB#include <tk.h>\fR |
| .sp |
| int |
| \fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR |
| .sp |
| int |
| \fBTk_Offset(\fItype, field\fB)\fR |
| .sp |
| int |
| \fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR |
| .sp |
| int |
| \fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR |
| .sp |
| \fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR |
| .SH ARGUMENTS |
| .AS Tk_ConfigSpec *widgRec in/out |
| .AP Tcl_Interp *interp in |
| Interpreter to use for returning error messages. |
| .AP Tk_Window tkwin in |
| Window used to represent widget (needed to set up X resources). |
| .AP Tk_ConfigSpec *specs in |
| Pointer to table specifying legal configuration options for this |
| widget. |
| .AP int argc in |
| Number of arguments in \fIargv\fR. |
| .AP "CONST char" **argv in |
| Command-line options for configuring widget. |
| .AP char *widgRec in/out |
| Points to widget record structure. Fields in this structure get |
| modified by \fBTk_ConfigureWidget\fR to hold configuration information. |
| .AP int flags in |
| If non-zero, then it specifies an OR-ed combination of flags that |
| control the processing of configuration information. |
| TK_CONFIG_ARGV_ONLY causes the option database and defaults to be |
| ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to |
| selectively disable entries in \fIspecs\fR. |
| .AP "type name" type in |
| The name of the type of a widget record. |
| .AP "field name" field in |
| The name of a field in records of type \fItype\fR. |
| .AP "CONST char" *argvName in |
| The name used on Tcl command lines to refer to a particular option |
| (e.g. when creating a widget or invoking the \fBconfigure\fR widget |
| command). If non-NULL, then information is returned only for this |
| option. If NULL, then information is returned for all available |
| options. |
| .AP Display *display in |
| Display containing widget whose record is being freed; needed in |
| order to free up resources. |
| .BE |
| .SH DESCRIPTION |
| .VS 8.1 |
| .PP |
| Note: \fBTk_ConfigureWidget\fP should be replaced with the new |
| \fBTcl_Obj\fP based API \fBTk_SetOptions\fP. The old interface is |
| retained for backward compatibility. |
| .VE |
| .PP |
| \fBTk_ConfigureWidget\fR is called to configure various aspects of a |
| widget, such as colors, fonts, border width, etc. |
| It is intended as a convenience procedure to reduce the amount |
| of code that must be written in individual widget managers to |
| handle configuration information. |
| It is typically |
| invoked when widgets are created, and again when the \fBconfigure\fR |
| command is invoked for a widget. |
| Although intended primarily for widgets, \fBTk_ConfigureWidget\fR |
| can be used in other situations where \fIargc-argv\fR information |
| is to be used to fill in a record structure, such as configuring |
| graphical elements for a canvas widget or entries of a menu. |
| .PP |
| \fBTk_ConfigureWidget\fR processes |
| a table specifying the configuration options that are supported |
| (\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and |
| \fIargv\fR) to fill in fields of a record (\fIwidgRec\fR). |
| It uses the option database and defaults specified in \fIspecs\fR |
| to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR. |
| \fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this |
| case it does not modify \fIinterp\fR. |
| If an error |
| occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will |
| leave an error message in \fIinterp->result\fR in the standard Tcl |
| fashion. |
| In the event of an error return, some of the fields of \fIwidgRec\fR |
| could already have been set, if configuration information for them |
| was successfully processed before the error occurred. |
| The other fields will be set to reasonable initial values so that |
| \fBTk_FreeOptions\fR can be called for cleanup. |
| .PP |
| The \fIspecs\fR array specifies the kinds of configuration options |
| expected by the widget. Each of its entries specifies one configuration |
| option and has the following structure: |
| .CS |
| typedef struct { |
| int \fItype\fR; |
| char *\fIargvName\fR; |
| char *\fIdbName\fR; |
| char *\fIdbClass\fR; |
| char *\fIdefValue\fR; |
| int \fIoffset\fR; |
| int \fIspecFlags\fR; |
| Tk_CustomOption *\fIcustomPtr\fR; |
| } Tk_ConfigSpec; |
| .CE |
| The \fItype\fR field indicates what type of configuration option this is |
| (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for |
| an integer value). The \fItype\fR field indicates how to use the |
| value of the option (more on this below). |
| The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'', |
| which is compared with the values in \fIargv\fR (if \fIargvName\fR is |
| NULL it means this is a grouped entry; see GROUPED ENTRIES below). The |
| \fIdbName\fR and \fIdbClass\fR fields are used to look up a value |
| for this option in the option database. The \fIdefValue\fR field |
| specifies a default value for this configuration option if no |
| value is specified in either \fIargv\fR or the option database. |
| \fIOffset\fR indicates where in \fIwidgRec\fR to store information |
| about this option, and \fIspecFlags\fR contains additional information |
| to control the processing of this configuration option (see FLAGS |
| below). |
| The last field, \fIcustomPtr\fR, is only used if \fItype\fR is |
| TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. |
| .PP |
| \fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which |
| (if any) configuration options are specified there. \fIArgv\fR |
| must contain an even number of fields; the first of each pair |
| of fields must match the \fIargvName\fR of some entry in \fIspecs\fR |
| (unique abbreviations are acceptable), |
| and the second field of the pair contains the value for that |
| configuration option. If there are entries in \fIspec\fR for which |
| there were no matching entries in \fIargv\fR, |
| \fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR |
| fields of the \fIspecs\fR entry to probe the option database; if |
| a value is found, then it is used as the value for the option. |
| Finally, if no entry is found in the option database, the |
| \fIdefValue\fR field of the \fIspecs\fR entry is used as the |
| value for the configuration option. If the \fIdefValue\fR is |
| NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in |
| \fIflags\fR, then there is no default value and this \fIspecs\fR entry |
| will be ignored if no value is specified in \fIargv\fR or the |
| option database. |
| .PP |
| Once a string value has been determined for a configuration option, |
| \fBTk_ConfigureWidget\fR translates the string value into a more useful |
| form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer |
| if \fItype\fR is TK_CONFIG_INT. This value is then stored in the |
| record pointed to by \fIwidgRec\fR. This record is assumed to |
| contain information relevant to the manager of the widget; its exact |
| type is unknown to \fBTk_ConfigureWidget\fR. The \fIoffset\fR field |
| of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store |
| the information about this configuration option. You should use the |
| \fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for |
| a description of \fBTk_Offset\fR). The location indicated by |
| \fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target'' |
| in the descriptions below. |
| .PP |
| The \fItype\fR field of each entry in \fIspecs\fR determines what |
| to do with the string value of that configuration option. The |
| legal values for \fItype\fR, and the corresponding actions, are: |
| .TP |
| \fBTK_CONFIG_ACTIVE_CURSOR\fR |
| The value |
| must be an ASCII string identifying a cursor in a form |
| suitable for passing to \fBTk_GetCursor\fR. |
| The value is converted to a \fBTk_Cursor\fR by calling |
| \fBTk_GetCursor\fR and the result is stored in the target. |
| In addition, the resulting cursor is made the active cursor |
| for \fItkwin\fR by calling \fBXDefineCursor\fR. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value |
| may be an empty string, in which case the target and \fItkwin\fR's |
| active cursor will be set to \fBNone\fR. |
| If the previous value of the target |
| wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR. |
| .TP |
| \fBTK_CONFIG_ANCHOR\fR |
| The value must be an ASCII string identifying an anchor point in one of the ways |
| accepted by \fBTk_GetAnchor\fR. |
| The string is converted to a \fBTk_Anchor\fR by calling |
| \fBTk_GetAnchor\fR and the result is stored in the target. |
| .TP |
| \fBTK_CONFIG_BITMAP\fR |
| The value must be an ASCII string identifying a bitmap in a form |
| suitable for passing to \fBTk_GetBitmap\fR. The value is converted |
| to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result |
| is stored in the target. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value |
| may be an empty string, in which case the target is set to \fBNone\fR. |
| If the previous value of the target |
| wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR. |
| .TP |
| \fBTK_CONFIG_BOOLEAN\fR |
| The value must be an ASCII string specifying a boolean value. Any |
| of the values ``true'', ``yes'', ``on'', or ``1'', |
| or an abbreviation of one of these values, means true; |
| any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of |
| one of these values, means false. |
| The target is expected to be an integer; for true values it will |
| be set to 1 and for false values it will be set to 0. |
| .TP |
| \fBTK_CONFIG_BORDER\fR |
| The value must be an ASCII string identifying a border color in a form |
| suitable for passing to \fBTk_Get3DBorder\fR. The value is converted |
| to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result |
| is stored in the target. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value |
| may be an empty string, in which case the target will be set to NULL. |
| If the previous value of the target |
| wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR. |
| .TP |
| \fBTK_CONFIG_CAP_STYLE\fR |
| The value must be |
| an ASCII string identifying a cap style in one of the ways |
| accepted by \fBTk_GetCapStyle\fR. |
| The string is converted to an integer value corresponding |
| to the cap style by calling |
| \fBTk_GetCapStyle\fR and the result is stored in the target. |
| .TP |
| \fBTK_CONFIG_COLOR\fR |
| The value must be an ASCII string identifying a color in a form |
| suitable for passing to \fBTk_GetColor\fR. The value is converted |
| to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result |
| is stored in the target. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value |
| may be an empty string, in which case the target will be set to \fBNone\fR. |
| If the previous value of the target |
| wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR. |
| .TP |
| \fBTK_CONFIG_CURSOR\fR |
| This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except |
| that the new cursor is not made the active one for \fItkwin\fR. |
| .TP |
| \fBTK_CONFIG_CUSTOM\fR |
| This option allows applications to define new option types. |
| The \fIcustomPtr\fR field of the entry points to a structure |
| defining the new option type. |
| See the section CUSTOM OPTION TYPES below for details. |
| .TP |
| \fBTK_CONFIG_DOUBLE\fR |
| The value must be an ASCII floating-point number in |
| the format accepted by \fBstrtol\fR. The string is converted |
| to a \fBdouble\fR value, and the value is stored in the |
| target. |
| .TP |
| \fBTK_CONFIG_END\fR |
| Marks the end of the table. The last entry in \fIspecs\fR |
| must have this type; all of its other fields are ignored and it |
| will never match any arguments. |
| .TP |
| \fBTK_CONFIG_FONT\fR |
| The value must be an ASCII string identifying a font in a form |
| suitable for passing to \fBTk_GetFont\fR. The value is converted |
| to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result |
| is stored in the target. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value |
| may be an empty string, in which case the target will be set to NULL. |
| If the previous value of the target |
| wasn't NULL, then it is freed by passing it to \fBTk_FreeFont\fR. |
| .TP |
| \fBTK_CONFIG_INT\fR |
| The value must be an ASCII integer string |
| in the format accepted by \fBstrtol\fR (e.g. ``0'' |
| and ``0x'' prefixes may be used to specify octal or hexadecimal |
| numbers, respectively). The string is converted to an integer |
| value and the integer is stored in the target. |
| .TP |
| \fBTK_CONFIG_JOIN_STYLE\fR |
| The value must be |
| an ASCII string identifying a join style in one of the ways |
| accepted by \fBTk_GetJoinStyle\fR. |
| The string is converted to an integer value corresponding |
| to the join style by calling |
| \fBTk_GetJoinStyle\fR and the result is stored in the target. |
| .TP |
| \fBTK_CONFIG_JUSTIFY\fR |
| The value must be |
| an ASCII string identifying a justification method in one of the |
| ways accepted by \fBTk_GetJustify\fR. |
| The string is converted to a \fBTk_Justify\fR by calling |
| \fBTk_GetJustify\fR and the result is stored in the target. |
| .TP |
| \fBTK_CONFIG_MM\fR |
| The value must specify a screen distance in one of the forms acceptable |
| to \fBTk_GetScreenMM\fR. |
| The string is converted to double-precision floating-point distance |
| in millimeters and the value is stored in the target. |
| .TP |
| \fBTK_CONFIG_PIXELS\fR |
| The value must specify screen units in one of the forms acceptable |
| to \fBTk_GetPixels\fR. |
| The string is converted to an integer distance in pixels and the |
| value is stored in the target. |
| .TP |
| \fBTK_CONFIG_RELIEF\fR |
| The value must be an ASCII string identifying a relief in a form |
| suitable for passing to \fBTk_GetRelief\fR. The value is converted |
| to an integer relief value by calling \fBTk_GetRelief\fR and the result |
| is stored in the target. |
| .TP |
| \fBTK_CONFIG_STRING\fR |
| A copy |
| of the value is made by allocating memory space with |
| \fBmalloc\fR and copying the value into the dynamically-allocated |
| space. A pointer to the new string is stored in the target. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value |
| may be an empty string, in which case the target will be set to NULL. |
| If the previous value of the target wasn't NULL, then it is |
| freed by passing it to \fBfree\fR. |
| .TP |
| \fBTK_CONFIG_SYNONYM\fR |
| This \fItype\fR value identifies special entries in \fIspecs\fR that |
| are synonyms for other entries. If an \fIargv\fR value matches the |
| \fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used |
| directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR |
| for another entry whose \fIargvName\fR is the same as the \fIdbName\fR |
| field in the TK_CONFIG_SYNONYM entry; this new entry is used just |
| as if its \fIargvName\fR had matched the \fIargv\fR value. The |
| synonym mechanism allows multiple \fIargv\fR values to be used for |
| a single configuration option, such as ``\-background'' and ``\-bg''. |
| .TP |
| \fBTK_CONFIG_UID\fR |
| The value is translated to a \fBTk_Uid\fR |
| (by passing it to \fBTk_GetUid\fR). The resulting value |
| is stored in the target. |
| If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value |
| is an empty string then the target will be set to NULL. |
| .TP |
| \fBTK_CONFIG_WINDOW\fR |
| The value must be a window path name. It is translated to a |
| \fBTk_Window\fR token and the token is stored in the target. |
| |
| .SH "GROUPED ENTRIES" |
| .PP |
| In some cases it is useful to generate multiple resources from |
| a single configuration value. For example, a color name might |
| be used both to generate the background color for a widget (using |
| TK_CONFIG_COLOR) and to generate a 3-D border to draw around the |
| widget (using TK_CONFIG_BORDER). In cases like this it is possible |
| to specify that several consecutive entries in \fIspecs\fR are to |
| be treated as a group. The first entry is used to determine a value |
| (using its \fIargvName\fR, \fIdbName\fR, |
| \fIdbClass\fR, and \fIdefValue\fR fields). The value will be processed |
| several times (one for each entry in the group), generating multiple |
| different resources and modifying multiple targets within \fIwidgRec\fR. |
| Each of the entries after the first must have a NULL value in its |
| \fIargvName\fR field; this indicates that the entry is to be grouped |
| with the entry that precedes it. Only the \fItype\fR and \fIoffset\fR |
| fields are used from these follow-on entries. |
| |
| .SH "FLAGS" |
| .PP |
| The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used |
| in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR |
| to provide additional control over the processing of configuration |
| options. These values are used in three different ways as |
| described below. |
| .PP |
| First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has |
| the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0), |
| then the option database and |
| \fIdefValue\fR fields are not used. In this case, if an entry in |
| \fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens: |
| the corresponding target isn't modified. This feature is useful |
| when the goal is to modify certain configuration options while |
| leaving others in their current state, such as when a \fBconfigure\fR |
| widget command is being processed. |
| .PP |
| Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used |
| to control the processing of that entry. Each \fIspecFlags\fR |
| field may consists of an OR-ed combination of the following values: |
| .TP |
| \fBTK_CONFIG_COLOR_ONLY\fR |
| If this bit is set then the entry will only be considered if the |
| display for \fItkwin\fR has more than one bit plane. If the display |
| is monochromatic then this \fIspecs\fR entry will be ignored. |
| .TP |
| \fBTK_CONFIG_MONO_ONLY\fR |
| If this bit is set then the entry will only be considered if the |
| display for \fItkwin\fR has exactly one bit plane. If the display |
| is not monochromatic then this \fIspecs\fR entry will be ignored. |
| .TP |
| \fBTK_CONFIG_NULL_OK\fR |
| This bit is only relevant for some types of entries (see the |
| descriptions of the various entry types above). |
| If this bit is set, it indicates that an empty string value |
| for the field is acceptable and if it occurs then the |
| target should be set to NULL or \fBNone\fR, depending |
| on the type of the target. |
| This flag is typically used to allow a |
| feature to be turned off entirely, e.g. set a cursor value to |
| \fBNone\fR so that a window simply inherits its parent's cursor. |
| If this bit isn't set then empty strings are processed as strings, |
| which generally results in an error. |
| .TP |
| \fBTK_CONFIG_DONT_SET_DEFAULT\fR |
| If this bit is one, it means that the \fIdefValue\fR field of the |
| entry should only be used for returning the default value in |
| \fBTk_ConfigureInfo\fR. |
| In calls to \fBTk_ConfigureWidget\fR no default will be supplied |
| for entries with this flag set; it is assumed that the |
| caller has already supplied a default value in the target location. |
| This flag provides a performance optimization where it is expensive |
| to process the default string: the client can compute the default |
| once, save the value, and provide it before calling |
| \fBTk_ConfigureWidget\fR. |
| .TP |
| \fBTK_CONFIG_OPTION_SPECIFIED\fR |
| This bit is set and cleared by \fBTk_ConfigureWidget\fR. Whenever |
| \fBTk_ConfigureWidget\fR returns, this bit will be set in all the |
| entries where a value was specified in \fIargv\fR. |
| It will be zero in all other entries. |
| This bit provides a way for clients to determine which values |
| actually changed in a call to \fBTk_ConfigureWidget\fR. |
| .PP |
| The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically |
| used to specify different default values for |
| monochrome and color displays. This is done by creating two |
| entries in \fIspecs\fR that are identical except for their |
| \fIdefValue\fR and \fIspecFlags\fR fields. One entry should have |
| the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the |
| default value for monochrome displays in its \fIdefValue\fR; the |
| other entry entry should have the value TK_CONFIG_COLOR_ONLY in |
| its \fIspecFlags\fR and the appropriate \fIdefValue\fR for |
| color displays. |
| .PP |
| Third, it is possible to use \fIflags\fR and \fIspecFlags\fR |
| together to selectively disable some entries. This feature is |
| not needed very often. It is useful in cases where several |
| similar kinds of widgets are implemented in one place. It allows |
| a single \fIspecs\fR table to be created with all the configuration |
| options for all the widget types. When processing a particular |
| widget type, only entries relevant to that type will be used. This |
| effect is achieved by setting the high-order bits (those in positions |
| equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR |
| values or in \fIflags\fR. In order for a particular entry in |
| \fIspecs\fR to be used, its high-order bits must match exactly |
| the high-order bits of the \fIflags\fR value passed to |
| \fBTk_ConfigureWidget\fR. If a \fIspecs\fR table is being used |
| for N different widget types, then N of the high-order bits will |
| be used. Each \fIspecs\fR entry will have one of more of those |
| bits set in its \fIspecFlags\fR field to indicate the widget types |
| for which this entry is valid. When calling \fBTk_ConfigureWidget\fR, |
| \fIflags\fR will have a single one of these bits set to select the |
| entries for the desired widget type. For a working example of |
| this feature, see the code in tkButton.c. |
| |
| .SH TK_OFFSET |
| .PP |
| The \fBTk_Offset\fR macro is provided as a safe way of generating |
| the \fIoffset\fR values for entries in Tk_ConfigSpec structures. |
| It takes two arguments: the name of a type of record, and the |
| name of a field in that record. It returns the byte offset of |
| the named field in records of the given type. |
| |
| .SH TK_CONFIGUREINFO |
| .PP |
| The \fBTk_ConfigureInfo\fR procedure may be used to obtain |
| information about one or all of the options for a given widget. |
| Given a token for a window (\fItkwin\fR), a table describing the |
| configuration options for a class of widgets (\fIspecs\fR), a |
| pointer to a widget record containing the current information for |
| a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument, |
| \fBTk_ConfigureInfo\fR generates a string describing all of the |
| configuration options for the window. The string is placed |
| in \fIinterp->result\fR. Under normal circumstances |
| it returns TCL_OK; if an error occurs then it returns TCL_ERROR |
| and \fIinterp->result\fR contains an error message. |
| .PP |
| If \fIargvName\fR is NULL, then the value left in |
| \fIinterp->result\fR by \fBTk_ConfigureInfo\fR |
| consists of a list of one or more entries, each of which describes |
| one configuration option (i.e. one entry in \fIspecs\fR). Each |
| entry in the list will contain either two or five values. If the |
| corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then |
| the list will contain two values: the \fIargvName\fR for the entry |
| and the \fIdbName\fR (synonym name). Otherwise the list will contain |
| five values: \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR, |
| and current value. The current value is computed from the appropriate |
| field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR. |
| .PP |
| If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL, |
| then it indicates a single option, and information is returned only |
| for that option. The string placed in \fIinterp->result\fR will be |
| a list containing two or five values as described above; this will |
| be identical to the corresponding sublist that would have been returned |
| if \fIargvName\fR had been NULL. |
| .PP |
| The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict |
| the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR. |
| |
| .SH TK_CONFIGUREVALUE |
| .PP |
| \fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR; |
| instead of returning a list of values, it just returns the current value |
| of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL). |
| The value is returned in \fIinterp->result\fR and TCL_OK is |
| normally returned as the procedure's result. |
| If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is |
| not a valid option name), TCL_ERROR is returned and an error message |
| is left in \fIinterp->result\fR. |
| This procedure is typically called to implement \fBcget\fR widget |
| commands. |
| |
| .SH TK_FREEOPTIONS |
| .PP |
| The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup |
| to release all of the resources associated with configuration options. |
| It scans through \fIspecs\fR and for each entry corresponding to a |
| resource that must be explicitly freed (e.g. those with |
| type TK_CONFIG_COLOR), it frees the resource in the widget record. |
| If the field in the widget record doesn't refer to a resource (e.g. |
| it contains a null pointer) then no resource is freed for that |
| entry. |
| After freeing a resource, \fBTk_FreeOptions\fR sets the |
| corresponding field of the widget record to null. |
| |
| .SH "CUSTOM OPTION TYPES" |
| .PP |
| Applications can extend the built-in configuration types with additional |
| configuration types by writing procedures to parse and print options |
| of the a type and creating a structure pointing to those procedures: |
| .CS |
| typedef struct Tk_CustomOption { |
| Tk_OptionParseProc *\fIparseProc\fR; |
| Tk_OptionPrintProc *\fIprintProc\fR; |
| ClientData \fIclientData\fR; |
| } Tk_CustomOption; |
| |
| typedef int Tk_OptionParseProc( |
| ClientData \fIclientData\fR, |
| Tcl_Interp *\fIinterp\fR, |
| Tk_Window \fItkwin\fR, |
| char *\fIvalue\fR, |
| char *\fIwidgRec\fR, |
| int \fIoffset\fR); |
| |
| typedef char *Tk_OptionPrintProc( |
| ClientData \fIclientData\fR, |
| Tk_Window \fItkwin\fR, |
| char *\fIwidgRec\fR, |
| int \fIoffset\fR, |
| Tcl_FreeProc **\fIfreeProcPtr\fR); |
| .CE |
| The Tk_CustomOption structure contains three fields, which are pointers |
| to the two procedures and a \fIclientData\fR value to be passed to those |
| procedures when they are invoked. The \fIclientData\fR value typically |
| points to a structure containing information that is needed by the |
| procedures when they are parsing and printing options. |
| .PP |
| The \fIparseProc\fR procedure is invoked by |
| \fBTk_ConfigureWidget\fR to parse a string and store the resulting |
| value in the widget record. |
| The \fIclientData\fR argument is a copy of the \fIclientData\fR |
| field in the Tk_CustomOption structure. |
| The \fIinterp\fR argument points to a Tcl interpreter used for |
| error reporting. \fITkwin\fR is a copy of the \fItkwin\fR argument |
| to \fBTk_ConfigureWidget\fR. The \fIvalue\fR argument is a string |
| describing the value for the option; it could have been specified |
| explicitly in the call to \fBTk_ConfigureWidget\fR or it could |
| come from the option database or a default. |
| \fIValue\fR will never be a null pointer but it may point to |
| an empty string. |
| \fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to |
| \fBTk_ConfigureWidget\fR; it points to the start of the widget |
| record to modify. |
| The last argument, \fIoffset\fR, gives the offset in bytes from the start |
| of the widget record to the location where the option value is to |
| be placed. The procedure should translate the string to whatever |
| form is appropriate for the option and store the value in the widget |
| record. It should normally return TCL_OK, but if an error occurs |
| in translating the string to a value then it should return TCL_ERROR |
| and store an error message in \fIinterp->result\fR. |
| .PP |
| The \fIprintProc\fR procedure is called |
| by \fBTk_ConfigureInfo\fR to produce a string value describing an |
| existing option. |
| Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR |
| arguments all have the same meaning as for Tk_OptionParseProc |
| procedures. |
| The \fIprintProc\fR procedure should examine the option whose value |
| is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing |
| that option, and return a pointer to the string. |
| If the string is stored in dynamically-allocated memory, then |
| the procedure must set \fI*freeProcPtr\fR to the address of |
| a procedure to call to free the string's memory; \fBTk_ConfigureInfo\fR |
| will call this procedure when it is finished with the string. |
| If the result string is stored in static memory then \fIprintProc\fR |
| need not do anything with the \fIfreeProcPtr\fR argument. |
| .PP |
| Once \fIparseProc\fR and \fIprintProc\fR have been defined and a |
| Tk_CustomOption structure has been created for them, options of this |
| new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR |
| fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point |
| to the Tk_CustomOption structure. |
| |
| .SH EXAMPLES |
| .PP |
| Although the explanation of \fBTk_ConfigureWidget\fR is fairly |
| complicated, its actual use is pretty straightforward. |
| The easiest way to get started is to copy the code |
| from an existing widget. |
| The library implementation of frames |
| (tkFrame.c) has a simple configuration table, and the library |
| implementation of buttons (tkButton.c) has a much more complex |
| table that uses many of the fancy \fIspecFlags\fR mechanisms. |
| |
| .SH "SEE ALSO" |
| Tk_SetOptions(3) |
| |
| .SH KEYWORDS |
| anchor, bitmap, boolean, border, cap style, color, configuration options, |
| cursor, custom, double, font, integer, join style, justify, millimeters, |
| pixels, relief, synonym, uid |