Manual Pages for UNIX Darwin command on man ConfigWidg

TkConfigureWidget(3) Tk Library Procedures TkConfigureWidget(3)

NAME

TkConfigureWidget, TkConfigureInfo, TkConfigureValue, TkFreeOptions

- process configuration options for widgets

SYNOPSIS

##iinncclluuddee <>

int TTkkCCoonnffiigguurreeWWiiddggeett((interp, tkwin, specs, argc, argv, widgRec, flags)) int TTkkCCoonnffiigguurreeIInnffoo((interp, tkwin, specs, widgRec, argvName, flags)) int TTkkCCoonnffiigguurreeVVaalluuee((interp, tkwin, specs, widgRec, argvName, flags)) TkFreeOptions(pc, ige, ipa, lg) AARRGGUUMMEENNTTSS TclInterp *interp (in) Interpreter to use for returning error messages. TkWindow tkwin (in) Window used to represent widget (needed to set up X resources). TkConfigSpec *specs (in) Pointer to table specifying legal configuration options for this widget. int argc (in) Number of arguments in argv.

CONST char **argv (in) Command-line options for configur-

ing widget. char *widgRec (in/out) Points to widget record structure.

Fields in this structure get modi-

fied by TTkkCCoonnffiigguurreeWWiiddggeett to hold configuration information.

int flags (in) If non-zero, then it specifies an

OR-ed combination of flags that

control the processing of configu-

ration information. TKCON-

FIGARGVONLY causes the option database and defaults to be

ignored, and flag bits TKCON-

FIGUSERBIT and higher are used to selectively disable entries in specs. type name type (in) The name of the type of a widget record. field name field (in) The name of a field in records of type type. 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 ccoonnffiigguurree widget com-

mand). If non-NULL, then informa-

tion is returned only for this option. If NULL, then information is returned for all available options. Display *display (in) Display containing widget whose record is being freed; needed in order to free up resources.

DESCRIPTION

Note: TTkkCCoonnffiigguurreeWWiiddggeett should be replaced with the new TTccllOObbjj based |

P TkSetOptions. h od nefc i rtie fr akad opt-

bility. TTkkCCoonnffiigguurreeWWiiddggeett is called to configure various aspects of a widget,

such as colors, fonts, border width, etc. It is intended as a conve-

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

uurree command is invoked for a widget. Although intended primarily for

widgets, TTkkCCoonnffiigguurreeWWiiddggeett can be used in other situations where argc-

argv 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. TTkkCCoonnffiigguurreeWWiiddggeett processes a table specifying the configuration

options that are supported (specs) and a collection of command-line

arguments (argc and argv) to fill in fields of a record (widgRec). It uses the option database and defaults specified in specs to fill in fields of widgRec that are not specified in argv. TTkkCCoonnffiigguurreeWWiiddggeett normally returns the value TCLOK; in this case it does not modify

interp. If an error occurs then TCLERROR is returned and TTkkCCoonnffiigg-

uurreeWWiiddggeett will leave an error message in interp->result in the standard

Tcl fashion. In the event of an error return, some of the fields of widgRec could already have been set, if configuration information for them was successfully processed before the error occurred. The other ils il e e t raoal iiil aus o ht TkFreeOptions can be called for cleanup. The specs array specifies the kinds of configuration options expected by the widget. Each of its entries specifies one configuration option and has the following structure: typedef struct { int type; char *argvName; char *dbName; char *dbClass; char *defValue; int offset; int specFlags; TkCustomOption *customPtr; } TkConfigSpec; The type field indicates what type of configuration option this is

(e.g. TKCONFIGCOLOR for a color value, or TKCONFIGINT for an inte-

ger value). The type field indicates how to use the value of the option (more on this below). The argvName field is a string such as

``-font'' or ``-bg'', which is compared with the values in argv (if

argvName is NULL it means this is a grouped entry; see GROUPED ENTRIES below). The dbName and dbClass fields are used to look up a value for this option in the option database. The defValue field specifies a default value for this configuration option if no value is specified in either argv or the option database. Offset indicates where in widgRec

to store information about this option, and specFlags contains addi-

tional information to control the processing of this configuration option (see FLAGS below). The last field, customPtr, is only used if

type is TKCONFIGCUSTOM; see CUSTOM OPTION TYPES below.

TTkkCCoonnffiigguurreeWWiiddggeett first processes argv to see which (if any) configu-

ration options are specified there. Argv must contain an even number of fields; the first of each pair of fields must match the argvName of

