Tk_ConfigureWidget(3tk)

📦

version 9.0.4 · 3 versions

9.0.4 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
8.6.18 · ubuntu questing, ubuntu resolute, ubuntu stonking
8.6.16 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

Tk_ConfigureWidget(3tk) — Tk Library Procedures 🫶

Okay bestie, gather round: Tk_ConfigureWidget, Tk_ConfigureInfo, Tk_ConfigureValue, and Tk_FreeOptions — they process configuration options for widgets. That's the whole name section, periodt. 💅

🌸 SYNOPSIS 🌸

#include <tk.h>

int
Tk_ConfigureWidget(interp, tkwin, specs, objc, objv, widgRec, flags)

int
Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)

int
Tk_ConfigureValue(interp, tkwin, specs, widgRec, argvName, flags)

Tk_FreeOptions(specs, widgRec, display, flags)

🎀 ARGUMENTS 🎀

Tcl_Interp *interp (in) — the interpreter you use for returning error messages. It's giving "where the drama goes if something breaks" 😭
Tk_Window tkwin (in) — the window used to represent the widget. Needed to set up X resources, no cap. 💖
const Tk_ConfigSpec *specs (in) — pointer to the table specifying legal configuration options for this widget. This is the master list, bestie. 👑
Tcl_Size objc (in) — number of arguments in objv. Count 'em. 🔢
Tcl_Obj *const * objv (in) — command-line options for configuring the widget. The actual argv energy. ✨
char *widgRec (in/out) — points to the widget record structure. Fields in this structure get modified by Tk_ConfigureWidget to hold configuration information. So it's not just a spectator, it gets edited. 💅
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 specs. Big brain flag stuff. 🧠
type name type (in) — the name of the type of a widget record. Yes, that's literally how it's written. 🙈
field name field (in) — the name of a field in records of type type. Okayyy. 🎀
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 configure widget command). If non-NULL, then information is returned only for this option. If NULL, then information is returned for all available options. So NULL = give me everything, bestie. 🌈
Display *display (in) — display containing widget whose record is being freed; needed in order to free up resources. Cleanup era. 🧹

💅 DESCRIPTION 💅

⚠️ Note that Tk_ConfigureWidget should be replaced with the new Tcl_Obj based API, Tk_SetOptions. The old interface is retained for backward compatibility. So yes, it's legacy, but we still love her. 💖

Tk_ConfigureWidget 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 configure command is invoked for a widget. Although intended primarily for widgets, Tk_ConfigureWidget can be used in other situations where objc-objv 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. So it's not just widget-coded, it's record-filling coded. 🫶

Tk_ConfigureWidget processes a table specifying the configuration options that are supported (specs) and a collection of command-line arguments (objc and objv) 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 objv. Tk_ConfigureWidget normally returns the value TCL_OK; in this case it does not modify interp. If an error occurs then TCL_ERROR is returned and Tk_ConfigureWidget will leave an error message in interpreter interp's 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 fields will be set to reasonable initial values so that Tk_FreeOptions can be called for cleanup. So yeah, partial progress is a thing, but cleanup is still possible. 😭💖

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;
    const char *argvName;
    const char *dbName;
    const char *dbClass;
    const char *defValue;
    Tcl_Size offset;
    int specFlags;
    const Tk_CustomOption *customPtr;
} Tk_ConfigSpec;

