view release on metacpan or  search on metacpan

pod/mega.pod  view on Meta::CPAN

## Author: Achim Bohnet <ach@mpe.mpg.de>
##
## Copyright (c) 1997-1998 Achim Bohnet. All rights reserved.
## You can redistribute this document and/or modify it under the
## same terms as Perl itself.
##
## Update for Tk804.025, Steve Lidie, 2004/01/11.

=head1 NAME

Tk::mega - Perl/Tk support for writing widgets in pure Perl

=for category Derived Widgets

=head1 SYNOPSIS

Define the widget's new class name:

S<    >B<package Tk::>I<MyNewWidget>;

For composite widget classes:

S<    >B<use base qw/ Tk::container />; # where B<container> is I<Frame> or I<Toplevel>

For derived widget classes:

S<    >B<use base qw/ Tk::Derived Tk::DerivedWidget /;>

Install the new widget in Tk's namespace and establish class and instance
constructors.

S<    >B<Construct Tk::>I<Widget> I<'MyNewWidget'>;

S<    >B<sub ClassInit> { I<my ($self, $args) = @_; ...> }

S<    >B<sub Populate> { I<my ($self, $args) = @_; ...> }

=head1 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.
I<For mega-widget sample code please run the B<widget> demonstration program and go to the section B<Sample Perl Mega-Widgets>.>

There are two kinds of mega-widgets:

=over 4

=item * Composite Widgets

A composite widget is composed with one or more existing widgets.
The composite widget looks to the user like a simple single widget.
A well known example is the file selection box.

=item * Derived Widgets

A derived widget adds/modifies/removes properties and methods
from a single widget (this widget may itself be a mega-widget).

=back

=head1 MEGA-WIDGET SUPPORT

=head2 Advertise

Give a subwidget a symbolic name.

Usage:

S<    >I<$self>-E<gt>B<Advertise>(B<name>=E<gt>I<$widget>);

Gives a subwidget I<$widget> of the mega-widget I<$self> the
name B<name>.  One can retrieve the reference of an advertised subwidget
with the L<Subwidget|"Subwidget"> method.

B<Comment:> Mega-Widget Writers: Please make sure to document the
advertised widgets that are intended for I<public> use.
If there are none, document this fact, e.g.:

	=head1 ADVERTISED WIDGETS

	None.

=head2 Callback

Invoke a callback specified with an option.

pod/mega.pod  view on Meta::CPAN

B<ClassInit> is called once for I<each> L<MainWindow|Tk::MainWindow>
just before the first widget instance of a class is created in
the widget tree of B<MainWindow>.

B<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 I<$class> is the class name (e.g. B<Tk::MyText>) and I<$mw> is the mainwindow.

Don't forget to call I<$class>-E<gt>B<SUPER::ClassInit($mw)> in
B<ClassInit>.

=head2 Component

Convenience function to create subwidgets.

Usage:

    $cw->Component('Whatever', 'AdvertisedName',
        -delegate => ['method1', 'method2', ...],
        ... more widget options ...,
    );

B<Component> does several things for you with one call:

=over 4

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)

=back

Example:

    $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});

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

=head2 Construct

Make the new mega-widget known to B<Tk>.

Usage:

S<    >B<Construct> I<baseclass> B<'Name'>;

B<Construct> declares the new widget class so that your mega-widget
works like normal Perl/Tk widgets.

Examples:

S<    >B<Construct Tk::Widget> I<'Whatever'>;
S<    >B<Construct Tk::Menu>   I<'MyItem'>;

First example lets one use I<$widget>-E<gt>B<Whatever> to create
new B<Whatever> widget.

The second example restricts the usage of the B<MyItem> constructor
method to widgets that are derived from B<Menu>:
I<$isamenu>-E<gt>I<MyItem>.

=head2 CreateArgs

Process options before any widget is created:

S<    >B<sub CreateArgs> { I<my ($package, $parent, $args) = @_; ...; return @newargs;> }

I<$package> is the package of the mega-widget (e.g., B<Tk::MyText>,
I<$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 I<$package>-E<gt>B<SUPER::CreateArgs>(I<$parent>, I<$args>) in
B<CreateArgs>.

=head2 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 B<'Construct'> delegation has a special meaning.  After
'Construct' is delegated all Widget constructors are redirected.
E.g. after

S<    >I<$self>-E<gt>B<Delegates>(B<'Construct'>=E<gt>I<$subframe>);

a I<$self>-E<gt>B<Button> does really a I<$subframe>-E<gt>B<Button>
so the created button is a child of I<$subframe> and not I<$self>.

B<Comment:> Delegates works only with methods that I<$cw> does
not have itself.

=head2 InitObject

I<Note: this method should not, in general, be used, as it has been
superceeded by B<Populate> and specifying B<Tk::Derived> as one of the base
classes.>

Defines construction and interface of derived widgets.

Usage:

    sub InitObject {
	my ($derived, $args) = @_;
	...
    }

where I<$derived> is the widget reference of the already created
baseclass widget and I<$args> is the reference to a hash of
I<-option-value> pairs.

B<InitObject> is almost identical to L<Populate|"Populate"> method.
B<Populate> does some more 'magic' things useful for mega-widgets
with several widgets.

Don't forget to call I<$derived>-E<gt>B<SUPER::InitObject>(I<$args>) in
B<InitObject>.

=head2 OnDestroy

Define a callback invoked when the mega-widget is destroyed.

Usage:

S<    >I<$widget>-E<gt>B<OnDestroy>(I<callback>);

B<OnDestroy> installs a L<callback|Tk::callbacks> that's called
when a widget is going to to be destroyed.  Useful
for special cleanup actions.  It differs from a normal B<destroy>
in that all the widget's data structures are still intact.

B<Comment:> This method could be used with any widgets not just
for mega-widgets.  It's listed here because of its usefulness.

=head2 Populate

Defines construction and interface of the composite
widget.

Usage:

    sub Populate {
	my ($self, $args) = @_;
	...
    }

where I<$self> is the widget reference of the already created baseclass
widget and I<$args> is the
reference to a hash of I<-option-value> pairs.

Most the other support function are normally used inside the B<Populate>
subroutine.

Don't forget to call I<$cw>-E<gt>B<SUPER::Populate>(I<$args>) in
B<Populate>.