some entry in specs (unique abbreviations are acceptable), and the sec-

ond field of the pair contains the value for that configuration option. If there are entries in spec for which there were no matching entries in argv, TTkkCCoonnffiigguurreeWWiiddggeett uses the dbName and dbClass fields of the specs 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 defValue field of the specs entry is used as the value for the configuration option. If the defValue is NULL, or if the TKCONFIGDONTSETDEFAULT bit is set in flags, then there is no

default value and this specs entry will be ignored if no value is spec-

ified in argv or the option database. Once a string value has been determined for a configuration option, TTkkCCoonnffiigguurreeWWiiddggeett translates the string value into a more useful form, such as a color if type is TKCONFIGCOLOR or an integer if type is TKCONFIGINT. This value is then stored in the record pointed to by widgRec. This record is assumed to contain information relevant to the

manager of the widget; its exact type is unknown to TTkkCCoonnffiigguurreeWWiidd-

ggeett. The offset field of each specs entry indicates where in widgRec to store the information about this configuration option. You should use the TTkkOOffffsseett macro to generate offset values (see below for a

description of TTkkOOffffsseett). The location indicated by widgRec and off-

set will be referred to as the ``target'' in the descriptions below. The type field of each entry in specs determines what to do with the string value of that configuration option. The legal values for type, and the corresponding actions, are: TTKKCCOONNFFIIGGAACCTTIIVVEECCUURRSSOORR The value must be an ASCII string identifying a cursor in a form suitable for passing to TTkkGGeettCCuurrssoorr. The value is converted to a TTkkCCuurrssoorr by calling TTkkGGeettCCuurrssoorr and the result is stored in the target. In addition, the resulting cursor is made the

active cursor for tkwin by calling XXDDeeffiinneeCCuurrssoorr. If TKCON-

FIGNULLOK is specified in specFlags then the value may be an empty string, in which case the target and tkwin's active cursor will be set to NNoonnee. If the previous value of the target wasn't NNoonnee, then it is freed by passing it to TTkkFFrreeeeCCuurrssoorr. TTKKCCOONNFFIIGGAANNCCHHOORR The value must be an ASCII string identifying an anchor point in

one of the ways accepted by TTkkGGeettAAnncchhoorr. The string is con-

verted to a TTkkAAnncchhoorr by calling TTkkGGeettAAnncchhoorr and the result is stored in the target. TTKKCCOONNFFIIGGBBIITTMMAAPP The value must be an ASCII string identifying a bitmap in a form suitable for passing to TTkkGGeettBBiittmmaapp. The value is converted to a PPiixxmmaapp by calling TTkkGGeettBBiittmmaapp and the result is stored in the target. If TKCONFIGNULLOK is specified in specFlags then the value may be an empty string, in which case the target is set to NNoonnee. If the previous value of the target wasn't NNoonnee, then it is freed by passing it to TTkkFFrreeeeBBiittmmaapp. TTKKCCOONNFFIIGGBBOOOOLLEEAANN 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 val-

ues ``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. TTKKCCOONNFFIIGGBBOORRDDEERR The value must be an ASCII string identifying a border color in a form suitable for passing to TTkkGGeett33DDBBoorrddeerr. The value is converted to a (TTkk33DDBBoorrddeerr **) by calling TTkkGGeett33DDBBoorrddeerr and the

result is stored in the target. If TKCONFIGNULLOK is speci-

fied in specFlags 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 TTkkFFrreeee33DDBBoorrddeerr. TTKKCCOONNFFIIGGCCAAPPSSTTYYLLEE The value must be an ASCII string identifying a cap style in one of the ways accepted by TTkkGGeettCCaappSSttyyllee. The string is converted to an integer value corresponding to the cap style by calling TTkkGGeettCCaappSSttyyllee and the result is stored in the target. TTKKCCOONNFFIIGGCCOOLLOORR The value must be an ASCII string identifying a color in a form suitable for passing to TTkkGGeettCCoolloorr. The value is converted to an (XXCCoolloorr **) by calling TTkkGGeettCCoolloorr and the result is stored in the target. If TKCONFIGNULLOK is specified in specFlags then the value may be an empty string, in which case the target will be set to NNoonnee. If the previous value of the target wasn't NULL, then it is freed by passing it to TTkkFFrreeeeCCoolloorr. TTKKCCOONNFFIIGGCCUURRSSOORR This option is identical to TTKKCCOONNFFIIGGAACCTTIIVVEECCUURRSSOORR except that the new cursor is not made the active one for tkwin. TTKKCCOONNFFIIGGCCUUSSTTOOMM This option allows applications to define new option types. The customPtr field of the entry points to a structure defining the

new option type. See the section CUSTOM OPTION TYPES below for

details. TTKKCCOONNFFIIGGDDOOUUBBLLEE

The value must be an ASCII floating-point number in the format

accepted by ssttrrttooll. The string is converted to a ddoouubbllee value, and the value is stored in the target. TTKKCCOONNFFIIGGEENNDD Marks the end of the table. The last entry in specs must have this type; all of its other fields are ignored and it will never match any arguments. TTKKCCOONNFFIIGGFFOONNTT The value must be an ASCII string identifying a font in a form suitable for passing to TTkkGGeettFFoonntt. The value is converted to a TTkkFFoonntt by calling TTkkGGeettFFoonntt and the result is stored in the target. If TKCONFIGNULLOK is specified in specFlags 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 TTkkFFrreeeeFFoonntt. TTKKCCOONNFFIIGGIINNTT The value must be an ASCII integer string in the format accepted by ssttrrttooll (e.g. ``0'' and ``0x'' prefixes may be used to specify

octal or hexadecimal numbers, respectively). The string is con-

verted to an integer value and the integer is stored in the tar-

get. TTKKCCOONNFFIIGGJJOOIINNSSTTYYLLEE The value must be an ASCII string identifying a join style in

one of the ways accepted by TTkkGGeettJJooiinnSSttyyllee. The string is con-

verted to an integer value corresponding to the join style by calling TTkkGGeettJJooiinnSSttyyllee and the result is stored in the target. TTKKCCOONNFFIIGGJJUUSSTTIIFFYY The value must be an ASCII string identifying a justification method in one of the ways accepted by TTkkGGeettJJuussttiiffyy. The string is converted to a TTkkJJuussttiiffyy by calling TTkkGGeettJJuussttiiffyy and the result is stored in the target. TTKKCCOONNFFIIGGMMMM The value must specify a screen distance in one of the forms

acceptable to TTkkGGeettSSccrreeeennMMMM. The string is converted to dou-

ble-precision floating-point distance in millimeters and the

value is stored in the target. TTKKCCOONNFFIIGGPPIIXXEELLSS

The value must specify screen units in one of the forms accept-

able to TTkkGGeettPPiixxeellss. The string is converted to an integer distance in pixels and the value is stored in the target. TTKKCCOONNFFIIGGRREELLIIEEFF The value must be an ASCII string identifying a relief in a form suitable for passing to TTkkGGeettRReelliieeff. The value is converted to an integer relief value by calling TTkkGGeettRReelliieeff and the result is stored in the target. TTKKCCOONNFFIIGGSSTTRRIINNGG

A copy of the value is made by allocating memory space with mmaall-

lloocc and copying the value into the dynamically-allocated space.

A pointer to the new string is stored in the target. If TKCON-

FIGNULLOK is specified in specFlags 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 ffrreeee. TTKKCCOONNFFIIGGSSYYNNOONNYYMM This type value identifies special entries in specs that are

synonyms for other entries. If an argv value matches the argv-

Name of a TKCONFIGSYNONYM entry, the entry isn't used directly. Instead, TTkkCCoonnffiigguurreeWWiiddggeett searches specs for another entry whose argvName is the same as the dbName field in the TKCONFIGSYNONYM entry; this new entry is used just as if its argvName had matched the argv value. The synonym mechanism

allows multiple argv values to be used for a single configura-

tion option, such as ``-background'' and ``-bg''.

TTKKCCOONNFFIIGGUUIIDD The value is translated to a TTkkUUiidd (by passing it to TTkkGGeettUUiidd). The resulting value is stored in the target. If TKCONFIGNULLOK is specified in specFlags and the value is an empty string then the target will be set to NULL. TTKKCCOONNFFIIGGWWIINNDDOOWW The value must be a window path name. It is translated to a TTkkWWiinnddooww token and the token is stored in the target. GGRROOUUPPEEDD EENNTTRRIIEESS 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 TKCONFIGCOLOR) and

to generate a 3-D border to draw around the widget (using TKCON-

FIGBORDER). In cases like this it is possible to specify that several consecutive entries in specs are to be treated as a group. The first entry is used to determine a value (using its argvName, dbName, dbClass, and defValue fields). The value will be processed several times (one for each entry in the group), generating multiple different resources and modifying multiple targets within widgRec. Each of the entries after the first must have a NULL value in its argvName field;

this indicates that the entry is to be grouped with the entry that pre-

cedes it. Only the type and offset fields are used from these follow-

on entries. FFLLAAGGSS The flags argument passed to TTkkCCoonnffiigguurreeWWiiddggeett is used in conjunction with the specFlags fields in the entries of specs to provide additional control over the processing of configuration options. These values are used in three different ways as described below.

First, if the flags argument to TTkkCCoonnffiigguurreeWWiiddggeett has the TKCON-

FIGARGVONLY bit set (i.e., flags | TKCONFIGARGVONLY != 0), then the option database and defValue fields are not used. In this case, if an entry in specs doesn't match a field in argv then nothing happens: the corresponding target isn't modified. This feature is useful when

the goal is to modify certain configuration options while leaving oth-

ers in their current state, such as when a ccoonnffiigguurree widget command is being processed. Second, the specFlags field of an entry in specs may be used to control the processing of that entry. Each specFlags field may consists of an

OR-ed combination of the following values:

TTKKCCOONNFFIIGGCCOOLLOORROONNLLYY If this bit is set then the entry will only be considered if the display for tkwin has more than one bit plane. If the display is monochromatic then this specs entry will be ignored. TTKKCCOONNFFIIGGMMOONNOOOONNLLYY If this bit is set then the entry will only be considered if the display for tkwin has exactly one bit plane. If the display is not monochromatic then this specs entry will be ignored. TTKKCCOONNFFIIGGNNUULLLLOOKK 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 NNoonnee, 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 NNoonnee 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. TTKKCCOONNFFIIGGDDOONNTTSSEETTDDEEFFAAUULLTT If this bit is one, it means that the defValue field of the entry should only be used for returning the default value in TTkkCCoonnffiigguurreeIInnffoo. In calls to TTkkCCoonnffiigguurreeWWiiddggeett 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 tar-

get 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 TTkkCCoonnffiigguurreeWWiiddggeett. TTKKCCOONNFFIIGGOOPPTTIIOONNSSPPEECCIIFFIIEEDD This bit is set and cleared by TTkkCCoonnffiigguurreeWWiiddggeett. Whenever TTkkCCoonnffiigguurreeWWiiddggeett returns, this bit will be set in all the entries where a value was specified in argv. 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 TTkkCCoonnffiigg-

uurreeWWiiddggeett. The TKCONFIGMONOONLY and TKCONFIGCOLORONLY flags are typically

used to specify different default values for monochrome and color dis-

plays. This is done by creating two entries in specs that are identi-

cal except for their defValue and specFlags fields. One entry should have the value TKCONFIGMONOONLY in its specFlags and the default value for monochrome displays in its defValue; the other entry entry should have the value TKCONFIGCOLORONLY in its specFlags and the appropriate defValue for color displays.

Third, it is possible to use flags and specFlags together to selec-

tively disable some entries. This feature is not needed very often.

It is useful in cases where several similar kinds of widgets are imple-

mented in one place. It allows a single specs table to be created with

all the configuration options for all the widget types. When process-

ing 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 TKCONFIGUSERBIT) in specFlags values or in flags. In order for a particular entry in specs to be

used, its high-order bits must match exactly the high-order bits of the

flags value passed to TTkkCCoonnffiigguurreeWWiiddggeett. If a specs table is being

used for N different widget types, then N of the high-order bits will

be used. Each specs entry will have one of more of those bits set in its specFlags field to indicate the widget types for which this entry is valid. When calling TTkkCCoonnffiigguurreeWWiiddggeett, flags 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 tkBut-

ton.c. TTKKOOFFFFSSEETT The TTkkOOffffsseett macro is provided as a safe way of generating the offset

values for entries in TkConfigSpec structures. It takes two argu-

ments: 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. TTKKCCOONNFFIIGGUURREEIINNFFOO The TTkkCCoonnffiigguurreeIInnffoo procedure may be used to obtain information about

one or all of the options for a given widget. Given a token for a win-

dow (tkwin), a table describing the configuration options for a class of widgets (specs), a pointer to a widget record containing the current information for a widget (widgRec), and a NULL argvName argument, TTkkCCoonnffiigguurreeIInnffoo generates a string describing all of the configuration

options for the window. The string is placed in interp->result. Under

normal circumstances it returns TCLOK; if an error occurs then it

returns TCLERROR and interp->result contains an error message.

If argvName is NULL, then the value left in interp->result by TTkkCCoonn-

ffiigguurreeIInnffoo consists of a list of one or more entries, each of which describes one configuration option (i.e. one entry in specs). Each

