diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/demos/widtrib/TEMPLATE.pl | 92 |
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! + + |