ConfigWidg

Tk_ConfigureWidget(3)        Tk Library Procedures       Tk_ConfigureWidget(3)



______________________________________________________________________________

NAME
       Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_ConfigureValue,
       Tk_FreeOptions - process configuration options for widgets

SYNOPSIS
       #include <tk.h>

       int
       Tk_ConfigureWidget(interp, tkwin, specs, argc, argv, widgRec, flags)

       int
       Tk_Offset(type, field)

       int
       Tk_ConfigureInfo(interp, tkwin, specs, widgRec, argvName, flags)

       int
       Tk_ConfigureValue(interp, tkwin, specs, widgRec, argvName, flags)

       Tk_FreeOptions(specs, widgRec, display, flags)

ARGUMENTS
       Tcl_Interp      *interp    (in)      Interpreter to use for returning
                                            error messages.

       Tk_Window       tkwin      (in)      Window used to represent widget
                                            (needed to set up X resources).

       Tk_ConfigSpec   *specs     (in)      Pointer to table specifying legal
                                            configuration options for this
                                            widget.

       int             argc       (in)      Number of arguments in argv.

       char            **argv     (in)      Command-line options for
                                            configuring widget.

       char            *widgRec   (in/out)  Points to widget record structure.
                                            Fields in this structure get
                                            modified by Tk_ConfigureWidget to
                                            hold configuration information.

       int             flags      (in)      If non-zero, then it specifies an
                                            OR-ed combination of flags that
                                            control the processing of
                                            configuration information.
                                            TK_CONFIG_ARGV_ONLY causes the
                                            option database and defaults to be
                                            ignored, and flag bits
                                            TK_CONFIG_USER_BIT and higher are
                                            used to selectively disable
                                            entries in specs.

       type name       type       (in)      The name of the type of a widget
                                            record.

       field name      field      (in)      The name of a field in records of
                                            type type.

       char            *argvName  (in)      The name used on Tcl command lines
                                            to refer to a particular option
                                            (e.g. when creating a widget or
                                            invoking the configure widget
                                            command).  If non-NULL, then
                                            information is returned only for
                                            this option.  If NULL, then
                                            information is returned for all
                                            available options.

       Display         *display   (in)      Display containing widget whose
                                            record is being freed;  needed in
                                            order to free up resources.
_________________________________________________________________

