Tk_SetOptions(3)

📦
version 9.0.3 · 6 versions
, in alpine 3.23, alpine 3.24, fedora 43, fedora 44, nixos 26.05

bestie, welcome to Tk_SetOptions(3) from the Tk Library Procedures 💅✨ we're doing configuration-option processing today and it's lowkey giving "group project but make it C" — but don't worry, the facts are all here and they're iconic.

✨ NAME ✨

Okay so these functions are literally the whole configuration-option friend group, and they all process configuration options 🫶:

  • Tk_CreateOptionTable
  • Tk_DeleteOptionTable
  • Tk_InitOptions
  • Tk_SetOptions
  • Tk_FreeSavedOptions
  • Tk_RestoreSavedOptions
  • Tk_GetOptionValue
  • Tk_GetOptionInfo
  • Tk_FreeConfigOptions

🌸 SYNOPSIS 🌸

#include <tk.h>

Tk_OptionTable
Tk_CreateOptionTable(interp, templatePtr)

Tk_DeleteOptionTable(optionTable)

int
Tk_InitOptions(interp, recordPtr, optionTable, tkwin)

int
Tk_SetOptions(interp, recordPtr, optionTable, objc, objv, tkwin, savePtr, maskPtr)

Tk_FreeSavedOptions(savedPtr)

Tk_RestoreSavedOptions(savedPtr)

Tcl_Obj *
Tk_GetOptionValue(interp, recordPtr, optionTable, namePtr, tkwin)

Tcl_Obj *
Tk_GetOptionInfo(interp, recordPtr, optionTable, namePtr, tkwin)

Tk_FreeConfigOptions(recordPtr, optionTable, tkwin)

🎀 ARGUMENTS 🎀

  • Tcl_Interp *interp (in) — a Tcl interpreter 💜 most of these procedures use it only for returning error messages, so if it's NULL then no error messages get returned, periodt. But for Tk_CreateOptionTable the value cannot be NULL — it gives the interpreter in which the option table will be used.
  • const Tk_OptionSpec *templatePtr (in) — points to an array of static information describing the configuration options that are supported. It's used to build a Tk_OptionTable. Big caveat bestie: the information pointed to by this argument must exist for the lifetime of the Tk_OptionTable 👑
  • Tk_OptionTable optionTable (in) — token for an option table. It must have been returned by a previous call to Tk_CreateOptionTable ✨
  • void *recordPtr (in/out) — points to the structure where values of configuration options are stored. Fields of this record are modified by procedures such as Tk_SetOptions and read by procedures such as Tk_GetOptionValue 🦋
  • Tk_Window tkwin (in) — for options such as TK_OPTION_COLOR, this argument indicates the window in which the option will be used. If optionTable uses no window-dependent options, then a NULL value may be supplied for this argument 🌈
  • Tcl_Size objc (in) — number of values in objv 🔢
  • Tcl_Obj *const *objv (in) — command-line arguments for setting configuring options 💅
  • Tk_SavedOptions *savePtr (out) — if not NULL, the structure pointed to by this argument is filled in with the old values of any options that were modified, and old values are restored automatically if an error occurs in Tk_SetOptions 😭🙈
  • int *maskPtr (out) — if not NULL, the word pointed to by maskPtr is filled in with the bit-wise OR of the typeMask fields for the options that were modified 🎀
  • Tk_SavedOptions *savedPtr (in/out) — points to a structure previously filled in by Tk_SetOptions with old values of modified options 💖
  • Tcl_Obj *namePtr (in) — the value of this object is the name of a particular option. If NULL is passed to Tk_GetOptionInfo then information is returned for all options. It must not be NULL when Tk_GetOptionValue is called ⭐
  • type name type (in) — the name of the type of a record 🧚
  • field name field (in) — the name of a field in records of type type 🌸

✨ DESCRIPTION ✨

