head	1.25;
access;
symbols
	core-8-5-9:1.20
	core-8-5-8:1.20
	macosx-cocoa-merge:1.24
	macosx-cocoa-premerge:1.24
	macosx-carbon-freeze:1.24
	core-8-5-7:1.20
	core-8-5-6:1.20
	core-8-6-b1:1.22
	core-8-6-a3:1.21
	core-8-5-5:1.20
	core-8-6-a2:1.21
	core-8-5-4:1.20
	core-8-5-3:1.20
	core-8-6-a1:1.20
	core-8-4-19:1.8.2.1
	core-8-5-branch:1.20.0.2
	core-8-5-2:1.20
	core-8-4-18:1.8.2.1
	core-8-5-1:1.20
	core-8-4-17:1.8.2.1
	core-8-5-0:1.20
	core-8-5-b3:1.19
	core-8-5-b2:1.18
	core-8-4-16:1.8.2.1
	core-8-5-b1:1.16
	core-stablilizer-merge:1.16
	core-stabilizer-branch:1.16.0.2
	core-stabilizer-merge:1.20
	core-8-4-15:1.8.2.1
	core-8-5-a6:1.16
	core-8-5-a5:1.14
	core-8-4-14:1.8.2.1
	core-8-5-a4:1.14
	core-8-4-13:1.8.2.1
	core-8-4-12:1.8.2.1
	core-8-4-11:1.8.2.1
	core-8-5-a3:1.13
	core-8-4-10:1.8.2.1
	core-8-4-9-branch:1.8.2.1.0.2
	core-8-5-a2:1.12
	core-8-4-9:1.8.2.1
	core-8-4-8:1.8.2.1
	core-8-4-7:1.8.2.1
	core-8-5-a1:1.9
	core-8-4-6:1.8.2.1
	core-8-4-5:1.8.2.1
	mistachkin-dev-branch:1.8.0.4
	core-8-4-4:1.8
	core-8-4-3:1.8
	core-8-4-branch:1.8.0.2
	core-8-4-2:1.8
	core-8-4-1:1.8
	core-8-3-5:1.5.12.1
	core-8-4-0:1.8
	macosx-8-4-merge-2002-08-31-trunk:1.8
	macosx-8-4-premerge-2002-08-31-branch:1.7.4.1
	macosx-8-4-premerge-2002-08-31-trunk:1.8
	macosx-8-4-merge-2002-08-30-branch:1.7.4.1
	macosx-8-4-merge-2002-08-30-trunk:1.8
	macosx-8-4-merge-2002-08-20-branch:1.7.4.1
	macosx-8-4-merge-2002-08-20-trunk:1.8
	core-8-4-b2:1.8
	core-8-4-b1:1.7
	macosx-premerge-6-9-02:1.7
	core-8-4-a4:1.7
	core-8-3-4:1.5.12.1
	macosx-8-4-branch:1.7.0.4
	macosx-8-4-branchpoint:1.7
	core-8-4-a3:1.7
	core-8-3-3:1.5.12.1
	dgp-privates-into-namespace:1.7.0.2
	tclpro-1-5-0:1.5
	core-8-4-win-speedup:1.6.0.2
	core-8-4-a2:1.6
	tclpro-1-4-1:1.5
	tclpro-1-4-0:1.5
	core-8-3-2:1.5
	ajuba-ajuba2-2-1-base:1.5
	ajuba-ajuba2-2-0:1.5
	core-8-4-a1:1.5
	core-8-3-1-branch:1.5.0.12
	core-8-3-1:1.5
	scriptics-sc-2-0-b5:1.5
	scriptics-sc-2-0-fixed:1.5
	scriptics-sc-2-0-b2:1.5
	scriptics-sc-2-0-b1:1.5
	core-8-3-0:1.5
	core-8-3-b2:1.5
	core-8-3-b1:1.5
	scriptics-sc-1-1:1.5
	scriptics-sc-1-1-b1:1.5
	core-8-2-3:1.5
	scriptics-sc-1-1-branch:1.5.0.10
	scriptics-sc-1-1-base:1.5
	scriptics-sc-1-0:1.5
	scriptics-sc-1-0-branch:1.5.0.8
	scriptics-sc-1-0-base:1.5
	core-8-2-2:1.5
	core-8-2-1:1.5
	scriptics-bc-1-0-b1:1.5
	core-8-2-1-branch:1.5.0.6
	scriptics-tclpro-1-3-0:1.5
	core-8-2-0:1.5
	core-8-2-b3-branch:1.5.0.2
	core-8-2-b3-base:1.5
	scriptics-tclpro-1-3-b4:1.5
	core-8-2-b2:1.5
	scriptics-tclpro-1-3-b3:1.5
	core-8-2-b1:1.5
	scriptics-tclpro-1-3-b2:1.5
	merge-to-mainline-5/21/99:1.5
	scriptics-tclpro-1-3-b2-branch:1.5.0.4
	core-8-1-1:1.5
	scriptics-tclpro-1-3-b1:1.5
	core-8-1-1-base:1.5
	core-8-1-0:1.5
	merge-to-mainline-4-29-99:1.5
	merge-to-mainline-4-23-99:1.5
	core-8-1-branch-old:1.1.0.4
	core-8-0-6-branch:1.2.0.6
	core-8-0-6-base:1.2
	core-8-0-5:1.2
	core-8-1-b3:1.1.4.2
	core-8-1-b2:1.1.4.2
	dev-8-1-stubs-branch:1.1.4.2.0.2
	dev-stubs-branch:1.2.0.4
	scriptics-tclpro-1-2:1.2
	scriptics-tclpro-1-2-b2:1.2
	core-8-1-merge-2/10/99:1.2
	core-8-0-5-branch:1.2.0.2
	core-8-0-5-base:1.2
	scriptics-tclpro-1-2-b1:1.2
	scriptics-tclpro-1-2-a1:1.2
	core-8-1-b1:1.1.4.2
	core-8-0-4:1.2
	core-8-1-a2:1.1.4.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


1.25
date	2010.02.17.19.21.17;	author nijtmans;	state Exp;
branches;
next	1.24;

1.24
date	2009.05.04.09.12.33;	author dkf;	state Exp;
branches;
next	1.23;

1.23
date	2009.01.06.21.58.15;	author nijtmans;	state Exp;
branches;
next	1.22;

1.22
date	2008.10.30.21.39.16;	author nijtmans;	state Exp;
branches;
next	1.21;

1.21
date	2008.06.30.22.57.00;	author dkf;	state Exp;
branches;
next	1.20;

1.20
date	2007.12.13.15.23.42;	author dgp;	state Exp;
branches;
next	1.19;

1.19
date	2007.10.29.16.04.12;	author dkf;	state Exp;
branches;
next	1.18;

