diff options
| -rw-r--r-- | doc/SetOptions.3 | 131 |
1 files changed, 56 insertions, 75 deletions
diff --git a/doc/SetOptions.3 b/doc/SetOptions.3 index 2eb3b88..7163214 100644 --- a/doc/SetOptions.3 +++ b/doc/SetOptions.3 @@ -14,30 +14,31 @@ Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions, Tk_SetOptions, Tk_Fr \fB#include <tk.h>\fR .sp Tk_OptionTable -\fBTk_CreateOptionTable(\fIinterp, templatePtr\fB)\fR +\fBTk_CreateOptionTable\fR(\fIinterp, templatePtr\fR) .sp -\fBTk_DeleteOptionTable(\fIoptionTable\fB)\fR +\fBTk_DeleteOptionTable\fR(\fIoptionTable\fR) .sp int -\fBTk_InitOptions(\fIinterp, recordPtr, optionTable, tkwin\fB)\fR +\fBTk_InitOptions\fR(\fIinterp, recordPtr, optionTable, tkwin\fR) .sp int -\fBTk_SetOptions(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fB)\fR +\fBTk_SetOptions\fR(\fIinterp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr\fR) .sp -\fBTk_FreeSavedOptions(\fIsavedPtr\fB)\fR +\fBTk_FreeSavedOptions\fR(\fIsavedPtr\fR) .sp -\fBTk_RestoreSavedOptions(\fIsavedPtr\fB)\fR +\fBTk_RestoreSavedOptions\fR(\fIsavedPtr\fR) .sp Tcl_Obj * -\fBTk_GetOptionValue(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR +\fBTk_GetOptionValue\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR) .sp Tcl_Obj * -\fBTk_GetOptionInfo(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fB)\fR +\fBTk_GetOptionInfo\fR(\fIinterp, recordPtr, optionTable, namePtr, tkwin\fR) .sp -\fBTk_FreeConfigOptions(\fIrecordPtr, optionTable, tkwin\fB)\fR +\fBTk_FreeConfigOptions\fR(\fIrecordPtr, optionTable, tkwin\fR) .sp int \fBTk_Offset(\fItype, field\fB)\fR +.fi .SH ARGUMENTS .AS Tk_SavedOptions "*const objv[]" in/out .AP Tcl_Interp *interp in @@ -101,7 +102,7 @@ practice the object may not actually be a widget. The term is used to refer to the C-level structure in which information about a particular widget or object is stored. .PP -Note: the easiest way to learn how to use these procedures is to +Note that the easiest way to learn how to use these procedures is to look at a working example. In Tk, the simplest example is the code that implements the button family of widgets, which is in \fBtkButton.c\fR. Other examples are in \fBtkSquare.c\fR and \fBtkMenu.c\fR. @@ -310,8 +311,7 @@ greater than or equal to zero. .PP The \fIflags\fR field consists of one or more bits ORed together. The following flags are supported: -.TP -\fBTK_OPTION_NULL_OK\fR +.IP \fBTK_OPTION_NULL_OK\fR If this bit is set for an option then an empty string will be accepted as the value for the option and the resulting internal form will be a NULL pointer, a zero value, or \fBNone\fR, depending on the type of the option. @@ -322,13 +322,13 @@ feature to be turned off entirely, e.g. set a cursor value to Not all option types support the \fBTK_OPTION_NULL_OK\fR flag; for those that do, there is an explicit indication of that fact in the descriptions below. -.TP -\fBTK_OPTION_DONT_SET_DEFAULT\fR +.IP \fBTK_OPTION_DONT_SET_DEFAULT\fR If this bit is set for an option then no default value will be set in \fBTk_InitOptions\fR for this option. Neither the option database, nor any 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. +.RS .PP The \fItype\fR field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The @@ -338,37 +338,34 @@ passed into procedures like \fBTk_SetOptions\fR, or if it uses the \fIclientData\fR field of the Tk_OptionSpec, then it is indicated explicitly; if not mentioned, the type requires neither \fItkwin\fR nor \fIclientData\fR. -.TP -\fBTK_OPTION_ANCHOR\fR +.RE +.IP \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. -.TP -\fBTK_OPTION_BITMAP\fR +.IP \fBTK_OPTION_BITMAP\fR The value must be a standard Tk bitmap name. The internal form is a Pixmap token like the ones returned by \fBTk_AllocBitmapFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_BOOLEAN\fR +.IP \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. -.TP -\fBTK_OPTION_BORDER\fR +\fBno\fR. The internal form is an integer with value 0 or 1. Note that if +the \fIobjOffset\fR field is not used, information about the original +value of this option will be lost. +.IP \fBTK_OPTION_BORDER\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. The internal form is a Tk_3DBorder token like the ones returned by \fBTk_Alloc3DBorderFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_COLOR\fR +.IP \fBTK_OPTION_COLOR\fR The value must be a standard color name such as \fBred\fR or \fB#ff8080\fR. The internal form is an (XColor *) token like the ones returned by \fBTk_AllocColorFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_CURSOR\fR +.IP \fBTK_OPTION_CURSOR\fR The value must be a standard cursor name such as \fBcross\fR or \fB@foo\fR. The internal form is a Tk_Cursor token like the ones returned by \fBTk_AllocCursorFromObj\fR. @@ -376,19 +373,16 @@ This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and when the option is set the cursor for the window is changed by calling \fBXDefineCursor\fR. This option type also supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_CUSTOM\fR +.IP \fBTK_OPTION_CUSTOM\fR This option allows applications to define new option types. The clientData field of the entry points to a structure defining the new option type. See the section \fBCUSTOM OPTION TYPES\fR below for details. -.TP -\fBTK_OPTION_DOUBLE\fR +.IP \fBTK_OPTION_DOUBLE\fR 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. -.TP -\fBTK_OPTION_END\fR +.IP \fBTK_OPTION_END\fR Marks the end of the template. There must be a Tk_OptionSpec structure with \fItype\fR \fBTK_OPTION_END\fR at the end of each template. If the \fIclientData\fR field of this structure is not NULL, then it points to @@ -396,48 +390,41 @@ an additional array of Tk_OptionSpec's, which is itself terminated by another \fBTK_OPTION_END\fR entry. Templates may be chained arbitrarily deeply. This feature allows common options to be shared by several widget classes. -.TP -\fBTK_OPTION_FONT\fR +.IP \fBTK_OPTION_FONT\fR The value must be a standard font name such as \fBTimes 16\fR. The internal form is a Tk_Font handle like the ones returned by \fBTk_AllocFontFromObj\fR. This option type requires \fItkwin\fR to be supplied to procedures such as \fBTk_SetOptions\fR, and it supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_INT\fR +.IP \fBTK_OPTION_INT\fR 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. -.TP -\fBTK_OPTION_JUSTIFY\fR +specify octal or hexadecimal numbers, respectively). The internal form is +a C \fBint\fR value. +.IP \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. -.TP -\fBTK_OPTION_PIXELS\fR +.IP \fBTK_OPTION_PIXELS\fR The value must specify a screen distance such as \fB2i\fR or \fB6.4\fR. The internal form is an integer value giving a distance in pixels, like the values returned by -\fBTk_GetPixelsFromObj\fR. Note: if the \fIobjOffset\fR field is not -used then information about the original value of this option will be lost. +\fBTk_GetPixelsFromObj\fR. Note that if the \fIobjOffset\fR field is not +used, 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. -.TP -\fBTK_OPTION_RELIEF\fR +internal representation is set to INT_MIN. +.IP \fBTK_OPTION_RELIEF\fR The value must be standard relief such as \fBraised\fR. The internal form is an integer relief value such as \fBTK_RELIEF_RAISED\fR. This option type supports the \fBTK_OPTION_NULL_OK\fR flag; if a NULL value is set, the internal representation is set to \fBTK_RELIEF_NULL\fR. -.TP -\fBTK_OPTION_STRING\fR +.IP \fBTK_OPTION_STRING\fR The value may be any string. The internal form is a (char *) pointer that points to a dynamically allocated copy of the value. This option type supports the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fBTK_OPTION_STRING_TABLE\fR +.IP \fBTK_OPTION_STRING_TABLE\fR For this type, \fIclientData\fR is a pointer to an array of strings suitable for passing to \fBTcl_GetIndexFromObj\fR. The value must be one of the strings in the table, or a unique abbreviation of @@ -446,15 +433,13 @@ into the table of the matching string, like the return value from \fBTcl_GetStringFromObj\fR. 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_SYNONYM\fR +.IP \fBTK_OPTION_SYNONYM\fR This type is used to provide alternative names for an option (for example, \fB\-bg\fR is often used as a synonym for \fB\-background\fR). The \fBclientData\fR field is a string that gives the name of another option in the same table. Whenever the synonym option is used, the information from the other option will be used instead. -.TP -\fBTK_OPTION_WINDOW\fR +.IP \fBTK_OPTION_WINDOW\fR The value must be a window path name. The internal form is a \fBTk_Window\fR token for the window. This option type requires \fItkwin\fR to be supplied to procedures @@ -504,8 +489,8 @@ the option is retrieved. In most cases it is convenient to use the \fIinternalOffset\fR field as well, so that the integer value is immediately available for use in the widget code (alternatively, \fBTk_GetPixelsFromObj\fR can be used to extract the integer value from -the object whenever it is needed). Note: the problem of losing information -on retrievals exists only for \fBTK_OPTION_PIXELS\fR options. +the object whenever it is needed). Note that the problem of losing +information on retrievals exists only for \fBTK_OPTION_PIXELS\fR options. .PP The second reason to use the \fIobjOffset\fR field is in order to implement new types of options not supported by these procedures. @@ -513,6 +498,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 @@ -521,7 +510,7 @@ free, and restore saved copies of the type and creating a structure pointing to those procedures: .CS typedef struct Tk_ObjCustomOption { - const char *\fname\fR; + const char *\fIname\fR; Tk_CustomOptionSetProc *\fIsetProc\fR; Tk_CustomOptionGetProc *\fIgetProc\fR; Tk_CustomOptionRestoreProc *\fIrestoreProc\fR; @@ -570,18 +559,14 @@ The \fIsetProc\fR procedure is invoked by \fBTk_SetOptions\fR to convert a Tcl_Obj into an internal representation and store the resulting value in the widget record. The arguments are: .RS -.TP -\fIclientData\fR +.IP \fIclientData\fR A copy of the \fIclientData\fR field in the Tk_ObjCustomOption structure. -.TP -\fIinterp\fR +.IP \fIinterp\fR A pointer to a Tcl interpreter, used for error reporting. -.TP -\fITkwin\fR +.IP \fITkwin\fR A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR -.TP -\fIvaluePtr\fR +.IP \fIvaluePtr\fR A pointer to a reference to a Tcl_Obj describing the new value for the option; it could have been specified explicitly in the call to \fBTk_SetOptions\fR or it could come from the option database or a @@ -591,22 +576,18 @@ pointer referenced by \fIvaluePtr\fR is the pointer that will be stored at the objOffset for the option. \fISetProc\fR may modify the value if necessary; for example, \fIsetProc\fR may change the value to NULL to support the \fBTK_OPTION_NULL_OK\fR flag. -.TP -\fIrecordPtr\fR +.IP \fIrecordPtr\fR A pointer to the start of the widget record to modify. -.TP -\fIinternalOffset\fR +.IP \fIinternalOffset\fR Offset in bytes from the start of the widget record to the location where the internal representation of the option value is to be placed. -.TP -\fIsaveInternalPtr\fR +.IP \fIsaveInternalPtr\fR A pointer to storage allocated in a Tk_SavedOptions structure for the internal representation of the original option value. Before setting the option to its new value, \fIsetProc\fR should set the value referenced by \fIsaveInternalPtr\fR to the original value of the option in order to support \fBTk_RestoreSavedOptions\fR. -.TP -\fIflags\fR +.IP \fIflags\fR A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the option .RE |