Seth Woolley's Man Viewer

Tk_SetOptions(3) - Tk_CreateOptionTable, Tk_DeleteOptionTable, Tk_FreeConfigOptions, Tk_FreeSavedOptions, Tk_GetOptionInfo, Tk_GetOptionValue, Tk_InitOptions, Tk_Offset, Tk_RestoreSavedOptions, Tk_SetOptions - process configuration options - man 3 Tk_SetOptions

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

Tk_SetOptions(3)             Tk Library Procedures            Tk_SetOptions(3)



______________________________________________________________________________

NAME
       Tk_CreateOptionTable,  Tk_DeleteOptionTable,  Tk_InitOptions, Tk_SetOp-
       tions, Tk_FreeSavedOptions, Tk_RestoreSavedOptions,  Tk_GetOptionValue,
       Tk_GetOptionInfo,  Tk_FreeConfigOptions, Tk_Offset - process configura-
       tion options

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)

       int
       Tk_Offset(type, field)

ARGUMENTS
       Tcl_Interp        *interp         (in(1,8))      A  Tcl  interpreter.   Most
                                                   procedures  use  this  only
                                                   for  returning  error(8,n)  mes-
                                                   sages;  if(3,n)  it is NULL then
                                                   no   error(8,n)   messages   are
                                                   returned.  For Tk_CreateOp-
                                                   tionTable the value  cannot
                                                   be   NULL;   it  gives  the
                                                   interpreter  in(1,8)  which  the
                                                   option  table will be used.

       Tk_OptionSpec     *templatePtr    (in(1,8))      Points  to  an   array   of
                                                   static   information   that
                                                   describes the configuration
                                                   options that are supported.
                                                   Used     to     build     a
                                                   Tk_OptionTable.  The infor-
                                                   mation pointed to  by  this
                                                   argument must exist for the
                                                   lifetime       of       the
                                                   Tk_OptionTable.

       Tk_OptionTable    optionTable     (in(1,8))      Token  for an option table.
                                                   Must have been returned  by
                                                   a  previous call to Tk_Cre-
                                                   ateOptionTable.

       char              *recordPtr      (in(1,8)/out)  Points  to   structure   in(1,8)
                                                   which  values of configura-
                                                   tion  options  are  stored;
                                                   fields  of  this record are
                                                   modified by procedures such
                                                   as  Tk_SetOptions  and read(2,n,1 builtins)
                                                   by   procedures   such   as
                                                   Tk_GetOptionValue.

       Tk_Window         tkwin           (in(1,8))      For    options    such   as
                                                   TK_OPTION_COLOR, this argu-
                                                   ment  indicates  the window
                                                   in(1,8) which the option will be
                                                   used.   If optionTable uses
                                                   no         window-dependent
                                                   options,  then a NULL value
                                                   may be  supplied  for  this
                                                   argument.

       int               objc            (in(1,8))      Number of values in(1,8) objv.

       Tcl_Obj           *CONST objv[]   (in(1,8))      Command-line  arguments for
                                                   setting         configuring
                                                   options.

       Tk_SavedOptions   *savePtr        (out)     If  not NULL, the structure
                                                   pointed to by this argument
                                                   is  filled  in(1,8) with the old
                                                   values of any options  that
                                                   were  modified and old val-
                                                   ues are restored  automati-
                                                   cally if(3,n) an error(8,n) occurs in(1,8)
                                                   Tk_SetOptions.

       int               *maskPtr        (out)     If  not  NULL,   the   word
                                                   pointed  to  by  maskPtr is
                                                   filled in(1,8) with the bit-wise
                                                   OR  of  the typeMask fields
                                                   for the options  that  were
                                                   modified.

       Tk_SavedOptions   *savedPtr       (in(1,8)/out)  Points  to a structure pre-
                                                   viously   filled   in(1,8)    by
                                                   Tk_SetOptions with old val-
                                                   ues of modified options.

       Tcl_Obj           *namePtr        (in(1,8))      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.   Must not be
                                                   NULL when Tk_GetOptionValue
                                                   is called.

       type name         type            (in(1,8))      The  name  of the type of a
                                                   record.

       field name        field           (in(1,8))      The  name  of  a  field  in(1,8)
                                                   records of type type.
