MEGA-WIDGET SUPPORT

   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:

           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
       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 PPooppuullaattee and specifying TTkk::::DDeerriivveedd 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 it's 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.

       o   Resource DB class name

           Some of the standard options use a resource date base class that is
           not equal to the resource database name.  E.g.,

             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.

       o   Method delegation

           Redirecting methods to a subwidget with Delegate can only work if
           the base widget itself does have a method with this name.
           Therefore one can't ``delegate'' any of the methods listed in
           Tk::Widget.  A common problematic method is bind.  In this case one
           as to explicitely redirect the method.

             sub bind {
                 my $self = shift;
                 my $to = $self->privateData->{'my_bind_target'};
                 $to->bind(@_);
             }

       o   privateData

           Graham Barr wrote: ... It is probably more private than most people
           think. Not all calls to privateData will return that same HASH
           reference. The HASH reference that is returned depends on the
           package it was called from, a different HASH is returned for each
           package. This allows a widget to hold private data, but then if it
           is sub-classed the sub-class will get a different HASH and so not
           cause duplicate name clashes.

           But privateData does take an optional argument if you want to force
           which HASH is returned.

       o   Scrolled and Composite

           Scrolled(Kind,...) constructor can not be used with Composite.  One
           has to use $cw->Composite(ScrlKind => 'name', ...);

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

       o   No support to define construction-time only options.

       o   No support to remove an option that is known to the base widget.

       o   It's hard to define undef as fallback for an widget option that is
           not already undef.

       o   Frame in Perl/Tk carries magic and overhead not needed for
           composite widget class definition.

       o   No support methods for bindings that are shared between all widgets
           of a composite widget (makes sense at all?)

       mega, composite, derived, widget

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



perl v5.18.0                      2010-05-29                           mega(3)