Okay bestie, so these procedures are literally the whole backstage crew for parsing configuration options — think the options on Tk widgets. You hand them a description of which options are supported, and they handle all the tedious little details: parsing the options, checking them, and stuffing their values into a C structure that belongs to the widget or object. They were designed mainly for widgets in Tk, but ngl they work for other kinds of objects that have configuration options too. In the rest of this manual page, “widget” refers to whatever object's options are being managed — in practice it might not actually be a widget, no cap. And “widget record” means the C-level structure where all the info about a particular widget or object lives. 🎀

Small heads-up, bestie: the easiest way to learn how to use these procedures is literally to look at a working example. In Tk, the simplest one is the code that implements the button family of widgets, which is in tkButton.c. Other examples live in tkSquare.c and tkMenu.c. Go peek, it's giving tutorial energy. 💅

So to use these procedures, the code that implements the widget has to contain a static array of Tk_OptionSpec structures. That array is a template describing the various options supported by that class of widget — and yes, there's a separate template for each kind of widget. The template holds things like the name of each option, its type, its default value, and where the option's value gets stored in the widget record. More deets in TEMPLATES below. 🦋

Now, to process configuration options efficiently, that static template has to get augmented with extra info that's only available at runtime. Enter Tk_CreateOptionTable — it creates this dynamic info from the template and returns a Tk_OptionTable token describing both the static and the dynamic info. All the other procedures, like Tk_SetOptions, take a Tk_OptionTable token as an argument. Typically Tk_CreateOptionTable gets called the first time a widget of a particular class is created, and the resulting Tk_OptionTable is reused for all widgets of that class forever after. ✨

⚠️ Important vibe check: a Tk_OptionTable may be used only in a single interpreter, given by the interp argument to Tk_CreateOptionTable.

When an option table is no longer needed, call Tk_DeleteOptionTable to free all of its resources. And if the interpreter itself gets deleted, all the option tables for that Tcl interpreter are freed automatically. Slay, no memory leaks. 🫶

Tk_InitOptions gets invoked when a new widget is created, to set the default values. It's passed a token for an option table (optionTable) and a pointer to a widget record (recordPtr) — that's the C structure holding info about this widget. Tk_InitOptions uses the info in the option table to pick an appropriate default for each option, then stores that default value directly into the widget record, overwriting any info that was already chilling there. Tk_InitOptions normally returns TCL_OK. But if an error happened while setting the default values (like, say, a default value was erroneous 😭), then TCL_ERROR is returned and an error message is left in interp's result — but only if interp isn't NULL. And for any widget's configuration option that has TK_OPTION_DONT_SET_DEFAULT set in its flags field, the whole initialization above is fully skipped. See below, bestie. 👑

Tk_SetOptions gets invoked to modify configuration options based on info specified in a Tcl command. That command might be one that creates a new widget, or one that modifies options on an existing widget. The objc and objv arguments describe the values of the arguments from the Tcl command. And listen: objv must contain an even number of objects — the first object of each pair gives the name of an option, and the second object gives the new value for that option. Tk_SetOptions looks up each name in optionTable, checks that the new value conforms to the type in optionTable, and stores the option's value into the widget record given by recordPtr. Tk_SetOptions normally returns TCL_OK. If an error occurred (like an unknown option name or an illegal option value), then TCL_ERROR is returned and an error message is left in interp's result if interp is not NULL. 💅

Tk_SetOptions has two extra features, and honestly? They ate. 🔥

Feature one: if the maskPtr argument isn't NULL, then it points to an integer value that gets filled in with info about which options were modified. For each option in the template passed to Tk_CreateOptionTable, there's a typeMask field. The bits of that field are defined by the code that implements the widget — for example, each bit might correspond to a particular configuration option. Or, alternatively, bits might be used functionally. Like, one bit might be used for redisplay: all options that affect the widget's display, such that changing the option requires the widget to be redisplayed, might have that bit set. Another bit might indicate that the widget's geometry has to be recomputed, and so on. Tk_SetOptions OR's together the typeMask fields from all the options that were modified and returns this value at *maskPtr. The caller can then use that info to optimize itself — so, for example, it doesn't redisplay the widget if the modified options don't affect the widget's appearance. Efficiency icon behaviour, honestly. ⭐

