summaryrefslogtreecommitdiffstats
path: root/doc/SetOptions.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/SetOptions.3')
-rw-r--r--doc/SetOptions.3141
1 files changed, 139 insertions, 2 deletions
diff --git a/doc/SetOptions.3 b/doc/SetOptions.3
index 16d645c..bef4ed5 100644
--- a/doc/SetOptions.3
+++ b/doc/SetOptions.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: SetOptions.3,v 1.5 2000/08/15 21:30:32 hobbs Exp $
+'\" RCS: @(#) $Id: SetOptions.3,v 1.6 2000/09/17 21:02:39 ericm Exp $
'\"
.so man.macros
.TH Tk_SetOptions 3 8.1 Tk "Tk Library Procedures"
@@ -368,6 +368,11 @@ 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 TK_OPTION_NULL_OK flag.
.TP
+\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 CUSTOM OPTION TYPES below for details.
+.TP
\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
@@ -496,11 +501,143 @@ on retrievals exists only for TK_OPTION_PIXELS 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.
-To implement a new type of option, use TK_OPTION_STRING as
+To implement a new type of option, you can use TK_OPTION_STRING 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.
+.SH "CUSTOM OPTION TYPES"
+.PP
+Applications can extend the built-in configuration types with
+additional configuration types by writing procedures to parse, print,
+free, and restore saved copies of the type and creating a structure
+pointing to those procedures:
+.CS
+typedef struct Tk_ObjCustomOption {
+ char *name;
+ Tk_CustomOptionSetProc *\fIsetProc\fR;
+ Tk_CustomOptionGetProc *\fIgetProc\fR;
+ Tk_CustomOptionRestoreProc *\fIrestoreProc\fR;
+ Tk_CustomOptionFreeProc *\fIfreeProc\fR;
+ ClientData \fIclientData\fR;
+} Tk_ObjCustomOption;
+
+typedef int Tk_CustomOptionSetProc(
+ ClientData \fIclientData\fR,
+ Tcl_Interp *\fIinterp\fR,
+ Tk_Window \fItkwin\fR,
+ Tcl_Obj **\fIvaluePtr\fR,
+ char *\fIinternalPtr\fR,
+ char *\fIsaveInternalPtr\fR,
+ int \fIflags\fR);
+
+typedef Tcl_Obj *Tk_CustomOptionGetProc(
+ ClientData \fIclientData\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIinternalPtr\fR);
+
+typedef void Tk_CustomOptionRestoreProc(
+ ClientData \fIclientData\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIinternalPtr\fR,
+ char *\fIsaveInternalPtr\fR);
+
+typedef void Tk_CustomOptionFreeProc(
+ ClientData \fIclientData\fR,
+ Tk_Window \fItkwin\fR,
+ char *\fIinternalPtr\fR);
+.CE
+.PP
+The Tk_ObjCustomOption structure contains six fields: a name
+for the custom option type; pointers to the four 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 \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
+A copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure.
+.TP
+\fIinterp\fR
+A pointer to a Tcl interpreter, used for error reporting.
+.TP
+\fITkwin\fR
+A copy of the \fItkwin\fR argument to \fBTk_SetOptions\fR
+.TP
+\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
+default. If the objOffset for the option is non-negative (the option
+value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj
+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 TK_OPTION_NULL_OK flag.
+.TP
+\fIinternalPtr\fR
+A pointer to the internal storage allocated for the option
+in the widget record. The value referenced by \fIinternalPtr\fR
+should be set to the internal representation of the new option value.
+.TP
+\fIsaveInternalPtr\fR
+A pointer to storage allocated in a Tk_SavedOptions structure for the
+internal representation of the original option value. Before setting
+\fIinternalPtr\fR 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
+A copy of the \fIflags\fR field in the Tk_OptionSpec structure for the
+option
+.RE
+.PP
+\fISetProc\fR returns a standard Tcl result: TCL_OK to indicate successful
+processing, or TCL_ERROR to indicate a failure of any kind. An error
+message may be left in the Tcl interpreter given by \fIinterp\fR in
+the case of an error.
+.PP
+The \fIgetProc\fR procedure is invoked by \fBTk_GetOptionValue\fR and
+\fBTk_GetOptionInfo\fR to retrieve a Tcl_Obj representation of the
+internal representation of an option. The \fIclientData\fR argument
+is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
+\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
+is a pointer to the internal representation of the option value.
+\fIGetProc\fR must return a pointer to a Tcl_Obj representing the
+value of the option.
+.PP
+The \fIrestoreProc\fR procedure is invoked by
+\fBTk_RestoreSavedOptions\fR to restore a previously saved internal
+representation of a custom option value. The \fIclientData\fR argument
+is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
+\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
+is a pointer to the internal representation of the option value.
+\fISaveInternalPtr\fR is a pointer to the saved value.
+\fIRestoreProc\fR must copy the value from \fIsaveInternalPtr\fR to
+\fIinternalPtr\fR to restore the value. \fIRestoreProc\fR need not
+free any memory associated with either \fIinternalPtr\fR or
+\fIsaveInternalPtr\fR; \fIfreeProc\fR will be invoked to free that
+memory if necessary. \fIRestoreProc\fR has no return value.
+.PP
+The \fIfreeProc\fR procedure is invoked by \fBTk_SetOptions\fR and
+\fBTk_FreeSavedOptions\fR to free any storage allocated for the
+internal representation of a custom option. The \fIclientData\fR argument
+is a copy of the \fIclientData\fR field in the Tk_ObjCustomOption
+structure. \fITkwin\fR is a copy of the \fItkwin\fR argument to
+\fBTk_GetOptionValue\fR or \fBTk_GetOptionInfo\fR. \fIInternalPtr\fR
+is a pointer to the internal representation of the option value.
+The \fIfreeProc\fR must free any storage associated with the option.
+\fIFreeProc\fR has no return value.
+
+
.SH KEYWORDS
anchor, bitmap, boolean, border, color, configuration option,
cursor, double, font, integer, justify,