1.18
date	2007.10.26.20.13.22;	author dgp;	state Exp;
branches;
next	1.17;

1.17
date	2007.10.24.14.32.56;	author dkf;	state Exp;
branches;
next	1.16;

1.16
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.16.2.1;
next	1.15;

1.15
date	2006.11.15.13.29.17;	author dkf;	state Exp;
branches;
next	1.14;

1.14
date	2005.12.06.09.16.10;	author dkf;	state Exp;
branches;
next	1.13;

1.13
date	2005.04.06.21.11.53;	author dkf;	state Exp;
branches;
next	1.12;

1.12
date	2004.09.19.16.05.36;	author dkf;	state Exp;
branches;
next	1.11;

1.11
date	2004.08.22.15.43.20;	author dkf;	state Exp;
branches;
next	1.10;

1.10
date	2004.03.22.16.04.51;	author dkf;	state Exp;
branches;
next	1.9;

1.9
date	2003.10.06.22.20.22;	author dgp;	state Exp;
branches;
next	1.8;

1.8
date	2002.08.05.04.30.38;	author dgp;	state Exp;
branches
	1.8.2.1;
next	1.7;

1.7
date	2000.11.21.16.35.27;	author dkf;	state Exp;
branches
	1.7.4.1;
next	1.6;

1.6
date	2000.07.25.21.14.34;	author jenglish;	state Exp;
branches
	1.6.2.1;
next	1.5;

1.5
date	99.04.21.21.53.20;	author rjohnson;	state Exp;
branches
	1.5.12.1;
next	1.4;

1.4
date	99.04.16.18.26.12;	author surles;	state Exp;
branches;
next	1.3;

1.3
date	99.04.16.01.51.07;	author stanton;	state Exp;
branches
	1.3.2.1;
next	1.2;

1.2
date	98.09.14.18.22.46;	author stanton;	state Exp;
branches;
next	1.1;

1.1
date	98.04.01.09.40.00;	author rjohnson;	state Exp;
branches
	1.1.4.1;
next	;

1.1.4.1
date	98.09.29.00.25.07;	author stanton;	state Exp;
branches;
next	1.1.4.2;

1.1.4.2
date	98.09.30.02.15.19;	author stanton;	state Exp;
branches;
next	;

1.3.2.1
date	99.04.21.02.32.54;	author rjohnson;	state Exp;
branches;
next	;

1.5.12.1
date	2001.04.04.07.23.48;	author hobbs;	state Exp;
branches;
next	;

1.6.2.1
date	2002.04.02.20.57.53;	author hobbs;	state Exp;
branches;
next	;

1.7.4.1
date	2002.08.20.20.27.00;	author das;	state Exp;
branches;
next	;

1.8.2.1
date	2003.10.06.22.15.17;	author dgp;	state Exp;
branches;
next	;

1.16.2.1
date	2007.11.01.16.37.11;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.25
log
@CONSTify everything related to Tk_ConfigSpec
@
text
@'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.24 2009/05/04 09:12:33 dkf Exp $
'\" 
.so man.macros
.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR
.sp
int
\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
int
\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
.sp
\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR
.SH ARGUMENTS
.AS char *widgRec in/out
.AP Tcl_Interp *interp in
Interpreter to use for returning error messages.
.AP Tk_Window tkwin in
Window used to represent widget (needed to set up X resources).
.AP "const Tk_ConfigSpec" *specs in
Pointer to table specifying legal configuration options for this
widget.
.AP int argc in
Number of arguments in \fIargv\fR.
.AP "const char" **argv in
Command-line options for configuring widget.
.AP char *widgRec in/out
Points to widget record structure.  Fields in this structure get
modified by \fBTk_ConfigureWidget\fR to hold configuration information.
.AP int flags in
If non-zero, then it specifies an OR-ed combination of flags that
control the processing of configuration information.
\fBTK_CONFIG_ARGV_ONLY\fR causes the option database and defaults to be
ignored, and flag bits \fBTK_CONFIG_USER_BIT\fR and higher are used to
selectively disable entries in \fIspecs\fR.
.AP "type name" type in
The name of the type of a widget record.
.AP "field name" field in
The name of a field in records of type \fItype\fR.
.AP "const char" *argvName in
The name used on Tcl command lines to refer to a particular option
(e.g. when creating a widget or invoking the \fBconfigure\fR widget
command).  If non-NULL, then information is returned only for this
option.  If NULL, then information is returned for all available
options.
.AP Display *display in
Display containing widget whose record is being freed;  needed in
order to free up resources.
.BE
.SH DESCRIPTION
.PP
Note: \fBTk_ConfigureWidget\fR should be replaced with the new
\fBTcl_Obj\fR based API \fBTk_SetOptions\fR.  The old interface is
retained for backward compatibility.
.PP
\fBTk_ConfigureWidget\fR is called to configure various aspects of a
widget, such as colors, fonts, border width, etc.
It is intended as a convenience procedure to reduce the amount
of code that must be written in individual widget managers to
handle configuration information.
It is typically
invoked when widgets are created, and again when the \fBconfigure\fR
command is invoked for a widget.
Although intended primarily for widgets, \fBTk_ConfigureWidget\fR
can be used in other situations where \fIargc-argv\fR information
is to be used to fill in a record structure, such as configuring
graphical elements for a canvas widget or entries of a menu.
.PP
\fBTk_ConfigureWidget\fR processes
a table specifying the configuration options that are supported
(\fIspecs\fR) and a collection of command-line arguments (\fIargc\fR and
\fIargv\fR) to fill in fields of a record (\fIwidgRec\fR).
It uses the option database and defaults specified in \fIspecs\fR
to fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.
\fBTk_ConfigureWidget\fR normally returns the value \fBTCL_OK\fR; in this
case it does not modify \fIinterp\fR.
If an error
occurs then \fBTCL_ERROR\fR is returned and \fBTk_ConfigureWidget\fR will
leave an error message in interpreter \fIinterp\fR's result in the standard Tcl
fashion.
In the event of an error return, some of the fields of \fIwidgRec\fR
could already have been set, if configuration information for them
was successfully processed before the error occurred.
The other fields will be set to reasonable initial values so that
\fBTk_FreeOptions\fR can be called for cleanup.
.PP
The \fIspecs\fR array specifies the kinds of configuration options
expected by the widget.  Each of its entries specifies one configuration
option and has the following structure:
.CS
typedef struct {
    int \fItype\fR;
    const char *\fIargvName\fR;
    const char *\fIdbName\fR;
    const char *\fIdbClass\fR;
    const char *\fIdefValue\fR;
    int \fIoffset\fR;
    int \fIspecFlags\fR;
    const Tk_CustomOption *\fIcustomPtr\fR;
} \fBTk_ConfigSpec\fR;
.CE
The \fItype\fR field indicates what type of configuration option this is
(e.g. \fBTK_CONFIG_COLOR\fR for a color value, or \fBTK_CONFIG_INT\fR for
an integer value).  The \fItype\fR field indicates how to use the
value of the option (more on this below).
The \fIargvName\fR field is a string such as
.QW \-font
or
.QW \-bg ,
which is compared with the values in \fIargv\fR (if \fIargvName\fR is
NULL it means this is a grouped entry;  see \fBGROUPED ENTRIES\fR below).  The
\fIdbName\fR and \fIdbClass\fR fields are used to look up a value
for this option in the option database.  The \fIdefValue\fR field
specifies a default value for this configuration option if no
value is specified in either \fIargv\fR or the option database.
\fIOffset\fR indicates where in \fIwidgRec\fR to store information
about this option, and \fIspecFlags\fR contains additional information
to control the processing of this configuration option (see FLAGS
below).
The last field, \fIcustomPtr\fR, is only used if \fItype\fR is
\fBTK_CONFIG_CUSTOM\fR;  see CUSTOM OPTION TYPES below.
.PP
\fBTk_ConfigureWidget\fR first processes \fIargv\fR to see which
(if any) configuration options are specified there.  \fIArgv\fR
must contain an even number of fields;  the first of each pair
of fields must match the \fIargvName\fR of some entry in \fIspecs\fR
(unique abbreviations are acceptable),
and the second field of the pair contains the value for that
configuration option.  If there are entries in \fIspec\fR for which
there were no matching entries in \fIargv\fR,
\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fR
fields of the \fIspecs\fR entry to probe the option database;  if
a value is found, then it is used as the value for the option.
Finally, if no entry is found in the option database, the
\fIdefValue\fR field of the \fIspecs\fR entry is used as the
value for the configuration option.  If the \fIdefValue\fR is
NULL, or if the \fBTK_CONFIG_DONT_SET_DEFAULT\fR bit is set in
\fIflags\fR, then there is no default value and this \fIspecs\fR entry
will be ignored if no value is specified in \fIargv\fR or the
option database.
.PP
Once a string value has been determined for a configuration option,
\fBTk_ConfigureWidget\fR translates the string value into a more useful
form, such as a color if \fItype\fR is \fBTK_CONFIG_COLOR\fR or an integer
if \fItype\fR is \fBTK_CONFIG_INT\fR.  This value is then stored in the
record pointed to by \fIwidgRec\fR.  This record is assumed to
contain information relevant to the manager of the widget;  its exact
type is unknown to \fBTk_ConfigureWidget\fR.  The \fIoffset\fR field
of each \fIspecs\fR entry indicates where in \fIwidgRec\fR to store
the information about this configuration option.  You should use the
\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below for
a description of \fBTk_Offset\fR).  The location indicated by
\fIwidgRec\fR and \fIoffset\fR will be referred to as the
.QW target
in the descriptions below.
.PP
The \fItype\fR field of each entry in \fIspecs\fR determines what
to do with the string value of that configuration option.  The
legal values for \fItype\fR, and the corresponding actions, are:
.TP
\fBTK_CONFIG_ACTIVE_CURSOR\fR
The value
must be an ASCII string identifying a cursor in a form
suitable for passing to \fBTk_GetCursor\fR. 
The value is converted to a \fBTk_Cursor\fR by calling
\fBTk_GetCursor\fR and the result is stored in the target.
In addition, the resulting cursor is made the active cursor
for \fItkwin\fR by calling \fBXDefineCursor\fR.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target and \fItkwin\fR's
active cursor will be set to \fBNone\fR.
If the previous value of the target
was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
.TP
\fBTK_CONFIG_ANCHOR\fR
The value must be an ASCII string identifying an anchor point in one of the ways
accepted by \fBTk_GetAnchor\fR.
The string is converted to a \fBTk_Anchor\fR by calling
\fBTk_GetAnchor\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_BITMAP\fR
The value must be an ASCII string identifying a bitmap in a form
suitable for passing to \fBTk_GetBitmap\fR.  The value is converted
to a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target is set to \fBNone\fR.
If the previous value of the target
was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
.TP
\fBTK_CONFIG_BOOLEAN\fR
The value must be an ASCII string specifying a boolean value.  Any
of the values
.QW true ,
.QW yes ,
.QW on ,
or
.QW 1 ,
or an abbreviation of one of these values, means true;
any of the values
.QW false ,
.QW no ,
.QW off ,
or
.QW 0 ,
or an abbreviation of one of these values, means false.
The target is expected to be an integer;  for true values it will
be set to 1 and for false values it will be set to 0.
.TP
\fBTK_CONFIG_BORDER\fR
The value must be an ASCII string identifying a border color in a form
suitable for passing to \fBTk_Get3DBorder\fR.  The value is converted
to a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target
was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
.TP
\fBTK_CONFIG_CAP_STYLE\fR
The value must be
an ASCII string identifying a cap style in one of the ways
accepted by \fBTk_GetCapStyle\fR.
The string is converted to an integer value corresponding
to the cap style by calling
\fBTk_GetCapStyle\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_COLOR\fR
The value must be an ASCII string identifying a color in a form
suitable for passing to \fBTk_GetColor\fR.  The value is converted
to an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to \fBNone\fR.
If the previous value of the target
was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
.TP
\fBTK_CONFIG_CURSOR\fR
This option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR except
that the new cursor is not made the active one for \fItkwin\fR.
.TP
\fBTK_CONFIG_CUSTOM\fR
This option allows applications to define new option types.
The \fIcustomPtr\fR 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_CONFIG_DOUBLE\fR
The value must be an ASCII floating-point number in
the format accepted by \fBstrtol\fR.  The string is converted
to a \fBdouble\fR value, and the value is stored in the
target.
.TP
\fBTK_CONFIG_END\fR
Marks the end of the table.  The last entry in \fIspecs\fR
must have this type;  all of its other fields are ignored and it
will never match any arguments.
.TP
\fBTK_CONFIG_FONT\fR
The value must be an ASCII string identifying a font in a form
suitable for passing to \fBTk_GetFont\fR.  The value is converted
to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target
was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
.TP
\fBTK_CONFIG_INT\fR
The value must be an ASCII integer string
in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
numbers, respectively).  The string is converted to an integer
value and the integer is stored in the target.
.TP
\fBTK_CONFIG_JOIN_STYLE\fR
The value must be
an ASCII string identifying a join style in one of the ways
accepted by \fBTk_GetJoinStyle\fR.
The string is converted to an integer value corresponding
to the join style by calling
\fBTk_GetJoinStyle\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_JUSTIFY\fR
The value must be
an ASCII string identifying a justification method in one of the
ways accepted by \fBTk_GetJustify\fR.
The string is converted to a \fBTk_Justify\fR by calling
\fBTk_GetJustify\fR and the result is stored in the target.
.TP
\fBTK_CONFIG_MM\fR
The value must specify a screen distance in one of the forms acceptable
to \fBTk_GetScreenMM\fR.
The string is converted to double-precision floating-point distance
in millimeters and the value is stored in the target.
.TP
\fBTK_CONFIG_PIXELS\fR
The value must specify screen units in one of the forms acceptable
to \fBTk_GetPixels\fR.
The string is converted to an integer distance in pixels and the
value is stored in the target.
.TP
\fBTK_CONFIG_RELIEF\fR
The value must be an ASCII string identifying a relief in a form
suitable for passing to \fBTk_GetRelief\fR.  The value is converted
to an integer relief value by calling \fBTk_GetRelief\fR and the result
is stored in the target.
.TP
\fBTK_CONFIG_STRING\fR
A copy
of the value is made by allocating memory space with
\fBTcl_Alloc\fR and copying the value into the dynamically-allocated
space.  A pointer to the new string is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR then the value
may be an empty string, in which case the target will be set to NULL.
If the previous value of the target was not NULL, then it is
freed by passing it to \fBTcl_Free\fR.
.TP
\fBTK_CONFIG_SYNONYM\fR
This \fItype\fR value identifies special entries in \fIspecs\fR that
are synonyms for other entries.  If an \fIargv\fR value matches the
\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
directly. Instead, \fBTk_ConfigureWidget\fR searches \fIspecs\fR
for another entry whose \fIargvName\fR is the same as the \fIdbName\fR
field in the \fBTK_CONFIG_SYNONYM\fR entry;  this new entry is used just
as if its \fIargvName\fR had matched the \fIargv\fR value.  The
synonym mechanism allows multiple \fIargv\fR values to be used for
a single configuration option, such as
.QW \-background
and
.QW \-bg .
.TP
\fBTK_CONFIG_UID\fR
The value is translated to a \fBTk_Uid\fR
(by passing it to \fBTk_GetUid\fR).  The resulting value
is stored in the target.
If \fBTK_CONFIG_NULL_OK\fR is specified in \fIspecFlags\fR and the value
is an empty string then the target will be set to NULL.
.TP
\fBTK_CONFIG_WINDOW\fR
The value must be a window path name.  It is translated to a
\fBTk_Window\fR token and the token is stored in the target.
.SH "GROUPED ENTRIES"
.PP
In some cases it is useful to generate multiple resources from
a single configuration value.  For example, a color name might
be used both to generate the background color for a widget (using
\fBTK_CONFIG_COLOR\fR) and to generate a 3-D border to draw around the
widget (using \fBTK_CONFIG_BORDER\fR).  In cases like this it is possible
to specify that several consecutive entries in \fIspecs\fR are to
be treated as a group.  The first entry is used to determine a value
(using its \fIargvName\fR, \fIdbName\fR,
\fIdbClass\fR, and \fIdefValue\fR fields).  The value will be processed
several times (one for each entry in the group), generating multiple
different resources and modifying multiple targets within \fIwidgRec\fR.
Each of the entries after the first must have a NULL value in its
\fIargvName\fR field;  this indicates that the entry is to be grouped
with the entry that precedes it.  Only the \fItype\fR and \fIoffset\fR
fields are used from these follow-on entries.
.SH "FLAGS"
.PP
The \fIflags\fR argument passed to \fBTk_ConfigureWidget\fR is used
in conjunction with the \fIspecFlags\fR fields in the entries of \fIspecs\fR
to provide additional control over the processing of configuration
options.  These values are used in three different ways as
described below.
.PP
First, if the \fIflags\fR argument to \fBTk_ConfigureWidget\fR has
the \fBTK_CONFIG_ARGV_ONLY\fR bit set (i.e., \fIflags\fR | \fBTK_CONFIG_ARGV_ONLY\fR != 0),
then the option database and
\fIdefValue\fR fields are not used.  In this case, if an entry in
\fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
the corresponding target is not modified.  This feature is useful
when the goal is to modify certain configuration options while
leaving others in their current state, such as when a \fBconfigure\fR
widget command is being processed.
.PP
Second, the \fIspecFlags\fR field of an entry in \fIspecs\fR may be used
to control the processing of that entry.  Each \fIspecFlags\fR
field may consists of an OR-ed combination of the following values:
.TP
\fBTK_CONFIG_COLOR_ONLY\fR
If this bit is set then the entry will only be considered if the
display for \fItkwin\fR has more than one bit plane.  If the display
is monochromatic then this \fIspecs\fR entry will be ignored.
.TP
\fBTK_CONFIG_MONO_ONLY\fR
If this bit is set then the entry will only be considered if the
display for \fItkwin\fR has exactly one bit plane.  If the display
is not monochromatic then this \fIspecs\fR entry will be ignored.
.TP
\fBTK_CONFIG_NULL_OK\fR
This bit is only relevant for some types of entries (see the
descriptions of the various entry types above).
If this bit is set, it indicates that an empty string value
for the field is acceptable and if it occurs then the
target should be set to NULL or \fBNone\fR, depending
on the type of the target.
This flag 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.
If this bit is not set then empty strings are processed as strings,
which generally results in an error.
.TP
\fBTK_CONFIG_DONT_SET_DEFAULT\fR
If this bit is one, it means that the \fIdefValue\fR field of the
entry should only be used for returning the default value in
\fBTk_ConfigureInfo\fR.
In calls to \fBTk_ConfigureWidget\fR no default will be supplied
for entries with this flag set;  it is assumed that the
caller has already supplied a default value in the target location.
This flag provides a performance optimization where it is expensive
to process the default string:  the client can compute the default
once, save the value, and provide it before calling
\fBTk_ConfigureWidget\fR.
.TP
\fBTK_CONFIG_OPTION_SPECIFIED\fR
This bit is
deprecated. It used to be set and cleared by \fBTk_ConfigureWidget\fR
so that callers could detect what entries were specified in
\fIargv\fR, but it was removed because it was inherently
thread-unsafe. Code that wishes to detect what options were specified
should use \fBTk_SetOptions\fR instead.
.PP
The \fBTK_CONFIG_MONO_ONLY\fR and \fBTK_CONFIG_COLOR_ONLY\fR flags are typically
used to specify different default values for
monochrome and color displays.  This is done by creating two
entries in \fIspecs\fR that are identical except for their
\fIdefValue\fR and \fIspecFlags\fR fields.  One entry should have
the value \fBTK_CONFIG_MONO_ONLY\fR in its \fIspecFlags\fR and the
default value for monochrome displays in its \fIdefValue\fR;  the
other entry should have the value \fBTK_CONFIG_COLOR_ONLY\fR in
its \fIspecFlags\fR and the appropriate \fIdefValue\fR for
color displays.
.PP
Third, it is possible to use \fIflags\fR and \fIspecFlags\fR
together to selectively disable some entries.  This feature is
not needed very often.  It is useful in cases where several
similar kinds of widgets are implemented in one place.  It allows
a single \fIspecs\fR table to be created with all the configuration
options for all the widget types.  When processing a particular
widget type, only entries relevant to that type will be used.  This
effect is achieved by setting the high-order bits (those in positions
equal to or greater than \fBTK_CONFIG_USER_BIT\fR) in \fIspecFlags\fR
values or in \fIflags\fR.  In order for a particular entry in
\fIspecs\fR to be used, its high-order bits must match exactly
the high-order bits of the \fIflags\fR value passed to
\fBTk_ConfigureWidget\fR.  If a \fIspecs\fR table is being used
for N different widget types, then N of the high-order bits will
be used.  Each \fIspecs\fR entry will have one of more of those
bits set in its \fIspecFlags\fR field to indicate the widget types
for which this entry is valid.  When calling \fBTk_ConfigureWidget\fR,
\fIflags\fR will have a single one of these bits set to select the
entries for the desired widget type.  For a working example of
this feature, see the code in tkButton.c.
.SH TK_OFFSET
.PP
The \fBTk_Offset\fR macro is provided as a safe way of generating
the \fIoffset\fR values for entries in Tk_ConfigSpec 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 TK_CONFIGUREINFO
.PP
The \fBTk_ConfigureInfo\fR procedure may be used to obtain
information about one or all of the options for a given widget.
Given a token for a window (\fItkwin\fR), a table describing the
configuration options for a class of widgets (\fIspecs\fR), a
pointer to a widget record containing the current information for
a widget (\fIwidgRec\fR), and a NULL \fIargvName\fR argument,
\fBTk_ConfigureInfo\fR generates a string describing all of the
configuration options for the window.  The string is placed
in interpreter \fIinterp\fR's result.  Under normal circumstances
it returns \fBTCL_OK\fR;  if an error occurs then it returns \fBTCL_ERROR\fR
and the interpreter's result will contain an error message.
.PP
If \fIargvName\fR is NULL, then the value left in
the interpreter's result by \fBTk_ConfigureInfo\fR
consists of a list of one or more entries, each of which describes
one configuration option (i.e. one entry in \fIspecs\fR).  Each
entry in the list will contain either two or five values.  If the
corresponding entry in \fIspecs\fR has type \fBTK_CONFIG_SYNONYM\fR, then
the list will contain two values:  the \fIargvName\fR for the entry
and the \fIdbName\fR (synonym name).  Otherwise the list will contain
five values:  \fIargvName\fR, \fIdbName\fR, \fIdbClass\fR, \fIdefValue\fR,
and current value.  The current value is computed from the appropriate
field of \fIwidgRec\fR by calling procedures like \fBTk_NameOfColor\fR.
.PP
If the \fIargvName\fR argument to \fBTk_ConfigureInfo\fR is non-NULL,
then it indicates a single option, and information is returned only
for that option.  The string placed in the interpreter's result will be
a list containing two or five values as described above;  this will
be identical to the corresponding sublist that would have been returned
if \fIargvName\fR had been NULL.
.PP
The \fIflags\fR argument to \fBTk_ConfigureInfo\fR is used to restrict
the \fIspecs\fR entries to consider, just as for \fBTk_ConfigureWidget\fR.
.SH TK_CONFIGUREVALUE
.PP
\fBTk_ConfigureValue\fR takes arguments similar to \fBTk_ConfigureInfo\fR;
instead of returning a list of values, it just returns the current value
of the option given by \fIargvName\fR (\fIargvName\fR must not be NULL).
The value is returned in interpreter \fIinterp\fR's result and \fBTCL_OK\fR is
normally returned as the procedure's result.
If an error occurs in \fBTk_ConfigureValue\fR (e.g., \fIargvName\fR is
not a valid option name), \fBTCL_ERROR\fR is returned and an error message
is left in the interpreter's result.
This procedure is typically called to implement \fBcget\fR widget
commands.
.SH TK_FREEOPTIONS
.PP
The \fBTk_FreeOptions\fR procedure may be invoked during widget cleanup
to release all of the resources associated with configuration options.
It scans through \fIspecs\fR and for each entry corresponding to a
resource that must be explicitly freed (e.g. those with
type \fBTK_CONFIG_COLOR\fR), it frees the resource in the widget record.
If the field in the widget record does not refer to a resource (e.g.
it contains a null pointer) then no resource is freed for that
entry.
After freeing a resource, \fBTk_FreeOptions\fR sets the
corresponding field of the widget record to null.
.SH "CUSTOM OPTION TYPES"
.PP
Applications can extend the built-in configuration types with additional
configuration types by writing procedures to parse and print options
of the a type and creating a structure pointing to those procedures:
.CS
typedef struct Tk_CustomOption {
    Tk_OptionParseProc *\fIparseProc\fR;
    Tk_OptionPrintProc *\fIprintProc\fR;
    ClientData \fIclientData\fR;
} \fBTk_CustomOption\fR;

