_________________________________________________________________



NAME

     Tcm_ConfigureObject, Tcm_ConfigureInfo

       - convenience functions to configure the slots of objects


SYNOPSIS

     #include <default.h>

     #include <tkConfig.h>
     #include <tkInt.h>

     #include <tcmConfig.h>

     int
     Tcm_ConfigureObject (interp, specs, argc, argv, objRec, flags)

     int
     Tcm_ConfigureInfo (interp, specs, objRec, argvName, flags)


ARGUMENTS

     Tcl_Interp       *interp   (in)      Used for error message.

     Tcm_ConfigSpec   *specs    (in)      Specification  of   the
                                          legal   slots   of  the
                                          object.

     int              argc      (in)      Number of args in argv.

     char             **argv    (in)      User supplied  command-
                                          line  strings that will
                                          be parsed to  configure
                                          the    slots   of   the
                                          object.

     char             *objRec   (in/out)  Pointer to  the  object
                                          record/struct   to   be
                                          configured.

     int              flags     (in)      If  non-zero,  then  it
                                          specifies  one  or more
                                          flags that control  the
                                          processing   of  confi-
                                          guration   information.
                                          Different  flags may be
                                          OR'ed together.

     char             *argvName (in)      The name of a  slot  of
                                          the  object.   If  non-
                                          NULL,  information   is
                                          returned  only for this
                                          slot.  If NULL,  infor-
                                          mation  is returned for
                                          all the object's slots.

_________________________________________________________________



