Nick Ing-Simmons (PAUSE Custodial Account) > Tk-800.024 > Tk::mega

Download:
Tk-800.024.tar.gz

Annotate this POD

CPAN RT

New  33
Open  54
Stalled  15
View/Report Bugs
Source   Latest Release: Tk-804.032

NAME ^

Tk::mega - perl/Tk support to write widgets in perl

SYNOPSIS ^

 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) = @_; ... }

DESCRIPTION ^

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:

MEGA WIDGET SUPPORT ^

Advertise

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.

Callback

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.

ClassInit

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.

Component

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'});

ConfigSpecs

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 Tk::ConfigSpecs and Tk::Derived for details).

Construct

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.

CreateArgs

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.

Delegates

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.

InitObject

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.

OnDestroy

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.

Populate

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.

privateData

Set/get a private hash of a widget to storage composite internal data

Usage:

 $hashref = $mega->privateData();

 $another = $mega->privateData(unique_key|package);

Subwidget

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.

PITFALLS ^

MISSING ^

Of course perl/Tk does not define support function for all necessities. Here's a short list of things you have to handle yourself:

KEYWORDS ^

mega, composite, derived, widget

SEE ALSO ^

Tk::composite Tk::ConfigSpecs Tk::option Tk::callbacks Tk::bind

syntax highlighting: