[graphic-forms-cvs] r227 - in trunk: . docs/manual docs/website - graphic-forms-cvs@common-lisp.net - mailman3.common-lisp.net

21 Aug 2006

Author: junrue
Date: Mon Aug 21 02:49:15 2006
New Revision: 227
Modified:
   trunk/NEWS.txt
   trunk/README.txt
   trunk/docs/manual/overview.texinfo
   trunk/docs/website/index.html
Log:
doc updates in preparation for the 0.5.0 release
Modified: trunk/NEWS.txt
==============================================================================

--- trunk/NEWS.txt	(original)
+++ trunk/NEWS.txt	Mon Aug 21 02:49:15 2006
@@ -1,15 +1,90 @@
+Release 0.5.0 of Graphic-Forms, a Common Lisp library for Windows GUI
+programming, is now available. This is an alpha release, meaning that
+the feature set and API have not yet stabilized.
+
+Here is what's new in this release:
+
+. SBCL is now supported (version 0.9.15 tested). Graphic-Forms includes
+  a small patch provided to the SBCL community by Alastair Bridgewater
+  to enable the stdcall calling convention for alien callbacks. Please
+  see src/external-libraries/sbcl-callback-patch
+
+. Implemented a plugin mechanism for integrating graphics libraries. This
+  means that ImageMagick is now optional -- if your application can get
+  by with just BMP and ICO formats, then the default plugin (which has no
+  external dependencies) may be used. This feature also allows applications
+  to integrate other graphics libraries of their choice.
+
+. In addition to ImageMagick now being optional, external library
+  dependencies have been further simplified. Several small libraries
+  are now directly bundled with the Graphic-Forms. Cells is no longer
+  used in the library proper nor in the demos (but may return at a
+  later point).
+
+. Implemented a class called icon-bundle which may be populated with
+  multiple images and then used to set icon data for window frames.
+  This includes the concept of there being 'large' and 'small' icon
+  sizes.
+
+. Simplified the argument lists for the event-*** generic functions.
+  Provided gfw:obtain-event-time as a substitute for passing a time
+  argument to every function (for which the vast majority of methods
+  had no use).
+
+. Provided a new generic function called event-session so applications
+  can participate in the WM_QUERYENDSESSION / WM_ENDSESSION protocol.
+
+. Provided event-activate and event-deactivate generic functions so
+  applications can respond to window activation state changes.
+
+. Defined generic functions for querying undo and redo state. Implemented
+  corresponding methods for edit controls.
+
+. Defined generic functions for configuring auto-scrolling and scrollbar
+  visibility. Implemented corresponding methods for edit controls.
+
+. Defined generic functions representing text clipboard data convenience
+  functionality. Implemented corresponding methods for edit controls.
-. SBCL 0.9.15 is now supported. Graphic-Forms includes a small patch
-  to enable the stdcall calling convention for alien callbacks, located
-  in src/external-libraries/sbcl-callback-patch.
+. Made other miscellaneous improvements to flesh out edit control
+  support.
-. Implemented a plugin mechanism for integrating graphics libraries.
+. Implemented the standard color chooser dialog and associated
+  convenience macro 'with-color-dialog'.
-. Implemented the standard color chooser dialog.
+. Added the macro 'with-graphics-context' as a convenience for code that
+  needs to instantiate a context outside of event-paint.
-. Simplified external library dependencies, getting rid of some and
-  bundling small libraries into the Graphic-Forms distribution.
+. Heavily revised internal layout manager code in preparation for
+  supporting more sophisticated layouts. A new class called layout-managed
+  has been created to serve as a mix-in when defining objects (not
+  necessarily only windows) that have children to be sized and positioned.
+
+. Implemented a new demo program called textedit which is essentially
+  a Notepad clone. Its purpose is to show off the multi-line edit
+  control and the standard Find/Replace dialog.
+
+. Upgraded to the latest lisp-unit and changed test loading code so that
+  unit-tests are no longer compiled.
+
+. Wrote more documentation and reorganized existing content a bit.
+  Added discussion of certain naming convention choices.
+
+. Made a variety of bug fixes.
+
+The README.txt file in the release zip file also has additional important
+information about this release.
+
+Download the release zip file here:
+http://prdownloads.sourceforge.net/graphic-forms/graphic-forms-0.5.0.zip?dow...
+
+The project website is:
+http://common-lisp.net/project/graphic-forms/
+
+Jack Unrue
+jdunrue (at) gmail (dot) com
+25 August 2006
==============================================================================
Modified: trunk/README.txt
==============================================================================
--- trunk/README.txt	(original)
+++ trunk/README.txt	Mon Aug 21 02:49:15 2006
@@ -1,5 +1,5 @@
-Graphic-Forms README for version 0.5.0
+Graphic-Forms README for version 0.5.0 (25 August 2006)
 Copyright (c) 2006, Jack D. Unrue
Graphic-Forms is a user interface library implemented in Common Lisp focusing
@@ -10,7 +10,8 @@
 Dependencies
 ------------
-Graphic-Forms depends on the following packages:
+Graphic-Forms requires the following libraries which must be downloaded
+separately:
- ASDF
    http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/
@@ -19,14 +20,13 @@
  - CFFI (cffi-060606 or later)
    http://common-lisp.net/project/cffi/
- - lw-compat
+ - Closer to MOP
    http://common-lisp.net/project/closer/downloads.html
- - Closer to MOP
+ - lw-compat
    http://common-lisp.net/project/closer/downloads.html
-The following libraries are bundled with Graphic-Forms, thus do not need
-to be downloaded separately:
+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
@@ -43,8 +43,8 @@
 Supported Common Lisp Implementations
 -------------------------------------
-Graphic-Forms currently supports CLISP 2.38, LispWorks 4.4.6, and SBCL 0.9.15
-(the latter with a small patch).
+Graphic-Forms currently supports CLISP 2.38 or higher, LispWorks 4.4.6,
+and SBCL 0.9.15 (the latter with a small patch).
Known Problems
@@ -58,103 +58,102 @@
http://sourceforge.net/tracker/index.php?func=detail&aid=1463994&gro...
-   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.
-
+   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 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.
How To Configure and Build
 --------------------------
-NOTE: in a future release, this project will be packaged for use
-with asdf-install.
+NOTE: in a future release, this project will be packaged for delivery
+via 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/".
+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.
+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 from your REPL
-
-  (load "config.lisp")
+5. Execute the following forms at your REPL
;;
-  ;; If ImageMagick is not installed in the default location, execute:
+  ;; 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.
+
   ;;
