Bug [2049429] - Documented TK_OPTION_DONT_SET_DEFAULT

1 files changed, 30 insertions, 20 deletions

diff --git a/doc/SetOptions.3 b/doc/SetOptions.3
index 028467a..f12a00f 100644
--- a/doc/SetOptions.3
+++ b/doc/SetOptions.3
@@ -129,19 +129,21 @@ option table is no longer needed \fBTk_DeleteOptionTable\fR should be
 called to free all of its resources.  All of the option tables
 for a Tcl interpreter are freed automatically if the interpreter is deleted.
 .PP
-\fBTk_InitOptions\fR is invoked when a new widget is created to set
-the default values for all of the widget's configuration options.
-\fBTk_InitOptions\fR is passed a token for an option table (\fIoptionTable\fR)
-and a pointer to a widget record (\fIrecordPtr\fR), which is the C
-structure that holds information about this widget. \fBTk_InitOptions\fR
-uses the information in the option table to
-choose an appropriate default for each option, then it stores the default
-value directly into the widget record, overwriting any information that
-was already present in the widget record.  \fBTk_InitOptions\fR normally
-returns \fBTCL_OK\fR.  If an error occurred while setting the default values
-(e.g., because a default value was erroneous) then \fBTCL_ERROR\fR is returned
-and an error message is left in \fIinterp\fR's result if \fIinterp\fR
-is not NULL.
+\fBTk_InitOptions\fR is invoked when a new widget is created to set the
+default values for all of the widget's configuration options that do not
+have \fBTK_OPTION_DONT_SET_DEFAULT\fR set in their \fIflags\fR field.
+\fBTk_InitOptions\fR is passed a token for an option table
+(\fIoptionTable\fR) and a pointer to a widget record (\fIrecordPtr\fR),
+which is the C structure that holds information about this widget.
+\fBTk_InitOptions\fR uses the information in the option table to choose an
+appropriate default for each option, except those having
+\fBTK_OPTION_DONT_SET_DEFAULT\fR set, then it stores the default value
+directly into the widget record, overwriting any information that was
+already present in the widget record.  \fBTk_InitOptions\fR normally
+returns \fBTCL_OK\fR.  If an error occurred while setting the default
+values (e.g., because a default value was erroneous) then \fBTCL_ERROR\fR
+is returned and an error message is left in \fIinterp\fR's result if
+\fIinterp\fR is not NULL.
 .PP
 \fBTk_SetOptions\fR is invoked to modify configuration options based
 on information specified in a Tcl command.  The command might be one that
@@ -306,19 +308,27 @@ given by \fIinternalOffset\fR.  For example, if the option's type is
 value is not stored in that form.  At least one of the offsets must be
 greater than or equal to zero.
 .PP
-The \fIflags\fR field consists of one or more bits ORed together.  At
-present only a single flag is supported: \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.  If the flag is not set then empty strings will result
-in errors.
+The \fIflags\fR field consists of one or more bits ORed together. The
+following flags are supported:
+.TP
+\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.
+If the flag is not set then empty strings will result in errors.
 \fBTK_OPTION_NULL_OK\fR 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.
 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
+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.
 .PP
 The \fItype\fR field of each Tk_OptionSpec structure determines
 how to parse the value of that configuration option. The