SpecPerl 1.0

This package contains two scripts for producing perl/Tk output from
specTcl. 

I have created and tested the scripts using perl 5.004, specTcl 1.1b2,
and Tk402.002 on a DEC Alpha running Digital Unix 4.0a. It will _not_
run with earlier versions of perl/Tk like Tk400.202, etc. If you are
still using Tk400.202, I'd recommend sticking with specPerl 0.2 and
spectcl 1.0 until you can upgrade.

Changes: 

0.1 to 0.2

        - better handling of variables and textvariables entered via
          the widget configuration dialog
        - better handling of attached scrollbars and other widget
          containing commands
        - now works correctly with files in other directories. This
          is still a bug in specTcl, but is now fixed in specPerl :)
          (Achim Bohnet and Stephen O. Lidie)
        - encapsulated MainWindow object $top in wrapper code;
          perl -w -Mstrict hello.ui.pl now passes
          (Larry Virden)
        - a number of less significant changes

0.2 to 1.0

   - The internals of spectTcl changed from 1.0 to 1.1 and broke the 0.2
     script. Warren Jones created a patch so that specPerl now works with
     specTcl 1.1.
   - menubuttons no longer give warnings under perl -w
   - scales no longer give warnings under perl -w
   - the wrapper code has been changed so that the perl code generated by
     specPerl compiles cleanly with perl -Mstrict -w
   - Nick Ing-Simmons fixed a bug in perl/Tk, and now specPerl builds
     the interface in a main window.

I would like to thank Achim Bohnet, Stephen O. Lidie, and Larry Virden
for their comments on and testing of specPerl 0.1. For version 1.0,
I'd like to thank Warren Jones for the patches for specTcl 1.1, Larry
Virden for encouraging me to get some Perl discipline, and Nick
Ing-Simmons for upgrading perl/Tk and answering my questions.


Installation:

0) get the SpecTcl distribution from

        http://www.scriptics.com/products/spectcl/
   
   and thank Stephen Uhler, Ken Corey, and Ray Johnson for making the
   source available. Unpacking it yields the directories

        SpecTcl1.1/
        SpecTcl1.1/SpecTcl/
        SpecTcl1.1/bin

1) move the script SpecTcl1.1/SpecTcl/perl_init.tk  
                to SpecTcl1.1/SpecTcl/perl_init.tk.old
   
   copy the script perl_init.tk to SpecTcl1.1/SpecTcl/perl_init.tk 
   copy the script specPerl     to SpecTcl1.1/bin/specPerl

2) edit the file specPerl and change the line

      DIR=../SpecTcl
  
   to the corresponding directory on your machine if you like.



Running specPerl:

specPerl runs in pretty much the same way as specTcl does, so the
online help is applicable for specPerl as well. When saving project
foo, specPerl produces two files: foo.ui and foo.ui.pl. One can test
the Tk perl script by pressing the execute button or "Build and Test
Perl" in the Commands menu. One kills the running script by pressing
the Stop button or the "Kill Perl" entry in the Commands menu. Note
that in addition to "Save" and "Save As", "Build and Test Perl" also
saves the project.


Two projects are included in the package:

    hello.ui, hello.ui.pl - the canonical Tk project
    trip.ui, trip.ui.pl - a nonsensical, but gnarly trip test for specPerl 

perl -Mstrict -w trip.ui.pl produces no errors for me.


perl/Tk code generation notes: 

The code consists of three parts: the preamble, the subroutine and the
postamble. 

The preamble initializes variables, loads in Tk and sets up the main
window.

The subroutine is the heart of the code. It consists of five parts:
   1) widget creation: all the widget objects are created and some
      configuration parameters are set.
   2) widget commands: any commands associated with the widgets are
      placed after the widgets are created. See below for the 
      explanation.
   3) Geometry management: all the widgets are placed in their
      proper positions in the grid.
   4) Resize behavior management: the resizing behavior of the grid is
      set according to widget properties, etc.
   5) additional interface code: this is where the extra code you
      entered while in specPerl goes. This is useful for defining
      command subroutines associated with buttons, etc. 

The postamble invokes the subroutine to generate the UI and executes
MainLoop to jump into the event loop. The 1; at the end is for require
and use.

In general, the perl code produced by specPerl is a close counterpart
to the tcl code produced by specTcl. The main difference lies in two
places: 
        - the wrapper around the subroutine. So that the code compiles
          under -Mstrict, I create a use vars qw(); statement in the 
          beginning on the wrapper code. The statement can be removed
          if you don't care abut being strict. Also, if you have any 
          scale variable associated with a scale widget, they will be
          initialized to 0. This is done to suppress a -w warning about
          an uninitialized variable.

        - As noted above, the wrapper now creates just a main window
          and dispenses with the frame used in specPerl 0.2.

        - the widget commands. When, e.g., attaching scrollbars to a
          text widget in Tcl/Tk, one can create -commands involving
          undefined widgets with impunity, as long as those widgets
          are defined by the time the -command gets executed. In
          perl/Tk by contrast, the widgets need to be defined before
          they are used in a -command. In specPerl, this is handled by
          creating all the widgets first, and then further configuring
          all the widgets with -command type options.



I would enjoy hearing your comments, what you are building with
specPerl, bug reports and fixes, etc. My address is kvale@phy.ucsf.edu

Enjoy!
                                -Mark