#    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 GUI api
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 directory (sound familiar?), many of which
are unashamedly plagerised from the Xforms DEMOS directory. 

This is the 7th 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 DEFINATELY(ISH) 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.

If, however, you have the rpm distribution, you only have active support for
Xforms 0.86. If you want backgraded support (which I do NOT advise - 0.86 is
a public release and is, therefore, as stable as 0.81 was) then you must get 
hold of the source rpm, install it and re-build it ('rm -ba Xform4*' from the 
RedHat/SPECS directory). Get Xforms 0.86 - its much easier!!

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. If you are installing from an rpm, then
this program gets copied to your /usr/local/bin directory.

Before using the extension, please read the comments at the top of the
Xforms.functions file in the doc directory. 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 is still changing here! In this release the packaging has been 
completely overhauled and amended to comply with standard Perl extension 
conventions and RedHat RPM conventions. 

The first thing to note is that I have reverted back to a single package 
for the Xforms related stuff, now named X11::Xforms, with two other independant
packages relating to XEvent and XFontStruct structure access, respectively 
named X11::Xevent and X11::XFontStruct. I intend to leave it at that, but,
then again, I said that for releases 5 and 6! REMEMBER ITS STILL ALPHA.

The reason for this reversion is that the single package is now smaller than 
the combined packages of the previous release, even smaller 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.

The reason for the further name change from 'Xforms' to 'X11::Xforms' is to 
comply with CPAN perl module standards.

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.5/0.6

	. Another name change, I'm afraid. The three packages have been moved
	  into the X11:: namespace to ensure that they live happlily with
	  other perl modules. This means that you must add X11:: to the 'use'
	  statements.
	. This is now available as a redhat RPM.
	. All documentation, copyright details, and the cnvtto7.pl script
	  have been moved to a subdirectory named 'doc', to help with 
	  RPM organization.
	. The 0.81 thru 0.85 demos have been removed. The 0.86 demos are under
	  the DEMOS directory, again to help with RPM organization (they get 
	  installed in the /usr/lib/Xforms4Perl/DEMOS directory by the RPM 
	  installation process, but stay in the distribution main directory
	  when installing from the tar file).
	. Install script removed in favour of native perl module build
	  in X11 directory.
	. All non-standard package make procedures either removed or 
	  automatically generated by MakeMaker (I took the time to learn how
	  in works!!)
	. All make warnings fixed. AIX and HP-UX make failures fixed.


*** 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 installed from a binary RPM, this section is an elephant .. er ...
sorry, irrelevant.

If you installed from a SOURCE rpm, then use rpm -ba from the RedHat SPECS
directory in order to build and install the binaries - then skip the remainder
of the section.

Otherwise 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 the Xforms, XEvent and XFontStruct subdirectories of the X11 
directory:

	1) edit Makefile.PL  # Read the comments in Makefile.PL that pertain
			     # to Include paths, Library paths, OpenGL, and
			     # object file 'stripping' and make any
			     # necessary changes.

Then, in the X11 directory, do

	2) perl Makefile.PL  # to make the makefile using the Perl 
			     # MakeMaker.pm extension 

	3) make 	     # To make a dynamic extension. 

	4) make install	     # To install the extension.

Then,

        5) cp fd2perl ...    # Where ... is a directory that is in your
			     # PATH when you run fdesign

	6) Convert your Xforms4Perl 0.4 scripts to 0.7 (see below)

*** HOW TO CONVERT Xforms4Perl 0.4, 0.5 or 0.6 SCRIPTS TO Xforms4Perl 0.7

The only changes are in the format and quantity of 'use' statements.

There is a Perl script named cnvtto7.pl, found in the doc directory,  which
will do the work for you. Invoke it like this:

	cnvtto7.pl <script.1> ...

It will back up the old script with a suffix of '.x4p.old'.

Note that the 0.4, 0.5 or 0.6 packages are NOT removed by 0.7. They are 
not even disabled. To remove previous versions of Xforms4Perl 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_*', 'Xforms', 
'XEvent' or 'XFontStruct' EXCEPT those found under the X11 directory trees
trees (sorry it's so confusing). If you do accidentally remove any under the
X11 trees, just re-install 0.7

*** HOW TO USE IT

Basically just add

	use X11::Xforms;

to your perl script, then follow the instructions given in the xforms
documentation, making any necessary semantic transformations between the
C presented therein 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 directory for examples of usage.

To access XFontStruct of XEvent structure fields, you will also have to 
add:

	use X11:XFontStruct;

and/or

	use X11:XEvent; 

*** THE DEMOS

There is a directory, named DEMOS, that, funnily enough, contains
demonstration scripts! Many of these are converted native xforms demos and, as 
such, should work on any OS platform that has successfully installed 
Xforms4Perl. 

The original inspiration for this project is also included. Its a toolbar (yawn
yawn - another toolbar). But the fact that it is written in Perl is what's
impressive. It has full GUI configuration, pixmap button support, tool tips
etc etc. Acts a bit like the M* Of*ice toolbar of Win*ows 3.*! This should also
work on all platforms. 

There are, however, three 'useful' demos that are designed specifically for
Linux - ProcCntl.pl, XFbat and proc-lookup. They all use the Linux /proc file 
system. ProcCntl also relies on the GNU ps 'tree' display for its pretty look.
These are, therefore, unlikely to work on non-Linux systems!   However, I would
be very interested to see someone elses workings of these in order to include 
more generic versions in future releases.

And if someone wants to re-work the XFtool demo to look like Of*ice 95/97 then
that might be quite cool too.
  
*** 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 <zoran@cs.cmu.edu> 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 <reza@reza.extern.ucsd.edu>, who has tested
and championed this other-wise personal project more as each release has
been delivered. Reza provided the proc-lookup demo.

Thanks to Michael Fulbright of RedHat for help with building the RPM.

Thanks to the following for platform problem reports (in no particular order):

	Randy J. Ray 		(HP-UX)
	Arthur Blair		(Spark/SunOS 4.1.3)
	Thomas Eickermann	(AIX and others)
	Phillips Nguyen		(SGI)

Further thanks to Randy for other suggestions that make this more portable,
more standard, and much cleaner. Incidentally, Randy has a perl extension of
his own, named X11::Fvwm that assists in the creation of FVWM modules written
in Perl. An Xforms extension to that package is being developed using 
Xforms4Perl. See any CPAN mirror site for details.

Martin Bartlett