Windows PowerShell command on Get-command Tk

Manual Pages for UNIX Operating System command usage for man Tk_GetOptionValue

Tk Library Procedures Tk_SetOptions(3TK)

_________________________________________________________________

NAME

Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_InitOptions,

Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions,

Tk_GetOptionValue, Tk_GetOptionInfo, Tk_FreeConfigOptions,

Tk_Offset - process configuration options

SYNOPSIS

#include

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

Tcl_Interp *interp (in) A Tcl inter-

preter. Most procedures use this only for returning error messages; if it is NULL then no error messages are returned. For

Tk_CreateOptionTable

the value cannot be NULL; it gives the Tk Last change: 8.1 1

Tk Library Procedures Tk_SetOptions(3TK)

interpreter in which the option table will be used.

Tk_OptionSpec *templatePtr (in) Points to an

array of static information that describes the configuration options that are supported. Used to build a

Tk_OptionTable.

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. Must have been returned by a previous call to

Tk_CreateOptionTable.

char *recordPtr (in/out) Points to struc-

ture in which

values of confi-

guration options are stored; fields of this

record are modi-

fied by pro-

cedures such as

Tk_SetOptions

and read by pro-

cedures such as

Tk_GetOptionValue.

Tk_Window tkwin (in) For options such

TK_OPTION_COLOR,

this argument indicates the window in which the option will be used. If optionTable uses Tk Last change: 8.1 2

Tk Library Procedures Tk_SetOptions(3TK)

no window-

dependent options, then a NULL value may be supplied for this argument. int objc (in) Number of values in objv.

Tcl_Obj *CONST objv[] (in) Command-line

arguments for

setting confi-

guring 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 modi-

fied 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 previ-

ously 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 Tk Last change: 8.1 3

Tk Library Procedures Tk_SetOptions(3TK)

particular option. If NULL is passed to

Tk_GetOptionInfo

then information is returned for all options. 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

These procedures handle most of the details of parsing con-

figuration options such as those for Tk widgets. Given a description of what options are supported, these procedures handle all the details of parsing options and storing their values into a C structure associated with the widget or object. The procedures 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: the easiest way to learn how to use these procedures

is to look at a working example. In Tk, the simplest exam-

ple is the code that implements the button family of widg-

ets, which is an tkButton.c. Other examples are in tkSquare.c and tkMenu.c. 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. Tk Last change: 8.1 4

Tk Library Procedures Tk_SetOptions(3TK)

In order to process configuration options efficiently, the

static template must be augmented with additional informa-

tion 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 inter-

preter, 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 inter-

preter are freed automatically if the interpreter is deleted.

Tk_InitOptions is invoked when a new widget is created to

set the default values for all of the widget's configuration

options. 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 isn't NULL.

Tk_SetOptions is invoked to modify configuration options

based on information specified in a Tcl command. The com-

mand 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 optionT-

able, 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 isn't NULL. Tk Last change: 8.1 5

Tk Library Procedures Tk_SetOptions(3TK)

Tk_SetOptions has two additional features. First, if the

maskPtr argument isn't 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 particu-

lar 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 doesn't redisplay the widget if the modified options don't affect the widget's appearance.

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 modi-

fied by the procedure. If Tk_SetOptions returns success-

fully, 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 Tk Last change: 8.1 6

Tk Library Procedures Tk_SetOptions(3TK)

first two options cannot be restored.

Tk_GetOptionValue returns the current value of a configura-

tion 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.

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 sub-

list 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.

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. TEMPLATES

The array of Tk_OptionSpec structures passed to

Tk_CreateOptionTable via its templatePtr argument describes

the configuration options supported by a particular class of widgets. Each structure specifies one configuration option Tk Last change: 8.1 7

Tk Library Procedures Tk_SetOptions(3TK)

and has the following fields: typedef struct {

Tk_OptionType type;

char *optionName; char *dbName; char *dbClass; char *defValue; int objOffset; int internalOffset; int flags; ClientData clientData; int typeMask;

} Tk_OptionSpec;

The type field indicates what kind of configuration option

this is (e.g. TK_OPTION_COLOR for a color value, or

TK_OPTION_INT for an integer value). Type determines how

the value of the option is parsed (more on this below). The

optionName field is a string such as -font or -bg; it is the

name used for the option in Tcl commands and passed to pro-

cedures via the objc or namePtr arguments. The dbName and

dbClass fields are used by Tk_InitOptions to look up a

default value for this option in the option database; if dbName is NULL then the option database is not used by

Tk_InitOptions for this option. The defValue field speci-

fies a default value for this configuration option if no value is specified in the option database. The objOffset and internalOffset fields indicate where to store the value of this option in widget records (more on this below); values for the objOffset and internalOffset fields should

always be generated with the Tk_Offset macro. The flags

field contains additional information to control the pro-

cessing of this configuration option (see below for

details). ClientData provides additional type-specific data

needed by certain types. For instance, for TK_OPTION_COLOR

types, clientData is a string giving the default value to use on monochrome displays. See the descriptions of the different types below for details. The last field,

typeMask, is used by Tk_SetOptions to return information

about which options were modified; see the description of

Tk_SetOptions above for details.

When Tk_InitOptions and Tk_SetOptions store the value of an

option into the widget record, they can do it in either of

two ways. 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 inter-

nalOffset. For example, if the option's type is

