Tk_SetOptions(3tk)

📦
version 8.6.18 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ Tk_SetOptions — part 1 ✨

okay so bestie, welcome to Tk_SetOptions(3tk), the Tk Library Procedures page that runs the whole configuration-options department. this is part 1 of 4, so hydrate, get comfy, and let's go 💅

💖 NAME 💖

this page is the whole girl squad, and every single one of them is here to process configuration options:

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

that's the roster. ten icons. no cap. 👑

🌸 SYNOPSIS 🌸

the vibe check, verbatim, don't touch a character:

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

int
Tk_Offset(type, field)

🎀 ARGUMENTS 🎀

every parameter, explained like we're texting at 2am. all of them. yes, all of them. 🫶

  • Tcl_Interp *interp (in) — a Tcl interpreter. most of these procedures only use it to hand back error messages, and if it's NULL then like… no error messages get returned at all, silence, nothing. but for Tk_CreateOptionTable the value cannot be NULL — it tells you which interpreter the option table is gonna live in.
  • const Tk_OptionSpec *templatePtr (in) — points to an array of static info describing the configuration options that are supported. it's what you build a Tk_OptionTable out of. ⚠️ and the info it points to has to exist for the entire lifetime of the Tk_OptionTable — so don't you dare free that memory early, bestie.
  • Tk_OptionTable optionTable (in) — the token for an option table. it must have come from a previous call to Tk_CreateOptionTable, no improvising.
  • char *recordPtr (in/out) — points to the structure where the values of the configuration options are stored. procedures like Tk_SetOptions modify the fields of this record, and procedures like Tk_GetOptionValue read them.
  • Tk_Window tkwin (in) — for options like TK_OPTION_COLOR, this tells you the window the option will be used in. if the optionTable uses no window-dependent options, you can totally pass a NULL value here and it's fine.
  • int objc (in) — the number of values in objv.
  • Tcl_Obj *const *objv (in) — command-line arguments for setting configuring options.
  • Tk_SavedOptions *savePtr (out) — if it's not NULL, the structure it points to gets filled in with the old values of any options that were modified, and those old values get restored automatically if an error happens inside Tk_SetOptions. it's giving built-in safety net ✨
  • int *maskPtr (out) — if it's not NULL, the word it points to gets 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 that was previously filled in by Tk_SetOptions with the 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 info comes back for all the options. but 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.

that's part 1 done and dusted 🦋 more parts incoming, don't go anywhere

✨ DESCRIPTION ✨

okay bestie, so these procedures? They handle most of the details of parsing configuration options — like the ones Tk widgets have. You hand them a description of what options are supported, and they take care of all the parsing and storing into a C structure that's chained to the widget or object. They were designed primarily for widgets in Tk, but they can also be used for other kinds of objects that have configuration options. In the rest of this manual page, “widget” will be used to refer to the object whose options are being managed; in practice the object may not actually be a widget. The term “widget record” is used to refer to the C-level structure in which information about a particular widget or object is stored. 💅

Note that the easiest way to learn how to use these procedures is to look at a working example. In Tk, the simplest example is the code that implements the button family of widgets, which is in tkButton.c. Other examples are in tkSquare.c and tkMenu.c. literally go peek at those files, iykyk.

In order to use these procedures, the code that implements the widget must contain a static array of Tk_OptionSpec structures. This is a template that describes the various options supported by that class of widget; there is a separate template for each kind of widget. The template contains information such as the name of each option, its type, its default value, and where the value of the option is stored in the widget record. See TEMPLATES below for more detail. 🎀

In order to process configuration options efficiently, the static template must be augmented with additional information that is available only at runtime. The procedure Tk_CreateOptionTable creates this dynamic information from the template and returns a Tk_OptionTable token that describes both the static and dynamic information. All of the other procedures, such as Tk_SetOptions, take a Tk_OptionTable token as argument. Typically, Tk_CreateOptionTable is called the first time that a widget of a particular class is created and the resulting Tk_OptionTable is used in the future for all widgets of that class. 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 Tk_DeleteOptionTable should be called to free all of its resources. All of the option tables for a Tcl interpreter are freed automatically if the interpreter is deleted. so like, one interpreter per table, periodt.