entry in the list will contain either two or five values. If the cor-

responding entry in specs has type TKCONFIGSYNONYM, then the list will contain two values: the argvName for the entry and the dbName

(synonym name). Otherwise the list will contain five values: argv-

Name, dbName, dbClass, defValue, and current value. The current value is computed from the appropriate field of widgRec by calling procedures like TTkkNNaammeeOOffCCoolloorr.

If the argvName argument to TTkkCCoonnffiigguurreeIInnffoo is non-NULL, then it indi-

cates a single option, and information is returned only for that

option. The string placed in interp->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 argvName had been NULL. The flags argument to TTkkCCoonnffiigguurreeIInnffoo is used to restrict the specs entries to consider, just as for TTkkCCoonnffiigguurreeWWiiddggeett. TTKKCCOONNFFIIGGUURREEVVAALLUUEE TTkkCCoonnffiigguurreeVVaalluuee takes arguments similar to TTkkCCoonnffiigguurreeIInnffoo; instead of returning a list of values, it just returns the current value of the option given by argvName (argvName must not be NULL). The value is

returned in interp->result and TCLOK is normally returned as the pro-

cedure's result. If an error occurs in TTkkCCoonnffiigguurreeVVaalluuee (e.g., argv-

Name is not a valid option name), TCLERROR is returned and an error

message is left in interp->result. This procedure is typically called

to implement ccggeett widget commands. TTKKFFRREEEEOOPPTTIIOONNSS h TkFreeOptions poeue a b ivkd uig igt lau t release all of the resources associated with configuration options. It scans through specs and for each entry corresponding to a resource that must be explicitly freed (e.g. those with type TKCONFIGCOLOR), 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, TkFreeOptions es h crepnig il o te igt eod o null. CCUUSSTTOOMM OOPPTTIIOONN TTYYPPEESS

Applications can extend the built-in configuration types with addi-

tional configuration types by writing procedures to parse and print

options of the a type and creating a structure pointing to those proce-

dures: typedef struct TkCustomOption { TkOptionParseProc *parseProc; TkOptionPrintProc *printProc; ClientData clientData; } TkCustomOption; typedef int TkOptionParseProc( ClientData clientData, TclInterp *interp, TkWindow tkwin, char *value, char *widgRec, int offset); typedef char *TkOptionPrintProc( ClientData clientData, TkWindow tkwin, char *widgRec, int offset, TclFreeProc **freeProcPtr); The TkCustomOption structure contains three fields, which are pointers

to the two procedures and a clientData value to be passed to those pro-

cedures when they are invoked. The clientData value typically points to a structure containing information that is needed by the procedures when they are parsing and printing options. The parseProc procedure is invoked by TTkkCCoonnffiigguurreeWWiiddggeett to parse a

string and store the resulting value in the widget record. The client-

Data argument is a copy of the clientData field in the TkCustomOption structure. The interp argument points to a Tcl interpreter used for

error reporting. Tkwin is a copy of the tkwin argument to TTkkCCoonnffiigg-

uurreeWWiiddggeett. The value argument is a string describing the value for the

option; it could have been specified explicitly in the call to TTkkCCoonn-

ffiigguurreeWWiiddggeett or it could come from the option database or a default. Value will never be a null pointer but it may point to an empty string. RecordPtr is the same as the widgRec argument to TTkkCCoonnffiigguurreeWWiiddggeett;

it points to the start of the widget record to modify. The last argu-

ment, offset, 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 TCLOK, but if an error occurs in translating the

string to a value then it should return TCLERROR and store an error

message in interp->result.

The printProc procedure is called by TTkkCCoonnffiigguurreeIInnffoo to produce a string value describing an existing option. Its clientData, tkwin, widgRec, and offset arguments all have the same meaning as for TkOptionParseProc procedures. The printProc procedure should examine the option whose value is stored at offset in widgRec, 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 *freeProcPtr to the address of a procedure to call to free the string's memory; TTkkCCoonnffiigguurreeIInnffoo will call this procedure when it is finished with the string. If the result string is stored in static

memory then printProc need not do anything with the freeProcPtr argu-

ment. Once parseProc and printProc have been defined and a TkCustomOption structure has been created for them, options of this new type may be

manipulated with TkConfigSpec entries whose type fields are TKCON-

FIGCUSTOM and whose customPtr fields point to the TkCustomOption structure. EEXXAAMMPPLLEESS Although the explanation of TTkkCCoonnffiigguurreeWWiiddggeett 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 specFlags mechanisms.