[graphic-forms-cvs] r337 - trunk/docs/manual
junrue at common-lisp.net
junrue at common-lisp.net
Tue Oct 17 05:47:04 UTC 2006
Author: junrue
Date: Tue Oct 17 01:47:04 2006
New Revision: 337
Added:
trunk/docs/manual/image-data-plugins.xml
trunk/docs/manual/miscellaneous-topics.xml
Modified:
trunk/docs/manual/graphic-forms.css
trunk/docs/manual/graphic-forms.xml
trunk/docs/manual/graphic-forms.xsl
trunk/docs/manual/introduction.xml
Log:
restored Miscellaneous Topics chapter
Modified: trunk/docs/manual/graphic-forms.css
==============================================================================
--- trunk/docs/manual/graphic-forms.css (original)
+++ trunk/docs/manual/graphic-forms.css Tue Oct 17 01:47:04 2006
@@ -2,6 +2,8 @@
font-size: 16;
font-family: { Arial, Helvetica, sans-serif; }
font-weight: Bold;
+ border-bottom-style: groove;
+ padding-bottom: 12px;
}
h2.subtitle {
@@ -29,3 +31,8 @@
font-size: 12;
font-family: { Arial, Helvetica, sans-serif; }
}
+
+p.small {
+ font-size: 11;
+ font-family: { Arial, Helvetica, sans-serif; }
+}
Modified: trunk/docs/manual/graphic-forms.xml
==============================================================================
--- trunk/docs/manual/graphic-forms.xml (original)
+++ trunk/docs/manual/graphic-forms.xml Tue Oct 17 01:47:04 2006
@@ -6,8 +6,10 @@
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[
- <!ENTITY legal SYSTEM "legal.xml">
- <!ENTITY introduction SYSTEM "introduction.xml">
+ <!ENTITY legal SYSTEM "legal.xml">
+ <!ENTITY introduction SYSTEM "introduction.xml">
+ <!ENTITY misctopics SYSTEM "miscellaneous-topics.xml">
+ <!ENTITY imdataplugins SYSTEM "image-data-plugins.xml">
]>
<book>
@@ -21,6 +23,7 @@
&legal;
&introduction;
+ &misctopics;
<index id="index"/>
</book>
Modified: trunk/docs/manual/graphic-forms.xsl
==============================================================================
--- trunk/docs/manual/graphic-forms.xsl (original)
+++ trunk/docs/manual/graphic-forms.xsl Tue Oct 17 01:47:04 2006
@@ -9,6 +9,7 @@
<xsl:param name="chapter.autolabel" select="0"/>
<xsl:param name="chunk.first.sections" select="1"/>
<xsl:param name="chunk.section.depth" select="2"/>
+ <xsl:param name="chunker.output.indent" select="'yes'"/>
<xsl:param name="generate.legalnotice.link" select="0"/>
<xsl:param name="generate.toc" />
<xsl:param name="html.stylesheet" select="'graphic-forms.css'"/>
Added: trunk/docs/manual/image-data-plugins.xml
==============================================================================
--- (empty file)
+++ trunk/docs/manual/image-data-plugins.xml Tue Oct 17 01:47:04 2006
@@ -0,0 +1,140 @@
+<!--
+ image-data-plugins.xml
+
+ Copyright (c) 2006, Jack D. Unrue
+-->
+<section>
+ <title>Image Data Plugins</title>
+
+ <bridgehead renderas="sect2">Rationale</bridgehead>
+
+ <para role="normal">
+ An important feature of a user interface library is the display of
+ graphical images, which are aggregates of pixel data and color information.
+ The Windows GDI provides adequate support
+ <footnote>
+ <para role="small">
+ Nowadays, the Windows platform offers alternatives, such as GDI+
+ which adds among other features native support for additional image
+ formats. Graphic-Forms sticks with plain-old gdi to avoid the
+ possibility of these alternatives not being installed.
+ </para>
+ </footnote>
+ for the basic tasks of
+ creating system objects populated with image data, drawing on them,
+ rendering them on the screen, and querying their attributes. Central to the
+ GDI concept of an image is the bitmap. This format has a long history which
+ becomes evident as one learns about features designed at a time when memory
+ and CPU performance were markedly constrained compared to today's machines.
+ For our purposes, the GDI bitmap serves as a normalized representation of
+ image data. Graphic-Forms encapsulates gdi bitmap functionality via the
+ graphics-context and image classes, plus related functions and macros.
+ </para>
+
+ <para role="normal">
+ A traditional Windows application embeds bitmap data within its binary
+ executable (or DLL) via the Windows resource compiler. Such an application
+ then uses Win32 API calls to access the resource data and instantiate
+ bitmap objects. Windows applications may also choose to store image data
+ in other locations, such as within files on disk. Graphic-Forms relies on
+ this latter arrangement instead of the resource infrastructure.
+ <footnote>
+ <para role="small">
+ As do GUI bindings in other languages such as Java.
+ </para>
+ </footnote>
+ </para>
+
+ <bridgehead renderas="sect2">Image file loading</bridgehead>
+
+ <para role="normal">
+ When an image file is to be loaded, such as when a pathname is supplied to
+ the <filename>:file</filename> keyword for the image or icon-bundle classes,
+ the library traverses a <emphasis>list</emphasis> of file loader functions
+ bound to the <emphasis>gfg::*image-plugins*</emphasis> variable,
+ funcall'ing each one in turn until one of them returns a non-nil
+ <emphasis>list</emphasis>, or the members of
+ <emphasis>gfg::*image-plugins*</emphasis> is exhausted. In the latter
+ case, a toolkit-error is raised to notify application code that no
+ registered plugin supports the file.
+ </para>
+
+ <para role="normal">
+ Under normal circumstances, the library will manage the
+ <emphasis>list</emphasis> bound to
+ <emphasis>gfg::*image-plugins*</emphasis> behind the scenes. However,
+ applications requiring precise control over loader function calling
+ order may directly modify <emphasis>gfg::*image-plugins*</emphasis>
+ <emphasis>but must take care to do so properly.</emphasis> Improper
+ modifications, such as accidentally assigning some other data structure,
+ or adding the wrong kind of object, will result in program errors.
+ </para>
+
+ <bridgehead renderas="sect2">Plugins bundled with the library</bridgehead>
+
+ <para role="normal">
+ Graphic-Forms includes two plugins in the distribution.
+ </para>
+
+ <para role="normal">
+ The <emphasis>Default</emphasis> plugin is available to applications
+ unless the <filename>:skip-default-plugin</filename> keyword symbol
+ is pushed onto <emphasis>*features*</emphasis> prior to loading the
+ system. This plugin implements support for the BMP and ICO formats
+ directly in Common Lisp, thus imposing no additional external dependencies
+ on applications.
+ </para>
+
+ <para role="normal">
+ The <emphasis>ImageMagick</emphasis> plugin is loaded when the
+ <filename>:load-imagemagick-plugin</filename> keyword symbol is pushed
+ onto <emphasis>*features*</emphasis> prior to loading the system. Thanks
+ to the ImageMagick library, this plugin supports most of the image formats
+ one might expect to need. However, it requires additional preparation
+ compared to the <emphasis>Default</emphasis> plugin. Developers must
+ download the ImageMagick Q16 distribution and install it.
+ <footnote>
+ <para role="small">
+ See the main ImageMagick <ulink url="http://imagemagick.org">website</ulink>
+ for downloads and documentation.
+ </para>
+ </footnote>
+ When delivering applications, the developer must execute the ImageMagick
+ installation process, or else replicate the expected directory structure and
+ registry entries. Also, bear in mind that due to the rich functionality
+ offered by ImageMagick, applications will pull in additional DLLs and may
+ have larger memory requirements.
+ </para>
+
+ <bridgehead renderas="sect2">Implementing additional plugins</bridgehead>
+
+ <para role="normal">
+ <emphasis role="bold">Note:</emphasis> this subsection will gain additional
+ content once the plugin system has matured further.
+ </para>
+
+ <para role="normal">
+ As described in the rationale, the role of an image data plugin is to
+ translate an external library representation of image data. In a nutshell,
+ this is accomplished by subclassing image-data-plugin and implementing
+ certain generic functions. Third parties may implement and register
+ additional plugins in an identical fashion.
+ </para>
+
+ <para role="normal">
+ As a convenience, the symbol <emphasis>gfg::*image-file-types*</emphasis>
+ is bound to an <emphasis>alist</emphasis> where the first of each pair is
+ a string naming a
+ file extension, and the second of each pair is a string supplying a brief
+ description of the format. Plugin developers may retrieve these pairs to
+ avoid duplication of the same information in their own code.
+ </para>
+
+ <para role="normal">
+ Developers are welcome to inspect the source code of bundled plugins
+ (located under <filename>src/uitoolkit/graphics/plugins</filename> in
+ the Graphic-Forms distribution) for additional hints as to how these
+ plugins may be implemented.
+ </para>
+
+</section>
Modified: trunk/docs/manual/introduction.xml
==============================================================================
--- trunk/docs/manual/introduction.xml (original)
+++ trunk/docs/manual/introduction.xml Tue Oct 17 01:47:04 2006
@@ -48,13 +48,29 @@
<itemizedlist mark="bullet" spacing="compact">
<listitem>CLISP 2.38 or later</listitem>
<listitem>LispWorks 4.4.6</listitem>
- <listitem>SBCL 0.9.15 or later</listitem>
+ <listitem>
+ SBCL 0.9.15 or later
+ <footnote>
+ <para role="small">
+ a small patch to enable the stdcall calling convention for callbacks
+ is temporarily bundled with Graphic-Forms, see
+ <filename>src/external-libraries/sbcl-callback-patch/</filename>
+ </para>
+ </footnote>
+ </listitem>
</itemizedlist>
<bridgehead renderas="sect2">Supported Windows Versions</bridgehead>
<itemizedlist mark="bullet" spacing="compact">
<listitem>XP SP2</listitem>
- <listitem>Vista</listitem>
+ <listitem>
+ Vista
+ <footnote>
+ <para role="small">
+ testing on RC1 is in-progress
+ </para>
+ </footnote>
+ </listitem>
</itemizedlist>
@@ -126,7 +142,46 @@
<section>
<title>Support and Feedback</title>
- <bridgehead renderas="sect2">Foo</bridgehead>
+ <variablelist><title>Mailing Lists</title>
+ <varlistentry>
+ <term><productname>Announcements</productname></term>
+ <listitem>
+ <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-announce"/>
+ <para/>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><productname>Developers</productname></term>
+ <listitem>
+ <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel"/>
+ <para/>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><productname>Source control</productname></term>
+ <listitem>
+ <ulink url="http://www.common-lisp.net/mailman/listinfo/graphic-forms-cvs"/>
+ <para/>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist><title>Bug Reports and Patches</title>
+ <varlistentry>
+ <term><productname>Bug reports</productname></term>
+ <listitem>
+ <ulink url="http://sourceforge.net/tracker/?group_id=163034&atid=826145"/>
+ <para/>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><productname>Patch submissions</productname></term>
+ <listitem>
+ <ulink url="http://sourceforge.net/tracker/?group_id=163034&atid=826147"/>
+ <para/>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
</chapter>
Added: trunk/docs/manual/miscellaneous-topics.xml
==============================================================================
--- (empty file)
+++ trunk/docs/manual/miscellaneous-topics.xml Tue Oct 17 01:47:04 2006
@@ -0,0 +1,16 @@
+<!--
+ miscellaneous-topics.xml
+
+ Copyright (c) 2006, Jack D. Unrue
+-->
+<chapter>
+ <title>Miscellaneous Topics</title>
+
+ <para role="normal">
+ Sections of this chapter discuss a variety of topics related to
+ Windows programming with Graphic-Forms.
+ </para>
+
+ &imdataplugins;
+
+</chapter>
More information about the Graphic-forms-cvs
mailing list