Graphic-Forms README for version 0.9.0

Copyright (c) 2006-2007, 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 requires the following libraries which must be downloaded separately:

• ASDF http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/ note: ASDF is bundled with SBCL

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

• Closer to MOP http://common-lisp.net/project/closer/downloads.html

• lw-compat http://common-lisp.net/project/closer/downloads.html

The following libraries are bundled with Graphic-Forms:

• Practical Common Lisp Chapter08 and Chapter24 http://www.gigamonkeys.com/book/practicals-1.0.3.tar.gz

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

The following libraries are optional:

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

Supported Common Lisp Implementations

Graphic-Forms currently supports Allegro CL 8.0, CLISP 2.40 or higher, LispWorks 5.0.1, and SBCL 1.0.5 or higher (with a small patch).

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 a GPF if a window's layout manager is changed. Compared to prior releases of Graphic-Forms, there is much less chance of this problem affecting layout management.

2. Please be advised that SBCL is itself still in the early stages of supporting Windows, and as a consequence, you may experience problems such as 'GC invariant lost' errors that result in a crash to LDB.

3. The 'unblocked' and 'textedit' demo programs are not yet complete.

4. The gfg:text-extent method currently does not return the correct text height value. As a workaround, get the text metrics for the font and compute height from that. The gfg:text-extent function does return the correct width.

5. If a Graphic-Forms application is launched from within SLIME with CLISP or SBCL as the backend (both of which are single-threaded on Win32), further SLIME commands will be 'pipelined' until the Graphic-Forms main message loop exits. If/when these implementations gain multi-threading support on Win32, then the Graphic-Forms library code will be updated to launch a separate thread, as is currently done for Allegro and LispWorks.

How To Configure and Build

NOTE: in a future release, this library will be packaged for delivery via asdf-install.

NOTE: the following steps are only suggestions provided as a default procedure for people new to Graphic-Forms or Common Lisp.

1. [OPTIONAL] 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. Note that SBCL bundles ASDF, so in this case you just need to (require 'asdf)

5. Execute the following forms at your REPL

;; ;; If you need the ImageMagick plugin, execute:

(push :load-imagemagick-plugin features) (setf cl-user::magick-library-directory "c:/path/to/ImageMagick/")

;; ... the latter being necessary only if ImageMagick is not installed ;; in the default location.

;; ;; Next, execute:

(load "config.lisp")

;; ;; Set 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. ;; ;; Note that gf-dir should be the Graphic-Forms top-level directory ;; path. ;; ;; gfsys::cffi-dir ;; gfsys::closer-mop-dir ;; gfsys::gf-dir ;; gfsys::lw-compat-dir

;; ;; 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. See the README.txt file in the docs/manual subdirectory for more details.

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

How To Run Tests And Demos

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

2. Execute the following forms from your REPL:

;; ;; configure ASDF for the test programs and then load it

(load "tests.lisp") (gfsys::load-tests)

;; ;; execute demos and test programs ;; (gft:hello-world)

(gft:unblocked)

(gft:textedit)

;; ;; see src/tests/uitoolkit/README.txt ;; for details on other test programs

;; ;; execute the unit-tests ;; (in-package :gft) (run-tests)

Feedback and Bug Reports

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]