The type 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 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 objv (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 objv or the option database. Offset indicates where in widgRec to store information about this option, and specFlags contains additional information to control the processing of this configuration option (see FLAGS below). The last field, customPtr, is only used if type is TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. Iconic struct behavior. ✨

Tk_ConfigureWidget first processes objv to see which (if any) configuration 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 second 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 objv, Tk_ConfigureWidget 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 TK_CONFIG_DONT_SET_DEFAULT bit is set in flags, then there is no default value and this specs entry will be ignored if no value is specified in objv or the option database. So defaults are not always defaulting, bestie. 🙈

Once a string value has been determined for a configuration option, Tk_ConfigureWidget translates the string value into a more useful form, such as a color if type is TK_CONFIG_COLOR or an integer if type is TK_CONFIG_INT. 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 Tk_ConfigureWidget. The offset field of each specs entry indicates where in widgRec to store the information about this configuration option. You should use the offsetof macro to generate offset values. The location indicated by widgRec and offset will be referred to as the “target” in the descriptions below. Target acquired, bestie. 🎯

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:

TK_CONFIG_ACTIVE_CURSOR — The value must be an ASCII string identifying a cursor in a form suitable for passing to Tk_GetCursor. The value is converted to a Tk_Cursor by calling Tk_GetCursor and the result is stored in the target. In addition, the resulting cursor is made the active cursor for tkwin by calling XDefineCursor. If TK_CONFIG_NULL_OK 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 None. If the previous value of the target was not None, then it is freed by passing it to Tk_FreeCursor. Cursor drama, but make it active. 🖱️✨
TK_CONFIG_ANCHOR — The value must be an ASCII string identifying an anchor point in one of the ways accepted by Tk_GetAnchor. The string is converted to a Tk_Anchor by calling Tk_GetAnchor and the result is stored in the target. Anchor it down. ⚓
TK_CONFIG_BITMAP — The value must be an ASCII string identifying a bitmap in a form suitable for passing to Tk_GetBitmap. The value is converted to a Pixmap by calling Tk_GetBitmap and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in specFlags then the value may be an empty string, in which case the target is set to None. If the previous value of the target was not None, then it is freed by passing it to Tk_FreeBitmap. Bitmap bestie. 🎨
TK_CONFIG_BOOLEAN — 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. Boolean slay. ✅❌
TK_CONFIG_BORDER — The value must be an ASCII string identifying a border color in a form suitable for passing to Tk_Get3DBorder. The value is converted to a (Tk_3DBorder *) by calling Tk_Get3DBorder and the result is stored in the target. If TK_CONFIG_NULL_OK 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 was not NULL, then it is freed by passing it to Tk_Free3DBorder. Border? More like baddie. 💅
TK_CONFIG_CAP_STYLE — The value must be an ASCII string identifying a cap style in one of the ways accepted by Tk_GetCapStyle. The string is converted to an integer value corresponding to the cap style by calling Tk_GetCapStyle and the result is stored in the target. Cap style, cap vibes. 🧢
TK_CONFIG_COLOR — bestie, this one's a color. The value has to be an ASCII string that names a color in a form you could hand straight to Tk_GetColor. We convert it by calling Tk_GetColor, get back an (XColor *), and stash that in the target. If TK_CONFIG_NULL_OK is set in specFlags, an empty string is allowed and the target gets set to None. And if the target's previous value wasn't NULL, we free it by passing it to Tk_FreeColor. 💖
TK_CONFIG_CURSOR — literally identical to TK_CONFIG_ACTIVE_CURSOR except the new cursor does not get made the active one for tkwin. That's it, that's the difference. 🎀
TK_CONFIG_CUSTOM — the one where apps get to invent their own option types, iconic behavior honestly. The customPtr field of the entry points at a structure defining the new option type. Full deets live in the CUSTOM OPTION TYPES section below. 🦋
TK_CONFIG_DOUBLE — the value has to be an ASCII floating-point number in the format strtol accepts. The string gets converted to a double value, and that value lands in the target. ✨
TK_CONFIG_END — this marks the end of the table, periodt. The last entry in specs must have this type; all its other fields are ignored and it will never match any arguments. 💀
TK_CONFIG_FONT — the value has to be an ASCII string naming a font in a form suitable for passing to Tk_GetFont. We convert it by calling Tk_GetFont, get a Tk_Font, and store that in the target. If TK_CONFIG_NULL_OK is set in specFlags, an empty string is fine and the target gets set to NULL. If the target's previous value wasn't NULL, we free it by passing it to Tk_FreeFont. 🫶
TK_CONFIG_INT — the value must be an ASCII integer string in the format strtol accepts (so yes, “0” and “0x” prefixes can be used to specify octal or hexadecimal numbers, respectively). The string gets converted to an integer value and the integer goes in the target. 🔥
TK_CONFIG_JOIN_STYLE — the value must be an ASCII string identifying a join style in one of the ways Tk_GetJoinStyle accepts. The string is converted to an integer value corresponding to the join style by calling Tk_GetJoinStyle, and that result goes in the target. 🌈
TK_CONFIG_JUSTIFY — the value must be an ASCII string identifying a justification method in one of the ways Tk_GetJustify accepts. The string is converted to a Tk_Justify by calling Tk_GetJustify, and the result is stored in the target. ⭐
TK_CONFIG_MM — the value must specify a screen distance in one of the forms Tk_GetScreenMM accepts. The string is converted to a double-precision floating-point distance in millimeters, and that value goes in the target. 💜
TK_CONFIG_PIXELS — the value must specify screen units in one of the forms Tk_GetPixels accepts. The string is converted to an integer distance in pixels, and the value goes in the target. 🌸
TK_CONFIG_RELIEF — the value must be an ASCII string identifying a relief in a form suitable for passing to Tk_GetRelief. The value is converted to an integer relief value by calling Tk_GetRelief, and the result is stored in the target. ✨
TK_CONFIG_STRING — a copy of the value gets made by allocating memory space with Tcl_Alloc and copying the value into that dynamically-allocated space. A pointer to the new string is stored in the target. If TK_CONFIG_NULL_OK is set in specFlags, an empty string is allowed and the target gets set to NULL. If the target's previous value wasn't NULL, it's freed by passing it to Tcl_Free. 😭 (memory management bestie, it's giving responsibility)
TK_CONFIG_SYNONYM — this type value identifies special entries in specs that are synonyms for other entries. If an objv value matches the argvName of a TK_CONFIG_SYNONYM entry, that entry is not used directly. Instead, Tk_ConfigureWidget searches specs for another entry whose argvName is the same as the dbName field in the TK_CONFIG_SYNONYM entry; this new entry is used just as if its argvName had matched the objv value. The synonym mechanism lets multiple objv values be used for a single configuration option, like “-background” and “-bg”. 👑
TK_CONFIG_UID — the value is translated to a Tk_Uid (by passing it to Tk_GetUid). The resulting value is stored in the target. If TK_CONFIG_NULL_OK is set in specFlags and the value is an empty string, then the target gets set to NULL. 🦋
TK_CONFIG_WINDOW — the value must be a window path name. It's translated to a Tk_Window token and the token is stored in the target. 🎀

