Author: junrue Date: Tue Mar 21 18:36:21 2006 New Revision: 64

Added: trunk/docs/manual/api.texinfo - copied, changed from r62, trunk/docs/manual/packages.texinfo Removed: trunk/docs/manual/packages.texinfo Modified: trunk/docs/manual/overview.texinfo trunk/docs/manual/reference.texinfo Log: programming manual updated content

Copied: trunk/docs/manual/api.texinfo (from r62, trunk/docs/manual/packages.texinfo) ============================================================================== --- trunk/docs/manual/packages.texinfo (original) +++ trunk/docs/manual/api.texinfo Tue Mar 21 18:36:21 2006 @@ -5,40 +5,628 @@ @c Copyright (c) 2006, Jack D. Unrue

@c =================================================================== -@c CHAPTER: Packages +@c CHAPTER: API

-@node Packages -@chapter Packages +@node API +@chapter API

-General comments about the packages. +This chapter documents the Graphic-Forms programming interface. All +of the package names are prefixed with @code{graphic-forms.uitoolkit}.

-@section Graphics -@cindex Graphics Package +@section graphics package +@cindex graphics package

Nickname: GFG

This package represents graphical functionality, particularly drawing operations. Support for the ImageMagick library is defined here. This -package along with GFW constitute the bulk of the public API for -Graphic-Forms. +package and GFW together constitute the bulk of the public API.

-@section System -@cindex System Package +@menu +* graphics types:: Documentation of the graphics types. +* graphics functions:: Documentation of the graphics methods and functions. +@end menu + + +@section system package +@cindex system package

Nickname: GFS

The symbols in this package correspond to system-level functionality, examples of which include bindings for Win32 API functions and associated -constants. +constants. The majority of the symbols herein are not exported, except for +a few fundamental types and methods + +@menu +* system types:: Documentation of the system types. +* system functions:: Documentation of the system functions. +* system conditions:: Documentation of the system conditions. +@end menu +

-@section Tests -@cindex Tests Package +@section tests package +@cindex tests package

-This package contains the symbols corresponding to test programs. +Nickname: GFT

-@section Widgets -@cindex Widgets Package +This package contains the symbols corresponding to test programs. No +symbols are exported. + + +@section widgets package +@cindex widgets package + +Nickname: GFW

