aquaterm egg
************

Bindings to the C API for AquaTerm

Written by Thomas Chust (http://www.chust.org/)

   This manual corresponds to version 1.0.0 of the aquaterm extension
library for Chicken Scheme.

1 About this egg
****************

1.1 Version history
===================

`1.0.0'
     Initial release

1.2 Usage
=========

Load this egg like so:

   `(require-extension aquaterm)'

2 Documentation
***************

This documentation page is acutally a rewrite of the documentation for
the Objective C AQTAdapter class. The C API this binding is relying on
is not documented in its own right.

   For in-depth information on the functionality of the routines and
general information you should consult the original AquaTerm
documentation (http://aquaterm.sourceforge.net/) as well as this manual.

   Please not that the whole AquaTerm library is using the unit pt for
its plot coordinates and sizes unless stated otherwise.

2.1 Initializing and Deinitializing the Library
===============================================

 -- procedure: aqt:init
          (aqt:init) => <boolean>

     Initializes the library and return whether it was successful. You
     should call this routine before using any of the other functions.

 -- procedure: aqt:terminate
          (aqt:terminate) => <void>

     Deinitializes the library, call it as the last thing before
     terminating your program.

2.2 Controlling Plots
=====================

 -- procedure: aqt:open-plot
          (aqt:open-plot (id <exact>)) => <void>

     Creates a new plot with an arbitrary identification number that
     can be used in calls to `aqt:select-plot' to reference that plot.

     Note that the plot is not displayed before you call
     `aqt:render-plot!'

 -- procedure: aqt:select-plot
          (aqt:select-plot (id <exact>)) => <void>

     Selects the plot identified by `id' as the target for subsequent
     commands.

 -- procedure: aqt:set-plot-size!
          (aqt:set-plot-size! (width <number>) (height <float>)) => <void>

     Defines the limits of the current plot area.

     This function must be called before any drawing command following
     an `aqt:open-plot' or `aqt:clear-plot!' command, otherwise
     behaviour is undefined.

 -- procedure: aqt:set-plot-title!
          (aqt:set-plot-title! (title <string>)) => <void>

     Sets a title for the current plot, which will be displayed in the
     plot window's titlebar and will be used as a default filename when
     saving the plot from AquaTerm.

 -- procedure: aqt:render-plot!
          (aqt:render-plot!) => <void>

     Displays the current plot in an AquaTerm window rendering all
     drawing operations performed so far.

 -- procedure: aqt:clear-plot!
          (aqt:clear-plot!) => <void>

     Clears the current plot and resets all its attributes. Remeber to
     call `aqt:set-plot-size!' again after using this function.

     To clear the plot without resetting it, use the `aqt:erase-rect!'
     procedure.

 -- procedure: aqt:close-plot!
          (aqt:close-plot!) => <void>

     Closes the connection to the current plot and disables event
     handling.

     Note that this function does not cause the plot window to
     disappear if it was shown before.

2.3 Clipping
============

 -- procedure: aqt:set-clip-rect!
          (aqt:set-clip-rect! (x <number>) (y <number>) (width <number>) (height <number>)) => <void>

     Set a rectangular clipping region to apply to all subsequent
     operations, until changed again by `aqt:set-clip-rect!' or
     `aqt:set-default-clip-rect!'

 -- procedure: aqt:set-default-clip-rect!
          (aqt:set-default-clip-rect!) => <void>

     Reset the clipping region to the entire plot for all subsequent
     operations, until changed again by `aqt:set-clip-rect!' or
     `aqt:set-default-clip-rect!'

2.4 Managing Colors
===================

 -- procedure: aqt:set-color!
          (aqt:set-color! (red <number>) (green <number>) (blue <number>)) => <void>

     Set the drawing color in the active plot to the given `red',
     `green' and `blue' intensities between 0 and 1.

 -- procedure: aqt:set-background-color!
          (aqt:set-background-color! (red <number>) (green <number>) (blue <number>)) => <void>

     Set the background color in the active plot to the given `red',
     `green' and `blue' intensities between 0 and 1.

 -- procedure: aqt:get-color
          (aqt:get-color) => <number>, <number>, <number>

     Retrieves the drawing color of the active plot and returns three
     values for its red, green and blue intensities between 0 and 1.

 -- procedure: aqt:get-background-color
          (aqt:get-background-color) => <number>, <number>, <number>

     Retrieves the background color of the active plot and returns
     three values for its red, green and blue intensities between 0 and
     1.

2.5 Managing the Colormap
=========================

 -- procedure: aqt:colormap-size
          (aqt:colormap-size) => <exact>

     Returns the number of colormap entries available for the
     programmer.

 -- procedure: aqt:set-colormap-entry!
          (aqt:set-colormap-entry! (idx <exact>) (red <number>) (green <number>) (blue <number>)) => <void>

     Set the entry at position `idx' in the colormap to the given
     `red', `green' and `blue' intensities between 0 and 1.

 -- procedure: aqt:get-colormap-entry
          (aqt:get-colormap-entry (idx <exact>)) => <number>, <number>, <number>

     Retrieves the color at index `idx' in the colormap and returns
     three values for its red, green and blue intensities between 0 and
     1.

 -- procedure: aqt:take-color-from-colormap-entry!
          (aqt:take-color-from-colormap-entry! (idx <exact>)) => <void>

     Set the drawing color in the active plot to the value of the
     colormap entry indicated by `idx'.

 -- procedure: aqt:take-background-color-from-colormap-entry!
          (aqt:take-background-color-from-colormap-entry! (idx <exact>)) => <void>

     Set the background color in the active plot to the value of the
     colormap entry indicated by `idx'.

2.6 Drawing Text
================

 -- procedure: aqt:set-fontname!
          (aqt:set-fontname! (name <string>)) => <void>

     Sets the font to be used for future operations.

     The default font is `"Times-Roman"'.

 -- procedure: aqt:set-fontsize!
          (aqt:set-fontsize! (size <number>)) => <void>

     Sets the font size in points for future operations.

     The default font size are 14 pt.

 -- procedure: aqt:add-label!
          (aqt:add-label! (text <string>) (x <number>) (y <number>) (angle <number>) #!optional ((h-align <symbol>) 'left) ((v-align <symbol>) 'baseline)) => <void>

     Adds text at position `x, y', rotated by `angle' degrees and
     aligned vertically and horizontally (with respect to position and
     rotation) according to `h-align' and `v-align'.

     The following values are allowed for the alignment parameters:

     `h-align' - Horizontal Alignment
     --------------------------------------------------------------------
     `left'
     `center'
     `right'

     `v-align' - Vertical Alignment
     --------------------------------------------------------------------
     `middle'
     `baseline'
     `bottom'
     `top'

 -- procedure: aqt:add-sheared-label!
          (aqt:add-sheared-label! (text <string>) (x <number>) (y <number>) (angle <number>) (shear-angle <number>) (h-align <symbol>) (v-align <symbol>)) => <void>

     Works like `aqt:add-label!' but additionally shears the text by
     `shear-angle' degrees in order to look right in 3D images for
     example.

2.7 Drawing Lines
=================

 -- procedure: aqt:set-linewidth!
          (aqt:set-linewidth! (width <number>)) => <void>

     Sets the current linewidth to `width' points, used for all
     subsequent lines.

     Any line currently being built by `aqt:move-to!' and
     `aqt:add-line-to!' will be considered finished since any coalesced
     sequence of line segments must share the same linewidth.

     The default linewidth is 1 pt.

 -- procedure: aqt:set-linestyle-pattern!
          (aqt:set-linestyle-pattern! (phase <number>) . pattern) => <void>

     Set the current line style to pattern style, used for all
     subsequent lines. The linestyle is specified as at most 8 numbers,
     where even positions in the list correspond to dash-lengths and
     odd positions correspond to gap-lengths.

     To produce e.g. a dash-dotted line, use the command
     `(aqt:set-linestyle-pattern! 0 4 2 1 2)'.

 -- procedure: aqt:set-linestyle-solid!
          (aqt:set-linestyle-solid!) => <void>

     Sets the current line style to solid, used for all subsequent
     lines.

     This is the default setting.

 -- procedure: aqt:set-line-cap-style!
          (aqt:set-line-cap-style! (style <symbol>)) => <void>

     Sets the current line cap style, used for all subsequent lines.

     Any line currently being built by `aqt:move-to!' and
     `aqt:add-line-to!' will be considered finished since any coalesced
     sequence of line segments must share the same cap style.

     The `style' parameter can have the following values:

     Style                Meaning
     --------------------------------------------------------------
     `butt'               Lines do not extend beyond their
                          endpoint.
     `round'              Lines extend into a half-circle beyond
                          their endpoint.
     `square'             Lines extend into a half-square beyond
                          their endpoint.

     The default line cap style is `round'.

 -- procedure: aqt:move-to!
          (aqt:move-to! (x <number>) (y <number>)) => <void>

     Moves the current point to `x, y' in preparation for a new
     sequence of line segments.

 -- procedure: aqt:add-line-to!
          (aqt:add-line-to! (x <number>) (y <number>)) => <void>

     Adds a line segment from the current point (given by a previous
     `aqt:move-to!' or `aqt:add-line-to!') to `x, y' and sets the
     target position as the new current point.

 -- procedure: aqt:add-polyline!
          (aqt:add-polyline! (points <list>)) => <void>

     Adds a sequence of line segments specified by a list of start-,
     join-, and endpoint(s) in `points', a list of two number lists.

2.8 Drawing Rectangles and Polygons
===================================

 -- procedure: aqt:move-to-vertex!
          (aqt:move-to-vertex! (x <number>) (y <number>)) => <void>

     Moves the current point to `x, y' in preparation for a new
     sequence of polygon edges.

 -- procedure: aqt:add-edge-to-vertex!
          (aqt:add-edge-to-vertex! (x <number>) (y <number>)) => <void>

     Adds a polygon edge from the current point (given by a previous
     `aqt:move-to-vertex!' or `aqt:add-edge-to-vertex!') to `x, y' and
     sets the target position as the new current point.

 -- procedure: aqt:add-polygon!
          (aqt:add-polygon! (points <list>)) => <void>

     Adds a polygon specified by a list of vertices in `points', a list
     of two number lists.

 -- procedure: aqt:add-filled-rect!
          (aqt:add-filled-rect! (x <number>) (y <number>) (width <number>) (height <number>)) => <void>

     Adds a filled rectangle and attempts to remove any objects that
     will be covered by it.

 -- procedure: aqt:erase-rect!
          (aqt:erase-rect! (x <number>) (y <number>) (width <number>) (height <number>)) => <void>

     Removes any objects completely inside aRect. Does not force a
     redraw of the plot.

