MAN page from Other perltk-800.022_5.00503-1.i386.rpm

CONFIGSPECS

Section: User Contributed Perl Documentation (1)
Updated: perl 5.005, patch 03
Index

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 likea regular Tk widget's configure as possible.(See the Tk::options manpage for a description of this behaviour.)To enable this the attributes that the composite as a whole acceptsneeds 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/replacea hash table for the widget. (More than one -option=>valuepair can be specified to a single call.)

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

It may be either one of the values below, or a list of such valuesenclosed 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 storingin $composite->{Configure}{-attribute}. This is appropriate for-command => ... attributes that are handled by the composite and notforwarded to a subwidget. (E.g. Tk::Tiler has -yscrollcommand toallow 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 immediatedescendants of a widget.)

'METHOD'

Call $cw->attribute(value)

This is the most general case. Simply have a method of the compositeclass with the same name as the attribute. The method may do anyvalidation and have whatever side-effects you like. (It is probablyworth `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 youcurrently only handle at create time.

'SELF'

Apply configure to the core widget (e.g. Frame) that is the basis ofthe composite. (This is the default behaviour for most attributes whichmakes a simple Frame behave the way you would expect.) Note that onceyou have specified ConfigSpecs for an attribute you must explicitlyinclude 'SELF' in the list if you want the attribute to apply to thecomposite 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. Theclass has configure and cget methods so allows higher level code toalways 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 probablybetter just to use the subwidget reference directly. The onlycase for retaining this form is to allow an additional layer ofabstraction - perhaps having a `current' subwidget - this is unproven.

Aliases

ConfigSpecs( -alias => '-otherattribute' ) is used to make -aliasequivalent 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 hashtake the form:

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

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

    -attribute => value

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

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

New()-time Configure

Once control returns to new, the list of user-supplied optionsaugmented by those from ConfigDefault are applied to the widget using theconfigure method below.

Widgets are most flexible and most Tk-like if they handle the majority oftheir 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 islooked up in this hash, if -attribute is not present in the hash then'DEFAULT' is looked for instead. (Aliases are tried as well and causeredirection to the aliased attribute). The result should be a reference to alist like:

  [ where, dbName, dbClass, default ]

at this stage only where is of interest, it maps to a list of objectreferences (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. Atpresent if where is a list of more than one object it is ignored completelyand the ``cached'' value in

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

is returned.

CAVEATS

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

Index

NAME
SYNOPSIS
DESCRIPTION
Defining the ConfigSpecs for a class.
Default Values
New()-time Configure
Configuring composites
Inquiring attributes of composites
CAVEATS
SEE ALSO

This document was created byman2html,using the manual pages.