Feature two: this one's about error recovery. If an error occurs while processing configuration options, this feature makes it possible to restore all the configuration options to their previous values. Errors can happen either while processing options in Tk_SetOptions or later, in the caller. In many cases the caller does extra processing after Tk_SetOptions returns — for example, it might use an option value to set a trace on a variable and detect an error if the variable is an array instead of a scalar. Error recovery gets enabled by passing a non-NULL value for the savePtr argument to Tk_SetOptions; that should be a pointer to an uninitialized Tk_SavedOptions structure on the caller's stack. Tk_SetOptions overwrites the structure pointed to by savePtr with info about the old values of any options modified by the procedure.

If Tk_SetOptions returns successfully, the caller uses that structure in one of two ways:

  1. If the caller finishes processing the new options without any errors, then it must pass the structure to Tk_FreeSavedOptions so the old values can be freed.
  2. If the caller detects an error in its processing of the new options, then it should pass the structure to Tk_RestoreSavedOptions, which copies the old values back into the widget record and frees the new values.

If Tk_SetOptions itself detects an error, then it automatically restores any options that had already been modified and leaves *savePtr in an empty state — so the caller doesn't need to call either Tk_FreeSavedOptions or Tk_RestoreSavedOptions. 🧚

💀 But if the savePtr argument to Tk_SetOptions is NULL, then Tk_SetOptions frees each old option value immediately when it sets a new value for that option. In that case, if an error occurs in the third option, the old values for the first two options cannot be restored. So like… choose wisely, bestie.

Tk_GetOptionValue returns the current value of a configuration option for a particular widget. The namePtr argument contains the name of an option; Tk_GetOptionValue uses optionTable to look up the option and extract its value from the widget record pointed to by recordPtr, then returns an object containing that value. If an error occurs (e.g., because namePtr contains an unknown option name), then NULL is returned and an error message is left in interp's result unless interp is NULL. 🌸

Tk_GetOptionInfo returns info about configuration options in a form suitable for configure widget commands. If the namePtr argument is not NULL, it points to an object giving the name of a configuration option; Tk_GetOptionInfo returns an object containing a list with five elements, which are:

  • the name of the option,
  • the name and class used for the option in the option database,
  • the default value for the option,
  • and the current value for the option.

If the namePtr argument is NULL, then Tk_GetOptionInfo returns info about all options in the form of a list of lists; each sublist describes one option. 🌈

Synonym options are handled differently depending on whether namePtr is NULL:

  • If namePtr is NULL, then the sublist for each synonym option has only two elements, which are the name of the option and the name of the other option that it refers to.
  • If namePtr is non-NULL and names a synonym option, then the object returned is the five-element list for the other option that the synonym refers to.

If an error occurs (e.g., because namePtr contains an unknown option name), then NULL is returned and an error message is left in interp's result unless interp is NULL. 😭

Tk_FreeConfigOptions must be invoked when a widget is deleted. It frees all of the resources associated with any of the configuration options defined in recordPtr by optionTable. Cleanup queen behaviour, we love to see it. 👑💖

💖 TEMPLATES 💖

okay so the array of Tk_OptionSpec structures that you pass to Tk_CreateOptionTable through its templatePtr argument — that's the thing that describes all the configuration options a particular class of widgets supports. Every single structure describes one configuration option, and it's got these fields:

typedef struct {
    Tk_OptionType type;
    const char *optionName;
    const char *dbName;
    const char *dbClass;
    const char *defValue;
    Tcl_Size objOffset;
    Tcl_Size internalOffset;
    int flags;
    const void *clientData;
    int typeMask;
} Tk_OptionSpec;

