NAME

       Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets.

SYNOPSIS

           sub Populate
           {
            my ($composite,$args) = @_;
            ...
            $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
            $composite->ConfigSpecs('-alias' => '-otherattribute');
            $composite->ConfigSpecs('DEFAULT' => [ where ]);
            $composite->ConfigSpecs($subwidget->ConfigSpecs);
            ...
           }

           $composite->configure(-attribute => value);

DESCRIPTION

       The aim is to make the composite widget configure method look as much like a regular Tk
       widget's configure as possible.  (See Tk::options for a description of this behaviour.)
       To enable this the attributes that the composite as a whole accepts needs to be defined.

   Defining the ConfigSpecs for a class.
       Typically a widget will have one or more calls like the following

           $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);

       in its Populate method. When ConfigSpecs is called this way (with arguments) the arguments
       are used to construct or augment/replace a hash table for the widget. (More than one
       -option=>value pair can be specified to a single call.)

       dbName, dbClass and default are only used by ConfigDefault described below, or to respond
       to 'inquiry' configure commands.

       It may be either one of the values below, or a list of such values enclosed in [].

       The currently permitted values of where are:

       'ADVERTISED'
           Apply configure to advertised subwidgets.

       'DESCENDANTS'
           Apply configure recursively to all descendants.

       'CALLBACK'
           Setting the attribute does "Tk::Callback->new($value)" before storing in
           "$composite->{Configure}{-attribute}". This is appropriate for "-command => ..."
           attributes that are handled by the composite and not forwarded to a subwidget. (E.g.
           Tk::Tiler has "-yscrollcommand" to allow it to have scrollbar attached.)

           This may be the first of several 'validating' keywords (e.g. font, cursor, anchor
           etc.) that core Tk makes special for C code.

       'CHILDREN'
           Apply configure to all children.  (Children are the immediate descendants of a
           widget.)

       'METHOD'
           Call "$cw->attribute(value)"

           This is the most general case. Simply have a method of the composite class with the
           same name as the attribute.  The method may do any validation and have whatever side-
           effects you like.  (It is probably worth 'queueing' using afterIdle for more complex
           side-effects.)

       'PASSIVE'
           Simply store value in "$composite->{Configure}{-attribute}".

           This form is also a useful placeholder for attributes which you currently only handle
           at create time.

       'SELF'
           Apply configure to the core widget (e.g. Frame) that is the basis of the composite.
           (This is the default behaviour for most attributes which makes a simple Frame behave
           the way you would expect.) Note that once you have specified ConfigSpecs for an
           attribute you must explicitly include 'SELF' in the list if you want the attribute to
           apply to the composite itself (this avoids nasty infinite recursion problems).

       $reference (blessed)
           Call $reference->configure(-attribute => value)

           A common case is where $reference is a subwidget.

           $reference may also be result of

                Tk::Config->new(setmethod,getmethod,args,...);

           Tk::Config class is used to implement all the above keyword types.  The class has
           "configure" and "cget" methods so allows higher level code to always just call one of
           those methods on an object of some kind.

       hash reference
           Defining:

                   $cw->ConfigSpecs(
                           ...
                           -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
                                           dbname dbclass default ],
                           ...
                           );

           So "$cw->configure(-option => value)" actually does

                   $w1->configure(-optionX => value);
                   $w2->configure(-optionY => value);
                   $w3->configure(-optionY => value);

       'otherstring'
           Call

               $composite->Subwidget('otherstring')->configure( -attribute => value );

           While this is here for backward compatibility with Tk-b5, it is probably better just
           to use the subwidget reference directly.  The only case for retaining this form is to
           allow an additional layer of abstraction - perhaps having a 'current' subwidget - this
           is unproven.

       Aliases
           "ConfigSpecs( -alias => '-otherattribute' )" is used to make "-alias" equivalent to
           "-otherattribute". For example the aliases

               -fg => '-foreground',
               -bg => '-background'

           are provided automatically (if not already specified).

   Delegating all options of a widget class to a subwidget
           $composite->ConfigSpecs($subwidget->ConfigSpecs);

       The above generates a list of composite ConfigSpecs arguments, one for each valid option
       in $subwidget's class, and delegates said option to $subwidget.  See Tk::Widget and the
       widget method ConfigSpecs.  Duplicating composite ConfigSpecs and widget ConfigSpecs keys
       will yield undefined results.

   Default values
       When the Populate method returns ConfigDefault is called.  This calls

           $composite->ConfigSpecs;

       (with no arguments) to return a reference to a hash. Entries in the hash take the form:

           '-attribute' => [ where, dbName, dbClass, default ]

       ConfigDefault ignores 'where' completely (and also the DEFAULT entry) and checks the
       'options' database on the widget's behalf, and if an entry is present matching
       dbName/dbClass

           -attribute => value

       is added to the list of options that new will eventually apply to the widget. Likewise if
       there is not a match and default is defined this default value will be added.

       Alias entries in the hash are used to convert user-specified values for the alias into
       values for the real attribute.

   New()-time configure
       Once control returns to new, the list of user-supplied options augmented by those from
       ConfigDefault are applied to the widget using the configure method below.

       Widgets are most flexible and most Tk-like if they handle the majority of their attributes
       this way.

   Configuring composites
       Once the above have occurred calls of the form:

           $composite->configure( -attribute => value );

       should behave like any other widget as far as end-user code is concerned.  configure will
       be handled by Tk::Derived::configure as follows:

           $composite->ConfigSpecs;

       is called (with no arguments) to return a reference to a hash -attribute is looked up in
       this hash, if -attribute is not present in the hash then 'DEFAULT' is looked for instead.
       (Aliases are tried as well and cause redirection to the aliased attribute).  The result
       should be a reference to a list like:

         [ where, dbName, dbClass, default ]

       at this stage only where is of interest, it maps to a list of object references (maybe
       only one) foreach one

          $object->configure( -attribute => value );

       is evaled.

   Inquiring attributes of composites
          $composite->cget( '-attribute' );

       This is handled by  Tk::Derived::cget in a similar manner to configure. At present if
       where is a list of more than one object it is ignored completely and the "cached" value in

          $composite->{Configure}{-attribute}.

       is returned.

CAVEATS

       The "-background" and "-foreground" option values are automatically propagated down to all
       composite widget's children. This may be sometimes not desirable, especially if some
       subwidgets should use own color schemes, either by using explicit options or by option
       database definitions. If this is the case, then just add

           -foreground => 'SELF',
           -background => 'SELF',

       to "ConfigSpecs".

       It is the author's intention to port as many of the "Tix" composite widgets as make sense.
       The mechanism described above may have to evolve in order to make this possible, although
       now aliases are handled I think the above is sufficient.

SEE ALSO

       Tk::composite, Tk::options, Tk::Widget