typedef int \fBTk_OptionParseProc\fR(
        ClientData \fIclientData\fR,
        Tcl_Interp *\fIinterp\fR,
        Tk_Window \fItkwin\fR,
        char *\fIvalue\fR,
        char *\fIwidgRec\fR,
        int \fIoffset\fR);

typedef const char *\fBTk_OptionPrintProc\fR(
        ClientData \fIclientData\fR,
        Tk_Window \fItkwin\fR,
        char *\fIwidgRec\fR,
        int \fIoffset\fR,
        Tcl_FreeProc **\fIfreeProcPtr\fR);
.CE
The Tk_CustomOption structure contains three fields, which are pointers
to the two 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 \fIparseProc\fR procedure is invoked by
\fBTk_ConfigureWidget\fR to parse a string and store the resulting
value in the widget record.
The \fIclientData\fR argument is a copy of the \fIclientData\fR
field in the Tk_CustomOption structure.
The \fIinterp\fR argument points to a Tcl interpreter used for
error reporting.  \fITkwin\fR is a copy of the \fItkwin\fR argument
to \fBTk_ConfigureWidget\fR.  The \fIvalue\fR argument is a string
describing the value for the option;  it could have been specified
explicitly in the call to \fBTk_ConfigureWidget\fR or it could
come from the option database or a default.
\fIValue\fR will never be a null pointer but it may point to
an empty string.
\fIRecordPtr\fR is the same as the \fIwidgRec\fR argument to
\fBTk_ConfigureWidget\fR;  it points to the start of the widget
record to modify.
The last argument, \fIoffset\fR, gives the offset in bytes from the start
of the widget record to the location where the option value is to
be placed.  The procedure should translate the string to whatever
form is appropriate for the option and store the value in the widget
record.  It should normally return \fBTCL_OK\fR, but if an error occurs
in translating the string to a value then it should return \fBTCL_ERROR\fR
and store an error message in interpreter \fIinterp\fR's result.
.PP
The \fIprintProc\fR procedure is called
by \fBTk_ConfigureInfo\fR to produce a string value describing an
existing option.
Its \fIclientData\fR, \fItkwin\fR, \fIwidgRec\fR, and \fIoffset\fR
arguments all have the same meaning as for Tk_OptionParseProc
procedures.
The \fIprintProc\fR procedure should examine the option whose value
is stored at \fIoffset\fR in \fIwidgRec\fR, produce a string describing
that option, and return a pointer to the string.
If the string is stored in dynamically-allocated memory, then
the procedure must set \fI*freeProcPtr\fR to the address of
a procedure to call to free the string's memory;  \fBTk_ConfigureInfo\fR
will call this procedure when it is finished with the string.
If the result string is stored in static memory then \fIprintProc\fR
need not do anything with the \fIfreeProcPtr\fR argument.
.PP
Once \fIparseProc\fR and \fIprintProc\fR have been defined and a
Tk_CustomOption structure has been created for them, options of this
new type may be manipulated with Tk_ConfigSpec entries whose \fItype\fR
fields are \fBTK_CONFIG_CUSTOM\fR and whose \fIcustomPtr\fR fields point
to the Tk_CustomOption structure.
.SH EXAMPLES
.PP
Although the explanation of \fBTk_ConfigureWidget\fR is fairly
complicated, its actual use is pretty straightforward.
The easiest way to get started is to copy the code
from an existing widget.
The library implementation of frames
(tkFrame.c) has a simple configuration table, and the library
implementation of buttons (tkButton.c) has a much more complex
table that uses many of the fancy \fIspecFlags\fR mechanisms.
.SH "SEE ALSO"
Tk_SetOptions(3)
.SH KEYWORDS
anchor, bitmap, boolean, border, cap style, color, configuration options,
cursor, custom, double, font, integer, join style, justify, millimeters,
pixels, relief, synonym, uid
@


