Graphic-Forms README for version 0.4.0
Copyright (c) 2006, Jack D. Unrue

Graphic-Forms is a user interface library implemented in Common Lisp focusing
on the Windows(R) platform. Graphic-Forms is licensed under the terms of the
BSD License.


Dependencies
------------

Graphic-Forms depends on the following packages:

 - ASDF
   http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/

 - Cells
   http://common-lisp.net/project/cells/

 - CFFI (cffi-060606 or later)
   http://common-lisp.net/project/cffi/

 - lw-compat
   http://common-lisp.net/project/cl-containers/lw-compat/lw-compat_latest.tar.gz

 - Closer to MOP
   http://common-lisp.net/project/cl-containers/closer-mop/closer-mop_latest.tar.gz

 - ImageMagick 6.2.6.5-Q16
   http://www.imagemagick.org/download/binaries/ImageMagick-6.2.6-5-Q16-windows-dll.exe

 - lisp-unit
   http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html


Supported Common Lisp Implementations
-------------------------------------

Graphic-Forms currently supports CLISP 2.38 and LispWorks 4.4.6.


Known Problems
--------------

Aside from the fact that there are a myriad of classes, functions, and
features in general that are not yet implemented, this section lists
known problems in this release:

1. The following bug filed against CLISP 2.38

   http://sourceforge.net/tracker/index.php?func=detail&aid=1463994&group_id=1355&atid=101355

   may result in intermittent GPFs when windows with layout managers are
   resized.

2. Image loading currently requires installation of the ImageMagick
   library as described in the next section. I have tested with Windows
   BMP files (and this is what the image-tester application displays).
   ImageMagick itself supports many image formats, but Graphic-Forms
   has not been tested with all of them. Therefore, images may not
   display properly, expecially when a transparency is selected.

3. The src/demos/unblocked directory contains a start at a demo
   program in the form of a simple game where one clicks on block
   shapes to score points, and the rest of the blocks fall down to
   fill in the gaps. This demo program is not yet finished, but the
   source code can still serve as sample code.

4. The text-extent generic function currently does not return
   the correct text height. As a workaround, get the text metrics
   for the desired font and base height calculations on that
   value. The text-extent function does return the correct width.



How To Configure and Build
--------------------------

NOTE: in a future release, this project will be packaged for use
with asdf-install.

1. Install ImageMagick 6.2.6.5-Q16 (note in particular that it is the Q16
   version that is needed, not the Q8 version). The default installation
   directory is "c:/Program Files/ImageMagick-6.2.6-Q16/".

2. Extract the Graphic-Forms distribution archive somewhere on your
   machine (or check out the source from Subversion).

3. Change to the Graphic-Forms top-level directory.

4. Load ASDF into your Lisp image if it is not already present.

5. Execute the following forms from your REPL

  (load "config.lisp")

  ;;
  ;; If ImageMagick is not installed in the default location, execute:
  ;;
  (setf cl-user::*magick-library-directory* "c:/path/to/your/ImageMagick/install/")

  ;; setf these variables as needed for your specific environment to
  ;; load the other dependencies besides ImageMagick. Or if your Lisp
  ;; image already has these systems loaded, set the variables to nil.
  ;;
  ;;   gfsys::*cells-dir*
  ;;   gfsys::*cffi-dir*
  ;;   gfsys::*closer-mop-dir*
  ;;   gfsys::*lw-compat-dir*
  ;;
  ;; Set the following var only if you want to run the unit-tests.
  ;; Its value is the path to the lisp-unit.lisp source file minus
  ;; the file extension.
  ;;
  ;;   gfsys::*lisp-unit-file*

  ;; Execute the following form to populate asdf:*central-registry*
  ;; Note that it will skip any systems whose location variables were
  ;; set to nil in the previous step.
  ;;
  (gfsys::configure-asdf)

  ;; Now load the graphic-forms system and its dependencies.
  ;;
  (asdf:operate 'asdf:load-op :graphic-forms-uitoolkit)

6. You may optionally compile the reference manual. GNU Make and
   makeinfo are prerequisites. Assuming you already have those
   components installed, the reference manual can be built by
   opening a command prompt and cd'ing to the `docs\manual'
   subdirectory, then typing `make'. The output will be
   produced within a subdirectory called `reference'.

7. Proceed to the next section to run the tests, or start coding!


How To Run Tests And Samples
----------------------------

1. Load the graphic-forms-uitoolkit system as described in the previous
   section.

2. Execute the following forms from your REPL:

  (load (compile-file gfsys::*lisp-unit-file*))

  (asdf:operate 'asdf:load-op :graphic-forms-tests)

  ;; execute one or more of the following:
  ;;

  (in-package :gft)
  (run-tests)  ;; runs the unit tests (many more to be added)

  (gft::run-drawing-tester)

  (gft::run-event-tester)

  (gft::run-image-tester)

  (gft::run-windlg)

  (gft::run-layout-tester)


Support and Feedback
--------------------

Please provide feedback via the following channels:

The development mailing list:
  http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel

The bug tracking system:
  http://sourceforge.net/tracker/?group_id=163034&atid=826145

The patch tracker:
  http://sourceforge.net/tracker/?group_id=163034&atid=826147


[the end]