summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/composite.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/composite.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/composite.pod171
1 files changed, 171 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/composite.pod b/Master/tlpkg/tlperl/lib/Tk/composite.pod
new file mode 100644
index 00000000000..c1dda4dbd19
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/composite.pod
@@ -0,0 +1,171 @@
+# $Id: composite.pod 1.2 Wed, 12 Nov 1997 00:30:45 +0100 ach $
+
+=head1 NAME
+
+Tk::composite - Defining a new composite widget class
+
+=for category Derived Widgets
+
+=head1 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
+
+ ...
+
+=head1 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 B<using> them, as opposed to specializing on them.
+For example, the supplied composite widget B<LabEntry> is I<made of> an
+B<Entry> and a B<Label>; it is neither a I<kind-of> B<Label>
+nor is it a I<kind-of> B<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.
+
+=head1 GLORY DETAILS
+
+Depending on your Perl/Tk knowledge this section may be enlighting
+or confusing.
+
+=head2 Composite Widget
+
+Since Perl/Tk is heavilly using an object-oriented approach, it is no
+suprise that creating a composite goes through a B<new()> method.
+However, the composite does not normally define a B<new()> method
+itself: it is usually sufficient to simply inherit it from
+B<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 B<Construct> method from class B<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, B<MyNewWidget> is the package name (aka the widget's B<class>). This
+will define a constructor method for B<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,
+C<Tk::Widget::new()> will be invoked via the widget's class
+constructor. That B<new> method will call
+
+ $self->Populate(\%args);
+
+where I<%args> is the arguments passed to the widget's constructor. Note
+that B<Populate> receives a B<reference> to the hash array
+containing all arguments.
+
+B<Populate> is typically defined in the composite class (package),
+which creates the characteristic subwidgets of the class.
+
+=head2 Creating Subwidgets
+
+Subwidget creation happens usually in B<Populate()>.
+The composite usually calls the
+subwidget's constructor method either directly, for "private" subwidgets,
+or indirectly through the B<Component> method for subwidgets that should
+be advertised to clients.
+
+B<Populate> may call B<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. B<ScrListbox> directs all methods to the core
+B<Listbox> so that I<$composite>-E<gt>B<get>(...) calls
+I<$listbox>-E<gt>B<get>(...).
+
+=head2 Defining mega-widget options
+
+B<Populate> should also call B<ConfigSpecs()> to specify the
+way that configure-like options should be handled in the composite.
+Once B<Populate> returns, method B<Tk::Frame::ConfigDefault>
+walks through the B<ConfigSpecs> entries and populates
+%$args hash with defaults for options from X resources (F<.Xdefaults>, etc).
+
+When B<Populate> returns to B<Tk::Widget::new()>,
+a call to B<$self>-E<gt>I<configure>(%$args) is made which sets *all*
+the options.
+
+=head1 SEE ALSO
+
+L<Tk::ConfigSpecs|Tk::ConfigSpecs>
+L<Tk::mega|Tk::mega>
+L<Tk::Derived|Tk::Derived>
+
+=cut
+