DESCRIPTION
       Note: Tk_ConfigureWidget should be replaced with the new Tcl_Obj based  │
       API Tk_SetOptions.  The old interface is retained for backward          │
       compatibility.

       Tk_ConfigureWidget is called to configure various aspects of a widget,
       such as colors, fonts, border width, etc.  It is intended as a
       convenience procedure to reduce the amount of code that must be written
       in individual widget managers to handle configuration information.  It
       is typically invoked when widgets are created, and again when the
       configure command is invoked for a widget.  Although intended primarily
       for widgets, Tk_ConfigureWidget can be used in other situations where
       argc-argv information is to be used to fill in a record structure, such
       as configuring graphical elements for a canvas widget or entries of a
       menu.

       Tk_ConfigureWidget processes a table specifying the configuration
       options that are supported (specs) and a collection of command-line
       arguments (argc and argv) to fill in fields of a record (widgRec).  It
       uses the option database and defaults specified in specs to fill in
       fields of widgRec that are not specified in argv.  Tk_ConfigureWidget
       normally returns the value TCL_OK; in this case it does not modify
       interp.  If an error occurs then TCL_ERROR is returned and
       Tk_ConfigureWidget will leave an error message in interp->result in the
       standard Tcl fashion.  In the event of an error return, some of the
       fields of widgRec could already have been set, if configuration
       information for them was successfully processed before the error
       occurred.  The other fields will be set to reasonable initial values so
       that Tk_FreeOptions can be called for cleanup.

       The specs array specifies the kinds of configuration options expected
       by the widget.  Each of its entries specifies one configuration option
       and has the following structure:
              typedef struct {
                int type;
                char *argvName;
                char *dbName;
                char *dbClass;
                char *defValue;
                int offset;
                int specFlags;
                Tk_CustomOption *customPtr;
              } Tk_ConfigSpec;
       The type field indicates what type of configuration option this is
       (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for an
       integer value).  The type field indicates how to use the value of the
       option (more on this below).  The argvName field is a string such as
       ``-font'' or ``-bg'', which is compared with the values in argv (if
       argvName is NULL it means this is a grouped entry;  see GROUPED ENTRIES
       below).  The dbName and dbClass fields are used to look up a value for
       this option in the option database.  The defValue field specifies a
       default value for this configuration option if no value is specified in
       either argv or the option database.  Offset indicates where in widgRec
       to store information about this option, and specFlags contains
       additional information to control the processing of this configuration
       option (see FLAGS below).  The last field, customPtr, is only used if
       type is TK_CONFIG_CUSTOM;  see CUSTOM OPTION TYPES below.

       Tk_ConfigureWidget first processes argv to see which (if any)
       configuration options are specified there.  Argv must contain an even
       number of fields;  the first of each pair of fields must match the
       argvName of some entry in specs (unique abbreviations are acceptable),
       and the second field of the pair contains the value for that
       configuration option.  If there are entries in spec for which there
       were no matching entries in argv, Tk_ConfigureWidget uses the dbName
       and dbClass fields of the specs entry to probe the option database;  if
       a value is found, then it is used as the value for the option.
       Finally, if no entry is found in the option database, the defValue
       field of the specs entry is used as the value for the configuration
       option.  If the defValue is NULL, or if the TK_CONFIG_DONT_SET_DEFAULT
       bit is set in flags, then there is no default value and this specs
       entry will be ignored if no value is specified in argv or the option
       database.

       Once a string value has been determined for a configuration option,
       Tk_ConfigureWidget translates the string value into a more useful form,
       such as a color if type is TK_CONFIG_COLOR or an integer if type is
       TK_CONFIG_INT.  This value is then stored in the record pointed to by
       widgRec.  This record is assumed to contain information relevant to the
       manager of the widget;  its exact type is unknown to
       Tk_ConfigureWidget.  The offset field of each specs entry indicates
       where in widgRec to store the information about this configuration
       option.  You should use the Tk_Offset macro to generate offset values
       (see below for a description of Tk_Offset).  The location indicated by
       widgRec 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 configuration option.  The legal values for type,
       and the corresponding actions, are:

       TK_CONFIG_ACTIVE_CURSOR
              The value must be an ASCII string identifying a cursor in a form
              suitable for passing to Tk_GetCursor.  The value is converted to
              a Tk_Cursor by calling Tk_GetCursor and the result is stored in
              the target.  In addition, the resulting cursor is made the
              active cursor for tkwin by calling XDefineCursor.  If
              TK_CONFIG_NULL_OK is specified in specFlags then the value may
              be an empty string, in which case the target and tkwin's active
              cursor will be set to None.  If the previous value of the target
              wasn't None, then it is freed by passing it to Tk_FreeCursor.

       TK_CONFIG_ANCHOR
              The value must be an ASCII string identifying an anchor point in
              one of the ways accepted by Tk_GetAnchor.  The string is
              converted to a Tk_Anchor by calling Tk_GetAnchor and the result
              is stored in the target.

       TK_CONFIG_BITMAP
              The value must be an ASCII string identifying a bitmap in a form
              suitable for passing to Tk_GetBitmap.  The value is converted to
              a Pixmap by calling Tk_GetBitmap and the result is stored in the
              target.  If TK_CONFIG_NULL_OK is specified in specFlags then the
              value may be an empty string, in which case the target is set to
              None.  If the previous value of the target wasn't None, then it
              is freed by passing it to Tk_FreeBitmap.

       TK_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.

       TK_CONFIG_BORDER
              The value must be an ASCII string identifying a border color in
              a form suitable for passing to Tk_Get3DBorder.  The value is
              converted to a (Tk_3DBorder *) by calling Tk_Get3DBorder and the
              result is stored in the target.  If TK_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 Tk_Free3DBorder.

       TK_CONFIG_CAP_STYLE
              The value must be an ASCII string identifying a cap style in one
              of the ways accepted by Tk_GetCapStyle.  The string is converted
              to an integer value corresponding to the cap style by calling
              Tk_GetCapStyle and the result is stored in the target.

       TK_CONFIG_COLOR
              The value must be an ASCII string identifying a color in a form
              suitable for passing to Tk_GetColor.  The value is converted to
              an (XColor *) by calling Tk_GetColor and the result is stored in
              the target.  If TK_CONFIG_NULL_OK is specified in specFlags then
              the value may be an empty string, in which case the target will
              be set to None.  If the previous value of the target wasn't
              NULL, then it is freed by passing it to Tk_FreeColor.

       TK_CONFIG_CURSOR
              This option is identical to TK_CONFIG_ACTIVE_CURSOR except that
              the new cursor is not made the active one for tkwin.

       TK_CONFIG_CUSTOM
              This option allows applications to define new option types.  The
              customPtr field of the entry points to a structure defining the
              new option type.  See the section CUSTOM OPTION TYPES below for
              details.

       TK_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.

       TK_CONFIG_END
              Marks the end of the table.  The last entry in specs must have
              this type;  all of its other fields are ignored and it will
              never match any arguments.

       TK_CONFIG_FONT
              The value must be an ASCII string identifying a font in a form
              suitable for passing to Tk_GetFont.  The value is converted to a
              Tk_Font by calling Tk_GetFont and the result is stored in the
              target.  If TK_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 Tk_FreeFont.

       TK_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.

       TK_CONFIG_JOIN_STYLE
              The value must be an ASCII string identifying a join style in
              one of the ways accepted by Tk_GetJoinStyle.  The string is
              converted to an integer value corresponding to the join style by
              calling Tk_GetJoinStyle and the result is stored in the target.

       TK_CONFIG_JUSTIFY
              The value must be an ASCII string identifying a justification
              method in one of the ways accepted by Tk_GetJustify.  The string
              is converted to a Tk_Justify by calling Tk_GetJustify and the
              result is stored in the target.

       TK_CONFIG_MM
              The value must specify a screen distance in one of the forms
              acceptable to Tk_GetScreenMM.  The string is converted to
              double-precision floating-point distance in millimeters and the
              value is stored in the target.

       TK_CONFIG_PIXELS
              The value must specify screen units in one of the forms
              acceptable to Tk_GetPixels.  The string is converted to an
              integer distance in pixels and the value is stored in the
              target.

       TK_CONFIG_RELIEF
              The value must be an ASCII string identifying a relief in a form
              suitable for passing to Tk_GetRelief.  The value is converted to
              an integer relief value by calling Tk_GetRelief and the result
              is stored in the target.

       TK_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
              TK_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.

       TK_CONFIG_SYNONYM
              This type value identifies special entries in specs that are
              synonyms for other entries.  If an argv value matches the
              argvName of a TK_CONFIG_SYNONYM entry, the entry isn't used
              directly. Instead, Tk_ConfigureWidget searches specs for another
              entry whose argvName is the same as the dbName field in the
              TK_CONFIG_SYNONYM entry;  this new entry is used just as if its
              argvName had matched the argv value.  The synonym mechanism
              allows multiple argv values to be used for a single
              configuration option, such as ``-background'' and ``-bg''.

       TK_CONFIG_UID
              The value is translated to a Tk_Uid (by passing it to
              Tk_GetUid).  The resulting value is stored in the target.  If
              TK_CONFIG_NULL_OK is specified in specFlags and the value is an
              empty string then the target will be set to NULL.

       TK_CONFIG_WINDOW
              The value must be a window path name.  It is translated to a
              Tk_Window token and the token is stored in the target.


