Advertise

Give a subwidget a symbolic name.

Usage:

    $self->Advertise(name=>$widget);

Gives a subwidget $widget of the mega-widget $self 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:

    $self->Callback(-option ?,args ...?);

Callback executes the callback defined with $self->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', ...],
        ... more widget options ...,
    );

Component does several things for you with one call:

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

Process 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

    $self->Delegates('Construct'=>$subframe);

a $self->Button does really a $subframe->Button so the created button is a child of $subframe and not $self.

Comment: Delegates works only with methods that $cw does not have itself.

InitObject

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

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 a callback invoked when the mega-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 its usefulness.

Populate

Defines construction and interface of the composite widget.

Usage:

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

where $self 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 = $self->privateData();

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

Subwidget

Get the widget reference of an advertised subwidget.

    @subwidget = $cw->Subwidget();

    $subwidget = $cw->Subwidget(name);

    @subwidget = $cw->Subwidget(name ?,...?);

Returns the widget reference(s) of the subwidget known under the given name(s). Without arguments, return all known subwidgets of $cw. See Advertise method how to define name for a subwidget.

Comment: Mega-Widget Users: Use Subwidget to get only documented subwidgets.