configspecs(3)

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->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 pos
sible. (See Tk::options for a description of this
behaviour.) To enable this the attributes that the com
posite 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,db

Name,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 com
mands.

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->{Config
ure}{-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->{Config
ure}{-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, -op

tionY=>[$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).

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-speci
fied 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 refer
ence 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

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 suf
ficient.

SEE ALSO

Tk::composite, Tk::options

perl v5.8.0 2000-03-31 CONFIGSPECS(1)