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%7D 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%7D). - -@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%7D). + +@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