-  (setf cl-user::*magick-library-directory* "c:/path/to/your/ImageMagick/install/")
+  ;; Next, execute:
-  ;; setf these variables as needed for your specific environment to
+  (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.
   ;;
   ;;   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.
   ;;
+  ;; 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'
+   makeinfo (version 4.8) 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'.
+   deposited in a subdirectory called `reference'.
7. Proceed to the next section to run the tests, or start coding!
-How To Run Tests And Samples
-----------------------------
+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:
-  (load (compile-file gfsys::*lisp-unit-file*))
+  ;;
+  ;; configure ASDF for the test programs and then load it
-  (asdf:operate 'asdf:load-op :graphic-forms-tests)
+  (load "tests.lisp")
+  (gfsys::load-tests)
-  ;; execute demos and test programs
   ;;
+  ;; execute demos and test programs
+
   (gft:unblocked)
(gft:textedit)
@@ -169,14 +168,15 @@
(gft:windlg)
-  ;; execute the unit-tests
   ;;
+  ;; execute the unit-tests
+
   (in-package :gft)
   (run-tests)
-Support and Feedback
---------------------
+Feedback and Bug Reports
+------------------------
Please provide feedback via the following channels:
Modified: trunk/docs/manual/overview.texinfo
==============================================================================
--- trunk/docs/manual/overview.texinfo	(original)
+++ trunk/docs/manual/overview.texinfo	Mon Aug 21 02:49:15 2006
@@ -14,19 +14,18 @@
 focusing on the Windows platform. Graphic-Forms is licensed under the
 terms of the BSD License.
-The goal is to provide a Lisp-based toolkit for developing GUI
-applications on Windows. Platform-specific features are encapsulated
-by a thin abstraction layer that presents a more Lisp-friendly
-interface for programmers. The library can be extended by using the
-Lisp bindings for system APIs, rather than requiring knowledge of
-some other programming language.
+The goal is to provide a Common Lisp-based toolkit for developing GUI
+applications on Windows. GUI features are encapsulated by a thin
+abstraction layer offering a Lisp-friendly interface. The library can
+be extended via Common Lisp bindings for system APIs, avoiding a
+prerequisite for coding ability in a non-Lisp programming language.
Why implement another UI toolkit? Applications that need portability
-across windowing systems are already served by projects such as McCLIM
-or LTK or wxCL in the open-source world, or the toolkits provided by
-commercial vendors. The audience served by Graphic-Forms consists of
+across windowing systems are served today by projects such as
+LTK or wxCL in the open-source world, or the toolkits provided by
+commercial vendors. The target audience of Graphic-Forms consists of
 GUI developers focused on the Windows platform who want to leverage
-platform features without compromises due to portability.
+platform-specific features.
Long-term goals for this project may include implementing an application
 framework on top of the toolkit, or a rapid UI development language, or
Modified: trunk/docs/website/index.html
==============================================================================
--- trunk/docs/website/index.html	(original)
+++ trunk/docs/website/index.html	Mon Aug 21 02:49:15 2006
@@ -30,46 +30,47 @@
   terms of the
   <a href="http://home.earthlink.net/~jdunrue/license.html">BSD License</a>.</p>
-  <p>The goal is to provide a Lisp-based toolkit for developing GUI
-     applications on Windows. Platform-specific features are encapsulated
-     by a thin abstraction layer that presents a more Lisp-friendly interface
-     for programmers. The library can be extended by using the Lisp
-     bindings for system APIs, rather than requiring knowledge of some other
-     programming language.</p>
-  <p>Why implement another UI toolkit? Applications that need portability
-     across windowing systems are already served by projects such as
-     <a href="http://common-lisp.net/project/mcclim/">McCLIM</a>
-     or
+  <p>The goal is to provide a <a href="http://www.lisp.org">Common Lisp</a>-based
+     toolkit for developing GUI applications on Windows. GUI features
+     are encapsulated by a thin abstraction layer offering a Lisp-friendly
+     interface. The library can be extended via
+     <a href="http://www.lisp.org">Common Lisp</a> bindings for system APIs,
+     avoiding a prerequisite for coding ability in a non-Lisp programming
+     language.</p>
+  <p>Why implement another UI toolkit? Applications requiring portability
+     across windowing systems are served today by projects such as
      <a href="http://www.peter-herth.de/ltk/">LTK</a>
      or
      <a href="http://www.wxcl-project.org">wxCL</a>
      in the open-source world, or the toolkits provided by commercial
-     vendors. The audience served by Graphic-Forms consists of GUI
+     vendors. The target audience of Graphic-Forms consists of GUI
      developers focused on the Windows platform who want to leverage
-     platform features without compromises due to portability.
+     platform-specific features.
   <p>Long-term goals for this project may include implementing an application
      framework on top of the toolkit, or a rapid UI development language, or a
      UI design tool, or some combination thereof.</p>
<h3>Status</h3>
- <p>The current release is
-    <a href="http://sourceforge.net/project/showfiles.php?group_id=163034">version 0.4.0</a>.
-    This library is in the alpha stage of development, which means that new
-    features are still being added and existing features require considerable
-    testing. Brave souls who experiment with the code should expect significant
-    API and behavior changes for at least several more releases.</p>
+ <p>The current version is
+    <a href="http://prdownloads.sourceforge.net/graphic-forms/graphic-forms-0.5.0.zip?download">
+    0.5.0</a>, released on 25 August 2006.</p>
+ <p>Graphic-Forms is in the alpha stage of development,
+    meaning new features are still being added and existing features require
+    considerable testing. Brave souls who experiment with the code should expect
+    significant API and behavior changes for at least several more releases.</p>
<p>The supported Lisp implementations are:
  <ul>
-   <li><a href="http://clisp.cons.org/">CLISP 2.38</a></li>
+   <li><a href="http://clisp.cons.org/">CLISP 2.38 or later</a></li>
    <li><a href="http://www.lispworks.com/">LispWorks 4.4.6</a></li>
+   <li><a href="http://sbcl.sourceforge.net/">SBCL 0.9.15 or later</a></li>
  </ul>
<p>The supported Windows versions are:
  <ul>
    <li>XP SP2</li>
-   <li>Vista <i>(in progress, testing on Beta 2 currently underway)</i></li>
+   <li>Vista <i>(testing on Beta 2 currently underway)</i></li>
  </ul>
<h3 id="mailinglists">Mailing Lists</h3>

    