1.24
log
@Purge mention of interp->result. [Bug 2431507]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.23 2009/01/06 21:58:15 nijtmans Exp $
d30 1
a30 1
.AS Tk_ConfigSpec *widgRec in/out
d35 1
a35 1
.AP Tk_ConfigSpec *specs in
@


1.23
log
@A few const -> CONST86 modifications, improving
backwards compatibility. Change Tk_ItemIndexProc
and Tk_ItemInsertProc signature to have a Tcl_Obj parameter
in stead of a string parameter. This is binary
and source compatible with previous API, it just prevents
the need for a type cast in the Tk_ItemType table construction.
Bring doc in line with API.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.22 2008/10/30 21:39:16 nijtmans Exp $
d94 1
a94 1
leave an error message in \fIinterp->result\fR in the standard Tcl
d491 1
a491 1
in \fIinterp->result\fR.  Under normal circumstances
d493 1
a493 1
and \fIinterp->result\fR contains an error message.
d496 1
a496 1
\fIinterp->result\fR by \fBTk_ConfigureInfo\fR
d509 1
a509 1
for that option.  The string placed in \fIinterp->result\fR will be
d521 1
a521 1
The value is returned in \fIinterp->result\fR and \fBTCL_OK\fR is
d525 1
a525 1
is left in \fIinterp->result\fR.
d595 1
a595 1
and store an error message in \fIinterp->result\fR.
@


