composite(3) User Contributed Perl Documentation composite(3)NAMETk::composite - Defining a new composite widget class
SYNOPSIS
package Tk::MyNewWidget;
use Tk:widgets qw/ list of Tk widgets /;
use base qw/ Tk::Frame /; # or Tk::Toplevel
Construct Tk::Widget 'MyNewWidget';
sub ClassInit {
my( $class, $mw ) = @_;
#... e.g., class bindings here ...
$class->SUPER::ClassInit( $mw );
}
sub Populate {
my( $self, $args ) = @_;
my $flag = delete $args->{-flag};
if( defined $flag ) {
# handle -flag => xxx which can only be done at create
# time the delete above ensures that new() does not try
# and do $self->configure( -flag => xxx );
}
$self->SUPER::Populate( $args );
$self = $self->Component( ... );
$self->Delegates( ... );
$self->ConfigSpecs(
'-cursor' => [ SELF, 'cursor', 'Cursor', undef ],
'-something' => [ METHOD, dbName, dbClass, default ],
'-text' => [ $label, dbName, dbClass, default ],
'-heading' => [ {-text => $head},
heading, Heading, 'My Heading' ],
);
}
sub something {
my( $self, $value) = @_;
if ( @_ > 1 ) {
# set it
}
return # current value
}
1;
__END__
=head1 NAME
Tk::Whatever - a whatever widget
=head1 SYNOPSIS
use Tk::Whatever;
$widget = $parent->Whatever(...);
=head1 DESCRIPTION
...
DESCRIPTION
The intention behind a composite is to create a higher-level widget,
sometimes called a "super-widget" or "mega-widget". Most often, a com‐
posite will be built upon other widgets by using them, as opposed to
specializing on them. For example, the supplied composite widget
LabEntry is made of an Entry and a Label; it is neither a kind-of Label
nor is it a kind-of Entry.
Most of the work of a composite widget consistd in creating subwidgets,
arranging to dispatch configure options to the proper subwidgets and
manage composite-specific configure options.
GLORY DETAILS
Depending on your Perl/Tk knowledge this section may be enlighting or
confusing.
Composite Widget
Since Perl/Tk is heavilly using an object-oriented approach, it is no
suprise that creating a composite goes through a new() method. How‐
ever, the composite does not normally define a new() method itself: it
is usually sufficient to simply inherit it from Tk::Widget.
This is what happens when the composite uses
use base qw/ Tk::Frame /; # or Tk::Toplevel
to specify its inheritance chain. To complete the initialisation of
the widget, it must call the Construct method from class Widget. That
method accepts the name of the new class to create, i.e. the package
name of your composite widget:
Construct Tk::Widget 'MyNewWidget';
Here, MyNewWidget is the package name (aka the widget's class). This
will define a constructor method for MyNewWidget, normally named after
the widget's class. Instanciating that composite in client code would
the look like:
$mw = MainWindow->new; # creates a top-level MainWindow
$self = $mw->MyNewWidget(); # creates an instance of the
# composite widget MyNewWidget
Whenever a composite is instanciated in client code, "Tk::Wid‐
get::new()" will be invoked via the widget's class constructor. That
new method will call
$self->Populate(\%args);
where %args is the arguments passed to the widget's constructor. Note
that Populate receives a reference to the hash array containing all
arguments.
Populate is typically defined in the composite class (package), which
creates the characteristic subwidgets of the class.
Creating Subwidgets
Subwidget creation happens usually in Populate(). The composite usu‐
ally calls the subwidget's constructor method either directly, for
"private" subwidgets, or indirectly through the Component method for
subwidgets that should be advertised to clients.
Populate may call Delegates to direct calls to methods of chosen sub‐
widgets. For simple composites, typically most if not all methods are
directed to a single subwidget - e.g. ScrListbox directs all methods to
the core Listbox so that $composite->get(...) calls $listbox->get(...).
Defining mega-widget options
Populate should also call ConfigSpecs() to specify the way that config‐
ure-like options should be handled in the composite. Once Populate
returns, method Tk::Frame::ConfigDefault walks through the ConfigSpecs
entries and populates %$args hash with defaults for options from X
resources (.Xdefaults, etc).
When Populate returns to Tk::Widget::new(), a call to $self->config‐
ure(%$args) is made which sets *all* the options.
SEE ALSO
Tk::ConfigSpecs Tk::mega Tk::Derived
perl v5.8.8 2004-02-28 composite(3)