_________________________________________________________________

DESCRIPTION
       These  procedures  handle  most of the details of parsing configuration
       options such as those for Tk widgets.   Given  a  description  of  what
       options are supported, these procedures handle all the details of pars-
       ing options and storing their values into a C structure associated with
       the  widget  or object. The procedures were designed primarily for wid-
       gets(3,n) in(1,8) 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(1,8)
       practice  the  object  may not actually be a widget.  The term(5,7) ``widget
       record'' is used to refer to the C-level structure in(1,8) which information
       about a particular widget or object is stored.

       Note:  the  easiest way to learn how to use these procedures is to look(1,8,3 Search::Dict)
       at a working example.  In Tk, the simplest example  is  the  code  that
       implements the button family of widgets, which is an tkButton.c.  Other
       examples are in(1,8) 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 tem-
       plate that describes the various options supported  by  that  class  of
       widget; there is a separate template for each kind of widget.  The tem-
       plate contains information such as the name of each option,  its  type,
       its  default  value, and where the value of the option is stored in(1,8) the
       widget record.  See TEMPLATES below for more detail.

       In order to process configuration options efficiently, the static  tem-
       plate  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(1,2,n)  that  a widget of a particular class is created and the resulting
       Tk_OptionTable is used in(1,8) the future for all widgets of that class.   A
       Tk_OptionTable  may  be used only in(1,8) 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(3,n) the interpreter is deleted.

       Tk_InitOptions  is  invoked  when  a  new  widget is created to set(7,n,1 builtins) the
       default values for all of the widget's configuration options.   Tk_Ini-
       tOptions  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 informa-
       tion in(1,8) 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(1,8)  the
       widget  record.   Tk_InitOptions  normally returns TCL_OK.  If an error(8,n)
       occurred while setting the default  values  (e.g.,  because  a  default
       value was erroneous) then TCL_ERROR is returned and an error(8,n) message is
       left in(1,8) interp's result if(3,n) interp isn't NULL.

       Tk_SetOptions is invoked  to  modify  configuration  options  based  on
       information  specified in(1,8) 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 argu-
       ments 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(1,8) optionTable, checks that the new value of the
       option conforms to the type in(1,8) optionTable, and stores the value of the
       option  into  the widget record given by recordPtr.  Tk_SetOptions nor-
       mally returns TCL_OK.  If an error(8,n) occurred (such as an unknown  option
       name  or  an  illegal  option  value) then TCL_ERROR is returned and an
       error(8,n) message is left in(1,8) interp's result if(3,n) interp isn't NULL.

       Tk_SetOptions has two additional features.  First, if(3,n) the maskPtr argu-
       ment  isn't  NULL  then it points to an integer value that is filled in(1,8)
       with information about the options that were modified.  For each option
       in(1,8)  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 con-
       figuration 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(3,n) the modified options don't  affect  the
       widget's appearance.

       The  second  additional  feature  of Tk_SetOptions has to do with error(8,n)
       recovery.  If an error(8,n) 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(1,8)  Tk_SetOptions  or  later in(1,8) the caller.  In many cases the
       caller does additional  processing  after  Tk_SetOptions  returns;  for
       example,  it might use an option value to set(7,n,1 builtins) a trace(3x,n,3x _nc_tracebits) on a variable and
       may detect an error(8,n) if(3,n) the variable is an array instead  of  a  scalar.
       Error  recovery  is  enabled  by  passing  in(1,8)  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 proce-
       dure.  If Tk_SetOptions  returns  successfully,  the  caller  uses  the
       structure  in(1,8)  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(8,n) in(1,8) 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(8,n)  then  it  automatically restores any
       options that had already been modified and leaves *savePtr in(1,8) 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(3,n) an error(8,n)  occurs  in(1,8)
       the  third  option,  the old values for the first two options cannot be
       restored.

       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(8,n) occurs  (e.g.,
       because  namePtr contains an unknown option name) then NULL is returned
       and an error(8,n) message is left in(1,8) interp's result unless interp is  NULL.

       Tk_GetOptionInfo  returns  information about configuration options in(1,8) 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 configura-
       tion 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(1,8) 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(1,8)
       the  form  of a list of lists; each sublist describes one option.  Syn-
       onym options are handled differently depending on  whether  namePtr  is
       NULL:  if(3,n)  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(3,n) namePtr is non-NULL and names a syn-
       onym option then the object returned is the five-element list  for  the
       other  option  that  the  synonym refers to.  If an error(8,n) occurs (e.g.,
       because namePtr contains an unknown option name) then NULL is  returned
       and  an error(8,n) message is left in(1,8) 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(1,8) recordPtr by optionTable.

       The Tk_Offset macro is provided as a safe way of generating the objOff-
       set(7,n,1 builtins)  and internalOffset values for entries in(1,8) Tk_OptionSpec structures.
       It takes two arguments: the name of a type of record, and the name of a
       field  in(1,8) that record. It returns the byte offset of the named(5,8) field in(1,8)
       records of the given type.