GROUPED ENTRIES
       In some cases it is useful to generate multiple resources from a single
       configuration value.  For example, a color name might be used both to
       generate the background color for a widget (using TK_CONFIG_COLOR) and
       to generate a 3-D border to draw around the widget (using
       TK_CONFIG_BORDER).  In cases like this it is possible to specify that
       several consecutive entries in specs are to be treated as a group.  The
       first entry is used to determine a value (using its argvName, dbName,
       dbClass, and defValue fields).  The value will be processed several
       times (one for each entry in the group), generating multiple different
       resources and modifying multiple targets within widgRec.  Each of the
       entries after the first must have a NULL value in its argvName field;
       this indicates that the entry is to be grouped with the entry that
       precedes it.  Only the type and offset fields are used from these
       follow-on entries.


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

       First, if the flags argument to Tk_ConfigureWidget has the
       TK_CONFIG_ARGV_ONLY bit set (i.e., flags | TK_CONFIG_ARGV_ONLY != 0),
       then the option database and defValue fields 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 configuration options while
       leaving others in their current state, such as when a configure widget
       command is being processed.

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

       TK_CONFIG_COLOR_ONLY
              If this bit is set then the entry will only be considered if the
              display for tkwin has more than one bit plane.  If the display
              is monochromatic then this specs entry will be ignored.

       TK_CONFIG_MONO_ONLY
              If this bit is set then the entry will only be considered if the
              display for tkwin has exactly one bit plane.  If the display is
              not monochromatic then this specs entry will be ignored.

       TK_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
              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.  If this bit isn't set then empty strings
              are processed as strings, which generally results in an error.

       TK_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
              Tk_ConfigureInfo.  In calls to Tk_ConfigureWidget 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
              target location.  This flag provides a performance optimization
              where it is expensive to process the default string:  the client
              can compute the default once, save the value, and provide it
              before calling Tk_ConfigureWidget.

       TK_CONFIG_OPTION_SPECIFIED
              This bit is set and cleared by Tk_ConfigureWidget.  Whenever
              Tk_ConfigureWidget 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
              Tk_ConfigureWidget.

       The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically
       used to specify different default values for monochrome and color
       displays.  This is done by creating two entries in specs that are
       identical except for their defValue and specFlags fields.  One entry
       should have the value TK_CONFIG_MONO_ONLY in its specFlags and the
       default value for monochrome displays in its defValue;  the other entry
       entry should have the value TK_CONFIG_COLOR_ONLY in its specFlags and
       the appropriate defValue for color displays.

       Third, it is possible to use flags and specFlags together to
       selectively disable some entries.  This feature is not needed very
       often.  It is useful in cases where several similar kinds of widgets
       are implemented in one place.  It allows a single specs table to be
       created with all the configuration options for all the widget types.
       When processing a particular widget 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 TK_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 Tk_ConfigureWidget.  If a specs table
       is being used for N different widget 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 widget types for which
       this entry is valid.  When calling Tk_ConfigureWidget, flags will have
       a single one of these bits set to select the entries for the desired
       widget type.  For a working example of this feature, see the code in
       tkButton.c.


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


