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).
$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.
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