Skip to content

Commit

Permalink
merge core-8-6-branch
Browse files Browse the repository at this point in the history
  • Loading branch information
@fvogelnew1
fvogelnew1 committed Aug 7, 2024
2 parents 5705b04 + bcbf095 commit d12d760
Show file tree
Hide file tree
Showing 96 changed files with 955 additions and 847 deletions.
131 changes: 56 additions & 75 deletions doc/SetOptions.3
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -338,106 +338,93 @@ 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.
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
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
Expand All @@ -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
Expand Down Expand Up @@ -504,15 +489,19 @@ 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.
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
Expand All @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading

0 comments on commit d12d760

Please sign in to comment.