TK_CONFIGUREINFO
       The Tk_ConfigureInfo procedure may be used to obtain information about
       one or all of the options for a given widget.  Given a token for a
       window (tkwin), a table describing the configuration options for a
       class of widgets (specs), a pointer to a widget record containing the
       current information for a widget (widgRec), and a NULL argvName
       argument, Tk_ConfigureInfo generates a string describing all of the
       configuration options for the window.  The string is placed in
       interp->result.  Under normal circumstances it returns TCL_OK;  if an
       error occurs then it returns TCL_ERROR and interp->result contains an
       error message.

       If argvName is NULL, then the value left in interp->result by
       Tk_ConfigureInfo consists of a list of one or more entries, each of
       which describes one configuration option (i.e. one entry in specs).
       Each entry in the list will contain either two or five values.  If the
       corresponding entry in specs has type TK_CONFIG_SYNONYM, then the list
       will contain two values:  the argvName for the entry and the dbName
       (synonym name).  Otherwise the list will contain five values:
       argvName, dbName, dbClass, defValue, and current value.  The current
       value is computed from the appropriate field of widgRec by calling
       procedures like Tk_NameOfColor.

       If the argvName argument to Tk_ConfigureInfo is non-NULL, then it
       indicates a single option, and information is returned only for that
       option.  The string placed in interp->result will be a list containing
       two or five 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 Tk_ConfigureInfo is used to restrict the specs
       entries to consider, just as for Tk_ConfigureWidget.


TK_CONFIGUREVALUE
       Tk_ConfigureValue takes arguments similar to Tk_ConfigureInfo; instead
       of returning a list of values, it just returns the current value of the
       option given by argvName (argvName must not be NULL).  The value is
       returned in interp->result and TCL_OK is normally returned as the
       procedure's result.  If an error occurs in Tk_ConfigureValue (e.g.,
       argvName is not a valid option name), TCL_ERROR is returned and an
       error message is left in interp->result.  This procedure is typically
       called to implement cget widget commands.


