summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl92
1 files changed, 92 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl b/Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl
new file mode 100644
index 00000000000..f0415ea9cae
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl
@@ -0,0 +1,92 @@
+# Learn how to write your own widget demonstration.
+
+use vars qw/$TOP/;
+
+sub TEMPLATE {
+ my($demo) = @_;
+ $TOP = $MW->WidgetDemo(
+ -name => $demo,
+ -text => 'Learn how to write a widget demonstration!',
+ -geometry_manager => 'grid',
+ -title => 'WidgetDemo Example',
+ -iconname => 'WidgetDemo',
+ );
+ $TOP->Label(-text => 'Click "See Code".')->grid;
+}
+__END__
+
+The template code above specifies how user contributed widget demonstrations
+can be written.
+
+widget looks in the directory specified on the command line to load user
+contributed demonstrations. If no directory name is specified when widget is
+invoked and the environment variable WIDTRIB is defined then demonstrations
+are loaded from the WIDTRIB directory. If WIDTRIB is undefined then widget
+defaults to the released user contributed directory.
+
+The first line of the file is the DDD (Demonstration Description Data), which
+briefly describes the purpose of the demonstration. The widget program reads
+this line and uses it when building its interface.
+
+Demonstrations must have a unique subroutine which is the same as the filename
+with .pl stripped off. When widget calls your subroutine it's passed one
+argument, the demonstration name. So file TEMPLATE.pl contains subroutine
+TEMPLATE(). But a demo can actually be an entire program - read on!
+
+For consistency your demonstration should use the WidgetDemo widget. This is
+a toplevel widget with three frames. The top frame contains descriptive
+demonstration text. The bottom frame contains the "Dismiss" and "See Code"
+buttons. The middle frame is the demonstration container, which can be
+managed by either the pack or grid geometry manager.
+
+Since your subroutine can "see" all of widget's global variables, you
+use $MW (the main window reference) to create the WidgetDemo toplevel; be sure
+to pass at least the -name and -text parameters. -geometry_manager defaults
+to "pack". The call to WidgetDemo() returns a reference to the containing
+frame for your demonstration, so treat it as if it were the MainWindow, the
+top-most window of your widget hierarchy.
+
+Alternatively the .pl file may contain typical Perl/Tk code of the form:
+
+ # Demonstration Description Data
+
+ use Tk;
+ my $top = MainWindow->new;
+ $top->Label(-text => 'Whatever');
+ MainLoop;
+ __END__
+
+widget has re-defined normal MainWindow to actually create a WidgetDemo
+on your code's behalf. MainLoop is optional in a demo (it will immediately
+return as MainLoop is already active).
+
+Other consideration:
+
+ . widget global variables are all uppercase, like $MW - be careful not
+ to stomp on them!
+
+ . Demo files should really be run in private packages to avoid those
+ problems.
+
+ . Don't subvert the inheritance mechanism by calling Tk::MainWindow
+ in your demo code.
+
+ . The description should really be extracted from POD documentation
+ in the .pl file rather than a magic comment.
+
+ . If your demonstration has a Quit button change it to ring the bell
+ and use the builtin Dismiss instead. In particular destroying a
+ MainWindow is acceptable, but exit will shut down widget itself!
+
+ . Be sure $TOP is declared in a "use vars" statement and not as a
+ lexical my() in the subroutine (see below).
+
+ . If you're wrapping an existing main program in a subroutine be very
+ alert for closure bugs. Lexicals inside a subroutine become closed
+ so you may run into initialization problems on the second and
+ subsequent invokations of the demonstration. The npuz and plop
+ demonstrations show how to work around this. Essentially, remove
+ all "global" my() variables and place them within a "use vars".
+ This practice is prone to subtle bugs and is not recommended!
+
+