TEMPLATES
       The array of Tk_OptionSpec structures  passed  to  Tk_CreateOptionTable
       via  its  templatePtr argument describes the configuration options sup-
       ported by a particular class of widgets.  Each structure specifies  one
       configuration option 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  inte-
       ger  value).   Type  determines  how  the value of the option is parsed
       (more on this below).  The optionName field is a string(3,n) such  as  -font
       or  -bg;  it is the name used for the option in(1,8) Tcl commands and passed
       to procedures via the  objc  or  namePtr  arguments.   The  dbName  and
       dbClass  fields  are  used by Tk_InitOptions to look(1,8,3 Search::Dict) up a default value
       for this option in(1,8) the option database; if(3,n)  dbName  is  NULL  then  the
       option  database  is  not  used by Tk_InitOptions for this option.  The
       defValue field specifies a default value for this configuration  option
       if(3,n)  no  value  is  specified in(1,8) the option database.  The objOffset and
       internalOffset fields indicate where to store the value of this  option
       in(1,8)  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
       processing 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(3,n)
       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(1,8)  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(1,8)  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(1,8) a type-specific internal form at the loca-
       tion in(1,8) the widget record given by internalOffset.  For example, if(3,n) 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(1,8) 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(7,n,1 builtins)
       for an option then an empty string(3,n) 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(7,n,1 builtins) then empty strings will result in(1,8) errors.  TK_OPTION_NULL_OK
       is typically used to allow a feature to be turned  off  entirely,  e.g.
       set(7,n,1 builtins)  a  cursor  value to None so that a window simply inherits its par-
       ent's cursor.  Not all option types support the TK_OPTION_NULL_OK flag;
       for  those that do, there is an explicit indication of that fact in(1,8) 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(3,n) it
       uses the clientData field of the Tk_OptionSpec, then  it  is  indicated
       explicitly;  if(3,n)  not  mentioned,  the  type  requires neither tkwin nor
       clientData.

       TK_OPTION_ANCHOR
              The value must be a standard anchor position such as ne or  cen-
              ter.   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  internal  form
              is  a  Pixmap token like the ones returned by Tk_AllocBitmapFro-
              mObj.  This option type requires tkwin to be supplied to  proce-
              dures    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_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(7,n,1 builtins)  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 allows applications to 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(3,n) value must be a floating-point number in(1,8)  the  format
              accepted  by  strtol.   The  internal  form is a C double value.
              This option type supports the TK_OPTION_NULL_OK flag; if(3,n) a  NULL
              value is set(7,n,1 builtins), the internal representation is set(7,n,1 builtins) 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 sup-
              plied to procedures such as Tk_SetOptions, and it  supports  the
              TK_OPTION_NULL_OK flag.

       TK_OPTION_INT
              The  string(3,n)  value  must be an integer in(1,8) 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.

       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(1,8) pixels,
              like the values returned by Tk_GetPixelsFromObj.  Note:  if(3,n)  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(3,n) a NULL value  is  set(7,n,1 builtins),  the  internal
              representation is set(7,n,1 builtins) 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(3,n) the empty
              string(3,n) is specified as the value for  the  option,  the  integer
              relief value is set(7,n,1 builtins) 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(1,8) 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(3,n), 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(1,8)  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 form is a
              Tk_Window token for the window.  This option type requires tkwin
              to  be supplied to procedures such as Tk_SetOptions (in(1,8) order to
              identify the application), and it supports the TK_OPTION_NULL_OK
              flag.