Tcm_ConfigureInfo

     Tcm_ConfigureObject is called to configure the slots  of  an
     object.   By "configure", we mean "to set the value of slots
     of an object".  Tcm_ConfigureObject is intended  as  a  con-
     venience procedure to reduce the amount of code that must be
     written in any object manager code that  handles  configura-
     tion  and  slot  processing.   It  is typically invoked when
     objects are created, and again  when  the  their  slots  are
     reconfigured.  This configuration facility for objects comes
     from the original  configuration  handling  on  Tk  widgets.
     (This man page, too, was a snarf.)

     Tcm_ConfigureObject processes a table (specs)  which  speci-
     fies  the legal slots of the object and a collection of slot
     and value pairs (coming from argc and argv) to configure the
     slots of an object (objRec).  It uses the defaults specified
     in specs to fill in slots of objRec that are  not  specified
     in  argv.   Tcm_ConfigureObject  normally  returns the value
     TCL_OK; in this case it does not modify interp.  If an error
     occurs,  then  TCL_ERROR  is  returned with an error message
     left in interp->result in the standard Tcl fashion.  In  the
     event of an error return, some of the fields of objRec could
     already have been modified, if some slots were  successfully
     processed before the error occurred.

     The specs array (or table) specifies the legal slots of  the
     object.   Each  of  array element specifies one slot and has
     the following structure:

          typedef struct {
              int   type;
              char *argvName;
              char *defValue;
              int   offset;
              int   specFlags;
              Tk_CustomOption *customPtr;                          |
          } Tcm_ConfigSpec;


     The argvName field is a string such as  "-font"  or  "-name"
     and  is the name of the slot.  (Slot names are prefixed with
     "-" by convention.)  The type field indicates  the  type  of
     the  slot  (e.g.  TCM_CONFIG_INT for an integer value).  The
     defValue field specifies a default value for  this  slot  to
     have  if no value was specified in argv during processing by
     Tcm_ConfigureObject.  The offset field indicates  in  offset
     bytes  where  in objRec the slots exists, and specFlags con-
     this  slot (see FLAGS below).  The last field, customPtr, is
     historical -- a beached dead-whale  -  something  unpleasant
     that's hard to get rid of.  Set it to NULL for no headaches.

     Tcm_ConfigureObject first processes argc  and  argv  to  see
     which  (if  any)  slot  and value pairs are specified there.
     (Thus, the argument argv must  contain  an  even  number  of
     fields.)   The first of each slot and value pair is the slot
     name (which must match the argvName of some entry in specs).
     Unique  abbreviations for the slot name are acceptable.  The
     second part of  the  slot  and  value  pair  is  the  string
     representation  of the value that the slot should be set to.
     If no entry is found in  the  argv  for  a  slot,  then  the
     defValue  field  of the entry in specs for that slot is used
     as the value for the slot.  If the defValue is NULL,  or  if
     the  TCM_CONFIG_DONT_SET_DEFAULT  bit  is set in flags, then
     the slot's value is untouched if no value  is  specified  in
     argv.

     Once a string representation of a new value has been  deter-
     mined for a slot, Tcm_ConfigureObject translates that string
     value into a more useful form, such as an integer if type is
     TCM_CONFIG_INT.   This  value  is  then stored in the record
     pointed to by objRec.  This record  is  assumed  to  contain
     information relevant to the manager of the object; its exact
     type is unknown to Tcm_ConfigureObject.  The offset field of
     each  specs  entry  indicates  where  in objRec to store the
     information about this slot.  You should use the  Tcm_Offset
     macro to generate offset values (see below for a description
     of Tcm_Offset).  The location indicated by objRec and offset
     will  be  referred  to as the ``target'' in the descriptions
     below.

     The type field of each entry in specs determines what to  do
     with  the  string  value of that slot.  The legal values for
     type, and the corresponding actions, are: (NOTE: the follow-  |
     ing  might  be  OUT-OF-DATE - to find the real legal values,  |
     look at the source code for tcmConfig.* !!)

     TCM_CONFIG_BOOLEAN
          The value must be an ASCII string specifying a  boolean
          value.  Any of the values ``true'', ``yes'', ``on'', or
          ``1'', or an abbreviation of one of these values, means
          true;  any of the values ``false'', ``no'', ``off'', or
          ``0'', or an abbreviation of one of these values, means
          false.   The  target is expected to be an integer;  for
          true values it will be set to 1 and for false values it
          will be set to 0.

     TCM_CONFIG_INT
          The value must be an ASCII integer string in the format
          accepted  by strtol (e.g. ``0'' and ``0x'' prefixes may
          be  used  to  specify  octal  or  hexadecimal  numbers,
          respectively).   The  string is converted to an integer
          value and the integer is stored in the target.

     TCM_CONFIG_DOUBLE
          The value must be an ASCII floating-point number in the
          format  accepted by strtol.  The string is converted to
          a double value, and the value is stored in the target.

     TCM_CONFIG_STRING
          A copy of the value is made by allocating memory  space
          with   malloc   and   copying   the   value   into  the
          dynamically-allocated space.   A  pointer  to  the  new
          string  is stored in the target.  If TCM_CONFIG_NULL_OK
          is specified in specFlags then  the  value  may  be  an
          empty  string,  in which case the target will be set to
          NULL.  If the previous value of the target wasn't NULL,
          then it is freed by passing it to free.

     TCM_CONFIG_UID
          The value is translated to a Tcm_Uid (by passing it  to
          Tcm_GetUid).  The resulting value is stored in the tar-
          get.  If TCM_CONFIG_NULL_OK is specified  in  specFlags
          and  the  value is an empty string then the target will
          be set to NULL.


