diff options
Diffstat (limited to 'doc/SetOptions.3')
| -rw-r--r-- | doc/SetOptions.3 | 77 |
1 files changed, 52 insertions, 25 deletions
diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index 2eb3b88..d84da6c 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -8,7 +8,7 @@ .so man.macros .BS .SH NAME -Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions, Tk_Offset \- process configuration options +Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions, Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions \- process configuration options .SH SYNOPSIS .nf \fB#include <tk.h>\fR @@ -35,9 +35,6 @@ Tcl_Obj * \fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR .sp \fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR -.sp -int -\fBTk_Offset(\fItype, field\fB)\fR .SH ARGUMENTS .AS Tk_SavedOptions "*const objv[]" in/out .AP Tcl_Interp *interp in @@ -52,7 +49,7 @@ pointed to by this argument must exist for the lifetime of the Tk_OptionTable. .AP Tk_OptionTable optionTable in Token for an option table. Must have been returned by a previous call to \fBTk_CreateOptionTable\fR. -.AP char *recordPtr in/out +.AP void *recordPtr in/out Points to structure in which values of configuration options are stored; fields of this record are modified by procedures such as \fBTk_SetOptions\fR and read by procedures such as \fBTk_GetOptionValue\fR. @@ -239,12 +236,6 @@ is returned and an error message is left in \fIinterp\fR's result unless \fBTk_FreeConfigOptions\fR must be invoked when a widget is deleted. It frees all of the resources associated with any of the configuration options defined in \fIrecordPtr\fR by \fIoptionTable\fR. -.PP -The \fBTk_Offset\fR macro is provided as a safe way of generating the -\fIobjOffset\fR and \fIinternalOffset\fR values for entries in -Tk_OptionSpec 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 "TEMPLATES" .PP The array of Tk_OptionSpec structures passed to \fBTk_CreateOptionTable\fR @@ -258,8 +249,8 @@ typedef struct { const char *\fIdbName\fR; const char *\fIdbClass\fR; const char *\fIdefValue\fR; - int \fIobjOffset\fR; - int \fIinternalOffset\fR; + size_t \fIobjOffset\fR; + size_t \fIinternalOffset\fR; int \fIflags\fR; const void *\fIclientData\fR; int \fItypeMask\fR; @@ -281,7 +272,7 @@ value is specified in the option database. The \fIobjOffset\fR and \fIinternalOffset\fR fields indicate where to store the value of this option in widget records (more on this below); values for the \fIobjOffset\fR and \fIinternalOffset\fR fields should always be generated with the -\fBTk_Offset\fR macro. +\fBoffsetof\fR macro. The \fIflags\fR field contains additional information to control the processing of this configuration option (see below for details). @@ -329,6 +320,20 @@ If this bit is set for an option then no default value will be set in system default value, nor \fIoptionTable\fR are used to give a default value to this option. Instead it is assumed that the caller has already supplied a default value in the widget code. +.TP +\fBTK_OPTION_ENUM_VAR\fR +If this value is set for an option, then it indicates the the +internalOffset points to an enum variable in stead of an int variable. +Only useful in combination with \fBTK_OPTION_STRING_TABLE\fR, +\fBTK_OPTION_BOOLEAN\fR, \fBTK_OPTION_ANCHOR\fR, \fBTK_OPTION_JUSTIFY\fR, +or \fBTK_OPTION_ANCHOR\fR. +.TP +\fBTK_OPTION_VAR(type)\fR +If this value is set for an option, then it indicates the the +internalOffset points to a \fItype\fR variable in stead of an int variable. +Only useful in combination with \fBTK_OPTION_STRING_TABLE\fR or +\fBTK_OPTION_BOOLEAN\fR, or as \fBTK_OPTION_VAR(Tcl_Size)\fR +with \fBTK_OPTION_INT\fR .PP The \fItype\fR field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The @@ -342,7 +347,9 @@ nor \fIclientData\fR. \fBTK_OPTION_ANCHOR\fR The value must be a standard anchor position such as \fBne\fR or \fBcenter\fR. The internal form is a Tk_Anchor value like the ones -returned by \fBTk_GetAnchorFromObj\fR. +returned by \fBTk_GetAnchorFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR +flag; if the empty string is specified as the value for the option, +the integer relief value is set to \fBTK_ANCHOR_NULL\fR. .TP \fBTK_OPTION_BITMAP\fR The value must be a standard Tk bitmap name. The internal form is a @@ -352,7 +359,11 @@ such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. .TP \fBTK_OPTION_BOOLEAN\fR The value must be a standard boolean value such as \fBtrue\fR or -\fBno\fR. The internal form is an integer with value 0 or 1. +\fBno\fR. The internal form is an integer with value 0 or 1. Note: if the +\fIobjOffset\fR field is not used then information about the original value +of this option will be lost. This option type supports the +\fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal +representation is set to -1. .TP \fBTK_OPTION_BORDER\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. @@ -386,7 +397,7 @@ option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. The string value must be a floating-point number in the format accepted by \fBstrtol\fR. The internal form is a C \fBdouble\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR -flag; if a NULL value is set, the internal representation is set to zero. +flag; if a NULL value is set, the internal representation is set to NaN. .TP \fBTK_OPTION_END\fR Marks the end of the template. There must be a Tk_OptionSpec structure @@ -408,12 +419,24 @@ such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. The string value must be an integer in the format accepted by \fBstrtol\fR (e.g. \fB0\fR and \fB0x\fR prefixes may be used to specify octal or hexadecimal numbers, respectively). The internal -form is a C \fBint\fR value. +form is a C \fBint\fR value. This option type supports the \fBTK_OPTION_NULL_OK\fR +flag; if a NULL value is set, the internal representation is set to INT_MIN. +.TP +\fBTK_OPTION_INDEX\fR +The string value must be an index in the format accepted by \fBTcl_GetIntForIndex()\fR +or the empty string. The internal form is a C \fBint\fR value. If the string +starts with \fB-\fR, the internal representation will be set to INT_MIN. If the +string has the form \fBend-???\fR, then the result will be a negative number: +\fB-1\fR stands for \fBend\fR, \fB-2\fR stands for \fBend-1\fR and so on. +This option type supports the \fBTK_OPTION_NULL_OK\fR flag; +if a NULL value is set, the internal representation is set to INT_MIN. .TP \fBTK_OPTION_JUSTIFY\fR The value must be a standard justification value such as \fBleft\fR. The internal form is a Tk_Justify like the values returned by -\fBTk_GetJustifyFromObj\fR. +\fBTk_GetJustifyFromObj\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR +flag; if the empty string is specified as the value for the option, +the integer relief value is set to \fBTK_JUSTIFY_NULL\fR. .TP \fBTK_OPTION_PIXELS\fR The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. @@ -423,7 +446,7 @@ distance in pixels, like the values returned by used then information about the original value of this option will be lost. See \fBOBJOFFSET VS. INTERNALOFFSET\fR below for details. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the -internal representation is set to zero. +internal representation is set to INT_MIN. .TP \fBTK_OPTION_RELIEF\fR The value must be standard relief such as \fBraised\fR. @@ -513,6 +536,10 @@ To implement a new type of option, you can use \fBTK_OPTION_STRING\fR as the type in the Tk_OptionSpec structure and set the \fIobjOffset\fR field but not the \fIinternalOffset\fR field. Then, after calling \fBTk_SetOptions\fR, convert the object to internal form yourself. +.PP +Ttk widgets do not support the \fIinternalOffset\fR machinery. +Option values of Ttk widgets are always stored as (Tcl_Obj *), meaning that +the \fIobjOffset\fR field must be used. .SH "CUSTOM OPTION TYPES" .PP Applications can extend the built-in configuration types with @@ -526,11 +553,11 @@ typedef struct Tk_ObjCustomOption { Tk_CustomOptionGetProc *\fIgetProc\fR; Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; Tk_CustomOptionFreeProc *\fIfreeProc\fR; - ClientData \fIclientData\fR; + void *\fIclientData\fR; } \fBTk_ObjCustomOption\fR; typedef int \fBTk_CustomOptionSetProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj **\fIvaluePtr\fR, @@ -540,19 +567,19 @@ typedef int \fBTk_CustomOptionSetProc\fR( int \fIflags\fR); typedef Tcl_Obj *\fBTk_CustomOptionGetProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIrecordPtr\fR, int \fIinternalOffset\fR); typedef void \fBTk_CustomOptionRestoreProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIinternalPtr\fR, char *\fIsaveInternalPtr\fR); typedef void \fBTk_CustomOptionFreeProc\fR( - ClientData \fIclientData\fR, + void *\fIclientData\fR, Tk_Window \fItkwin\fR, char *\fIinternalPtr\fR); .CE |