_________________________________________________________________
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)