FLAGS

     The flags argument passed to Tcm_ConfigureObject is used  in
     conjunction  with  the  specFlags  fields  in the entries of
     specs to provide additional control over the  processing  of
     slots.   These  flags  are  used  in three different ways as
     described below.

     First, if the  flags  argument  to  Tcm_ConfigureObject  has
     TCM_CONFIG_ARGV_ONLY set (i.e., flags | TCM_CONFIG_ARGV_ONLY
     != 0), then the defValue fields of specs are not  used.   In
     this  case,  if  an  entry in specs doesn't match a field in
     argv then nothing happens: the  corresponding  target  isn't
     modified.  This feature is useful when the goal is to modify
     certain slots while leaving others in their  current  state,
     such  as  when  a  "configure"  object command is being pro-
     cessed.

     Second, the specFlags field of an entry in specs may be used
     to  control  the  processing  of  that  entry's  slot.  Each
     specFlags field may consists of an OR-ed combination of  the
     following values:

     TCM_CONFIG_NULL_OK
          This bit is only relevant for  some  types  of  entries
          (see  the  descriptions  of  the  various  entry  types
          above).  If this bit is set, it indicates that an empty
          string  value  for  the  field  is acceptable and if it
          occurs then the target should be set to NULL  or  None,
          depending on the type of the target.  This flag is typ-
          ically 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.   If  this
          bit  isn't  set  then  empty  strings  are processed as
          strings, which generally results in an error.

     TCM_CONFIG_DONT_SET_DEFAULT
          If this bit is one, it means that the defValue field of
          the entry should only be used for returning the default
          value    in    Tcm_ConfigureInfo.     In    calls    to
          Tcm_ConfigureObject  no  default  will  be supplied for
          entries with this flag set;  it  is  assumed  that  the
          caller has already supplied a default value in the tar-
          get location.  This flag provides a performance optimi-
          zation  where  it  is  expensive to process the default
          string:  the client can compute the default once,  save
          the    value,    and    provide   it   before   calling
          Tcm_ConfigureObject.

     TCM_CONFIG_OPTION_SPECIFIED
          This bit is set  and  cleared  by  Tcm_ConfigureObject.
          Whenever  Tcm_ConfigureObject returns, this bit will be
          set in all the entries where a value was  specified  in
          argv.   It will be zero in all other entries.  This bit
          provides a way for clients to  determine  which  values
          actually changed in a call to Tcm_ConfigureObject.

     It is possible to use flags and specFlags together to selec-
     tively  disable  some  entries.   This feature is not needed
     very often.  It is useful in  cases  where  several  similar
     kinds  of objects are implemented in one place.  It allows a
     single specs table to be created with all the slots  defined
     for  all  the  object  types.   When processing a particular
     object type, only entries relevant  to  that  type  will  be
     used.   This  effect  is  achieved by setting the high-order
     bits  (those  in  positions  equal  to   or   greater   than
     TCM_CONFIG_USER_BIT)  in  specFlags  values or in flags.  In
     order for a particular entry in specs to be used, its  high-
     order  bits  must  match  exactly the high-order bits of the
     flags value passed to Tcm_ConfigureObject.  If a specs table
     is  being  used  for N different object types, then N of the
     high-order bits will be used.  Each specs  entry  will  have
     one  of  more  of  those  bits set in its specFlags field to
     indicate the object types for which  this  entry  is  valid.
     When  calling  Tcm_ConfigureObject, flags will have a single
     one of these bits set to select the entries for the  desired
     object type.



TCM_OFFSET

     The Tcm_Offset macro is provided as a safe way of generating
     the  offset values for entries in Tcm_ConfigSpec 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.


Tcm_ConfigureInfo

     The Tcm_ConfigureInfo procedure may be used to obtain infor-
     mation  about  one  or  all of the slots for a given object.
     Given a pointer to an object, a table describing  the  slots
     for a class of objects (specs), a pointer to a object record
     containing the current information for  a  object  (objRec),
     and  a NULL argvName argument, Tcm_ConfigureInfo generates a
     string describing all of the  slots  for  the  window.   The
     string  is  placed  in  interp->result.   Under  normal cir-
     cumstances it returns TCL_OK; if an  error  occurs  then  it
     returns  TCL_ERROR and interp->result contains an error mes-
     sage.

     If argvName is NULL, then the value left  in  interp->result
     by  Tcm_ConfigureInfo  consists  of  a  list  of one or more
     entries, each of which describes  one  slot  of  the  object
     (i.e. one entry in specs).  Each entry in the list will con-
     tain three values: argvName, defValue, and current value.

     If the argvName argument to Tcm_ConfigureInfo  is  non-NULL,
     then it indicates a single slot, and information is returned
     only for that slot.  The  string  placed  in  interp->result
     will  be  a list containing three values as described above;
     this will be identical to  the  corresponding  sublist  that
     would have been returned if argvName had been NULL.

     The flags argument to Tcm_ConfigureInfo is used to  restrict
     the    specs    entries    to    consider,   just   as   for
     Tcm_ConfigureObject.


EXAMPLES

     Although the explanation of  Tcm_ConfigureObject  is  fairly
     complicated,  its actual use is pretty straightforward.  The
     easiest way to get started is  to  copy  the  code  from  an
     existing object.


KEYWORDS

     bitmap,  boolean,  configuration  options,  object,  double,
     integer, join style, justify, uid, slots


AUTHOR

     Brian Smith (bsmith@cs.berkeley.edu)
     Steve Yen (syen@cs.berkeley.edu)