Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

Tk::composite (3)

Name

Tk::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

User Contributed Perl Documentation                               composite(3)



NAME
       Tk::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
       composite 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.
       However, 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::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(...).

   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.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+----------------------------+
       |ATTRIBUTE TYPE |      ATTRIBUTE VALUE       |
       +---------------+----------------------------+
       |Availability   | library/perl-5/perl-tk-532 |
       +---------------+----------------------------+
       |Stability      | Volatile                   |
       +---------------+----------------------------+

SEE ALSO
       Tk::ConfigSpecs Tk::mega Tk::Derived



NOTES
       Source code for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This software was built from source available at
       https://github.com/oracle/solaris-userland.  The original community
       source was downloaded from
       http://search.cpan.org/CPAN/authors/id/S/SR/SREZIC/Tk-804.036.tar.gz.

       Further information about this software can be found on the open source
       community website at http://search.cpan.org/~srezic/Tk.



perl v5.32.0                      2013-12-07                      composite(3)