'\"'\" 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.'\" '\" SCCS: @(#) ConfigWidg.3 1.30 96/08/27 13:21:18'\" .so man.macros.TH Tk_ConfigureWidget 3 4.1 Tk "Tk Library Procedures".BS.SH NAMETk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue, Tk_FreeOptions \- process configuration options for widgets.SH SYNOPSIS.nf\fB#include <tk.h>\fR.spint\fBTk_ConfigureWidget(\fIinterp, tkwin, specs, argc, argv, widgRec, flags\fB)\fR.spint\fBTk_Offset(\fItype, field\fB)\fR.spint\fBTk_ConfigureInfo(\fIinterp, tkwin, specs, widgRec, argvName, flags\fB)\fR.spint.sp\fBTk_FreeOptions(\fIspecs, widgRec, display, flags\fB)\fR.SH ARGUMENTS.AS Tk_ConfigSpec *widgRec.AP Tcl_Interp *interp inInterpreter to use for returning error messages..AP Tk_Window tkwin inWindow used to represent widget (needed to set up X resources)..AP Tk_ConfigSpec *specs inPointer to table specifying legal configuration options for thiswidget..AP int argc inNumber of arguments in \fIargv\fR..AP char **argv inCommand-line options for configuring widget..AP char *widgRec in/outPoints to widget record structure.  Fields in this structure getmodified by \fBTk_ConfigureWidget\fR to hold configuration information..AP int flags inIf non-zero, then it specifies an OR-ed combination of flags thatcontrol the processing of configuration information.TK_CONFIG_ARGV_ONLY causes the option database and defaults to beignored, and flag bits TK_CONFIG_USER_BIT and higher are used toselectively disable entries in \fIspecs\fR..AP "type name" type inThe name of the type of a widget record..AP "field name" field inThe name of a field in records of type \fItype\fR..AP char *argvName inThe name used on Tcl command lines to refer to a particular option(e.g. when creating a widget or invoking the \fBconfigure\fR widgetcommand).  If non-NULL, then information is returned only for thisoption.  If NULL, then information is returned for all availableoptions..AP Display *display inDisplay containing widget whose record is being freed;  needed inorder to free up resources..BE.SH DESCRIPTION.PP\fBTk_ConfigureWidget\fR is called to configure various aspects of awidget, such as colors, fonts, border width, etc.It is intended as a convenience procedure to reduce the amountof code that must be written in individual widget managers tohandle configuration information.It is typicallyinvoked when widgets are created, and again when the \fBconfigure\fRcommand is invoked for a widget.Although intended primarily for widgets, \fBTk_ConfigureWidget\fRcan be used in other situations where \fIargc-argv\fR informationis to be used to fill in a record structure, such as configuringgraphical elements for a canvas widget or entries of a menu..PP\fBTk_ConfigureWidget\fR processesa 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\fRto fill in fields of \fIwidgRec\fR that are not specified in \fIargv\fR.\fBTk_ConfigureWidget\fR normally returns the value TCL_OK; in thiscase it does not modify \fIinterp\fR.If an erroroccurs then TCL_ERROR is returned and \fBTk_ConfigureWidget\fR willleave an error message in \fIinterp->result\fR in the standard Tclfashion.In the event of an error return, some of the fields of \fIwidgRec\fRcould already have been set, if configuration information for themwas 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..PPThe \fIspecs\fR array specifies the kinds of configuration optionsexpected by the widget.  Each of its entries specifies one configurationoption and has the following structure:.CStypedef 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;.CEThe \fItype\fR field indicates what type of configuration option this is(e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT foran integer value).  The \fItype\fR field indicates how to use thevalue 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 isNULL it means this is a grouped entry;  see GROUPED ENTRIES below).  The\fIdbName\fR and \fIdbClass\fR fields are used to look up a valuefor this option in the option database.  The \fIdefValue\fR fieldspecifies a default value for this configuration option if novalue is specified in either \fIargv\fR or the option database.\fIOffset\fR indicates where in \fIwidgRec\fR to store informationabout this option, and \fIspecFlags\fR contains additional informationto control the processing of this configuration option (see FLAGSbelow).The last field, \fIcustomPtr\fR, is only used if \fItype\fR isTK_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\fRmust contain an even number of fields;  the first of each pairof 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 thatconfiguration option.  If there are entries in \fIspec\fR for whichthere were no matching entries in \fIargv\fR,\fBTk_ConfigureWidget\fR uses the \fIdbName\fR and \fIdbClass\fRfields of the \fIspecs\fR entry to probe the option database;  ifa 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 thevalue for the configuration option.  If the \fIdefValue\fR isNULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in\fIflags\fR, then there is no default value and this \fIspecs\fR entrywill be ignored if no value is specified in \fIargv\fR or theoption database..PPOnce a string value has been determined for a configuration option,\fBTk_ConfigureWidget\fR translates the string value into a more usefulform, such as a color if \fItype\fR is TK_CONFIG_COLOR or an integerif \fItype\fR is TK_CONFIG_INT.  This value is then stored in therecord pointed to by \fIwidgRec\fR.  This record is assumed tocontain information relevant to the manager of the widget;  its exacttype is unknown to \fBTk_ConfigureWidget\fR.  The \fIoffset\fR fieldof each \fIspecs\fR entry indicates where in \fIwidgRec\fR to storethe information about this configuration option.  You should use the\fBTk_Offset\fR macro to generate \fIoffset\fR values (see below fora 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..PPThe \fItype\fR field of each entry in \fIspecs\fR determines whatto do with the string value of that configuration option.  Thelegal values for \fItype\fR, and the corresponding actions, are:.TP\fBTK_CONFIG_ACTIVE_CURSOR\fRThe valuemust be an ASCII string identifying a cursor in a formsuitable 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 cursorfor \fItkwin\fR by calling \fBXDefineCursor\fR.If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the valuemay be an empty string, in which case the target and \fItkwin\fR'sactive cursor will be set to \fBNone\fR.If the previous value of the targetwasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeCursor\fR..TP\fBTK_CONFIG_ANCHOR\fRThe value must be an ASCII string identifying an anchor point in one of the waysaccepted 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\fRThe value must be an ASCII string identifying a bitmap in a formsuitable for passing to \fBTk_GetBitmap\fR.  The value is convertedto a \fBPixmap\fR by calling \fBTk_GetBitmap\fR and the resultis stored in the target.If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the valuemay be an empty string, in which case the target is set to \fBNone\fR.If the previous value of the targetwasn't \fBNone\fR, then it is freed by passing it to \fBTk_FreeBitmap\fR..TP\fBTK_CONFIG_BOOLEAN\fRThe value must be an ASCII string specifying a boolean value.  Anyof 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 ofone of these values, means false.The target is expected to be an integer;  for true values it willbe set to 1 and for false values it will be set to 0..TP\fBTK_CONFIG_BORDER\fRThe value must be an ASCII string identifying a border color in a formsuitable for passing to \fBTk_Get3DBorder\fR.  The value is convertedto a (\fBTk_3DBorder *\fR) by calling \fBTk_Get3DBorder\fR and the resultis stored in the target.If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the valuemay be an empty string, in which case the target will be set to NULL.If the previous value of the targetwasn't NULL, then it is freed by passing it to \fBTk_Free3DBorder\fR..TP\fBTK_CONFIG_CAP_STYLE\fRThe value must bean ASCII string identifying a cap style in one of the waysaccepted by \fBTk_GetCapStyle\fR.The string is converted to an integer value correspondingto the cap style by calling\fBTk_GetCapStyle\fR and the result is stored in the target..TP\fBTK_CONFIG_COLOR\fRThe value must be an ASCII string identifying a color in a formsuitable for passing to \fBTk_GetColor\fR.  The value is convertedto an (\fBXColor *\fR) by calling \fBTk_GetColor\fR and the resultis stored in the target.If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the valuemay be an empty string, in which case the target will be set to \fBNone\fR.If the previous value of the targetwasn't NULL, then it is freed by passing it to \fBTk_FreeColor\fR..TP\fBTK_CONFIG_CURSOR\fRThis option is identical to \fBTK_CONFIG_ACTIVE_CURSOR\fR exceptthat the new cursor is not made the active one for \fItkwin\fR..TP\fBTK_CONFIG_CUSTOM\fRThis option allows applications to define new option types.The \fIcustomPtr\fR field of the entry points to a structuredefining the new option type.See the section CUSTOM OPTION TYPES below for details..TP\fBTK_CONFIG_DOUBLE\fRThe value must be an ASCII floating-point number inthe format accepted by \fBstrtol\fR.  The string is convertedto a \fBdouble\fR value, and the value is stored in thetarget..TP\fBTK_CONFIG_END\fRMarks the end of the table.  The last entry in \fIspecs\fRmust have this type;  all of its other fields are ignored and itwill never match any arguments..TP\fBTK_CONFIG_FONT\fRThe value must be an ASCII string identifying a font in a formsuitable for passing to \fBTk_GetFontStruct\fR.  The value is convertedto an (\fBXFontStruct *\fR) by calling \fBTk_GetFontStruct\fR and the resultis stored in the target.If TK_CONFIG_NULL_OK is specified in \fIspecFlags\fR then the valuemay be an empty string, in which case the target will be set to NULL.If the previous value of the targetwasn't NULL, then it is freed by passing it to \fBTk_FreeFontStruct\fR..TP\fBTK_CONFIG_INT\fRThe value must be an ASCII integer stringin the format accepted by \fBstrtol\fR (e.g. ``0''and ``0x'' prefixes may be used to specify octal or hexadecimalnumbers, respectively).  The string is converted to an integervalue and the integer is stored in the target..TP\fBTK_CONFIG_JOIN_STYLE\fRThe value must bean ASCII string identifying a join style in one of the waysaccepted by \fBTk_GetJoinStyle\fR.The string is converted to an integer value correspondingto the join style by calling\fBTk_GetJoinStyle\fR and the result is stored in the target..TP\fBTK_CONFIG_JUSTIFY\fRThe value must bean ASCII string identifying a justification method in one of theways 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\fRThe value must specify a screen distance in one of the forms acceptableto \fBTk_GetScreenMM\fR.The string is converted to double-precision floating-point distancein millimeters and the value is stored in the target..TP\fBTK_CONFIG_PIXELS\fRThe value must specify screen units in one of the forms acceptableto \fBTk_GetPixels\fR.The string is converted to an integer distance in pixels and thevalue is stored in the target..TP\fBTK_CONFIG_RELIEF\fRThe value must be an ASCII string identifying a relief in a formsuitable for passing to \fBTk_GetRelief\fR.  The value is convertedto an integer relief value by calling \fBTk_GetRelief\fR and the resultis stored in the target..TP\fBTK_CONFIG_STRING\fRA copyof the value is made by allocating memory space with