Author: junrue
Date: Tue Aug 22 02:42:16 2006
New Revision: 230
Added:
trunk/docs/manual/image-plugins.texinfo
trunk/docs/manual/terminology.texinfo
Modified:
trunk/docs/manual/glossary.texinfo
trunk/docs/manual/graphics-api.texinfo
trunk/docs/manual/miscellaneous.texinfo
Log:
documented the image plugin mechanism
Modified: trunk/docs/manual/glossary.texinfo
==============================================================================
--- trunk/docs/manual/glossary.texinfo (original)
+++ trunk/docs/manual/glossary.texinfo Tue Aug 22 02:42:16 2006
@@ -10,7 +10,8 @@
@node Glossary
@chapter Glossary
-Terms and definitions. Content will be added in due time.
+This chapter defines fundamental terms encountered throughout
+the documentation of Graphic-Forms.
@table @samp
@@ -18,44 +19,65 @@
@anchor{accelerator}
@cindex accelerator
An accelerator is a key sequence assigned to an application function
-that allows a user to bypass navigation of the menu or control
+allowing a user to bypass navigation of the menu or control
hierarchy normally required to invoke the function. Some accelerators
are established by Windows style guidelines, such as @sc{control-c}
for the clipboard copy operation from an Edit menu. Applications may
define other accelerators as appropriate. Accelerators are generally
intended for more knowledgeable users and should not be the sole
-mechanism for invoking functionality. Compare with @ref{mnemonic}.
+mechanism for invoking functionality. Compare with @ref{mnemonic}.@*
@item auto-scrolling
@cindex auto-scrolling
Auto-scrolling is a feature whereby scrolling occurs
as a side effect of user input so content can remain visible,
thus avoiding the need to explicitly manipulate scrollbars to
-achieve the same result.
+achieve the same result.@*
@item control
@cindex control
-A control is a system-defined window class that accepts user input
-and/or generates notification events.
+A control is a system-defined window class whose role is to
+accept user input and possibly generate notification events
+based on such input.@*
@item dialog
@cindex dialog
A dialog is a mechanism for collecting user input or showing
information. The system defines common dialogs for tasks like
choosing files, fonts, or colors. Custom dialogs can be defined
-by application code.
+by application code.@*
+
+@item extension
+@anchor{extension}
+@cindex extension
+An extension is code providing additional functionality beyond the
+original scope of a system. An extension framework encourages
+modularity. More importantly, it is a conscious design choice to allow
+a system to be stretched beyond what the original designers may have
+anticipated. Compare with @ref{plugin}.@*
@item menu
@cindex menu
-A collection of menu items.
+A collection of menu items presented within a single rectangular
+region. Menus are often anchored to a menu bar, but may also be
+invoked in a context-sensitive manner via the mouse or an
+@ref{accelerator}.@*
@item mnemonic
@anchor{mnemonic}
@cindex mnemonic
A mnemonic is a key sequence (usually a single character modified by
-the @sc{alt} key) that enables mouse-free navigation of a menu or
+the @sc{alt} key) enabling mouse-free navigation of a menu or
control hierarchy to invoke an application function. Depending on
the user's system settings, mnemonic characters may be hidden until
-the user presses the @sc{alt} key. Compare with @ref{accelerator}.
+the user presses the @sc{alt} key. Compare with @ref{accelerator}.@*
+
+@item plugin
+@anchor{plugin}
+@cindex plugin
+A plugin is code integrated into a larger system in order to implement
+a specific instance of an established category of services. A plugin
+framework encourages modularity within a defined scope of
+functionality. Compare with @ref{extension}.@*
@end table
Modified: trunk/docs/manual/graphics-api.texinfo
==============================================================================
--- trunk/docs/manual/graphics-api.texinfo (original)
+++ trunk/docs/manual/graphics-api.texinfo Tue Aug 22 02:42:16 2006
@@ -220,8 +220,9 @@
order to create Windows icons, a value may be supplied for the
@code{:transparency-pixel} initarg of this class to select the
proper transparency @ref{color}; or else by default, the pixel
-color at @code{(0, 0)} in each image will be used. @emph{FIXME:
-link to documentation of graphics plugins here}.
+color at @code{(0, 0)} in each image will be used. See
+@ref{Image data plugins} for more information on how image
+files are loaded.
@end deffn
@deffn Initarg :images
This initarg accepts a @sc{cl:list} of image objects. Since
@@ -263,8 +264,8 @@
This subclass of @ref{native-object} wraps a Win32 bitmap handle.
Instances may be drawn using @ref{draw-image} or displayed within
certain @ref{control}s such as a @ref{label}. Images may originate
-from a variety of formats. @emph{FIXME: link to documentation
-of graphics plugins here}.
+from a variety of formats -- see @ref{Image data plugins} for
+more information on how file formats are loaded.
@table @var
@anchor{transparency-pixel}
@item transparency-pixel
@@ -288,8 +289,9 @@
may be loaded (via the @ref{load} method) and then converted to an
@ref{image} object by the @ref{data-object} @sc{setf} function.@*@*
@code{image-data} serves as an integration point between Graphic-Forms
-and third-party graphics libraries such as ImageMagick. @emph{FIXME:
-link to documentation of graphics plugins here}.
+and third-party graphics libraries such as ImageMagick -- see
+@ref{Image data plugins} for more information on supporting other
+representations.
@table @var
@item data-plugin
This slot holds a subclass of @ref{image-data-plugin} encapsulating
@@ -302,9 +304,10 @@
@anchor{image-data-plugin}
@deftp Class image-data-plugin
This is a base class for plugin objects that encapsulate third-party
-library representations of images. @emph{FIXME:
-link to documentation of graphics plugins here}. It derives from
-@ref{native-object}.
+library representations of images. See @ref{Image data plugins} for
+more information on the role of this class.
+
+This class derives from @ref{native-object}.
@end deftp
Added: trunk/docs/manual/image-plugins.texinfo
==============================================================================
--- (empty file)
+++ trunk/docs/manual/image-plugins.texinfo Tue Aug 22 02:42:16 2006
@@ -0,0 +1,118 @@
+
+@c This file is part of the documentation source for
+@c the Graphic-Forms library.
+@c
+@c Copyright (c) 2006, Jack D. Unrue
+
+@node Image data plugins
+@section Image data plugins
+
+This section documents the image data plugin system.
+
+
+@subsection Rationale
+
+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 @sc{gdi} provides adequate
+support@footnote{Nowadays, the Windows platform offers alternatives,
+such as @sc{gdi+} which adds among other features native support for
+additional image formats. Graphic-Forms sticks with plain-old @sc{gdi}
+to avoid the possibility of these alternatives not being installed.}
+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 @sc{gdi} concept of an image is the
+@emph{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 @sc{gdi} bitmap serves as a normalized
+representation of image data. Graphic-Forms encapsulates @sc{gdi}
+bitmap functionality via the @ref{graphics-context} and @ref{image}
+classes, plus related functions and macros.
+
+A traditional Windows application embeds bitmap data within its binary
+executable (or @sc{dll}) via the Windows resource compiler. Such an
+application then uses Win32 @sc{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{As do GUI bindings in other
+languages such as Java.}
+
+There are many image formats in use today. Whether images are stored
+as @sc{gif}, @sc{jpeg}, @sc{png}, @sc{bmp}, or some other format,
+there must be code to read the file data and convert it into a
+@sc{gdi} bitmap format for use with drawing operations. This is the
+problem solved by the image data plugin mechanism in Graphic-Forms.
+It is solved in a manner insulating format-independent code in the
+main library from format-specific details, and in a manner allowing
+applications to provide their own code to do likewise.
+
+
+@subsection Image file loading
+
+When an image file is to be loaded, such as when a @sc{pathname} is
+supplied to the @code{:file} keyword for the @ref{image} or
+@ref{icon-bundle} classes, the library traverses a list of file loader
+functions bound to the @code{gfg::*image-plugins*} variable --
+@code{funcall}'ing each one in turn until one of them returns a
+non-@sc{nil} list, or the members of @code{gfg::*image-plugins*} is
+exhausted. In the latter case, a @ref{toolkit-error} is raised to
+notify application code that no registered plugin supports the file.
+
+Under normal circumstances, the library will manage the list bound to
+@code{gfg::*image-plugins*} behind the scenes. However, applications
+requiring precise control over loader function calling order may
+directly modify @code{gfg::*image-plugins*} @emph{but must take care
+to do so properly}. Improper modifications, such as accidentally
+assigning some other data structure, or adding the wrong kind of
+object, will result in program errors.
+
+
+@subsection Plugins bundled with the library
+
+Graphic-Forms includes two plugins in the distribution.
+
+The @emph{Default} plugin is available to applications unless the
+@code{:skip-default-plugin} keyword symbol is pushed onto
+@code{*features*} prior to loading the system. This plugin implements
+support for the @sc{bmp} and @sc{ico} formats directly in Common Lisp,
+thus imposing no additional external dependencies on applications.
+
+The @emph{ImageMagick} plugin is loaded when the
+@code{:load-imagemagick-plugin} keyword symbol is pushed onto
+@code{*features*} 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 @emph{Default} plugin. Developers must download the
+ImageMagick Q16 distribution and install it.@footnote{See the main
+ImageMagick website at @url{http://imagemagick.org} for downloads and
+documentation.} 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 @sc{dll}s and may have larger
+memory requirements.
+
+
+@subsection Implementing additional plugins
+
+@strong{FIXME:} @emph{add more info to this subsection once the plugin
+system has matured a bit.}
+
+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 @ref{image-data-plugin}
+and implementing certain generic functions. Third parties may
+implement and register additional plugins in an identical fashion.
+
+As a convenience, the symbol @code{gfg::*image-file-types*} is bound
+to an @sc{alist} 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.
+
+Developers are welcome to inspect the source code of bundled plugins
+(located under @code{src/uitoolkit/graphics/plugins} in the
+distribution) for additional hints as to how these plugins may be
+implemented.
Modified: trunk/docs/manual/miscellaneous.texinfo
==============================================================================
--- trunk/docs/manual/miscellaneous.texinfo (original)
+++ trunk/docs/manual/miscellaneous.texinfo Tue Aug 22 02:42:16 2006
@@ -11,77 +11,9 @@
@chapter Miscellaneous Topics
@menu
-* terminology:: Some notes about terminology conventions.
+* Image data plugins:: Documentation of the image data plugin system.
+* Terminology conventions:: Some notes about terminology conventions.
@end menu
-
-@node terminology
-@section terminology
-
-This chapter documents terminology conventions observed in
-Graphic-Forms. These conventions should be interpreted with the
-traditional Common Lisp conventions in mind (some of which are
-documented here: @url{http://www.cliki.net/Naming%20conventions}).
-
-@table @option
-
-@item accessor names
-For clearer identification of accessors, Graphic-Forms
-uses the suffix @samp{-of} whenever possible.
-
-@item @samp{check} versus @samp{select}
-Admittedly, these two concepts are similar. They can be used as verbs
-and they both describe a state of being (@samp{checked} and
-@samp{selected}). Yet they need to remain separate due to the fact
-that certain @ref{widget}s can exist in both states simultaneously,
-like a tri-state @ref{button}, or a table or tree whose items are
-checkboxes. The choice of which best describes an action or state
-amounts to a judgement call. In Graphic-Forms, the author chooses to
-use @samp{select} when a user gesture causes a widget to issue its
-primary notification event, such as a menu item or button being
-clicked. Hence, the verb @samp{select} aligns with the
-@ref{event-select} function.@footnote{This topic gets muddier when
-edit controls come into the picture. Text in an edit control is
-selected despite there being no notification event; yet there is a
-notification (event-modify) then the user types text. I'm choosing to
-live with this inconsistency, partly because otherwise my
-categorization scheme seems to work well; and one can refer to the act
-of retrieving edit control selection, confident that developers will
-know this means obtaining highlighted text.} And so the
-@samp{selection} state is associated with highlighting of an
-@ref{item}. Graphic-Forms uses @samp{check} to identify an operation
-that flags or annotates a widget; the @samp{checked} state means being
-annotated.
-
-@c @item @samp{clear} versus @samp{delete}
-@c There is a distinction between @samp{clear} and @samp{delete} which
-@c hinges on the difference between the primary content of a @ref{widget}
-@c and secondary state information. An example of primary content is text
-@c within an @ref{edit} @ref{control}. An example of secondary state
-@c information (relevant to this topic at least) is the @ref{span} of
-@c selected text in an edit control. With that in mind, Graphic-Forms
-@c functions @samp{delete} content but @samp{clear} secondary state. This
-@c choice aligns with the semantics of @sc{CL:delete}, including the
-@c notion of that function being a destructive operation.
-
-@item function and method names
-Functions and methods should be named using a verb to suggest
-action. It may be tempting (especially for former Java programmers) to
-use the Java getter/setter naming conventions for accessor-like
-functions, but the author prefers @samp{obtain} rather than
-@samp{get}, and he prefers @sc{setf}'able places which therefore can
-have @sc{setf} functions defined for them. For status querying
-functions, the author suggests @samp{available-p}, such as
-@ref{undo-available-p}.
-
-@item macro names
-Macros should be named consistent with established Common Lisp
-practice, with an exception being allowed for convenience wrappers
-around structure accessors (see for example
-@ref{location}). Otherwise, the temptation to define an unorthodox
-macro name is a symptom that maybe the code in question should not be
-a macro in the first place. The rule of thumb is: if something can
-be a function, then let it be a function; in general, think carefully
-before creating a new macro.
-
-@end table
+@include image-plugins.texinfo
+@include terminology.texinfo
Added: trunk/docs/manual/terminology.texinfo
==============================================================================
--- (empty file)
+++ trunk/docs/manual/terminology.texinfo Tue Aug 22 02:42:16 2006
@@ -0,0 +1,73 @@
+
+@c This file is part of the documentation source for
+@c the Graphic-Forms library.
+@c
+@c Copyright (c) 2006, Jack D. Unrue
+
+@node Terminology conventions
+@section Terminology conventions
+
+This section documents terminology conventions observed in
+Graphic-Forms. These conventions should be interpreted with the
+traditional Common Lisp conventions in mind (some of which are
+documented here: @url{http://www.cliki.net/Naming%20conventions}).
+
+@table @option
+
+@item accessor names
+For clearer identification of accessors, Graphic-Forms
+uses the suffix @samp{-of} whenever possible.
+
+@item @samp{check} versus @samp{select}
+Admittedly, these two concepts are similar. They can be used as verbs
+and they both describe a state of being (@samp{checked} and
+@samp{selected}). Yet they need to remain separate due to the fact
+that certain @ref{widget}s can exist in both states simultaneously,
+like a tri-state @ref{button}, or a table or tree whose items are
+checkboxes. The choice of which best describes an action or state
+amounts to a judgement call. In Graphic-Forms, the author chooses to
+use @samp{select} when a user gesture causes a widget to issue its
+primary notification event, such as a menu item or button being
+clicked. Hence, the verb @samp{select} aligns with the
+@ref{event-select} function.@footnote{This topic gets muddier when
+edit controls come into the picture. Text in an edit control is
+selected despite there being no notification event; yet there is a
+notification (event-modify) then the user types text. I'm choosing to
+live with this inconsistency, partly because otherwise my
+categorization scheme seems to work well; and one can refer to the act
+of retrieving edit control selection, confident that developers will
+know this means obtaining highlighted text.} And so the
+@samp{selection} state is associated with highlighting of an
+@ref{item}. Graphic-Forms uses @samp{check} to identify an operation
+that flags or annotates a widget; the @samp{checked} state means being
+annotated.
+
+@c @item @samp{clear} versus @samp{delete}
+@c There is a distinction between @samp{clear} and @samp{delete} which
+@c hinges on the difference between the primary content of a @ref{widget}
+@c and secondary state information. An example of primary content is text
+@c within an @ref{edit} @ref{control}. An example of secondary state
+@c information (relevant to this topic at least) is the @ref{span} of
+@c selected text in an edit control. With that in mind, Graphic-Forms
+@c functions @samp{delete} content but @samp{clear} secondary state. This
+@c choice aligns with the semantics of @sc{CL:delete}, including the
+@c notion of that function being a destructive operation.
+
+@item function and method names
+Functions and methods should be named using a verb to suggest
+action. It may be tempting (especially for former Java programmers) to
+use the Java getter/setter naming conventions for accessor-like
+functions, but the author prefers @samp{obtain} rather than
+@samp{get}, and he prefers @sc{setf}able places to Java-style
+@samp{put} or @samp{set} functions. In the latter case, where a symbol
+refers to both an accessor and a @sc{setf} function, the author
+omits the @samp{obtain} prefix (like @ref{size}). For status querying
+functions, the author suggests following the standard Common Lisp
+convention of @samp{availablep} or @samp{some-test-p}.
+
+@item macro names
+Macro names should be chosen in a manner consistent with established
+Common Lisp practice. An exception is allowed for convenience wrappers
+around structure accessors (see for example @ref{location}).
+
+@end table
