composite(3pm)

💖 NAME 💖

Tk::composite — bestie, this is the page that teaches you how to define a brand-new composite widget class. Like, from scratch. It's giving "build your own super-widget" main character energy. 👑

---

✨ 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 🌸

okay so the whole intention behind a composite is to make a higher-level widget — people call it a "super-widget" or a "mega-widget", iconic naming honestly. Most often, a composite gets built upon other widgets by using them, as opposed to specializing on them. Example that ate: the supplied composite widget LabEntry is made of an Entry and a Label — and it is neither a kind-of Label nor a kind-of Entry. Not me being like "it contains them, it isn't them" 💅

Most of the work of a composite widget consists in creating subwidgets, arranging to dispatch configure options to the proper subwidgets and manage composite-specific configure options. That's the vibe. That's the job.

---

👑 GLORY DETAILS 👑

Depending on your Perl/Tk knowledge this section may be enlightening or confusing. fr fr, it could go either way. 🫶

🧩 Composite Widget

Since Perl/Tk is heavily using an object-oriented approach, it is no surprise that creating a composite goes through a new() method. However — plot twist — 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. Instantiating that composite in client code would then 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 instantiated in client code, Tk::Widget::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 usually 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 subwidgets. 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(...). Lowkey elegant, no cap. ✨

🎀 Defining mega-widget options

Populate should also call ConfigSpecs() to specify the way that configure-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->configure(%$args) is made which sets all the options. All of them. Every single one. periodt. 💅

---

🌈 SEE ALSO 🌈

• Tk::ConfigSpecs
• Tk::mega
• Tk::Derived

---

that's the whole page bestie, go forth and make a mega-widget, i believe in you 🎀

this was perl v5.40.1, dated 2025-04-13, from the User Contributed Perl Documentation collection — mwah, see u next manpage 💖