view release on metacpan or  search on metacpan

pod/ConfigSpecs.pod  view on Meta::CPAN

equivalent to C<-otherattribute>. For example the aliases

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

are provided automatically (if not already specified).

=back

=head2 Delegating all options of a widget class to a subwidget

    $composite->ConfigSpecs($subwidget->ConfigSpecs);

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


=head2 Default values

When the B<Populate> method returns B<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 ]

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

=head2 B<New()-time configure>

Once control returns to B<new>, the list of user-supplied options
augmented by those from B<ConfigDefault> are applied to the widget using the
B<configure> method below.

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

=head2 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.
B<configure> will be handled by B<Tk::Derived::configure> as follows:

    $composite->ConfigSpecs;

is called (with no arguments) to return a reference to a hash B<-attribute> is
looked up in this hash, if B<-attribute> is not present in the hash then
B<'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 I<where> is of interest, it maps to a list of object
references (maybe only one) foreach one

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

is B<eval>ed.

=head2 Inquiring attributes of composites

   $composite->cget( '-attribute' );

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

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

is returned.

=head1 CAVEATS

The C<-background> and C<-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 C<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.

=head1 SEE ALSO

L<Tk::composite|Tk::composite>,
L<Tk::options|Tk::options>,
L<Tk::Widget>

=cut