Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TK::COMPOSITE (3)

.ds Aq ’


Tk::composite - Defining a new composite widget class



    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( ... );

            -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



   =head1 NAME

   Tk::Whatever - a whatever widget

   =head1 SYNOPSIS

     use Tk::Whatever;

     $widget = $parent->Whatever(...);




The intention behind a composite is to create a higher-level widget, sometimes called a super-widget or mega-widget. Most often, a composite will be built upon other widgets by <B>usingB> them, as opposed to specializing on them. For example, the supplied composite widget <B>LabEntryB> is made of an <B>EntryB> and a <B>LabelB>; it is neither a kind-of <B>LabelB> nor is it a kind-of <B>EntryB>.

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.


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 <B>B>new()<B>B> method. However, the composite does not normally define a <B>B>new()<B>B> method itself: it is usually sufficient to simply inherit it from <B>Tk::WidgetB>.

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 <B>ConstructB> method from class <B>WidgetB>. 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, <B>MyNewWidgetB> is the package name (aka the widget’s <B>classB>). This will define a constructor method for <B>MyNewWidgetB>, 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::Widget::new() will be invoked via the widget’s class constructor. That <B>newB> method will call


where %args is the arguments passed to the widget’s constructor. Note that <B>PopulateB> receives a <B>referenceB> to the hash array containing all arguments.

<B>PopulateB> is typically defined in the composite class (package), which creates the characteristic subwidgets of the class.

    Creating Subwidgets

Subwidget creation happens usually in <B>B>Populate()<B>B>. The composite usually calls the subwidget’s constructor method either directly, for private subwidgets, or indirectly through the <B>ComponentB> method for subwidgets that should be advertised to clients.

<B>PopulateB> may call <B>DelegatesB> to direct calls to methods of chosen subwidgets. For simple composites, typically most if not all methods are directed to a single subwidget - e.g. <B>ScrListboxB> directs all methods to the core <B>ListboxB> so that $composite-><B>getB>(...) calls $listbox-><B>getB>(...).

    Defining mega-widget options

<B>PopulateB> should also call <B>B>ConfigSpecs()<B>B> to specify the way that configure-like options should be handled in the composite. Once <B>PopulateB> returns, method <B>Tk::Frame::ConfigDefaultB> walks through the <B>ConfigSpecsB> entries and populates %$args hash with defaults for options from X resources (.Xdefaults, etc).

When <B>PopulateB> returns to <B>B>Tk::Widget::new()<B>B>, a call to <B>B>$self<B>B>->configure(%$args) is made which sets *all* the options.


Tk::ConfigSpecs Tk::mega Tk::Derived
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 COMPOSITE (3) 2013-12-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.