This package contains symbols for all of the widgets, event methods, and other UI objects defined by Graphic-Forms. This package and GFG together constitute the bulk of the public API. + +@menu +* widget types:: Documentation of the widget types. +* layout types:: Documentation of the pre-defined layout manager classes. +* widget functions:: Documentation of the widget methods and functions. +* event functions:: Documentation of event-handling functions. +* layout functions:: Documentation of layout manager functions. +@end menu + + +@node system types +@section system types + +@anchor{native-object} +@deftp Class native-object handle +This class encapsulates a Win32 object handle, which is technically a +foreign pointer but should be treated as an opaque cookie. +@deffn Initarg :handle +@end deffn +@deffn Reader handle +@end deffn +@end deftp + +@anchor{point} +@deftp Structure point x y z +This structure represents a point in the Cartesian coordinate system. +@end deftp + +@anchor{rectangle} +@deftp Class rectangle location size +This class identifies a region in the Cartesian coordinate system +consisting of an upper-left coordinate and bounds. See @ref{point} and +@ref{size}. +@deffn Initarg :location +@end deffn +@deffn Initarg :size +@end deffn +@deffn Accessor location +@end deffn +@deffn Accessor size +@end deffn +@end deftp + +@anchor{size} +@deftp Structure size width height depth +This structure represents an area or volume. +@end deftp + +@anchor{span} +@deftp Structure span start end +This structure represents a range of values or times in a collection. +@end deftp + + +@node system functions +@section system functions + +@anchor{dispose} +@deffn GenericFunction dispose self +This function is called to discard the underlying native @var{handle} +and execute any other necessary cleanup code. +@end deffn + +@deffn GenericFunction disposed-p self +Returns T if @ref{dispose} has been called on @var{self} and the +object has not since been re-initialized; returns nil otherwise. +This function also returns T if @var{self} has been instantiated +but secondary initialization code has not yet executed. +@end deffn + +@deffn Function make-point :x :y :z +This function creates a new @ref{point} object. +@end deffn + +@deffn Function make-size :width :height :depth +This function creates a new @ref{size} object. +@end deffn + +@deffn Function make-span :start :end +This function creates a new @ref{span} object. +@end deffn + + +@node system conditions +@section system conditions + +@anchor{toolkit-error} +@deftp Condition toolkit-error detail +Error conditions originating from Graphic-Forms library code (as opposed +to system errors) are reported by raising this condition. The detail slot +is a string that describes the error in more detail. +@deffn Initarg :detail +@end deffn +@deffn Reader detail +@end deffn +@end deftp + +@deftp Condition win32-error +This condition is a subclass of toolkit-error that is used by the +library to report system-level errors. @xref{toolkit-error}. +@deffn Initarg :code +@end deffn +@deffn Reader code +@end deffn +@end deftp + + +@node widget types +@section widget types + +@strong{NOTE:} A future release will provide additional widget +classes. + +@deftp Class button +This @ref{control} class represents selectable controls that issue +notifications when clicked. +@end deftp + +@anchor{control} +@deftp Class control +The base class for widgets having pre-defined native behavior. It derives from +@ref{widget}. +@end deftp + +@deftp Class event-dispatcher +This is the base class for objects process events on behalf of user interface objects. +@end deftp + +@anchor{event-source} +@deftp Class event-source dispatcher +This is the base class for user interface objects that generate events. It +derives from @ref{native-object}. +@deffn Initarg :dispatcher +@end deffn +@deffn Accessor dispatcher +@end deffn +@end deftp + +@anchor{item} +@deftp Class item +The item class is the base class for all non-windowed user interface objects. +@deffn Initarg :item-id +@end deffn +@deffn Accessor item-id +@end deffn +@end deftp + +@deftp Class label +This @ref{control} class represents non-selectable controls that +display a string or image. +@end deftp + +@deftp Class menu +The menu class represents a container for menu items and submenus. It +derives from @ref{widget-with-items}. +@end deftp + +@deftp Class menu-item +A subclass of @ref{item} representing a menu item. +@end deftp + +@deftp Class panel +Base class for @ref{window}s that are children of @ref{top-level} @ref{window}s (or +other panels). +@end deftp + +@deftp Class timer +A timer is a non-windowed object that generates events at a regular (adjustable) frequency. +It derives from @ref{event-source}. +@deffn Reader id-of +@end deffn +@deffn Initarg :initial-delay +@end deffn +@deffn Reader initial-delay +@end deffn +@deffn Initarg :delay +@end deffn +@deffn Accessor delay +@end deffn +@end deftp + +@anchor{top-level} +@deftp Class top-level +Base class for @ref{window}s that can be moved and resized by the +user, and which normally have title bars. +@end deftp + +@anchor{widget} +@deftp Class widget +The widget class is the base class for all windowed user interface objects. It +derives from @ref{event-source}. +@end deftp + +@anchor{widget-with-items} +@deftp Class widget-with-items +The widget-with-items class is the base class for objects composed of sub-items. +It derives from @ref{widget}. +@deffn Initarg :items +@end deffn +@deffn Accessor items +@end deffn +@end deftp + +@anchor{window} +@deftp Class window +This is the base class for user-defined @ref{widget}s that serve as containers. +@deffn Reader layout-p +@end deffn +@deffn Initarg :layout +@end deffn +@deffn Accessor layout +@end deffn +@end deftp + + +@node layout types +@section layout types + +@strong{NOTE:} A future release will provide additional layout +manager classes. + +@anchor{layout-manager} +@deftp Class layout-manager style +Subclasses implement layout strategies on behalf of window objects. +@end deftp + +@anchor{flow-layout} +@deftp Class flow-layout spacing left-margin top-margin right-margin bottom-margin +This @ref{layout-manager} subclass arranges window children in a row +or column, with optional margins around the row/column and spacing in +between children. The layout can wrap the window children if desired +and the available horizontal (or vertical) space is constrained. +@end deftp + + +@node event functions +@section event functions + +@strong{NOTE:} There are (and will be) additional event methods defined +in future releases, they just aren't all documented or implemented at +this time. + +@deffn GenericFunction event-activate dispatcher widget time +Implement this to respond to an object being activated. +@end deffn + +@deffn GenericFunction event-arm dispatcher item time +Implement this to respond to an object about to be selected. +@end deffn + +@deffn GenericFunction event-close dispatcher widget time +Implement this to respond to an object being closed. +@end deffn + +@deffn GenericFunction event-dispose dispatcher widget time +Implement this to respond to an object being disposed (via +@ref{dispose}, not the garbage collector). +@end deffn + +@deffn GenericFunction event-key-down dispatcher widget time keycode char +Implement this to respond to a key down event. +@end deffn + +@deffn GenericFunction event-key-up dispatcher widget time keycode char +Implement this to respond to a key up event. +@end deffn + +@deffn GenericFunction event-mouse-double dispatcher widget time point button +Implement this to respond to a mouse double-click. +@end deffn + +@deffn GenericFunction event-mouse-down dispatcher widget time point button +Implement this to respond to a mouse down event. +@end deffn + +@deffn GenericFunction event-mouse-enter dispatcher widget time point button +Implement this to respond to a mouse passing into the bounds of an object. +@end deffn + +@deffn GenericFunction event-mouse-exit dispatcher widget time point button +Implement this to respond to a mouse leaving the bounds an object. +@end deffn + +@deffn GenericFunction event-mouse-hover dispatcher widget time point button +Implement this to respond to a mouse that stops moving for a period of time within an object. +@end deffn + +@deffn GenericFunction event-mouse-move dispatcher widget time point button +Implement this to respond to a mouse move event. +@end deffn + +@deffn GenericFunction event-mouse-up dispatcher widget time point button +Implement this to respond to a mouse up event. +@end deffn + +@deffn GenericFunction event-move dispatcher widget time point +Implement this to respond to an object being moved within its parent's coordinate system. +@end deffn + +@anchor{event-paint} +@deffn GenericFunction event-paint dispatcher widget time gc rect +Implement this to respond to paint requests. +@end deffn + +@deffn GenericFunction event-pre-modify dispatcher widget time keycode char span new-content +Implement this to respond to content (e.g., text) in an object about to be modified. +@end deffn + +@deffn GenericFunction event-resize dispatcher widget time size type +Implement this to respond to an object being resized. +@end deffn + +@deffn GenericFunction event-select dispatcher item time rect +Implement this to respond to an object (or item within) being selected. +@end deffn + +@deffn GenericFunction event-timer dispatcher timer time +Implement this to respond to a tick from a specific timer. +@end deffn + + +@node widget functions +@section widget functions + +@strong{NOTE:} There are (and will be) additional widget methods defined +in future releases, they just aren't all documented or implemented at +this time. + +@deffn GenericFunction ancestor-p ancestor descendant +Returns T if ancestor is an ancestor of descendant; nil otherwise. +@end deffn + +@deffn GenericFunction append-item object text image dispatcher +Adds the new item with the specified text to the object, and returns the newly-created item. +@end deffn + +@deffn GenericFunction append-submenu object text submenu dispatcher +Adds a submenu anchored to a parent menu and returns the corresponding item. +@end deffn + +@deffn GenericFunction check object flag +Sets the object into the checked state. +@end deffn + +@deffn GenericFunction checked-p object +Returns T if the object is in the checked state; nil otherwise. +@end deffn + +@deffn GenericFunction clear-item object index +Clears the item at the zero-based index. +@end deffn + +@deffn GenericFunction clear-span object sp +Clears the items whose zero-based indices lie within the specified span. +@end deffn + +@deffn GenericFunction client-size object +Returns a size object that describes the region of the object that can be drawn within or can display data. +@end deffn + +@deffn GenericFunction compute-style-flags object &rest style +Convert a list of keyword symbols to a pair of native bitmasks; the first conveys normal/standard flags, whereas the second any extended flags that the system supports. +@end deffn + +@deffn GenericFunction compute-outer-size object desired-client-size +Return a size object describing the dimensions of the area required to enclose the specified desired client area and this object's trim. +@end deffn + +@deffn GenericFunction display-to-object object pnt +Return a point that is the result of transforming the specified point from display-relative coordinates to this object's coordinate system. +@end deffn + +@deffn GenericFunction enable object flag +Enables or disables the object, causing it to be redrawn with its default look and allows it to be selected. +@end deffn + +@deffn GenericFunction enable-layout object flag +Cause the object to allow or disallow layout management. +@end deffn + +@deffn GenericFunction enabled-p object +Returns T if the object is enabled; nil otherwise. +@end deffn + +@deffn GenericFunction item-at object index +Return the item at the given zero-based index from the object. +@end deffn + +@deffn GenericFunction item-count object +Return the number of items possessed by the object. +@end deffn + +@deffn GenericFunction item-index object item +Return the zero-based index of the location of the other object in this object. +@end deffn + +@deffn GenericFunction item-owner item +Return the widget containing this item. +@end deffn + +@deffn GenericFunction layout object +Set the size and location of this object's children. +@end deffn + +@deffn GenericFunction location object +Returns a point object describing the coordinates of the top-left corner of the object in its parent's coordinate system. +@end deffn + +@deffn GenericFunction menu-bar object +Returns the menu object serving as the menubar for this object. +@end deffn + +@deffn GenericFunction object-to-display object pnt +Return a point that is the result of transforming the specified point from this object's coordinate system to display-relative coordinates. +@end deffn + +@anchor{pack} +@deffn GenericFunction pack object +Causes the object to be resized to its preferred size. +@end deffn + +@deffn GenericFunction parent object +Returns the object's parent. +@end deffn + +@deffn GenericFunction preferred-size object width-hint height-hint +Returns a size object representing the object's 'preferred' size. +@end deffn + +@deffn GenericFunction redraw object +Causes the entire bounds of the object to be marked as needing to be redrawn +@end deffn + +@deffn GenericFunction running-p object +Returns T if the object is in event generation mode; nil otherwise. +@end deffn + +@deffn GenericFunction show object flag +Causes the object to be visible or hidden on the screen, but not necessarily top-most in the display z-order. +@end deffn + +@deffn GenericFunction size object +Returns a size object describing the size of the object in its parent's coordinate system. +@end deffn + +@deffn GenericFunction start object +Enable event generation at regular intervals. +@end deffn + +@deffn GenericFunction stop object +Stop producing events. +@end deffn + +@deffn GenericFunction text object +Returns the object's text. +@end deffn + +@deffn GenericFunction update object +Forces all outstanding paint requests for the object to be processed before this function returns. +@end deffn + +@deffn GenericFunction visible-p object +Returns T if the object is visible (not necessarily top-most); nil otherwise. +@end deffn + + +@node layout functions +@section layout functions + +@deffn GenericFunction compute-layout layout window width-hint height-hint +Returns a list of conses @code{(window . rectangle)} describing the +new bounds of each child window or control. A @ref{layout-manager} subclass +implements this method based on its particular layout strategy, taking +into account attributes set by the user. Certain Graphic-Forms functions +call this method to accomplish layout within a window. +@end deffn + +@deffn GenericFunction compute-size layout window width-hint height-hint +Computes and returns the new @ref{size} of the window's client area. A +@ref{layout-manager} subclass implements this method based on its +particular layout strategy, taking into account attributes set by the +user. The @ref{pack} function ultimately calls this method. +@end deffn + + +@node graphics types +@section graphics types + +@strong{NOTE:} A future release will provide additional graphics +classes. + +@deftp Structure color red green blue +This is a structure representing a color using three bytes in the RGB colorspace. +@end deftp + +@anchor{font} +@deftp Class font +This subclass of @ref{native-object} encapsulates a native font +object. @xref{font-metrics}. +@end deftp + +@anchor{font-metrics} +@deftp Structure font-metrics ascent descent leading avg-char-width max-char-width +This structure describes basic attributes of a font in terms that drawing code +may use to position graphical elements. @xref{font}. +@end deftp + +@deftp Class graphics-context +This subclass of @ref{native-object} wraps a native device context, +hence instances of this class are used to perform drawing operations. +One normally obtains a graphics-context via @ref{event-paint}. +@end deftp + +@deftp Class image-data +This subclass of @ref{native-object} maintains image attributes, +color, and pixel data. +@end deftp + +@node graphics functions +@section graphics functions + +@strong{NOTE:} There are (and will be) additional event methods defined +in future releases, they just aren't all documented or implemented at +this time. + +@deffn GenericFunction background-color object +Returns a color object corresponding to the current background color. +@end deffn + +@deffn GenericFunction data-obj object +Returns the data structure representing the raw form of the object. +@end deffn + +@deffn GenericFunction depth object +Returns the bits-per-pixel depth of the object. +@end deffn + +@deffn GenericFunction draw-filled-rectangle object rect +Fills the interior of the rectangle in the current background color. +@end deffn + +@deffn GenericFunction draw-image object im pnt +Draws the given image in the receiver at the specified coordinates. +@end deffn + +@deffn GenericFunction draw-text object text pnt +Draws the given string in the current font and foreground color, with (x, y) being the top-left coordinate of a bounding box for the string. +@end deffn + +@deffn GenericFunction font object +Returns the current font. +@end deffn + +@deffn GenericFunction foreground-color object +Returns a color object corresponding to the current foreground color. +@end deffn + +@deffn GenericFunction metrics object +Returns a metrics object describing key attributes of the specified object. +@end deffn + +@deffn GenericFunction size object +Returns a size object describing the size of the object. +@end deffn + +@deffn GenericFunction transparency-mask object +Returns an image object that will serve as the transparency mask for the original image, based on the original image's assigned transparency. +@end deffn