🌟 GROUPED ENTRIES 🌟

Okay so sometimes it's genuinely useful to generate multiple resources from a single configuration value. Like, 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). Two resources, one vibe. 💅

In cases like this, you can specify that several consecutive entries in specs are treated as a group. The first entry determines a value (using its argvName, dbName, dbClass, and defValue fields). That value then gets processed several times — once 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; that's the signal that the entry is grouped with the entry that precedes it. And from these follow-on entries, only the type and offset fields are used. That's the whole rule, no cap. 💖

🚩 FLAGS 🚩

The flags argument passed to Tk_ConfigureWidget works together with the specFlags fields in the entries of specs to give you extra control over how configuration options get processed. These values are used in three different ways, bestie. Let me break it down. ✨

First up: if the flags argument to Tk_ConfigureWidget has the TK_CONFIG_ARGV_ONLY bit set (i.e., flags | TK_CONFIG_ARGV_ONLY != 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 objv 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 — like when a configure widget command is being processed. 🎀

Second: the specFlags field of an entry in specs can be used to control the processing of that entry. Each specFlags field can consist of an OR-ed combination of the following values: 🦋

TK_CONFIG_COLOR_ONLY — if this bit is set, the entry is only considered if the display for tkwin has more than one bit plane. If the display is monochromatic, then this specs entry gets ignored. 🌈
TK_CONFIG_MONO_ONLY — if this bit is set, the entry is only considered if the display for tkwin has exactly one bit plane. If the display is not monochromatic, then this specs entry gets ignored. 💀
TK_CONFIG_NULL_OK — this bit is only relevant for some types of entries (peep the descriptions of the various entry types above). If this bit is set, it means an empty string value for the field is acceptable, and if one shows up then the target should be set to NULL or None, depending on the type of the target. This flag is typically used to let a feature be turned off entirely — e.g. set a cursor value to None so a window just inherits its parent's cursor. If this bit is not set, then empty strings get processed as strings, which generally results in an error. 😭
TK_CONFIG_DONT_SET_DEFAULT — if this bit is one, it means the defValue field of the entry should only be used for returning the default value in Tk_ConfigureInfo. In calls to Tk_ConfigureWidget, no default will be supplied for entries with this flag set; it's assumed the caller already supplied a default value in the target location. This flag is a performance optimization for when it's expensive to process the default string: the client can compute the default once, save the value, and provide it before calling Tk_ConfigureWidget. Efficiency queen behavior honestly. 👑

The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically used to specify different default values for monochrome and color displays. How? By creating two entries in specs that are identical except for their defValue and specFlags fields. One entry should have the value TK_CONFIG_MONO_ONLY in its specFlags and the default value for monochrome displays in its defValue; the other entry should have the value TK_CONFIG_COLOR_ONLY in its specFlags and the appropriate defValue for color displays. 💅

Third: you can use flags and specFlags together to selectively disable some entries. This feature isn't needed very often, ngl. It's useful when several similar kinds of widgets are implemented in one place, because it lets a single specs table be created with all the configuration options for all the widget types. When processing a particular widget type, only the entries relevant to that type get used. 🌟

How's that achieved? By setting the high-order bits (those in positions equal to or greater than TK_CONFIG_USER_BIT) in specFlags values or in flags. 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 Tk_ConfigureWidget. If a specs table is being used for N different widget types, then N of the high-order bits get used. Each specs entry will have one or more of those bits set in its specFlags field to indicate the widget types for which this entry is valid. When calling Tk_ConfigureWidget, 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 tkButton.c. 🔥

🧐 TK_CONFIGUREINFO

okay bestie, so Tk_ConfigureInfo is the little detective 🔍 that goes and finds out stuff about a widget's options — one of them, or literally all of them, your choice, we love options.

So you hand it:

a token for a window (tkwin)
a table describing the configuration options for a class of widgets (specs)
a pointer to a widget record with the current info for a widget (widgRec)
and an argvName argument that's NULL

…and it generates a string describing all the configuration options for the window. That string goes into interpreter interp's result. Under normal circumstances it returns TCL_OK; but if an error happens, it returns TCL_ERROR and the interpreter's result will hold an error message. 😭

If argvName is NULL, then the value left in the interpreter's result by Tk_ConfigureInfo is a list of one or more entries, and each one describes one configuration option (i.e. one entry in specs). Every entry in that list will contain either two or five values:

if the corresponding entry in specs has type TK_CONFIG_SYNONYM, the list has two values: the argvName for the entry and the dbName (synonym name) ✨
otherwise the list has five values: argvName, dbName, dbClass, defValue, and current value

The current value gets computed from the appropriate field of widgRec by calling procedures like Tk_NameOfColor. iconic.

But wait — if the argvName argument to Tk_ConfigureInfo is non-NULL, then it's pointing at a single option, and you only get info back for that one option. The string in the interpreter's result will be a list with two or five values as described above, and it will be identical to the corresponding sublist that would've been returned if argvName had been NULL. no cap.

And the flags argument to Tk_ConfigureInfo is used to restrict the specs entries to consider, just as for Tk_ConfigureWidget. 💅

💖 TK_CONFIGUREVALUE

Tk_ConfigureValue takes arguments similar to Tk_ConfigureInfo, but instead of giving you a whole list of values, it just returns the current value of the option given by argvName — and heads up, argvName must not be NULL. 🚨

The value is returned in interpreter interp's result and TCL_OK is normally returned as the procedure's result. But if an error occurs in Tk_ConfigureValue (like, say, argvName isn't a valid option name), then TCL_ERROR is returned and an error message is left in the interpreter's result. 😭

This procedure is typically called to implement cget widget commands. slay.

🧹 TK_FREEOPTIONS

Tk_FreeOptions is your cleanup bestie — invoke it during widget cleanup to release all 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 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 nothing gets freed for that entry, no stress. And after freeing a resource, Tk_FreeOptions sets the corresponding field of the widget record to null. clean. ✨

🦋 CUSTOM OPTION TYPES

Okay this part is the DIY section and it's lowkey the coolest. Applications can extend the built-in configuration types with extra configuration types by writing procedures to parse and print options of the a type and creating a structure pointing to those procedures:

typedef struct {
    Tk_OptionParseProc *parseProc;
    Tk_OptionPrintProc *printProc;
    void *clientData;
} Tk_CustomOption;

typedef int Tk_OptionParseProc(
        void *clientData,
        Tcl_Interp *interp,
        Tk_Window tkwin,
        const char *value,
        char *widgRec,
        Tcl_Size offset);

typedef const char *Tk_OptionPrintProc(
        void *clientData,
        Tk_Window tkwin,
        char *widgRec,
        Tcl_Size offset,
        Tcl_FreeProc **freeProcPtr);

The Tk_CustomOption structure contains three fields, which are pointers to the two procedures and a clientData value to be passed to those procedures when they get invoked. The clientData value typically points to a structure containing info that the procedures need when they're parsing and printing options. 💜

🌸 the parseProc situation

The parseProc procedure is invoked by Tk_ConfigureWidget to parse a string and store the resulting value in the widget record. Let's break down who's who:

clientData — a copy of the clientData field in the Tk_CustomOption structure
interp — points to a Tcl interpreter used for error reporting
Tkwin — a copy of the tkwin argument to Tk_ConfigureWidget
value — a string describing the value for the option; it could've been specified explicitly in the call to Tk_ConfigureWidget, 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 — the same as the widgRec argument to Tk_ConfigureWidget; it points to the start of the widget record to modify
offset — the last argument, 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 translating the string to a value then it should return TCL_ERROR and store an error message in interpreter interp's result. 😤

🎀 the printProc situation

The printProc procedure is called by Tk_ConfigureInfo to produce a string value describing an existing option. Its clientData, tkwin, widgRec, and offset arguments all have the same meaning as for Tk_OptionParseProc 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. And here's the important bit: 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 — Tk_ConfigureInfo will call this procedure when it's finished with the string. If the result string is stored in static memory then printProc need not do anything with the freeProcPtr argument. easy ✨

👑 putting it together

Once parseProc and printProc 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 type fields are TK_CONFIG_CUSTOM and whose customPtr fields point to the Tk_CustomOption structure. periodt. 💅

🌈 EXAMPLES

Although the explanation of Tk_ConfigureWidget is fairly complicated, its actual use is pretty straightforward, bestie, I promise. 🫶

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 🔥

🔍 SEE ALSO

Tk_SetOptions(3tk)

⭐ KEYWORDS

anchor, bitmap, boolean, border, cap style, color, configuration options, cursor, custom, double, font, integer, join style, justify, millimeters, pixels, relief, synonym, uid

okay that's the whole thing, we made it, you're officially a Tk_ConfigureWidget girlie now 💅✨ this page comes to you from the Tk 4.1 era and lives under the name Tk_ConfigureWidget(3tk) — iconic behavior, honestly, and yes you should absolutely go read Tk_SetOptions(3tk) next. mwah 💖🎀🦋

📦 where this page comes from

debian trixie: tk9.0-doc 9.0.1-3
ubuntu questing: tk9.0-doc 9.0.2-1
ubuntu resolute: tk9.0-doc 9.0.3-1
ubuntu stonking: tk9.0-doc 9.0.4-1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms