| Tk::mega - perl/Tk support to write widgets in perl |
Tk::mega - perl/Tk support to write widgets in perl
package Tk::Whatever;
Construct Tk::ValidFor 'Whatever';
sub ClassInit { my ($mega, $args) = @_; ... }
For composite widget classes:
sub Populate { my ($composite, $args) = @_; ... }
For derived widget classes:
sub InitObject { my ($derived, $args) = @_; ... }
The goal of the mega widget support of perl/Tk is to make it easy to write mega widgets that obey the same protocol and interface that the Tk core widgets support. There are two kinds of mega widgets:
Give a subwidget a symbolic name.
Usage:
$cw->Advertise(name=>$widget);
Gives a subwidget $widget of the composite widget $cw the name name. One can retrieve the reference of an advertised subwidget with the Subwidget method.
Comment: Mega Widget Writers: Please make sure to document the advertised widgets that are intended for public use. If there are none, document this fact, e.g.:
=head1 ADVERTISED WIDGETS
None.
Invoke a callback specified with an option.
Usage:
$mega->Callback(-option ?,args ...?);
Callback executes the callback defined with $mega->ConfigSpecs(-option, [CALLBACK, ...]); If args are given they are passed to the callback. If -option is not defined it does nothing.
Initialization of the mega widget class.
Usage:
sub ClassInit { my ($class, $mw) = @_; ... }
ClassInit is called once for each MainWindow just before the first widget instance of a class is created in the widget tree of MainWindow.
ClassInit is often used to define bindings and/or other resources shared by all instances, e.g., images.
Examples:
$mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
$mw->bind($class,"<Return>", ['Insert',"\n"]);
$mw->bind($class,"<Delete>",'Delete');
Notice that $class is the class name (e.g. Tk::MyText) and $mw is the mainwindow.
Don't forget to call $class->SUPER::ClassInit($mw) in ClassInit.
Convenience function to create subwidgets.
Usage:
$cw->Component('Whatever', 'AdvertisedName',
-delegate => ['method1', 'method2', ...],
... Whatever widget options ...,
);
Component does several things for you with one call:
o Creates the widget
o Advertises it with a given name (overridden by 'Name' option)
o Delegates a set of methods to this widget (optional)
Example:
$cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});
Defines options and their treatment
Usage:
$cw->ConfigSpecs(
-option => [ where, dbname, dbclass, default],
...,
DEFAULT => [where],
);
Defines the options of a mega widget and what actions are triggered by configure/cget of an option (see the Tk::ConfigSpecs manpage and the Tk::Derived manpage for details).
Make the new mega widget known to Tk.
Usage:
Construct baseclass 'Name';
Construct declares the new widget class so that your mega widget works like normal Perl/Tk widgets.
Examples:
Construct Tk::Widget 'Whatever'; Construct Tk::Menu 'MyItem';
First example lets one use $widget->Whatever to create new Whatever widget.
The second example restricts the usage of the MyItem constructor method to widgets that are derived from Menu: $isamenu->MyItem.
Mess with options before any widget is created
sub CreateArgs { my ($package, $parent, $args) = @_; ...; return @newargs; }
$package is the package of the mega widget (e.g., Tk::MyText, $parent the parent of the widget to be created and $args the hash reference to the options specified in the widget constructor call.
Don't forget to call $package->SUPER::CreateArgs($parent, $args) in CreateArgs.
Redirect a method of the mega widget to a subwidget of the composite widget
Usage:
$cw->Delegates(
'method1' => $subwidget1,
'method2' => 'advertived_name',
...,
'Construct' => $subwidget2,
'DEFAULT' => $subwidget3,
);
The 'Construct' delegation has a special meaning. After 'Construct' is delegated all Widget constructors are redirected. E.g. after
$mega->Delegates('Construct'=>$subframe);
a $mega->Button does really a $subframe->Button so the created button is a child of $subframe and not $mega.
Comment: Delegates works only with methods that $cw does not have itself.
Defines construction and interface of derived widgets.
Usage:
sub InitObject {
my ($derived, $args) = @_;
...
}
where $derived is the widget reference of the already created baseclass widget and $args is the reference to a hash of -option-value pairs.
InitObject is almost identical to Populate method. Populate does some more 'magic' things useful for mega widgets with several widgets.
Don't forget to call $derived->SUPER::InitObject($args) in InitObject.
Define callback invoked when widget is destroyed.
Usage:
$widget->OnDestroy(callback);
OnDestroy installs a callback that's called when a widget is going to to be destroyed. Useful for special cleanup actions. It differs from a normal destroy in that all the widget's data structures are still intact.
Comment: This method could be used with any widgets not just for mega widgets. It's listed here because of it's usefulness.
Defines construction and interface of the composite widget.
Usage:
sub Populate {
my ($mega, $args) = @_;
...
}
where $mega is the widget reference of the already created baseclass widget and $args is the reference to a hash of -option-value pairs.
Most the other support function are normally used inside the Populate subroutine.
Don't forget to call $cw->SUPER::Populate($args) in Populate.
Set/get a private hash of a widget to storage composite internal data
Usage:
$hashref = $mega->privateData();
$another = $mega->privateData(unique_key|package);
Get the widget reference of an advertised subwidget.
$subwidget = $cw->Subwidget(name);
@subwidget = $cw->Subwidget(name ?,...?);
Returns the widget reference(s) of the subwidget known under the
name name. See Advertise method how to define
name for a subwidget.
Comment: Mega Widget Users: Use Subwidget to get only documented subwidgets.
Switch: Name: Class:
-padx padX Pad -activerelief activeRelief Relief -activebackground activeBackground Foreground -status undef undef
One should do the same when one defines one of these options via ConfigSpecs.
sub bind
{
my $mega = shift;
my $to = $mega->privateData->{'my_bind_target'};
$to->bind(@_);
}
But privateData does take an optional argument if you want to force which HASH is returned.
Of course perl/Tk does not define support function for all necessities. Here's a short list of things you have to handle yourself:
mega, composite, derived, widget
Tk::composite Tk::ConfigSpecs Tk::option Tk::callbacks Tk::bind
| Tk::mega - perl/Tk support to write widgets in perl |