Modified: trunk/docs/manual/overview.texinfo ============================================================================== --- trunk/docs/manual/overview.texinfo (original) +++ trunk/docs/manual/overview.texinfo Tue Mar 21 18:36:21 2006 @@ -51,7 +51,7 @@ time a policy for backwards compatibility will be published.

The main project website: @* -@indicateurl{http://common-lisp.net/project/graphic-forms%7D +@url{http://common-lisp.net/project/graphic-forms%7D

@section Dependencies

@@ -59,47 +59,50 @@

@table @code @item ASDF -@indicateurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf%7D +@url{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf%7D

@item CFFI -@indicateurl{http://common-lisp.net/project/cffi%7D +@url{http://common-lisp.net/project/cffi%7D

@item lw-compat -@indicateurl{http://common-lisp.net/project/cl-containers/lw-compat/lw-compat_latest.tar.... +@url{http://common-lisp.net/project/cl-containers/lw-compat/lw-compat_latest.tar....

@item Closer to MOP -@indicateurl{http://common-lisp.net/project/cl-containers/closer-mop/closer-mop_latest.ta... +@url{http://common-lisp.net/project/cl-containers/closer-mop/closer-mop_latest.ta...

@item ImageMagick -@indicateurl{http://www.imagemagick.org/download/binaries/ImageMagick-6.2.6-5-Q16-windows... +@url{http://www.imagemagick.org/download/binaries/ImageMagick-6.2.6-5-Q16-windows...

@item lisp-unit -@indicateurl{http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html... +@url{http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html... @end table

@section Building the Library and Running Tests

-For the time being, please see the @code{README.txt} file included in the +Please see the @code{README.txt} file included in the distribution for instructions on how to load the ASDF system and run tests.

-@section Mailing Lists and Bug Reports +@section Support + + +@subsection Mailing Lists and Bug Reports

Announcements mailing list: @* -@indicateurl{http://www.common-lisp.net/mailman/listinfo/graphic-forms-announce%7D +@url{http://www.common-lisp.net/mailman/listinfo/graphic-forms-announce%7D

Developer mailing list (for both users and maintainers): @* -@indicateurl{http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel%7D +@url{http://www.common-lisp.net/mailman/listinfo/graphic-forms-devel%7D

Source control log mailing list: @* -@indicateurl{http://www.common-lisp.net/mailman/listinfo/graphic-forms-cvs%7D +@url{http://www.common-lisp.net/mailman/listinfo/graphic-forms-cvs%7D

The bug tracking system: @* -@indicateurl{http://sourceforge.net/tracker/?group_id=20959&atid=120959%7D +@url{http://sourceforge.net/tracker/?group_id=20959&atid=120959%7D

-@section Submitting Patches +@subsection Submitting Patches

Please use the SourceForge patch tracking mechanism to contribute patches: -@indicateurl{http://sourceforge.net/tracker/?atid=826147&group_id=163034&func=bro... +@url{http://sourceforge.net/tracker/?atid=826147&group_id=163034&func=bro...

Modified: trunk/docs/manual/reference.texinfo ============================================================================== --- trunk/docs/manual/reference.texinfo (original) +++ trunk/docs/manual/reference.texinfo Tue Mar 21 18:36:21 2006 @@ -10,6 +10,8 @@ @settitle Graphic-Forms Programming Reference @exampleindent 2

+ + @c ============================= Macros =============================

@macro Function {args} @@ -27,6 +29,11 @@ @end deffn @end macro

+@macro Reader {args} +@deffn {Reader} \args\ +@end deffn +@end macro + @macro GenericFunction {args} @deffn {Generic Function} \args\ @end deffn @@ -84,12 +91,6 @@

@c ==========================End Macros =============================

-@c Coallesce all the index types into one master index. -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex tp cp -@syncodeindex vr cp - @copying Copyright @copyright{} 2006, Jack D. Unrue <jdunrue at gmail.com> @*

@@ -135,7 +136,7 @@

@ifnottex @node Top -@top Graphic-Forms Programming Reference +@top Graphic-Forms Programming Reference (version 0.2.0) @insertcopying @end ifnottex

@@ -143,25 +144,30 @@

@menu * Overview:: Basic information about Graphic-Forms. -* Packages:: Summary of the library packages. +* API:: Documentation of the library API. * Miscellaneous Topics:: Various topics germane to Windows programming and Graphic-Forms. * Glossary:: Terms and definitions. -* Master Index:: +* Types Index:: +* Function Index:: @end menu

@contents

@include overview.texinfo -@include glossary.texinfo -@include packages.texinfo +@include api.texinfo @include miscellaneous.texinfo +@include glossary.texinfo

@c =================================================================== @c Index

-@node Master Index -@unnumbered Master Index -@printindex cp +@node Types Index +@unnumbered Types Index +@printindex tp + +@node Function Index +@unnumbered Function Index +@printindex fn

@bye