1.22
log
@[Bug 2190619] Warnings due to Tk_SmoothMethod
name constness change.

Although dkf's solution (simply adding a type cast)
is correct as well, changing the return value (as das
suggested) has the advantage that
all Tk_OptionPrintProc implementations don't
need a type cast any more in its code. This
makes all those functions robust against
the -Wwrite-strings warning option.

Further on, the customPtr field of Tk_ConfigSpec
can be a constant, without any danger of
source incompatibility.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.21 2008/06/30 22:57:00 dkf Exp $
d108 4
a111 4
    char *\fIargvName\fR;
    char *\fIdbName\fR;
    char *\fIdbClass\fR;
    char *\fIdefValue\fR;
@


1.21
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.20 2007/12/13 15:23:42 dgp Exp $
d114 1
a114 1
    Tk_CustomOption *\fIcustomPtr\fR;
d560 1
a560 1
typedef char *\fBTk_OptionPrintProc\fR(
@


1.20
log
@merge stable branch onto HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.16.2.1 2007/11/01 16:37:11 dgp Exp $
d66 1
a66 1
.PP 
d115 1
a115 1
} Tk_ConfigSpec;
a360 1

a377 1

a436 1
.VS 8.5
a441 1
.VE 8.5
a473 1

a480 1

a515 1

a527 1

a539 1

d550 1
a550 9
} Tk_CustomOption;

typedef int Tk_OptionParseProc(
    ClientData \fIclientData\fR,
    Tcl_Interp *\fIinterp\fR,
    Tk_Window \fItkwin\fR,
    char *\fIvalue\fR,
    char *\fIwidgRec\fR,
    int \fIoffset\fR);
d552 14
a565 6
typedef char *Tk_OptionPrintProc(
    ClientData \fIclientData\fR,
    Tk_Window \fItkwin\fR,
    char *\fIwidgRec\fR,
    int \fIoffset\fR,
    Tcl_FreeProc **\fIfreeProcPtr\fR);
a617 1

a627 1

a629 1

@


1.19
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.18 2007/10/26 20:13:22 dgp Exp $
@


