Subversion Repositories or1k

'\"

'\" 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.1.1.1 2002-01-16 10:25:48 markom Exp $

'\"

.so man.macros

.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures"

.BS

.SH NAME

Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets

.SH SYNOPSIS

.nf

\fB#include \fR

.sp

int

\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR

.sp

int

\fBTk_Offset(\fItype, field\fB)\fR

.sp

int

\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR

.sp

int

.sp

\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR

.SH ARGUMENTS

.AS Tk_ConfigSpec *widgRec

.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 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 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.

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

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 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

\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 TCL_OK; in this

case it does not modify \fIinterp\fR.

If an error

occurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR will

leave an error message in \fIinterp->result\fR 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;

        char *\fIargvName\fR;

        char *\fIdbName\fR;

        char *\fIdbClass\fR;

        char *\fIdefValue\fR;

        int \fIoffset\fR;

        int \fIspecFlags\fR;

        Tk_CustomOption *\fIcustomPtr\fR;

} Tk_ConfigSpec;

.CE

The \fItype\fR field indicates what type of configuration option this is

(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT 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 ``\-font'' or ``\-bg'',

which is compared with the values in \fIargv\fR (if \fIargvName\fR is

NULL it means this is a grouped entry;  see GROUPED ENTRIES 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

TK_CONFIG_CUSTOM;  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 TK_CONFIG_DONT_SET_DEFAULT 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 TK_CONFIG_COLOR or an integer

if \fItype\fR is TK_CONFIG_INT.  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 ``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 TK_CONFIG_NULL_OK 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

wasn't \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 TK_CONFIG_NULL_OK 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

wasn't \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 ``true'', ``yes'', ``on'', or ``1'',

or an abbreviation of one of these values, means true;

any of the values ``false'', ``no'', ``off'', or ``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 TK_CONFIG_NULL_OK 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

wasn't 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 TK_CONFIG_NULL_OK 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

wasn't 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 CUSTOM OPTION TYPES 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_GetFontStruct\fR.  The value is converted

to an (\fBXFontStruct *\fR) by calling \fBTk_GetFontStruct\fR and the result

is stored in the target.

If TK_CONFIG_NULL_OK 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

wasn't NULL, then it is freed by passing it to \fBTk_FreeFontStruct\fR.

.TP

\fBTK_CONFIG_INT\fR

The value must be an ASCII integer string

in the format accepted by \fBstrtol\fR (e.g. ``0''

and ``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

\fBmalloc\fR and copying the value into the dynamically-allocated

space.  A pointer to the new string is stored in the target.

If TK_CONFIG_NULL_OK 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 wasn't NULL, then it is

freed by passing it to \fBfree\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 TK_CONFIG_SYNONYM entry, the entry isn't 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 TK_CONFIG_SYNONYM 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 ``\-background'' and ``\-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 TK_CONFIG_NULL_OK 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

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

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 TK_CONFIG_ARGV_ONLY bit set (i.e., \fIflags\fR | TK_CONFIG_ARGV_ONLY != 0),

then the option database and

\fIdefValue\fR fields are not used.  In this case, if an entry in

\fIspecs\fR doesn't match a field in \fIargv\fR then nothing happens:

the corresponding target isn't 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 isn't 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 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.

.PP

The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY 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 TK_CONFIG_MONO_ONLY in its \fIspecFlags\fR and the

default value for monochrome displays in its \fIdefValue\fR;  the

other entry entry should have the value TK_CONFIG_COLOR_ONLY 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 TK_CONFIG_USER_BIT) 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 \fIinterp->result\fR.  Under normal circumstances

it returns TCL_OK;  if an error occurs then it returns TCL_ERROR

and \fIinterp->result\fR contains an error message.

.PP

If \fIargvName\fR is NULL, then the value left in

\fIinterp->result\fR 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 TK_CONFIG_SYNONYM, 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 \fIinterp->result\fR 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 \fIinterp->result\fR and TCL_OK 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), TCL_ERROR is returned and an error message

is left in \fIinterp->result\fR.

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 TK_CONFIG_COLOR), it frees the resource in the widget record.

If the field in the widget record doesn't 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;

} 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);

typedef char *Tk_OptionPrintProc(

        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 TCL_OK, but if an error occurs

in translating the string to a value then it should return TCL_ERROR

and store an error message in \fIinterp->result\fR.

.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 TK_CONFIG_CUSTOM 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 KEYWORDS

anchor, bitmap, boolean, border, cap style, color, configuration options,

cursor, custom, double, font, integer, join style, justify, millimeters,

pixels, relief, synonym, uid