# README - An extension to Perl to access Xforms functions. # Copyright (C) 1996-1997 Martin Bartlett # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. *** INTRODUCTION This is an extension to Perl that allows you to call the Xforms functions from a standard Perl script. The implications are quite impressive - you can now develop complex X applications in Perl. The package includes a number of examples in the DEMOS directories (sound familiar?), many of which are unashamedly plagerised from the Xforms DEMOS directory. The inspiration for this project is also included - XFtool, an 'MS Office'-like toolbar - as are a couple of other useful applications developed using the package. This is the fifth release of the extension and operates with the 0.81 and 0.86 public releases, and the 0.84 and 0.85 testing releases of the Xforms library. It requires at least Perl 5.002. Please consider this an Alpha release - that is, it's a release that may cause you to 'alf-beat your head on a hard spiky object! I have not tested EVERY function. As releases pile up on each other this becomes less and less of a 'good-thing' since now most of the functions are definately NOT implemented with bog-standard XSUB code. THIS IS THE LAST RELEASE TO SUPPORT 0.81 thru 0.85. *** WHAT'S IMPLEMENTED Almost everything in Xforms 0.81, 0.84, 0.85 and 0.86! From basic forms to XEvent processing, from GL canvases to XY plots. There is a file, Xforms.not_implemented that covers whats NOT here - and why. For the most part, the functions have the same protocols from Perl as they do from C. This proves mighty useful, since you can very easily convert the nnnnnnn.c output from Fdesign into equivalent Perl statements. To this end, the master directory contains a program named fd2perl which is an fdesign filter program. By invoking fdesign in the following way: fdesign -perl a file, by the name of your .fd file but with a .pl suffix, will be generated. This will contain the perl code to build your fdesign-ed forms. The program is also callable from the command line. Before using the extension, please read the comments at the top of the Xforms.functions file. They contain information that you should be aware of, especially usage restrictions (I don't mean copyright restrictions, I mean things that you can't do because you'll probably die horribly!!!!). *** HOW'S IT IMPLEMENTED The world changes here! In this release the packaging has been completely overhauled and amended to comply with standard Perl extension conventions. The first thing to note is that I have reverted back to a single package for the Xforms related stuff, with two other independant packages relating to XEvent and XFontStruct structure access. The package itself has undergone its third name change. It is now called Xforms, and I intend to leave it at that. The reason for this reversion is that the single package is now smaller than the combined packages of the previous release, slightly bigger than the main Forms_BASIC package therein (unstripped), due to copious (ab)use of the xsubpp compiler's new-found ability to use aliases. This also means that the package will NOT compile on anything earlier than Perl5.002. In previous versions, there were two files that used to help you sort out what modules you needed for a particular application: forms.functions and forms.all_functions. The former still exists (but is renamed to Xforms.functions) since it also lists protocol differences between the Xforms 'C' interface and those provided by this package. The latter, however, has been removed. The Xforms.constants file still exists, containing usage notes for symbolic constants. *** WHAT'S CHANGED SINCE VERSION 0.4 . Single package named 'Xforms' replaces all Forms_* packages . Package version numbers conform to perl standards . OpenGL support is conditionally 'enable-able' using C compiler directives to include or exclude it based upon a symbol defined (or not) in the makefile . Extensive use of 'ALIAS'es in the xsubs allows a huge reduction in the Xforms library size . Consequently this version will not compile in Perl 5.001 environments (actually its the xs compiler that is the problem) . XEvent and XFontStruct packages also enjoy size reduction benefits from alias usage. . FD_FSELECTOR, FD_CMDLOG (>=0.84), FL_EditKeymap(>=0.85) , and FL_IOPT structures defined as perl objects . Extensive write access added to fields of FL_OBJECT and FL_FORM. . Pixmap and bitmap data support added . 0.84 and 0.85 changes and additions . Forms 0.81, 0.84, 0.85 and 0.86 supported (recompile required on version change) with constant values reflecting the correct version (yes some did change their values between versions!) . Old cnvrtfd.pl fdesign file converter modified to be a valid fdesign filter, and renamed to fd2perl. . Conversion routine to move 0.4 scripts to 0.6 added. *** WHAT IMPROVED BETWEEN THE FIRST CUT AND VERSION 0.4 . obviously the huge increase in supported functions. . fl_initialize now supports the FL_CMD_OPT parameters. . the fl...resource functions are now supported. . There are also fixes to the very weak callback mechanism I used in the first one - like no longer ignoring warnings in the perlcall manual page!! . The compile should now be completely warning free due to the addition of a typemap fix that gets rid of the const violation warnings. . XEvent structures are registered as perl objects of class XEventPtr. Using the separate, but jointly delivered XEventPtr extension (found in the XEvent directory), you can access the XEvent structures returned by some Forms functions. . XFontStruct structures are registered as perl objects of class XFontStructPtr. Using the separate, but jointly delivered XEventPtr extension (found in the XFontStruct directory), you can manipulate the XFontStruct structures used by some Forms functions. . You now have read access to the more interesting fields in the FL_OBJECT and FL_FORM structures (via perl OO syntax - $form->window for instance) and you have read AND WRITE access to the u_vdata and u_ldata fields in those structures (again, via perl OO syntax - see DEMOS/free1.pl for an example) PLEASE NOTE: The u_vdata field you access is NOT the REAL one, it's in a structure I chain off the real one - so don't try and mess with the real one. . The XFtool DEMO is a more solid implementation of a toolbar, with tooltips and command-line and pixmap browse/edit facilities. . Finally, the entire package has been broken into a number of modules to help with run time speed (most standard applications will only require one or two of the modules). *** WHAT YOU NEED You need a couple of things: . T.C.Zhao's and Mark Overmars' Forms Library for X, version 0.81 or above. You can get that from einstein.phys.uwm.edu /pub/xforms . Perl version 5.003. You need to have installed the full distribution (though you don't need the source tree itself). The make process checks your kit - but don't thank me for that as its all part of the standard Perl extension implementation process! You need the Perl extensions that get distributed with Perl but no others. The package may compile successfully on 5.002 as well. *** HOW TO INSTALL IT If you are reading this then you know how to gunzip/untar the distribution! From there you SHOULD be able to just do the following IF you want to use the extension as a dynamically loaded extension. If you want it statically bound then you need to read the comments that are found in the Makefile generated by the first step: In each of the Xforms, XEvent and XFontStruct directories of the master directory: 1) edit Makefile.PL # Read the comments in Makefile.PL that pertain # to Include paths, Library paths, and OpenGL, # and make any necessary changes. 2) perl Makefile.PL # to make the makefile using the Perl # MakeMaker.pm extension 3) make # To make a dynamic extension. The old error # ./blib/auto/Forms/.packlist: No such file # or directory # does not seem to occur at Perl 5.002 and above # Ignore warning messages of the form: # 'Warning: Aliases...' # These come from the xsubp compiler. I'm afraid I # deliberately use duplicate aliases to implement # some #define C aliases. 4) make install # To install the extension. Then, 5) cp fd2perl ... # Where ... is a deirectory that is in your # PATH when you run fdesign 6) Convert you Xforms4Perl 0.4 scripts to 0.6 (see below) If you want minimum size then, before step four, locate the .so files in the blib/arch/auto/ subdirectory of each directory, and execute your system's 'strip' program against the files. On my system this cuts about 30K off the Xforms package alone. Well, I'm nice! I have actually provided a RUDIMENTARY shell script that does steps 2 through 4 for you. It's called MakeF4P and it's in the master directory - and I do NOT gaurantee its accuracy (but it works for me!) You run MakeF4P from the master directory and it will make everything you need. BUT if you want OpenGL you MUST make the necessary changes to the Makefile.PL file in the Xforms subdirectory BEFORE running MakeF4P. The script will write all make results to a file named make.results in each of the direct subdirectories of the master directory. It will ask you if you want to look at the results once it has finished - you should! Note that the script also performs the 'strip' step mentioned above. *** HOW TO CONVERT Xforms4Perl 0.4 SCRIPTS TO Xforms4Perl 0.6 There's not much to do - just remove all use Forms_; statements and add use Xforms; But I have been nice (again). There is a Perl script named cnvt4to5.pl which will do the work for you. Invoke it like this: cnvt4to5.pl ... It will back up the old script with a suffix of '.x4p.4'. Note that the Xforms component Xforms4Perl.5 does not remove the Forms_* packages of Xforms4Perl.4, and does not even disable them. This is because of the differences in package names. To remove Xforms4Perl5 you must look in the site_perl directory of your base perl directory (mine is /usr/lib/perl5) and remove all files and directories with names matching 'Forms_*' (in UNIX file globbing notation). *** HOW TO USE IT Basically just add use Xforms; to your perl script, then follow the instructions given in the xforms documentation, making any necessary semantic transformations between the C presented therin and the Perl you are using. See the Xforms.functions file in the master directory for more details on this. Also, take a look at the DEMOS directories for examples of usage. *** OPENGL NOTES The OpenGL related functions are now part of Xforms. To use them you MUST change the Makefile.PL file in the Xforms directory. See the comments in Makefile.PL for details. If you attempt to use an OpenGL function WITHOUT compiling them into the package then your perl script will die with a message: Xforms4Perl OpenGL functions are not installed. To rectify, make the changes necessary in the Makefile.PL and re-build the package. *** DEVELOPMENT DETAILS This version was developed on an IBM Thinkpad 760ED running Linux 2.0.28 from RedHat, X11R6, the Xforms Library 0.81-to-6 and Perl 5.003. It should work on any version of Linux that runs other Xforms applications and Perl 5.002 and above. It should also run on any Unix system that can run Xforms and Perl 5.002 and above, or at least be reasonably easy to port. Your implementation stories, along with comments/questions/bug-reports are welcome, to martin@nitram.demon.co.uk or on the Xforms mailing list, which I read (but to make sure I do, put the phrase 'Xforms4Perl' in the heading!!) *** THANKS My main 'other party' thanks goes to Zoran Popovic for his extensive testing efforts on the original versions (especially around the OpenGL area) and suggestions, and also for the convert fd file script upon which the fdesign filter is based (fd2perl, found in the master directory). Thanks to the CPAN people for their packaging comments - it only took me six months to implement their ideas!! Growing thanks go to Reza Naima , who has tested and championed this other-wise personal project more as each release has been delivered. Reza provided the proc-lookup demo. Martin Bartlett