STORAGE MANAGEMENT ISSUES
       If a field of a widget record has its offset stored in(1,8) 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 issues associated with the field.   When  the  value  of  an
       option is changed, Tk_SetOptions (or Tk_FreeSavedOptions) will automat-
       ically free any resources  associated  with  the  old  value,  such  as
       Tk_Fonts for TK_OPTION_FONT options or dynamically 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  ref-
       erence  count  for  this  object is incremented when a pointer to it is
       stored in(1,8) the widget record and decremented when the  option  is  modi-
       fied.   When  the  widget  is  deleted  Tk_FreeConfigOptions  should be
       invoked; it will free the resources associated  with  all  options  and
       decrement reference counts for any objects.

       However, the widget code is responsible for storing NULL or None in(1,8) all
       pointer and token  fields  before  invoking  Tk_InitOptions.   This  is
       needed  to  allow proper cleanup in(1,8) the rare case where an error(8,n) occurs
       in(1,8) 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 available to the widget code  so
       the  value  doesn't have to be extracted from an object each time(1,2,n) it is
       used.  However, there are two cases where the objOffset field  is  use-
       ful.   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 config-
       ure -borderwidth 2m, the command .b configure -borderwidth might return
       7, which is the integer pixel  value  corresponding  to  2m.   Unfortu-
       nately,  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(1,8) 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
       integer value is immediately available  for  use  in(1,8)  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(1,8) 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(1,8)  the
       Tk_OptionSpec  structure and set(7,n,1 builtins) the objOffset field but not the inter-
       nalOffset 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 addi-
       tional 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(
                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.   RestoreProc  and  freeProc  may  be NULL, indicating that no
       function 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(1,8) the
       widget record.  The arguments are:

              clientData
                     A copy of the clientData field in(1,8) the  Tk_ObjCustomOption
                     structure.

              interp A pointer to a Tcl interpreter, used for error(8,n) 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(1,8) 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(1,8)  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(3,n) 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(1,8) 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(1,8)  a  Tk_SavedOptions
                     structure for the internal representation of the original
                     option value.  Before  setting  the  option  to  its  new
                     value, setProc should set(7,n,1 builtins) the value referenced by saveIn-
                     ternalPtr to the original value of the option in(1,8) order to
                     support Tk_RestoreSavedOptions.

              flags  A  copy of the flags field in(1,8) 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(8,n)
       message may be left in(1,8) the Tcl interpreter given by interp in(1,8) the  case
       of an error.

       The getProc procedure is invoked by Tk_GetOptionValue and Tk_GetOption-
       Info to retrieve a Tcl_Obj representation of the  internal  representa-
       tion of an option.  The clientData argument is a copy of the clientData
       field in(1,8) 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.  InternalOff-
       set(7,n,1 builtins)  is  the offset in(1,8) 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  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(1,8)
       the  Tk_ObjCustomOption  structure.  Tkwin is a copy of the tkwin argu-
       ment  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(3,n) necessary.  RestoreProc has no return value.

       The freeProc procedure is invoked by Tk_SetOptions and  Tk_FreeSavedOp-
       tions  to free any storage allocated for the internal representation of
       a custom option.  The clientData argument is a copy of  the  clientData
       field  in(1,8)  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
       anchor,  bitmap,  boolean, border, color, configuration option, cursor,
       double, font, integer, justify, pixels, relief, screen  distance,  syn-
       onym



Tk                                    8.1                     Tk_SetOptions(3)

References for this manual (incoming links)