home *** CD-ROM | disk | FTP | other *** search
/ CD Actual Thematic 7: Programming / CDAT7.iso / Share / Editores / Perl5 / perl / lib / site / Tk / demos / widtrib / TEMPLATE.pl < prev   
Encoding:
Text File  |  1997-08-10  |  3.1 KB  |  70 lines
  1. # Learn how to write your own widget demonstration!
  2.  
  3. use vars qw/$TOP/;
  4.  
  5. sub TEMPLATE {
  6.     my($demo) = @ARG;
  7.     my $demo_widget = $MW->WidgetDemo(
  8.         -name             => $demo,
  9.         -text             => 'Learn how to write a widget demonstration!',
  10.     -geometry_manager => 'grid',
  11.         -title            => 'WidgetDemo Example',
  12.         -iconname         => 'WidgetDemo',
  13.     );
  14.     $TOP = $demo_widget->Top;    # get geometry master
  15.     $TOP->Label(-text => 'Click "See Code".')->grid;
  16. }
  17. __END__
  18.  
  19. The template code above specifies how user contributed widget demonstrations
  20. must be written.  
  21.  
  22. All demonstrations must be a unique subroutine, in a directory of your
  23. choosing, stored in a file with the same name as the subroutine suffixed with
  24. ".pl".  So file TEMPLATE.pl contains subroutine TEMPLATE().
  25.  
  26. widget looks in the directory specified on the command line to load user
  27. contributed demonstrations.  If no directory name is specified when widget is
  28. invoked and the environment variable WIDTRIB is defined then demonstrations
  29. are loaded from the WIDTRIB directory. If WIDTRIB is undefined then widget
  30. defaults to the released user contributed directory.
  31.  
  32. The first line of the file is the DDD (Demonstration Description Data), which
  33. briefly describes the purpose of the demonstration.  The widget program reads
  34. this line and uses it when building its interface.
  35.  
  36. For consistency your demonstration should use the WidgetDemo widget.  This is  
  37. a toplevel widget with three frames. The top frame contains descriptive
  38. demonstration text.  The bottom frame contains the "Dismiss" and "See Code"
  39. buttons.  The middle frame is the demonstration container, which can be
  40. managed by either the pack or grid geometry manager.
  41.  
  42. When widget calls your subroutine it's passed one argument, the demonstration
  43. name.  Since your subroutine can "see" all of widget's global variables, you
  44. use $MW (the main window reference) to create the WidgetDemo toplevel; be
  45. sure to pass at least the -name and -text parameters.  -geometry_manager
  46. defaults to "pack".  Invoke the Top() method to fetch the containing frame
  47. for your demonstration, and treat it as if it were the MainWindow - the
  48. top-most window of your widget hierarchy.
  49.  
  50. Other consideration:
  51.  
  52.     . widget global variables are all uppercase, like $MW - be careful not
  53.       to stomp on them!
  54.  
  55.     . If your demonstration has a Quit button change it to ring the bell
  56.       and use the builtin Dismiss instead.
  57.  
  58.     . Remove a MainLoop() call, if present.
  59.  
  60.     . Be sure $TOP is declared in a "use vars" statement and not as a
  61.       lexical my() in the subroutine (see below).
  62.  
  63.     . If you're wrapping an existing main program in a subroutine be very
  64.       alert for closure bugs.  Lexicals inside a subroutine become closed
  65.       so you may run into initialization problems on the second and
  66.       subsequent invokations of the demonstration.  The npuz and plop
  67.       demonstrations show how to work around this.  Essentially, remove
  68.       all "global" my() variables and place them within a "use vars".
  69.       This practice is prone to subtle bugs and is not recommended!
  70.