let me walk you through it bestie, field by field 🫶

  • type — says what kind of configuration option this is (like TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an integer value). The type determines how the value of the option gets parsed (more on that below, don't worry).
  • optionName — a string like -font or -bg. It's the name used for the option in Tcl commands, and it's what gets passed to procedures via the objc or namePtr arguments.
  • dbName and dbClass — these two are used by Tk_InitOptions to look up a default value for this option in the option database. And heads up: if dbName is NULL then the option database is not used by Tk_InitOptions for this option.
  • defValue — the default value for this configuration option, for when no value was specified in the option database.
  • objOffset and internalOffset — where to store the value of this option in the widget records (again, more below). And these should always be generated with the offsetof macro, no cap.
  • flags — extra info that controls the processing of this configuration option (details below ✨).
  • clientData — extra type-specific data that certain types need. For instance, for TK_OPTION_COLOR types, clientData is a string giving the default value to use on monochrome displays. Check the descriptions of the different types below for the deets.
  • typeMask — the last field! It's used by Tk_SetOptions to return info about which options were actually modified. See the description of Tk_SetOptions above for that one.

So when Tk_InitOptions and Tk_SetOptions store the value of an option into the widget record, they've got two whole ways to do it, and it's giving choose-your-own-adventure:

  • If the objOffset field of the Tk_OptionSpec is greater than or equal to zero, then the value of the option is stored as a (Tcl_Obj *) at the location in the widget record given by objOffset.
  • If the internalOffset field of the Tk_OptionSpec is greater than or equal to zero, then the value of the option is stored in a type-specific internal form at the location in the widget record given by internalOffset. Like, if the option's type is TK_OPTION_INT then the internal form is an integer.
  • If the objOffset or internalOffset field is negative, then the value is not stored in that form.
⚠️ At least one of the offsets must be greater than or equal to zero. That's not optional, bestie.

🌸 the flags field 🌸

The flags field is one or more bits ORed together. These are the flags that are supported:

  • TK_OPTION_NULL_OK — if this bit is set for an option, then an empty string is accepted as the value for the option, and the resulting internal form will be a NULL pointer, a zero value, or None, depending on the type of the option. If the flag is not set, then empty strings result in errors 😭. TK_OPTION_NULL_OK is typically used to let a feature be turned off entirely — e.g. set a cursor value to None so that a window simply inherits its parent's cursor. Not all option types support the TK_OPTION_NULL_OK flag; for the ones that do, there's an explicit indication of that fact in the descriptions below. iykyk.
  • TK_OPTION_DONT_SET_DEFAULT — if this bit is set for an option, then no default value will be set in Tk_InitOptions for this option. Neither the option database, nor any system default value, nor optionTable are used to give a default value to this option. Instead it's assumed that the caller already supplied a default value in the widget code. main character energy: you're on your own.
  • TK_OPTION_ENUM_VAR — if this value is set for an option, then it indicates that the internalOffset points to an enum variable in stead of an int variable. Only useful in combination with TK_OPTION_STRING_TABLE, TK_OPTION_BOOLEAN, TK_OPTION_ANCHOR, TK_OPTION_JUSTIFY, or TK_OPTION_ANCHOR.
  • TK_OPTION_VAR(type) — if this value is set for an option, then it indicates that the internalOffset points to a type variable in stead of an int variable. Only useful in combination with TK_OPTION_STRING_TABLE or TK_OPTION_BOOLEAN, or as TK_OPTION_VAR(Tcl_Size) with TK_OPTION_INT.

The type field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. The legal values for type, and the corresponding actions, are described below 💅. If the type requires a tkwin value to be passed into procedures like Tk_SetOptions, or if it uses the clientData field of the Tk_OptionSpec, then it's indicated explicitly; if it's not mentioned, the type requires neither tkwin nor clientData.

✨ the types, one by one ✨

  • TK_OPTION_ANCHOR — the value must be a standard anchor position such as ne or center. The internal form is a Tk_Anchor value like the ones returned by Tk_GetAnchorFromObj. This option type supports the TK_OPTION_NULL_OK flag; if the empty string is specified as the value for the option, the integer relief value is set to TK_ANCHOR_NULL.
  • TK_OPTION_BITMAP — the value must be a standard Tk bitmap name. The internal form is a Pixmap token like the ones returned by Tk_AllocBitmapFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_BOOLEAN — the value must be a standard boolean value such as true or no. The internal form is an integer with value 0 or 1. Note that if the objOffset field is not used, information about the original value of this option will be lost 👀. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to -1.
  • TK_OPTION_BORDER — the value must be a standard color name such as red or #ff8080. The internal form is a Tk_3DBorder token like the ones returned by Tk_Alloc3DBorderFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_COLOR — the value must be a standard color name such as red or #ff8080. The internal form is an (XColor *) token like the ones returned by Tk_AllocColorFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_CURSOR — the value must be a standard cursor name such as cross or @foo. The internal form is a Tk_Cursor token like the ones returned by Tk_AllocCursorFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and when the option is set the cursor for the window is changed by calling XDefineCursor. This option type also supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_CUSTOM — this option lets applications define new option types 🎀. The clientData field of the entry points to a structure defining the new option type. See the section CUSTOM OPTION TYPES below for details.
  • TK_OPTION_DOUBLE — the string value must be a floating-point number in the format accepted by strtol. The internal form is a C double value. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to NaN.
  • TK_OPTION_END — marks the end of the template. There must be a Tk_OptionSpec structure with type TK_OPTION_END at the end of each template, periodt. If the clientData field of this structure is not NULL, then it points to an additional array of Tk_OptionSpec's, which is itself terminated by another TK_OPTION_END entry. Templates may be chained arbitrarily deeply — this feature lets common options be shared by several widget classes. iconic tbh.
  • TK_OPTION_FONT — the value must be a standard font name such as Times 16. The internal form is a Tk_Font handle like the ones returned by Tk_AllocFontFromObj. This option type requires tkwin to be supplied to procedures such as Tk_SetOptions, and it supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_INT — the string value must be an integer in the format accepted by strtol (e.g. 0 and 0x prefixes may be used to specify octal or hexadecimal numbers, respectively). The internal form is a C int value. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to INT_MIN.
  • TK_OPTION_INDEX — the string value must be an index in the format accepted by Tcl_GetIntForIndex() or the empty string. The internal form is a C int value. If the string starts with -, the internal representation will be set to INT_MIN. If the string has the form end-???, then the result will be a negative number: -1 stands for end, -2 stands for end-1 and so on. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to INT_MIN.
  • TK_OPTION_JUSTIFY — the value must be a standard justification value such as left. The internal form is a Tk_Justify like the values returned by Tk_GetJustifyFromObj. This option type supports the TK_OPTION_NULL_OK flag; if the empty string is specified as the value for the option, the integer relief value is set to TK_JUSTIFY_NULL.
  • TK_OPTION_PIXELS — the value must specify a screen distance such as 2i or 6.4. The internal form is an integer value giving a distance in pixels, like the values returned by Tk_GetPixelsFromObj. Note that if the objOffset field is not used, information about the original value of this option will be lost 🙈. See OBJOFFSET VS. INTERNALOFFSET below for details. This option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to INT_MIN.

💅 TK_OPTION_RELIEF

The value has to be a standard relief, bestie — think raised. The internal form is an integer relief value like TK_RELIEF_RAISED. This type is down with the TK_OPTION_NULL_OK flag, and if you set a NULL value, the internal representation gets set to TK_RELIEF_NULL. Slay.

✨ TK_OPTION_STRING

Honestly the most chill type — the value can be literally any string. The internal form is a (char *) pointer pointing at a dynamically allocated copy of the value. Also supports the TK_OPTION_NULL_OK flag. 🎀

🦋 TK_OPTION_STRING_TABLE

For this one, clientData is a pointer to an array of strings, all set up nicely for passing to Tcl_GetIndexFromObj. The value has to be one of the strings in that table, or a unique abbreviation of one of them (iykyk). The internal form is an integer giving the index into the table of the matching string, like the return value from Tcl_GetStringFromObj. Supports TK_OPTION_NULL_OK too — and if a NULL value is set, the internal representation becomes -1.

🧚 TK_OPTION_SYNONYM

This type is literally just for giving an option alternate names (classic example: -bg is often used as a synonym for -background). The clientData field is a string giving the name of another option in the same table, and whenever the synonym gets used, the info from that other option is used instead. Iconic behaviour, no notes.

👑 TK_OPTION_WINDOW

The value must be a window path name. The internal form is a Tk_Window token for that window. This type requires tkwin to be supplied to procedures like Tk_SetOptions (that's how it identifies the application), and yeah — it supports the TK_OPTION_NULL_OK flag.

💀 STORAGE MANAGEMENT ISSUES

Okay so this part is important, listen up 🫶

If a field of a widget record has its offset stored in the objOffset or internalOffset field of a Tk_OptionSpec structure, then the procedures described here will handle all the storage allocation and resource management drama for that field. When the value of an option changes, Tk_SetOptions (or Tk_FreeSavedOptions) will automatically free whatever resources were tied to the old value — like Tk_Fonts for TK_OPTION_FONT options, or the dynamically allocated memory for TK_OPTION_STRING options. Zero manual cleanup required, we love to see it.

For an option stored as an object using the objOffset field of a Tk_OptionSpec, the widget record shares the object pointed to by the objv value from the call to Tk_SetOptions. The reference count for that object gets incremented when a pointer to it is stored in the widget record, and decremented when the option is modified. When the widget gets deleted, you should invoke Tk_FreeConfigOptions — it'll free the resources for all options and decrement reference counts for any objects.

But heads up bestie: the widget code is responsible for storing NULL or None in all pointer and token fields before invoking Tk_InitOptions. This is required so proper cleanup can happen in the rare case where an error occurs in Tk_InitOptions. Don't skip this step, fr fr. 😭

🌈 OBJOFFSET VS. INTERNALOFFSET

In most cases it's simplest to use the internalOffset field of a Tk_OptionSpec structure and not the objOffset field. That way the internal form of the value is immediately available to the widget code, so you don't have to extract it from an object every single time you use it. Efficient queen behaviour. 👑

But there are two cases where the objOffset field is actually useful:

Case one: TK_OPTION_PIXELS options. Here the internal form is an integer pixel value that's only valid for a particular screen. If you retrieve the option's value, it comes back as a simple number. For example, after the command .b configure -borderwidth 2m, the command .b configure -borderwidth might return 7, which is the integer pixel value corresponding to 2m. Unfortunately that loses the original screen-independent value. So for TK_OPTION_PIXELS options it's better to use the objOffset field — the original value of the option stays in the object and can be returned when you retrieve it.

It might seem convenient to use the internalOffset field as well, so the integer value is immediately available in the widget code. But if scaling is involved, internalOffset won't change value when the scaling changes. So it's better to always use Tk_GetPixelsFromObj to extract the integer value from the object whenever it's needed. Note that the losing-information-on-retrieval problem exists only for TK_OPTION_PIXELS options. 💅

Case two: implementing new types of options that these procedures don't support. To do that, use TK_OPTION_STRING as the type in the Tk_OptionSpec structure and set the objOffset field but not the internalOffset field. Then, after calling Tk_SetOptions, convert the object to internal form yourself. DIY era. 🛠️

Also lowkey crucial: Ttk widgets do not support the internalOffset machinery. Option values of Ttk widgets are always stored as (Tcl_Obj *), which means the objOffset field must be used. No exceptions. 🌸

✨ CUSTOM OPTION TYPES ✨

okay so bestie, here's the actual glow-up path: applications can extend the built-in configuration types with additional configuration types by writing procedures to parse, print, free, and restore saved copies of the type and creating a structure pointing to those procedures:

typedef struct {
    const char *name;
    Tk_CustomOptionSetProc *setProc;
    Tk_CustomOptionGetProc *getProc;
    Tk_CustomOptionRestoreProc *restoreProc;
    Tk_CustomOptionFreeProc *freeProc;
    void *clientData;
} Tk_ObjCustomOption;

typedef int Tk_CustomOptionSetProc(
    void *clientData,
    Tcl_Interp *interp,
    Tk_Window tkwin,
    Tcl_Obj **valuePtr,
    char *recordPtr,
    Tcl_Size internalOffset,
    char *saveInternalPtr,
    int flags);

typedef Tcl_Obj *Tk_CustomOptionGetProc(
    void *clientData,
    Tk_Window tkwin,
    char *recordPtr,
    Tcl_Size internalOffset);

typedef void Tk_CustomOptionRestoreProc(
    void *clientData,
    Tk_Window tkwin,
    char *internalPtr,
    char *saveInternalPtr);

typedef void Tk_CustomOptionFreeProc(
    void *clientData,
    Tk_Window tkwin,
    char *internalPtr);

The Tk_ObjCustomOption structure contains six fields: a name for the custom option type; pointers to the four procedures; and a clientData value to be passed to those procedures 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. restoreProc and freeProc may be NULL, indicating that no function should be called for those operations.

🛠️ the setProc procedure 🛠️

The setProc procedure is invoked by Tk_SetOptions to convert a Tcl_Obj into an internal representation and store the resulting value in the widget record. The arguments are:

  • clientData — a copy of the clientData field in the Tk_ObjCustomOption structure.
  • interp — a pointer to a Tcl interpreter, used for error reporting.
  • Tkwin — a copy of the tkwin argument to Tk_SetOptions.
  • valuePtr — a pointer to a reference to a Tcl_Obj describing the new value for the option; it could have been specified explicitly in the call to Tk_SetOptions or it could come from the option database or a default. If the objOffset for the option is non-negative (the option value is stored as a (Tcl_Obj *) in the widget record), the Tcl_Obj pointer referenced by valuePtr is the pointer that will be stored at the objOffset for the option. SetProc may modify the value if necessary; for example, setProc may change the value to NULL to support the TK_OPTION_NULL_OK flag.
  • recordPtr — a pointer to the start of the widget record to modify.
  • internalOffset — offset in bytes from the start of the widget record to the location where the internal representation of the option value is to be placed.
  • saveInternalPtr — a pointer to storage allocated in a Tk_SavedOptions structure for the internal representation of the original option value. Before setting the option to its new value, setProc should set the value referenced by saveInternalPtr to the original value of the option in order to support Tk_RestoreSavedOptions.
  • flags — a copy of the flags field in the Tk_OptionSpec structure for the option.

SetProc returns a standard Tcl result: TCL_OK to indicate successful processing, or TCL_ERROR to indicate a failure of any kind. An error message may be left in the Tcl interpreter given by interp in the case of an error.

🦋 the getProc procedure 🦋

The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOptionInfo to retrieve a Tcl_Obj representation of the internal representation of an option. The clientData argument is a copy of the clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. RecordPtr is a pointer to the beginning of the widget record to query. InternalOffset is the offset in bytes from the beginning of the widget record to the location where the internal representation of the option value is stored. GetProc must return a pointer to a Tcl_Obj representing the value of the option.

🎀 the restoreProc procedure 🎀

The restoreProc procedure is invoked by Tk_RestoreSavedOptions to restore a previously saved internal representation of a custom option value. The clientData argument is a copy of the clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a pointer to the location where internal representation of the option value is stored. SaveInternalPtr is a pointer to the saved value. RestoreProc must copy the value from saveInternalPtr to internalPtr to restore the value. RestoreProc need not free any memory associated with either internalPtr or saveInternalPtr; freeProc will be invoked to free that memory if necessary. RestoreProc has no return value.

💅 the freeProc procedure 💅

The freeProc procedure is invoked by Tk_SetOptions and Tk_FreeSavedOptions to free any storage allocated for the internal representation of a custom option. The clientData argument is a copy of the clientData field in the Tk_ObjCustomOption structure. Tkwin is a copy of the tkwin argument to Tk_GetOptionValue or Tk_GetOptionInfo. InternalPtr is a pointer to the location where the internal representation of the option value is stored. The freeProc must free any storage associated with the option. FreeProc has no return value.

🧚 KEYWORDS 🧚

the keyword lineup is literally: anchor, bitmap, boolean, border, color, configuration option, cursor, double, font, integer, justify, pixels, relief, screen distance, synonym.

okay that's the whole page, bestie 💖 source/version: Tk 8.1; page: Tk_SetOptions(3); date: literally not in the footer, so no cap. go customize iconically ✨🫶💅

📦 where this page comes from