NAME

       Tk_CreateOptionTable,   Tk_DeleteOptionTable,   Tk_InitOp­
       tions, Tk_SetOptions, Tk_FreeSavedOptions, Tk_RestoreSave­
       dOptions,       Tk_GetOptionValue,       Tk_GetOptionInfo,
       Tk_FreeConfigOptions, Tk_Offset  -  process  configuration
       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  inter­
                                                   preter.   Most
                                                   procedures use
                                                   this only  for
                                                   returning
                                                   error     mes­
                                                   sages;  if  it
                                                   is  NULL  then
                                                   no  error mes­
                                                   sages      are
                                                   returned.  For
                                                   Tk_CreateOp­
                                                   tionTable  the
                                                   value   cannot
                                                   interpreter in
                                                   which      the
                                                   option   table
                                                   will be  used.

       Tk_OptionSpec     *templatePtr    (in)      Points  to  an
                                                   array       of
                                                   static  infor­
                                                   mation    that
                                                   describes  the
                                                   configuration
                                                   options   that
                                                   are supported.
                                                   Used  to build
                                                   a
                                                   Tk_OptionTable.
                                                   The   informa­
                                                   tion   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­
                                                   ateOp­
                                                   tionTable.

       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_GetOption­
                                                   Value.

                                                   TK_OPTION_COLOR,
                                                   this  argument
                                                   indicates  the
                                                   window      in
                                                   which      the
                                                   option will be
                                                   used.       If
                                                   optionTable
                                                   uses  no  win­
                                                   dow-dependent
                                                   options,  then
                                                   a  NULL  value
                                                   may   be  sup­
                                                   plied for this
                                                   argument.

       int               objc            (in)      Number of val­
                                                   ues in objv.

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

       Tk_SavedOptions   *savePtr        (out)     If  not  NULL,
                                                   the  structure
                                                   pointed to  by
                                                   this  argument
                                                   is  filled  in
                                                   with  the  old
                                                   values of  any
                                                   options   that
                                                   were  modified
                                                   and old values
                                                   are   restored
                                                   automatically
                                                   if  an   error
                                                   occurs      in
                                                   Tk_SetOptions.

       int               *maskPtr        (out)     If  not  NULL,
                                                   the       word
                                                   pointed  to by
                                                   maskPtr     is
                                                   filled in with
                                                   the   bit-wise
                                                   OR    of   the
                                                   typeMask
                                                   fields for the
                                                   options   that
                                                   were modified.
                                                   structure pre­
                                                   viously filled
                                                   in          by
                                                   Tk_SetOptions
                                                   with  old val­
                                                   ues  of  modi­
                                                   fied  options.

       Tcl_Obj           *namePtr        (in)      The  value  of
                                                   this object is
                                                   the name of  a
                                                   particular
                                                   option.     If
                                                   NULL is passed
                                                   to   Tk_GetOp­
                                                   tionInfo  then
                                                   information is
                                                   returned   for
                                                   all   options.
                                                   Must   not  be
                                                   NULL      when
                                                   Tk_GetOption­
                                                   Value       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  proce­
       dures  handle all the details of parsing options and stor­
       ing 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  ``wid­
       get  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
       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 template that describes the various
       options supported by that class of widget; there is a sep­
       arate template for each kind of widget.  The template con­
       tains information such as the name  of  each  option,  its
       type, its default value, and where the value of the option
       is stored in the widget record.  See TEMPLATES  below  for
       more detail.

       In order to process configuration options efficiently, the
       static template must be augmented with additional 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_CreateOp­
       tionTable is called the first time that a widget of a par­
       ticular 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_DeleteOp­
       tionTable  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  configura­
       tion  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 informa­
       tion 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
       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  con­
       forms  to the type in optionTable, and stores the value of
       the option into the  widget  record  given  by  recordPtr.
       Tk_SetOptions   normally  returns  TCL_OK.   If  an  error
       occurred (such as an unknown option  name  or  an  illegal
       option value) then TCL_ERROR is returned and an error mes­
       sage is left in interp's result if interp isn't NULL.

       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 imple­
       ments the widget; for example, each bit  might  correspond
       to a particular configuration option.  Alternatively, bits
       might be used functionally.  For example, one bit might be
       used  for  redisplay: all options that affect the widget's
       display, such that changing the option requires the widget
       to  be  redisplayed, might have that bit set.  Another bit
       might indicate that the geometry of  the  widget  must  be
       recomputed,  and  so  on.  Tk_SetOptions OR's together the
       typeMask fields from all the options  that  were  modified
       and  returns  this  value at *maskPtr; the caller can then
       use this information to optimize itself so that, for exam­
       ple,  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 vari­
       able  is  an array instead of a scalar.  Error recovery is
       enabled by passing in a non-NULL  value  for  the  savePtr
       argument  to Tk_SetOptions; this should be a pointer to an
       uninitialized Tk_SavedOptions structure  on  the  caller's
       stack.   Tk_SetOptions overwrites the structure pointed to
       by savePtr with information about the old  values  of  any
       options  modified  by  the  procedure.   If  Tk_SetOptions
       returns successfully, the caller uses the structure in one
       of  two  ways.   If the caller completes its processing of
       the new options without any errors, then it must pass  the
       structure  to  Tk_FreeSavedOptions  so that the old values
       can be freed.  If the caller detects an error in its  pro­
       cessing of the new options, then it should pass the struc­
       ues.  If Tk_SetOptions detects an error then it  automati­
       cally  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  configu­
       ration  option for a particular widget.  The namePtr argu­
       ment 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
       sublist  for  each  synonym  option has only two elements,
       which are the name of the option and the name of the other
       option that it refers to; if namePtr is non-NULL and names
       a synonym option then the object returned is the five-ele­
       ment 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  generat­
       ing 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
       The  array  of  Tk_OptionSpec structures passed to Tk_Cre­
       ateOptionTable via its templatePtr argument describes  the
       configuration  options  supported 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 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  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
       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 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_GetAnchorFro­
              mObj.

       TK_OPTION_BITMAP
              The  value  must  be a standard Tk bitmap name. The
              internal form is  a  Pixmap  token  like  the  ones
              returned  by  Tk_AllocBitmapFromObj.   This  option
              type requires tkwin to be  supplied  to  procedures
              such   as   Tk_SetOptions,   and  it  supports  the
              TK_OPTION_NULL_OK flag.

       TK_OPTION_BOOLEAN
              The value must be a standard boolean value such  as
              true  or  no.  The internal form is an integer with
              value 0 or 1.

       TK_OPTION_BORDER
              The value must be a standard color name such as red
              or  #ff8080.   The  internal  form is a Tk_3DBorder
              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_AllocColorFro­
              mObj.   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_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_AllocCursorFro­
              mObj.  This option type requires tkwin to  be  sup­
              plied 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 sev­
              eral 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  to  specify  octal  or  hexadecimal  numbers,
              respectively).  The internal form is a C int value.

              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 giv­
              ing  a distance in pixels, like the values returned
              by Tk_GetPixelsFromObj.   Note:  if  the  objOffset
              field  isn't used then information about the origi­
              nal value of this option will be lost.  See OBJOFF­
              SET VS. INTERNALOFFSET 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 sup­
              ports 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_GetIndexFro­
              mObj.  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 syn­
              onym 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 proce­
              dures  such  as Tk_SetOptions (in order to identify
              the   application),    and    it    supports    the
              TK_OPTION_NULL_OK flag.



STORAGE MANAGEMENT ISSUES

       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  automatically 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  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 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 immedi­
       ately 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
       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  sim­
       ple  number.   For example, after the command .b configure
       -borderwidth 2m, the  command  .b  configure  -borderwidth
       might  return  7,  which is the integer pixel value corre­
       sponding to 2m.  Unfortunately, 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  immedi­
       ately 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
       ture  and set the objOffset field but not the internalOff­
       set field.  Then, after calling Tk_SetOptions, convert the
       object to internal form yourself.



KEYWORDS

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