2.9 Drawing Bitmaps
===================

 -- procedure: aqt:set-image-transform!
          (aqt:set-image-transform! (M-11 <number>) (M-12 <number>) (M-21 <number>) (M-22 <number>) (t-x <number>) (t-y <number>)) => <void>

     Sets a transformation matrix for images added by
     `aqt:add-transformed-image-with-bitmap!', see the ADC Reference
     Documentation on Basic Drawing
     (http://developer.apple.com/documentation/Cocoa/Conceptual/DrawBasic/Concepts/transforms.html#//apple_ref/doc/uid/20000887)
     for more information how this works.

 -- procedure: aqt:reset-image-transform!
          (aqt:reset-image-transform!) => <void>

     Sets the transformation matrix to unity, i.e. no transform.

 -- procedure: aqt:add-image-with-bitmap!
          (aqt:add-image-with-bitmap! (data <string|byte-vector>) (data-width <exact>) (data-height <exact>) (x <number>) (y <number>) (width <number>) (height <number>)) => <void>

     Adds a bitmap image of size `data-width * data-height' pixels to
     the plot at position `x, y', scaling it to `width x height' plot
     units.

     The bitmap must be stored in `data' as 24 bit per pixel, 8 bit per
     color channel raw RGB data.

     Does not apply transform.

 -- procedure: aqt:add-transformed-image-with-bitmap!
          (aqt:add-transformed-image-with-bitmap! (data <string|byte-vector>) (data-width <exact>) (data-height <exact>) (x <number>) (y <number>) (width <number>) (height <number>)) => <void>

     Adds a bitmap image of size `data-width * data-height' pixels to
     the plot at position `x, y', scaling it to `width x height' plot
     units and applying the stored transformation matrix to it.

     The bitmap must be stored in `data' as 24 bit per pixel, 8 bit per
     color channel raw RGB data.

2.10 Handling Events
====================

 -- procedure: aqt:set-accepting-events!
          (aqt:set-accepting-events! (yes <boolean>)) => <void>

     Inform AquaTerm whether or not events should be passed from the
     currently selected plot. Deactivates event passing from any plot
     previously set to pass events.

 -- procedure: aqt:get-last-event
          (aqt:get-last-event) => <list|boolean>

     Reads the last event logged by the viewer. Will always return `#f'
     unless `aqt:set-accepting-events!' was called with a `#t' argument.

     The event is returned by AquaTerm as a string but is decoded
     internally and passed back as follows:

     Return value         Meaning
     --------------------------------------------------------------
     `#f'                 No event was received.
     `('mouse (x y)       The mouse-button with the number
     button)'             `button' was clicked at the position
                          `x, y' in plot coordinates.
     `('key (x y) key)'   The key corresponding to the character
                          `key' was clicked while the mouse was
                          at the position `x, y' in plot
                          coordinates.

     Should the event returned from the library encode an error, a
     continuable exception of the composite kind `(exn aquaterm)' is
     thrown, which has an additional property `type' holding either the
     symbol `server' or `general' depending on the source of the error.

 -- procedure: aqt:wait-next-event
          (aqt:wait-next-event) => <list|boolean>

     Works analogous to `aqt:get-last-event' but blocks and waits for
     an event instead of returning immediately.

3 Examples
**********

The following code is a free translation of the C API demo program
shipped with AquaTerm. Most of the functionality of the library is
demonstrated here.

;;;; amb-demo.scm
;;;; A solution for the Kalotan puzzle using amb

(require-extension amb)

(define (xor a? b?)
  (if (and a? b?) #f (or a? b?)))

(define (solve-kalotan-puzzle)
  (let ((parent1 (amb 'm 'f))
	(parent2 (amb 'm 'f))
	(kibi (amb 'm 'f))
	(kibi-self-desc (amb 'm 'f))
	(kibi-lied? (amb #t #f)))
    (amb-assert
     (not (eq? parent1 parent2)))
    (if kibi-lied?
	(amb-assert
	 (xor
	  (and (eqv? kibi-self-desc 'm)
	       (eqv? kibi 'f))
	  (and (eqv? kibi-self-desc 'f)
	       (eqv? kibi 'm)))))
    (if (not kibi-lied?)
	(amb-assert
	 (xor
	  (and (eqv? kibi-self-desc 'm)
	       (eqv? kibi 'm))
	  (and (eqv? kibi-self-desc 'f)
	       (eqv? kibi 'f)))))
    (if (eqv? parent1 'm)
	(amb-assert
	 (and
	  (eqv? kibi-self-desc 'm)
	  (xor
	   (and (eqv? kibi 'f)
		(eqv? kibi-lied? #f))
	   (and (eqv? kibi 'm)
		(eqv? kibi-lied? #t))))))
    (if (eqv? parent1 'f)
	(amb-assert
	 (and
	  (eqv? kibi 'f)
	  (eqv? kibi-lied? #t))))
    (list parent1 parent2 kibi)))

(write (amb-collect (solve-kalotan-puzzle)))
(newline)

4 License
*********

Copyright (c) 2005, Thomas Chust <chust@web.de>.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer. Redistributions in
  binary form must reproduce the above copyright notice, this list of
  conditions and the following disclaimer in the documentation and/or
  other materials provided with the distribution. Neither the name of the
  author nor the names of its contributors may be used to endorse or
  promote products derived from this software without specific prior
  written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.