ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tk_RestoreSavedOptions

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)      A  Tcl  interpreter.   Most
                                                   procedures  use  this  only
                                                   for  returning  error  mes-
                                                   sages;  if  it is NULL then
                                                   no   error   messages   are
                                                   returned.  For Tk_CreateOp-
                                                   tionTable the value  cannot
                                                   be   NULL;   it  gives  the
                                                   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 infor-
                                                   mation 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_Cre-
                                                   ateOptionTable.

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

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

       int               objc            (in)      Number of values in objv.

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

       Tk_SavedOptions   *savePtr        (out)     If  not NULL, the structure
                                                   pointed to by this argument
                                                   is  filled  in with the old
                                                   values of any options  that
                                                   were  modified and old val-
                                                   ues are restored  automati-
                                                   cally 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 pre-
                                                   viously   filled   in    by
                                                   Tk_SetOptions with old val-
                                                   ues of modified options.

       Tcl_Obj           *namePtr        (in)      The value of this object is
                                                   the  name  of  a particular
                                                   option.  If NULL is  passed
                                                   to   Tk_GetOptionInfo  then
                                                   information is returned for
                                                   all  options.   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 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 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 example  is  the  code  that
       implements the button family of widgets, 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 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 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  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.

       Tk_InitOptions  is  invoked  when  a  new  widget is created to set 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 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 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 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 nor-
       mally 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_SetOptions has two additional features.  First, if the maskPtr argu-
       ment  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 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 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 modified by the proce-
       dure.  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.

       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.

       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 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 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.  Syn-
       onym 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 syn-
       onym 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 objOff-
       set  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 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 such  as  -font
       or  -bg;  it is the name used for the option in Tcl commands and passed
       to procedures 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 specifies 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
       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
       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 loca-
       tion in the widget record given by internalOffset.  For example, if the
       option's  type  is  TK_OPTION_INT then the internal form is an integer.
       If the objOffset or internalOffset field is negative then the value  is
       not  stored  in that form.  At least one of the offsets must be greater
       than or equal to zero.

       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 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 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 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  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  the cursor for the window is changed by calling
              XDefineCursor.    This   option   type   also    supports    the
              TK_OPTION_NULL_OK flag.

       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.

       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 value must be an integer in the  format  accepted  by
              strtol  (e.g.  0 and 0x prefixes may be used to specify octal or
              hexadecimal numbers, respectively).  The internal form  is  a  C
              int value.

       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.

       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.

       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.

       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 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 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 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 automati-
       cally 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 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 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 available 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  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 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  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 procedures.  To implement a
       new type of option, use TK_OPTION_STRING as the type in the  Tk_Option-
       Spec  structure  and set the objOffset field but not the internalOffset
       field.  Then, after calling Tk_SetOptions, convert the object to inter-
       nal form yourself.


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)