Graphic-Forms README for version 0.2.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/

 - CFFI 0.9.0
   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


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

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

1. When running the layout-tester application on CLISP, you may experience
   intermittent GPFs given sufficient playing around with window sizing,
   or adding/removing/hiding/showing controls if the flow layout is set to
   wrap.

   This problem needs further in-depth investigation.

2. When running the event-tester application on CLISP, you may experience
   intermittent GPFs after selecting File | Start Timer to start the
   timer test.

   This problem needs further in-depth investigation.

3. 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.

4. The event-tester application's menu definition specifies that the
   Test Menu | Submenu | Item A  item should be disabled but it does
   not get disabled. However, the GFW:ENABLE function does otherwise
   work correctly for menu items.

5. Graphic-Forms supports CLISP 2.38 and LispWorks 4.4.6. The
   intention is to support additional Lisp vendors, but currently
   the library will not run on anything but CLISP or LW due to some
   vendor-specific features that have to be used.


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 ImageMagic is not installed in the default location, execute:
  ;;
  (setf gfsys::*imagemagick-dir* "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::*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. Proceed to the next section to run the tests, or start coding!
   (note: I will add instructions in the future for building the
    documentation)


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)

  ;; Change the working directory to the uitoolkit tests
  ;; directory.
  ;;

  (chdir "c:/example/path/graphic-forms/src/tests/uitoolkit/")

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

  (run-tests)  ;; runs the unit tests (many more to be added)

  (gft::run-event-tester)

  (gft::run-image-tester)

  (gft::run-windlg)

  (gft::run-layout-tester)


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

Please provide feedback via the development mailing list:
  http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel

Bug reports via the bug tracking system:
  http://sourceforge.net/tracker/?group_id=163034&atid=826147

Patches via the patch tracker:
  http://sourceforge.net/tracker/?group_id=163034&atid=826147


[the end]