Tk_InitOptions is invoked when a new widget is created to set the default values. Tk_InitOptions is passed a token for an option table (optionTable) and a pointer to a widget record (recordPtr), which is the C structure that holds information about this widget. Tk_InitOptions uses the information in the option table to choose an appropriate default for each option, then it stores the default value directly into the widget record, overwriting any information that was already present in the widget record. Tk_InitOptions normally returns TCL_OK. If an error occurred while setting the default values (e.g., because a default value was erroneous) then TCL_ERROR is returned and an error message is left in interp's result if interp is not NULL. For any widget's configuration option that has TK_OPTION_DONT_SET_DEFAULT set in its flags field, the above initialization is fully skipped, see below. not me skipping the default when that flag is set 🙈.

Tk_SetOptions is invoked to modify configuration options based on information specified in a Tcl command. The command might be one that creates a new widget, or a command that modifies options on an existing widget. The objc and objv arguments describe the values of the arguments from the Tcl command. 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 of the option conforms to the type in optionTable, and stores the value of the option into the widget record given by recordPtr. Tk_SetOptions normally returns TCL_OK. If an error occurred (such as 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. even number of objects, bestie, don't come at me with an odd one 💀.

Tk_SetOptions has two additional features. First, if the maskPtr argument is not NULL then it points to an integer value that is filled in with information about the options that were modified. For each option in the template passed to Tk_CreateOptionTable there is a typeMask field. The bits of this field are defined by the code that implements the widget; for example, each bit might correspond to a particular configuration option. Alternatively, bits might be used functionally. For example, 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 geometry of the widget must 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 this information to optimize itself so that, for example, it does not redisplay the widget if the modified options do not affect the widget's appearance. the way that maskPtr lets you skip unnecessary redraws? iconic.

The second additional feature of Tk_SetOptions has to do with 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 occur either while processing options in Tk_SetOptions or later in the caller. In many cases the caller does additional processing after Tk_SetOptions returns; for example, it might use an option value to set a trace on a variable and may detect an error if the variable is an array instead of a scalar. Error recovery is enabled by passing in a non-NULL value for the savePtr argument to Tk_SetOptions; this 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 information about the old values of any options modified by the procedure. If Tk_SetOptions returns successfully, the caller uses the structure in one of two ways. If the caller completes its processing of the new options without any errors, then it must pass the structure to Tk_FreeSavedOptions so that the old values can be freed. If the caller detects an error in its processing of the new options, then it should pass the structure to Tk_RestoreSavedOptions, which will copy the old values back into the widget record and free the new values. If Tk_SetOptions detects an error then it automatically restores any options that had already been modified and leaves *savePtr in an empty state: the caller need not call either Tk_FreeSavedOptions or Tk_RestoreSavedOptions. 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 the option. In this case, if an error occurs in the third option, the old values for the first two options cannot be restored.

🚨 bestie, real talk: if savePtr is NULL, those old values get freed on the spot, so if the third option errors out, the first two are gone gone. no take-backs. 🙈

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 lookup the option and extract its value from the widget record pointed to by recordPtr, then it 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. just hand over the current value, no drama.

Tk_GetOptionInfo returns information about configuration options in a form suitable for configure widget commands. If the namePtr argument is not NULL, it points to an object that gives 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 information 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. five elements when you name one, list-of-lists when you don't, and synonyms get special treatment — it's giving configure-core energy ✨

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. clean up after yourself, bestie, no leaked options.

The Tk_Offset macro is provided as a safe way of generating the objOffset and internalOffset values for entries in Tk_OptionSpec structures. It takes two arguments: the name of a type of record, and the name of a field in that record. It returns the byte offset of the named field in records of the given type. safe offset math so you don't have to hardcode byte positions, 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 literally the blueprint of every config option a widget class supports 💖 each structure in that array = one configuration option, and it looks like this:

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

let's go field by field bestie, no skipping 🫶

  • type — tells you what kind of option this is (like TK_OPTION_COLOR for a color value, or TK_OPTION_INT for an integer value). this is the field that decides how the value gets parsed (more on that in a sec).
  • optionName — the string like -font or -bg. it's the name used for the option in Tcl commands and the one passed to procedures through the objc or namePtr arguments.
  • dbName and dbClass — these are what Tk_InitOptions uses to look up a default value for this option in the option database. and if dbName is NULL? then Tk_InitOptions just doesn't touch the option database for this option, periodt.
  • defValue — the default value for this configuration option, used when the option database didn't give you one.
  • objOffset and internalOffset — these say where to stash the value of this option inside the widget record (again, more below 👇). and ngl, you should always generate these with the Tk_Offset macro. always.
  • flags — extra info that controls how this configuration option gets processed (details below ✨).
  • clientData — extra type-specific data that certain types need. for example, for TK_OPTION_COLOR types, clientData is a string giving the default value to use on monochrome displays. the type descriptions below will fill you in.
  • typeMask — the last one! Tk_SetOptions uses this to hand back info about which options were modified. see the description of Tk_SetOptions above for the deets.

so when Tk_InitOptions and Tk_SetOptions store an option's value into the widget record, they've got two ways to do it:

  • if the objOffset field of the Tk_OptionSpec is greater than or equal to zero, the value gets stored as a (Tcl_Obj *) at the spot in the widget record given by objOffset.
  • if the internalOffset field of the Tk_OptionSpec is greater than or equal to zero, the value gets stored in a type-specific internal form at the spot given by internalOffset. like, if the option's type is TK_OPTION_INT then the internal form is an integer.
  • if either objOffset or internalOffset is negative, the value just isn't stored in that form.

and the rule: at least one of the offsets must be greater than or equal to zero. you can't skip both, bestie, that's not a vibe 💅

the flags field is one or more bits ORed together. here's what's supported:

  • TK_OPTION_NULL_OK — if this bit is set for an option, then an empty string is accepted as the value, and the resulting internal form is a NULL pointer, a zero value, or None, depending on the type of the option. if the flag is not set, empty strings = errors 😭. TK_OPTION_NULL_OK is typically used to let a feature be turned off entirely — like setting a cursor value to None so a window just inherits its parent's cursor. heads up tho: not all option types support the TK_OPTION_NULL_OK flag; for the ones that do, the descriptions below will say so explicitly.
  • TK_OPTION_DONT_SET_DEFAULT — if this bit is set for an option, then no default value gets set in Tk_InitOptions for this option. neither the option database, nor any system default value, nor optionTable is used to give this option a default value. instead it's assumed that the caller already supplied a default value in the widget code. so like, you're on your own and that's the point 🙈

the type field of each Tk_OptionSpec structure determines how to parse the value of that configuration option. the legal values for type, and what each one actually does, are described below. and if the type needs a tkwin value passed into procedures like Tk_SetOptions, or if it uses the clientData field of the Tk_OptionSpec, it's called out explicitly; if it's not mentioned, the type needs neither tkwin nor clientData.

✨ the option types ✨

  • 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 Tk_GetAnchorFromObj returns.
  • TK_OPTION_BITMAP — the value must be a standard Tk bitmap name. the internal form is a Pixmap token like the ones Tk_AllocBitmapFromObj returns. this option type needs tkwin 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 isn't used, info about the original value of this option will be lost. 👀
  • 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 Tk_Alloc3DBorderFromObj returns. this option type needs tkwin 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 Tk_AllocColorFromObj returns. this option type needs tkwin 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 Tk_AllocCursorFromObj returns. this option type needs tkwin supplied to procedures such as Tk_SetOptions, and when the option is set, the cursor for the window is changed by calling XDefineCursor. it also supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_CUSTOM — this one 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 the whole story. main character energy tbh 👑
  • 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 zero.
  • 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 every template, no exceptions. and 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 is what lets common options be shared by several widget classes.
  • 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 Tk_AllocFontFromObj returns. this option type needs tkwin 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 (so like, 0 and 0x prefixes can be used to specify octal or hexadecimal numbers, respectively). the internal form is a C int value.
  • TK_OPTION_JUSTIFY — the value must be a standard justification value such as left. the internal form is a Tk_Justify, like the values Tk_GetJustifyFromObj returns.
  • 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 Tk_GetPixelsFromObj returns. note that if the objOffset field isn't used, info 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 must be standard relief such as raised. the internal form is an integer relief value such as TK_RELIEF_RAISED. this option type supports the TK_OPTION_NULL_OK flag; if a NULL value is set, the internal representation is set to TK_RELIEF_NULL.
  • TK_OPTION_STRING — the value may be any string. the internal form is a (char *) pointer that points to a dynamically allocated copy of the value. this option type supports the TK_OPTION_NULL_OK flag.
  • TK_OPTION_STRING_TABLE — for this type, clientData is a pointer to an array of strings suitable for passing to Tcl_GetIndexFromObj. the value must be one of the strings in the table, or a unique abbreviation of one of the strings. the internal form is an integer giving the index into the table of the matching string, like the return value from Tcl_GetStringFromObj. 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_SYNONYM — this type gives you alternative names for an option (for 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. whenever the synonym option is used, the info from the other option gets used instead. so cute, so efficient 🎀
  • TK_OPTION_WINDOW — the value must be a window path name. the internal form is a Tk_Window token for the window. this option type needs tkwin supplied to procedures such as Tk_SetOptions (so it can identify the application), and it supports the TK_OPTION_NULL_OK flag.

🗄️ STORAGE MANAGEMENT ISSUES ✨

ok so listen bestie, this is the part where Tk is literally doing the most for you 💅

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 of the storage allocation and resource management stuff for that field. Like, all of it. You don't gotta lift a finger 🫶

When the value of an option changes, Tk_SetOptions (or Tk_FreeSavedOptions) will automatically free any resources tied to the old value — think Tk_Fonts for TK_OPTION_FONT options, or dynamically allocated memory for TK_OPTION_STRING options. Auto-cleanup, no cap 🧹✨

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. It's giving shared custody, honestly.

When the widget is deleted, Tk_FreeConfigOptions should be invoked — it'll free the resources for all options and decrement the reference counts for any objects.

⚠️ But heads up queen: the widget code is responsible for storing NULL or None in all pointer and token fields before invoking Tk_InitOptions. This is needed to allow proper cleanup in the rare case where an error occurs in Tk_InitOptions. Don't skip this, fr fr 😭

🦋 OBJOFFSET VS. INTERNALOFFSET 🌸

okay so in most cases it's simplest to use the internalOffset field of a Tk_OptionSpec structure and not the objOffset field. Why? Because it makes the internal form of the value immediately available to the widget code, so the value doesn't have to be extracted from an object every single time it's used. Convenience, periodt 💅

However — and this is the plot twist — there are two cases where the objOffset field is actually useful:

  1. The first case is for TK_OPTION_PIXELS options. Here the internal form is an integer pixel value that is valid only for a particular screen. If the value of the option is retrieved, it'll be returned 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, this loses the original screen-independent value 😔 Thus for TK_OPTION_PIXELS options it's better to use the objOffset field. In this case the original value of the option is retained in the object and can be returned when the option is retrieved. In most cases it's convenient to use the internalOffset field as well, so that the integer value is immediately available for use in the widget code (alternatively, Tk_GetPixelsFromObj can be used to extract the integer value from the object whenever it's needed). Note that the problem of losing information on retrievals exists only for TK_OPTION_PIXELS options.
  2. The second reason to use the objOffset field is in order to implement new types of options not supported by these procedures. To implement a new type of option, you can 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 icon behaviour ✨
💀 Ttk widgets do not support the internalOffset machinery. Option values of Ttk widgets are always stored as (Tcl_Obj *), meaning that the objOffset field must be used. No exceptions, bestie.

🎀 CUSTOM OPTION TYPES 🧚

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 Tk_ObjCustomOption {
    const char *name;
    Tk_CustomOptionSetProc *setProc;
    Tk_CustomOptionGetProc *getProc;
    Tk_CustomOptionRestoreProc *restoreProc;
    Tk_CustomOptionFreeProc *freeProc;
    ClientData clientData;
} Tk_ObjCustomOption;

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

typedef Tcl_Obj *Tk_CustomOptionGetProc(
    ClientData clientData,
    Tk_Window tkwin,
    char *recordPtr,
    int internalOffset);

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

typedef void Tk_CustomOptionFreeProc(
    ClientData 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're invoked. The clientData value typically points to a structure containing information that's needed by the procedures when they're parsing and printing options. RestoreProc and freeProc may be NULL, indicating that no function should be called for those operations. (so valid, so optional 💅)

✨ 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. no cap, that's the whole job 🫡

💖 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. (cleanup is somebody else's problem, iconic 💅)

🍓 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. bye bye memory, you were real 🧹✨

🔥 KEYWORDS 🔥

  • anchor
  • bitmap
  • boolean
  • border
  • color
  • configuration option
  • cursor
  • double
  • font
  • integer
  • justify
  • pixels
  • relief
  • screen distance
  • synonym

okay bestie that's the whole thing, you made it to the end 🫶✨ go forth and configure your widgets, you absolute icon 👑

this one's from Tk 8.1, page Tk_SetOptions(3tk) — stay slay, stay saved-options-safe, mwah 💋🎀

📦 where this page comes from