TK_OPTION_INT then the internal form is an integer. If the

Tk Last change: 8.1 8

Tk Library Procedures Tk_SetOptions(3TK)

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. The flags field consists of one or more bits ORed together. At present only a single flag is supported:

TK_OPTION_NULL_OK. If this bit is set for an option then an

empty string will be 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 will result in

errors. TK_OPTION_NULL_OK is typically used to allow a

feature to be turned off entirely, e.g. set a cursor value

to None so that a window simply inherits its parent's cur-

sor. Not all option types support the TK_OPTION_NULL_OK

flag; for those that do, there is an explicit indication of that fact in the descriptions below.

The type field of each Tk_OptionSpec structure determines

how to parse the value of that configuration option. The legal value 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 is indicated

explicitly; if not mentioned, the type requires neither tkwin nor clientData.

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.

TK_OPTION_BITMAP

The value must be a standard Tk bitmap name. The inter-

nal 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.

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 Last change: 8.1 9

Tk Library Procedures Tk_SetOptions(3TK)

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 XDefineCur-

sor. This option type also supports the

TK_OPTION_NULL_OK flag.

TK_OPTION_CUSTOM

This option allows applications to define new option types. The clientData field of the entry points to a

structure defining the new option type. See the sec-

tion 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 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 each template. If the clientData field of this structure isn't 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 allows common options to 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 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 Tk Last change: 8.1 10

Tk Library Procedures Tk_SetOptions(3TK)

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 returned by Tk_GetJustifyFromObj.

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: if the objOffset field

isn't used then information about the original value of

this option will be lost. See OBJOFFSET VS. INTER-

NALOFFSET 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 zero.

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 the empty string is speci-

fied as the value for the option, the integer relief

value 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 inter-

nal form is an integer giving the index into the table of the matching string, like the return value from

Tcl_GetStringFromObj.

TK_OPTION_SYNONYM

This type is used to provide alternative names for an

option (for example, -bg is often used as a synonym for

-background). The clientData field is a (char *)

pointer that gives the name of another option in the same table. Whenever the synonym option is used, the information from the other option will be used instead.

TK_OPTION_WINDOW

The value must be a window path name. The internal Tk Last change: 8.1 11

Tk Library Procedures Tk_SetOptions(3TK)

form is a Tk_Window token for the window. This option

type requires tkwin to be supplied to procedures such

as Tk_SetOptions (in order to identify the applica-

tion), and it supports the TK_OPTION_NULL_OK flag.

STORAGE MANAGEMENT ISSUES If a field of a widget record has its offset stored in the

objOffset or internalOffset field of a Tk_OptionSpec struc-

ture then the procedures described here will handle all of

the storage allocation and resource management issues asso-

ciated with the field. When the value of an option is

changed, Tk_SetOptions (or Tk_FreeSavedOptions) will

automatically free any resources associated with the old

value, such as Tk_Fonts for TK_OPTION_FONT options or dynam-

ically allocated memory for TK_OPTION_STRING options. 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 this object is incremented when a pointer to it is stored in the widget record and decremented when the option is modified. When the widget is deleted

Tk_FreeConfigOptions should be invoked; it will free the

resources associated with all options and decrement refer-

ence counts for any objects. However, 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.

OBJOFFSET VS. INTERNALOFFSET In most cases it is simplest to use the internalOffset field

of a Tk_OptionSpec structure and not the objOffset field.

This makes the internal form of the value immediately avail-

able to the widget code so the value doesn't have to be extracted from an object each time it is used. However, there are two cases where the objOffset field is useful.

The first case is for TK_OPTION_PIXELS options. In this

case, 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 will 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. Unfor-

tunately, this loses the original screen-independent value.

Thus for TK_OPTION_PIXELS options it is 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 is convenient to use the internalOffset field field as well, so that the Tk Last change: 8.1 12

Tk Library Procedures Tk_SetOptions(3TK)

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 is needed). Note: the problem of losing information on

retrievals exists only for TK_OPTION_PIXELS options.

The second reason to use the objOffset field is in order to

implement new types of options not supported by these pro-

cedures. 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. 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 {

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(

Tk Last change: 8.1 13

Tk Library Procedures Tk_SetOptions(3TK)

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 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. Res-

toreProc and freeProc may be NULL, indicating that no func-

tion should be called for those operations.

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. Tk Last change: 8.1 14

Tk Library Procedures Tk_SetOptions(3TK)

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, set-

Proc should set the value referenced by saveInter-

nalPtr 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 inter-

preter given by interp in the case of an error.

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 argu-

ment 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. Get-

Proc must return a pointer to a Tcl_Obj representing the

value of the option. The restoreProc procedure is invoked by

Tk_RestoreSavedOptions to restore a previously saved inter-

nal 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. Inter-

nalPtr is a pointer to the location where internal represen-

tation 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 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.

Tk Last change: 8.1 15

Tk Library Procedures Tk_SetOptions(3TK)

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 anchor, bitmap, boolean, border, color, configuration option, cursor, double, font, integer, justify, pixels, relief, screen distance, synonym

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

_______________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE|

|____________________|__________________|_

| Availability | runtime/tk-8 |

|____________________|__________________|_

| Interface Stability| Uncommitted |

|____________________|_________________|

NOTES Source for Tk is available on http://opensolaris.org. Tk Last change: 8.1 16