1.18
log
@        * doc/*.1:              Revert doc changes that broke
        * doc/*.3:              `make html` so we can get the release
        * doc/*.n:              out the door.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.16 2007/01/05 00:00:48 nijtmans Exp $
d121 4
a124 1
The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'',
d126 1
a126 1
NULL it means this is a grouped entry;  see GROUPED ENTRIES below).  The
d168 2
a169 1
\fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target''
d188 1
a188 1
wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
d204 1
a204 1
wasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
d208 6
a213 1
of the values ``true'', ``yes'', ``on'', or ``1'',
d215 7
a221 2
any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of
one of these values, means false.
d233 1
a233 1
wasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
d251 1
a251 1
wasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
d282 1
a282 1
wasn't NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
d286 5
a290 2
in the format accepted by \fBstrtol\fR (e.g. ``0''
and ``0x'' prefixes may be used to specify octal or hexadecimal
d334 1
a334 1
If the previous value of the target wasn't NULL, then it is
d340 1
a340 1
\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry isn't used
d346 4
a349 1
a single configuration option, such as ``\-background'' and ``\-bg''.
d392 2
a393 2
\fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens:
the corresponding target isn't modified.  This feature is useful
d422 1
a422 1
If this bit isn't set then empty strings are processed as strings,
d543 1
a543 1
If the field in the widget record doesn't refer to a resource (e.g.
@


1.17
log
@Lots of improvements to look and feel of manual pages
@
text
@d121 1
a121 4
The \fIargvName\fR field is a string such as 
.QW \-font
or
.QW \-bg ,
d165 1
a165 2
\fIwidgRec\fR and \fIoffset\fR will be referred to as the
.QW target
d204 1
a204 6
of the values
.QW true ,
.QW yes ,
.QW on ,
or
.QW 1,
d206 2
a207 7
any of the values
.QW false ,
.QW no ,
.QW off ,
or
.QW 0 ,
or an abbreviation of one of these values, means false.
d272 2
a273 5
in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
d329 1
a329 4
a single configuration option, such as
.QW \-background
and
.QW \-bg .
@


1.16
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.15 2006/11/15 13:29:17 dkf Exp $
d121 4
a124 1
The \fIargvName\fR field is a string such as ``\-font'' or ``\-bg'',
d168 2
a169 1
\fIwidgRec\fR and \fIoffset\fR will be referred to as the ``target''
d208 6
a213 1
of the values ``true'', ``yes'', ``on'', or ``1'',
d215 7
a221 2
any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of
one of these values, means false.
d286 5
a290 2
in the format accepted by \fBstrtol\fR (e.g. ``0''
and ``0x'' prefixes may be used to specify octal or hexadecimal
d346 4
a349 1
a single configuration option, such as ``\-background'' and ``\-bg''.
@


1.16.2.1
log
@merge updates from HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.16 2007/01/05 00:00:48 nijtmans Exp $
d121 1
a121 4
The \fIargvName\fR field is a string such as
.QW \-font
or
.QW \-bg ,
d123 1
a123 1
NULL it means this is a grouped entry;  see \fBGROUPED ENTRIES\fR below).  The
d165 1
a165 2
\fIwidgRec\fR and \fIoffset\fR will be referred to as the
.QW target
d184 1
a184 1
was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR.
d200 1
a200 1
was not \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR.
d204 1
a204 6
of the values
.QW true ,
.QW yes ,
.QW on ,
or
.QW 1 ,
d206 2
a207 7
any of the values
.QW false ,
.QW no ,
.QW off ,
or
.QW 0 ,
or an abbreviation of one of these values, means false.
d219 1
a219 1
was not NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR.
d237 1
a237 1
was not NULL, then it is freed by passing it to \fBTk_FreeColor\fR.
d268 1
a268 1
was not NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
d272 2
a273 5
in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
d317 1
a317 1
If the previous value of the target was not NULL, then it is
d323 1
a323 1
\fIargvName\fR of a \fBTK_CONFIG_SYNONYM\fR entry, the entry is not used
d329 1
a329 4
a single configuration option, such as
.QW \-background
and
.QW \-bg .
d372 2
a373 2
\fIspecs\fR does not match a field in \fIargv\fR then nothing happens:
the corresponding target is not modified.  This feature is useful
d402 1
a402 1
If this bit is not set then empty strings are processed as strings,
d523 1
a523 1
If the field in the widget record does not refer to a resource (e.g.
@


1.15
log
@Convert \fP to \fR so that man-page scrapers have an easier time.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.14 2005/12/06 09:16:10 dkf Exp $
d40 1
a40 1
.AP "CONST char" **argv in
d55 1
a55 1
.AP "CONST char" *argvName in
@


1.14
log
@Doc change to discourage the use of TK_CONFIG_OPTION_SPECIFIED which was not
thread-safe and is now no-longer used.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.13 2005/04/06 21:11:53 dkf Exp $
d67 2
a68 2
Note: \fBTk_ConfigureWidget\fP should be replaced with the new
\fBTcl_Obj\fP based API \fBTk_SetOptions\fP.  The old interface is
@


1.13
log
@Purge old and inaccurate .VS/.VE macros.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.12 2004/09/19 16:05:36 dkf Exp $
d418 8
a425 6
This bit is set and cleared by \fBTk_ConfigureWidget\fR.  Whenever
\fBTk_ConfigureWidget\fR returns, this bit will be set in all the
entries where a value was specified in \fIargv\fR.
It will be zero in all other entries.
This bit provides a way for clients to determine which values
actually changed in a call to \fBTk_ConfigureWidget\fR.
@


1.12
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.11 2004/08/22 15:43:20 dkf Exp $
a65 1
.VS 8.1 
a69 1
.VE 
@


1.11
log
@More doc fixes from Mikhail Kolesnitchenko. [Patch 1013520]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.10 2004/03/22 16:04:51 dkf Exp $
d48 2
a49 2
TK_CONFIG_ARGV_ONLY causes the option database and defaults to be
ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to
d92 1
a92 1
\fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in this
d95 1
a95 1
occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will
d109 8
a116 8
	int \fItype\fR;
	char *\fIargvName\fR;
	char *\fIdbName\fR;
	char *\fIdbClass\fR;
	char *\fIdefValue\fR;
	int \fIoffset\fR;
	int \fIspecFlags\fR;
	Tk_CustomOption *\fIcustomPtr\fR;
d120 1
a120 1
(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for
d135 1
a135 1
TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.
d151 1
a151 1
NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in
d158 2
a159 2
form, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integer
if \fItype\fR is TK_CONFIG_INT.  This value is then stored in the
d182 1
a182 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
d199 1
a199 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
d218 1
a218 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
d236 1
a236 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
d249 1
a249 1
See the section CUSTOM OPTION TYPES below for details.
d267 1
a267 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
d317 1
a317 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the value
d325 1
a325 1
\fIargvName\fR of a TK_CONFIG_SYNONYM entry, the entry isn't used
d328 1
a328 1
field in the TK_CONFIG_SYNONYM entry;  this new entry is used just
d337 1
a337 1
If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR and the value
d349 2
a350 2
TK_CONFIG_COLOR) and to generate a 3-D border to draw around the
widget (using TK_CONFIG_BORDER).  In cases like this it is possible
d371 1
a371 1
the TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0),
d427 1
a427 1
The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically
d432 1
a432 1
the value TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the
d434 1
a434 1
other entry should have the value TK_CONFIG_COLOR_ONLY in
d446 1
a446 1
equal to or greater than TK_CONFIG_USER_BIT) in \fIspecFlags\fR
d478 1
a478 1
it returns TCL_OK;  if an error occurs then it returns TCL_ERROR
d486 1
a486 1
corresponding entry in \fIspecs\fR has type TK_CONFIG_SYNONYM, then
d508 1
a508 1
The value is returned in \fIinterp->result\fR and TCL_OK is
d511 1
a511 1
not a valid option name), TCL_ERROR is returned and an error message
d522 1
a522 1
type TK_CONFIG_COLOR), it frees the resource in the widget record.
d536 3
a538 3
	Tk_OptionParseProc *\fIparseProc\fR;
	Tk_OptionPrintProc *\fIprintProc\fR;
	ClientData \fIclientData\fR;
d542 6
a547 6
	ClientData \fIclientData\fR,
	Tcl_Interp *\fIinterp\fR,
	Tk_Window \fItkwin\fR,
	char *\fIvalue\fR,
	char *\fIwidgRec\fR,
	int \fIoffset\fR);
d550 5
a554 5
	ClientData \fIclientData\fR,
	Tk_Window \fItkwin\fR,
	char *\fIwidgRec\fR,
	int \fIoffset\fR,
	Tcl_FreeProc **\fIfreeProcPtr\fR);
d582 2
a583 2
record.  It should normally return TCL_OK, but if an error occurs
in translating the string to a value then it should return TCL_ERROR
d605 1
a605 1
fields are TK_CONFIG_CUSTOM and whose \fIcustomPtr\fR fields point
@


1.10
log
@Corrected docs to no longer use malloc/free. [Bug 920695]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.9 2003/10/06 22:20:22 dgp Exp $
d434 1
a434 1
other entry entry should have the value TK_CONFIG_COLOR_ONLY in
@


1.9
log
@        * doc/ConfigWidg.3:     Removed reference to Tk_Offset from the
        NAME section to resolve mkLinks conflict with SetOptions.3 [Bug 404197]
        * unix/mkLinks:         make mklinks
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.8 2002/08/05 04:30:38 dgp Exp $
d315 1
a315 1
\fBmalloc\fR and copying the value into the dynamically-allocated
d320 1
a320 1
freed by passing it to \fBfree\fR.
@


1.8
log
@Applied companion patch for Tcl Patch 585105,
updating Tk to use Tcl 8.4's fully CONST-ified
interface, and fully CONSTifying Tk at the
same time.

This patch includes purging Tk of its last
direct access to interp->result.  [Bug 589853]

The substantial changes include copying
event sequence strings into Tcl_DStrings
in tkBind.c, and copying [text] indices into
Tcl_DStrings because parsing them involved
overwriting them.  If this causes performance
trouble, that can be resolved by further
converting them to Tcl_Obj's.

The #defines USE_NON_CONST and USE_COMPAT_CONST
have the same effect for Tk as they do for Tcl.
(They actually change tcl.h)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.7 2000/11/21 16:35:27 dkf Exp $
d14 1
a14 1
Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
a20 3
.sp
int
\fBTk_Offset(\fItype, field\fB)\fR
@


1.8.2.1
log
@        * doc/ConfigWidg.3:     Removed reference to Tk_Offset from the
        NAME section to resolve mkLinks conflict with SetOptions.3 [Bug 404197]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.8 2002/08/05 04:30:38 dgp Exp $
d14 1
a14 1
Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets
d21 3
@


1.7
log
@Added deprecation note from Bug #120944
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.6 2000/07/25 21:14:34 jenglish Exp $
d43 1
a43 1
.AP char **argv in
d58 1
a58 1
.AP char *argvName in
@


1.7.4.1
log
@merged with trunk at tag macosx-8-4-merge-2002-08-20-trunk
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d43 1
a43 1
.AP "CONST char" **argv in
d58 1
a58 1
.AP "CONST char" *argvName in
@


1.6
log
@CanvPsY.3, ConfigWidg.3, CrtImgType.3, CrtItemType.3,
FontId.3, GetFont.3, canvas.n, font.n, options.n, text.n:
Documentation fix: Replaced references to XFontStruct *
and Tk_FontStruct with Tk_Font.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.5 1999/04/21 21:53:20 rjohnson Exp $
d69 6
d621 3
@


1.6.2.1
log
@sync with head
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.7 2000/11/21 16:35:27 dkf Exp $
a68 6
.VS 8.1 
.PP 
Note: \fBTk_ConfigureWidget\fP should be replaced with the new
\fBTcl_Obj\fP based API \fBTk_SetOptions\fP.  The old interface is
retained for backward compatibility.
.VE 
a614 3

.SH "SEE ALSO"
Tk_SetOptions(3)
@


1.5
log
@
Merged 8-1-0 into mainline.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.4 1999/04/16 18:26:12 surles Exp $
d262 1
a262 1
to an (\fBXFontStruct *\fR) by calling \fBTk_GetFont\fR and the result
@


1.5.12.1
log
@doc cleanup and clarifications from 8.4aCVS backport
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.7 2000/11/21 16:35:27 dkf Exp $
a68 6
.VS 8.1 
.PP 
Note: \fBTk_ConfigureWidget\fP should be replaced with the new
\fBTcl_Obj\fP based API \fBTk_SetOptions\fP.  The old interface is
retained for backward compatibility.
.VE 
d262 1
a262 1
to a \fBTk_Font\fR by calling \fBTk_GetFont\fR and the result
a614 3

.SH "SEE ALSO"
Tk_SetOptions(3)
@


1.4
log
@fixed Tk doc bugs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.3 1999/04/16 01:51:07 stanton Exp $
@


1.3
log
@* Merged 8.1 branch into the main trunk
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d261 2
a262 2
suitable for passing to \fBTk_GetFontStruct\fR.  The value is converted
to an (\fBXFontStruct *\fR) by calling \fBTk_GetFontStruct\fR and the result
d267 1
a267 1
wasn't NULL, then it is freed by passing it to \fBTk_FreeFontStruct\fR.
@


1.3.2.1
log
@
Merged with mainline.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.4 1999/04/16 18:26:12 surles Exp $
d261 2
a262 2
suitable for passing to \fBTk_GetFont\fR.  The value is converted
to an (\fBXFontStruct *\fR) by calling \fBTk_GetFont\fR and the result
d267 1
a267 1
wasn't NULL, then it is freed by passing it to \fBTk_FreeFont\fR.
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d29 1
d33 1
a33 1
.AS Tk_ConfigSpec *widgRec
@


1.1
log
@Initial revision
@
text
@d8 1
a8 1
'\" SCCS: @@(#) ConfigWidg.3 1.30 96/08/27 13:21:18
@


1.1.4.1
log
@initial tk8.1a2 version
@
text
@d8 1
a8 1
'\" SCCS: @@(#) ConfigWidg.3 1.32 98/01/02 13:18:16
a28 1
\fBTk_ConfigureValue(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR
d32 1
a32 1
.AS Tk_ConfigSpec *widgRec in/out
@


1.1.4.2
log
@Merged 8.0.3 changes into 8.1
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ConfigWidg.3,v 1.2 1998/09/14 18:22:46 stanton Exp $
@