TK_FREEOPTIONS
       The Tk_FreeOptions procedure may be invoked during widget cleanup to
       release all of the resources associated with configuration options.  It
       scans through specs and for each entry corresponding to a resource that
       must be explicitly freed (e.g. those with type TK_CONFIG_COLOR), it
       frees the resource in the widget record.  If the field in the widget
       record doesn't refer to a resource (e.g.  it contains a null pointer)
       then no resource is freed for that entry.  After freeing a resource,
       Tk_FreeOptions sets the corresponding field of the widget record to
       null.


CUSTOM OPTION TYPES
       Applications can extend the built-in configuration types with
       additional configuration types by writing procedures to parse and print
       options of the a type and creating a structure pointing to those
       procedures:
              typedef struct Tk_CustomOption {
                Tk_OptionParseProc *parseProc;
                Tk_OptionPrintProc *printProc;
                ClientData clientData;
              } Tk_CustomOption;

              typedef int Tk_OptionParseProc(
                ClientData clientData,
                Tcl_Interp *interp,
                Tk_Window tkwin,
                char *value,
                char *widgRec,
                int offset);

              typedef char *Tk_OptionPrintProc(
                ClientData clientData,
                Tk_Window tkwin,
                char *widgRec,
                int offset,
                Tcl_FreeProc **freeProcPtr);
       The Tk_CustomOption structure contains three fields, which are pointers
       to the two procedures and a clientData value to be passed to those
       procedures when they are invoked.  The clientData value typically
       points to a structure containing information that is needed by the
       procedures when they are parsing and printing options.

       The parseProc procedure is invoked by Tk_ConfigureWidget to parse a
       string and store the resulting value in the widget record.  The
       clientData argument is a copy of the clientData field in the
       Tk_CustomOption structure.  The interp argument points to a Tcl
       interpreter used for error reporting.  Tkwin is a copy of the tkwin
       argument to Tk_ConfigureWidget.  The value argument is a string
       describing the value for the option;  it could have been specified
       explicitly in the call to Tk_ConfigureWidget or it could come from the
       option database or a default.  Value will never be a null pointer but
       it may point to an empty string.  RecordPtr is the same as the widgRec
       argument to Tk_ConfigureWidget;  it points to the start of the widget
       record to modify.  The last argument, offset, gives the offset in bytes
       from the start of the widget record to the location where the option
       value is to be placed.  The procedure should translate the string to
       whatever form is appropriate for the option and store the value in the
       widget record.  It should normally return TCL_OK, but if an error
       occurs in translating the string to a value then it should return
       TCL_ERROR and store an error message in interp->result.

       The printProc procedure is called by Tk_ConfigureInfo to produce a
       string value describing an existing option.  Its clientData, tkwin,
       widgRec, and offset arguments all have the same meaning as for
       Tk_OptionParseProc procedures.  The printProc procedure should examine
       the option whose value is stored at offset in widgRec, produce a string
       describing that option, and return a pointer to the string.  If the
       string is stored in dynamically-allocated memory, then the procedure
       must set *freeProcPtr to the address of a procedure to call to free the
       string's memory;  Tk_ConfigureInfo will call this procedure when it is
       finished with the string.  If the result string is stored in static
       memory then printProc need not do anything with the freeProcPtr
       argument.

       Once parseProc and printProc have been defined and a Tk_CustomOption
       structure has been created for them, options of this new type may be
       manipulated with Tk_ConfigSpec entries whose type fields are
       TK_CONFIG_CUSTOM and whose customPtr fields point to the
       Tk_CustomOption structure.


EXAMPLES
       Although the explanation of Tk_ConfigureWidget is fairly complicated,
       its actual use is pretty straightforward.  The easiest way to get
       started is to copy the code from an existing widget.  The library
       implementation of frames (tkFrame.c) has a simple configuration table,
       and the library implementation of buttons (tkButton.c) has a much more
       complex table that uses many of the fancy specFlags mechanisms.


SEE ALSO
       Tk_SetOptions(3)


KEYWORDS
       anchor, bitmap, boolean, border, cap style, color, configuration
       options, cursor, custom, double, font, integer, join style, justify,
       millimeters, pixels, relief, synonym, uid



Tk                                    4.1                Tk_ConfigureWidget(3)