move tlperl.straw to tlperl

git-svn-id: svn://tug.org/texlive/trunk@18210 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 423 insertions, 0 deletions

diff --git a/Master/tlpkg/tlperl/lib/Tk/mega.pod b/Master/tlpkg/tlperl/lib/Tk/mega.pod
new file mode 100755
index 00000000000..76e40e7891f
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/mega.pod
@@ -0,0 +1,423 @@
+
+## Author: Achim Bohnet <ach@mpe.mpg.de>
+##
+## Copyright (c) 1997-1998 Achim Bohnet. All rights reserved.
+## You can redistribute this document and/or modify it under the
+## same terms as Perl itself.
+##
+## Update for Tk804.025, Steve Lidie, 2004/01/11.
+
+=head1 NAME
+
+Tk::mega - Perl/Tk support for writing widgets in pure Perl
+
+=for category Derived Widgets
+
+=head1 SYNOPSIS
+
+Define the widget's new class name:
+
+S<    >B<package Tk::>I<MyNewWidget>;
+
+For composite widget classes:
+
+S<    >B<use base qw/ Tk::container />; # where B<container> is I<Frame> or I<Toplevel>
+
+For derived widget classes:
+
+S<    >B<use base qw/ Tk::Derived Tk::DerivedWidget /;>
+
+Install the new widget in Tk's namespace and establish class and instance
+constructors.
+
+S<    >B<Construct Tk::>I<Widget> I<'MyNewWidget'>;
+
+S<    >B<sub ClassInit> { I<my ($self, $args) = @_; ...> }
+
+S<    >B<sub Populate> { I<my ($self, $args) = @_; ...> }
+
+=head1 DESCRIPTION
+
+The goal of the mega-widget support of Perl/Tk is to make it
+easy to write mega-widgets that obey the same protocol and
+interface that the Tk core widgets support.
+I<For mega-widget sample code please run the B<widget> demonstration program and go to the section B<Sample Perl Mega-Widgets>.>
+
+There are two kinds of mega-widgets:
+
+=over 4
+
+=item * Composite Widgets
+
+A composite widget is composed with one or more existing widgets.
+The composite widget looks to the user like a simple single widget.
+A well known example is the file selection box.
+
+=item * Derived Widgets
+
+A derived widget adds/modifies/removes properties and methods
+from a single widget (this widget may itself be a mega-widget).
+
+=back
+
+=head1 MEGA-WIDGET SUPPORT
+
+=head2 Advertise
+
+Give a subwidget a symbolic name.
+
+Usage:
+
+S<    >I<$self>-E<gt>B<Advertise>(B<name>=E<gt>I<$widget>);
+
+Gives a subwidget I<$widget> of the mega-widget I<$self> the
+name B<name>.  One can retrieve the reference of an advertised subwidget
+with the L<Subwidget|"Subwidget"> method.
+
+B<Comment:> Mega-Widget Writers: Please make sure to document the
+advertised widgets that are intended for I<public> use.
+If there are none, document this fact, e.g.:
+
+	=head1 ADVERTISED WIDGETS
+
+	None.
+
+=head2 Callback
+
+Invoke a callback specified with an option.
+
+Usage:
+
+S<    >I<$self>-E<gt>B<Callback>(I<-option> ?,I<args> ...?);
+
+B<Callback> executes the L<callback|Tk::callbacks> defined with
+I<$self>-E<gt>B<ConfigSpecs>(I<-option>, [B<CALLBACK>, ...]);
+If I<args> are given they are passed to the callback. If
+I<-option> is not defined it does nothing.
+
+=head2 ClassInit
+
+Initialization of the mega-widget class.
+
+Usage:
+
+S<    >B<sub ClassInit> { I<my ($class, $mw) = @_;> ...  }
+
+B<ClassInit> is called once for I<each> L<MainWindow|Tk::MainWindow>
+just before the first widget instance of a class is created in
+the widget tree of B<MainWindow>.
+
+B<ClassInit> is often used to define bindings and/or other
+resources shared by all instances, e.g., images.
+
+Examples:
+
+ $mw->bind($class,"<Tab>", sub { my $w = shift; $w->Insert("\t"); $w->focus; $w->break});
+ $mw->bind($class,"<Return>", ['Insert',"\n"]);
+ $mw->bind($class,"<Delete>",'Delete');
+
+Notice that I<$class> is the class name (e.g. B<Tk::MyText>) and I<$mw> is the mainwindow.
+
+Don't forget to call I<$class>-E<gt>B<SUPER::ClassInit($mw)> in
+B<ClassInit>.
+
+=head2 Component
+
+Convenience function to create subwidgets.
+
+Usage:
+
+    $cw->Component('Whatever', 'AdvertisedName',
+        -delegate => ['method1', 'method2', ...],
+        ... more widget options ...,
+    );
+
+B<Component> does several things for you with one call:
+
+=over 4
+
+o Creates the widget
+
+o Advertises it with a given name (overridden by 'Name' option)
+
+o Delegates a set of methods to this widget (optional)
+
+=back
+
+Example:
+
+    $cw->Component('Button', 'quitButton', -command => sub{$mw->'destroy'});
+
+=head2 ConfigSpecs
+
+Defines options and their treatment
+
+Usage:
+
+    $cw->ConfigSpecs(
+        -option => [ where, dbname, dbclass, default],
+        ...,
+        DEFAULT => [where],
+    );
+
+Defines the options of a mega-widget and what actions
+are triggered by configure/cget of an option
+(see L<Tk::ConfigSpecs> and L<Tk::Derived> for details).
+
+=head2 Construct
+
+Make the new mega-widget known to B<Tk>.
+
+Usage:
+
+S<    >B<Construct> I<baseclass> B<'Name'>;
+
+B<Construct> declares the new widget class so that your mega-widget
+works like normal Perl/Tk widgets.
+
+Examples:
+
+S<    >B<Construct Tk::Widget> I<'Whatever'>;
+S<    >B<Construct Tk::Menu>   I<'MyItem'>;
+
+First example lets one use I<$widget>-E<gt>B<Whatever> to create
+new B<Whatever> widget.
+
+The second example restricts the usage of the B<MyItem> constructor
+method to widgets that are derived from B<Menu>:
+I<$isamenu>-E<gt>I<MyItem>.
+
+=head2 CreateArgs
+
+Process options before any widget is created:
+
+S<    >B<sub CreateArgs> { I<my ($package, $parent, $args) = @_; ...; return @newargs;> }
+
+I<$package> is the package of the mega-widget (e.g., B<Tk::MyText>,
+I<$parent> the parent of the widget to be created and $args the hash
+reference to the options specified in the widget constructor call.
+
+Don't forget to call I<$package>-E<gt>B<SUPER::CreateArgs>(I<$parent>, I<$args>) in
+B<CreateArgs>.
+
+=head2 Delegates
+
+Redirect a method of the mega-widget to a subwidget of
+the composite widget
+
+Usage:
+
+    $cw->Delegates(
+        'method1' => $subwidget1,
+        'method2' => 'advertived_name',
+        ...,
+        'Construct' => $subwidget2,
+        'DEFAULT'   => $subwidget3,
+    );
+
+The B<'Construct'> delegation has a special meaning.  After
+'Construct' is delegated all Widget constructors are redirected.
+E.g. after
+
+S<    >I<$self>-E<gt>B<Delegates>(B<'Construct'>=E<gt>I<$subframe>);
+
+a I<$self>-E<gt>B<Button> does really a I<$subframe>-E<gt>B<Button>
+so the created button is a child of I<$subframe> and not I<$self>.
+
+B<Comment:> Delegates works only with methods that I<$cw> does
+not have itself.
+
+=head2 InitObject
+
+I<Note: this method should not, in general, be used, as it has been
+superceeded by B<Populate> and specifying B<Tk::Derived> as one of the base
+classes.>
+
+Defines construction and interface of derived widgets.
+
+Usage:
+
+    sub InitObject {
+	my ($derived, $args) = @_;
+	...
+    }
+
+where I<$derived> is the widget reference of the already created
+baseclass widget and I<$args> is the reference to a hash of
+I<-option-value> pairs.
+
+B<InitObject> is almost identical to L<Populate|"Populate"> method.
+B<Populate> does some more 'magic' things useful for mega-widgets
+with several widgets.
+
+Don't forget to call I<$derived>-E<gt>B<SUPER::InitObject>(I<$args>) in
+B<InitObject>.
+
+=head2 OnDestroy
+
+Define a callback invoked when the mega-widget is destroyed.
+
+Usage:
+
+S<    >I<$widget>-E<gt>B<OnDestroy>(I<callback>);
+
+B<OnDestroy> installs a L<callback|Tk::callbacks> that's called
+when a widget is going to to be destroyed.  Useful
+for special cleanup actions.  It differs from a normal B<destroy>
+in that all the widget's data structures are still intact.
+
+B<Comment:> This method could be used with any widgets not just
+for mega-widgets.  It's listed here because of it's usefulness.
+
+=head2 Populate
+
+Defines construction and interface of the composite
+widget.
+
+Usage:
+
+    sub Populate {
+	my ($self, $args) = @_;
+	...
+    }
+
+where I<$self> is the widget reference of the already created baseclass
+widget and I<$args> is the
+reference to a hash of I<-option-value> pairs.
+
+Most the other support function are normally used inside the B<Populate>
+subroutine.
+
+Don't forget to call I<$cw>-E<gt>B<SUPER::Populate>(I<$args>) in
+B<Populate>.
+
+=head2 privateData
+
+Set/get a private hash of a widget to storage
+composite internal data
+
+Usage:
+
+S<    >I<$hashref> = I<$self>-E<gt>B<privateData>();
+
+S<    >I<$another> = I<$self>-E<gt>B<privateData>(I<unique_key>|I<package>);
+
+=head2 Subwidget
+
+Get the widget reference of an advertised subwidget.
+
+S<    >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>();
+
+S<    >I<$subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name>);
+
+S<    >I<@subwidget> = I<$cw>-E<gt>B<Subwidget>(I<name> ?,...?);
+
+Returns the widget reference(s) of the subwidget known under the given
+name(s). Without arguments, return all known subwidgets of I<$cw>. See
+L<Advertise|"Advertise"> method how to define I<name> for a subwidget.
+
+B<Comment:> Mega-Widget Users: Use B<Subwidget> to get I<only>
+documented subwidgets.
+
+=head1 PITFALLS
+
+=over 4
+
+=item * Resource DB class name
+
+Some of the standard options use a resource date base class
+that is not equal to the resource database name.  E.g.,
+
+  Switch:            Name:             Class:
+
+  -padx              padX              Pad
+  -activerelief      activeRelief      Relief
+  -activebackground  activeBackground  Foreground
+  -status            undef             undef
+
+One should do the same when one defines one of these
+options via B<ConfigSpecs>.
+
+=item * Method delegation
+
+Redirecting methods to a subwidget with B<Delegate>
+can only work if the base widget itself does have a
+method with this name.  Therefore one can't ``I<delegate>''
+any of the methods listed in L<Tk::Widget|Tk::Widget>.
+A common problematic method is B<bind>.  In this case
+one as to explicitely redirect the method.
+
+  sub bind {
+      my $self = shift;
+      my $to = $self->privateData->{'my_bind_target'};
+      $to->bind(@_);
+  }
+
+=item * privateData
+
+Graham Barr wrote: ... It is probably
+more private than most people think. Not all calls to privateData will
+return that same HASH reference. The HASH reference that is returned
+depends on the package it was called from, a different HASH is returned
+for each package. This allows a widget to hold private data, but then
+if it is sub-classed the sub-class will get a different HASH and so not
+cause duplicate name clashes.
+
+But privateData does take an optional argument if you want to
+force which HASH is returned.
+
+=item * Scrolled and Composite
+
+B<Scrolled>(I<Kind>,...) constructor can not be used with B<Composite>.
+One has to use $cw->B<Composite>(B<Scrl>I<Kind> =E<gt> B<'name'>, ...);
+
+=back
+
+=head1 MISSING
+
+Of course Perl/Tk does not define support function for
+all necessities.  Here's a short list of things you have to
+handle yourself:
+
+=over 4
+
+=item *
+
+No support to define construction-time only options.
+
+=item *
+
+No support to remove an option that is known to the
+base widget.
+
+=item *
+
+It's hard to define B<undef> as fallback for an widget
+option that is not already B<undef>.
+
+=item *
+
+Frame in Perl/Tk carries magic and overhead not needed
+for composite widget class definition.
+
+=item *
+
+No support methods for bindings that are shared between all
+widgets of a composite widget (makes sense at all?)
+
+=back
+
+=head1 KEYWORDS
+
+mega, composite, derived, widget
+
+=head1 SEE ALSO
+
+L<Tk::composite|Tk::composite>
+L<Tk::ConfigSpecs|Tk::ConfigSpecs>
+L<Tk::option|Tk::option>
+L<Tk::callbacks|Tk::callbacks>
+L<Tk::bind|Tk::bind>
+
+=cut
+