<h1><tt>base</tt> Module</h1>
<h2>Synopsis</h2>
<table>
<tr>
<th>Racket</th>
<td><code>(require (planet murphy/canvas-draw:1:0/base))</code></td>
</tr>
<tr>
<th>CHICKEN</th>
<td><code>(require-extension canvas-draw-base)</code></td>
</tr>
</table>
Basic CD library support. Initializes the CD library when loaded.
<h2>Data Types</h2>
<h3><a id="canvas_"><code><nowiki>(canvas? [v any/c]) → boolean?</nowiki></code></a></h3>
Check whether a value is a CD canvas.
<h3><a id="context_"><code><nowiki>(context? [v any/c]) → boolean?</nowiki></code></a></h3>
Check whether a value is a CD driver context.
<h3><a id="state_"><code><nowiki>(state? [v any/c]) → boolean?</nowiki></code></a></h3>
Check whether a value is a CD canvas state.
<h2>Canvas Management</h2>
<h3><a id="context-capabilities"><code><nowiki>(context-capabilities [context context?]) → (listof symbol?)</nowiki></code></a></h3>
Returns a list of flags describing the capabilities supported by the given
context.
The following flags may show up in the list:
* <code>'flush</code>
* <code>'clear</code>
* <code>'play</code>
* <code>'y-axis</code>
* <code>'clip-area</code>
* <code>'clip-polygon</code>
* <code>'region</code>
* <code>'rectangle</code>
* <code>'chord</code>
* <code>'image/rgb</code>
* <code>'image/rgba</code>
* <code>'image/map</code>
* <code>'get-image/rgb</code>
* <code>'image/server</code>
* <code>'background</code>
* <code>'background-opacity</code>
* <code>'write-mode</code>
* <code>'line-style</code>
* <code>'line-width</code>
* <code>'fprimtives</code>
* <code>'hatch</code>
* <code>'stipple</code>
* <code>'pattern</code>
* <code>'font</code>
* <code>'font-dimensions</code>
* <code>'text-size</code>
* <code>'text-orientation</code>
* <code>'palette</code>
* <code>'line-cap</code>
* <code>'line-join</code>
* <code>'path</code>
* <code>'bezier</code>
<h3><a id="use-context_"><code><nowiki>[use-context+ (parameter/c any)]</nowiki></code></a></h3>
A parameter determining whether calls to <code>[#make-canvas|make-canvas]</code>
should use extended variants of the passed context drivers.
Defaults to <code>#f</code>.
<h3><a id="make-canvas"><code><nowiki>(make-canvas [context context?] [data (or/c string? pointer?)]) → canvas?</nowiki></code></a></h3>
Creates a new canvas with the given driver context. The <code>data</code> is
context specific and is either a string describing the setup of the new canvas
or a pointer to some native data object.
<h3><a id="call-with-canvas"><code>
<nowiki>(call-with-canvas [canvas canvas?] [proc (-> canvas? any)]) → any</nowiki><br>
<nowiki>(call-with-canvas [context context?] [data (or/c string? pointer?)] [proc (-> canvas? any)]) → any</nowiki>
</code></a></h3>
Calls the given procedure with the given canvas and makes sure the canvas is
synchronized with external resources around the call.
If called in the three argument form, a fresh canvas is created using the given
context and is automatically destroyed upon return from the given procedure.
<h3><a id="canvas-context"><code><nowiki>(canvas-context [canvas canvas?]) → context?</nowiki></code></a></h3>
Retrieves the context from a given canvas.
<h3><a id="canvas-simulate_"><code><nowiki>(canvas-simulate! [canvas canvas?] [flags (listof symbol?)]) → (listof symbol?)</nowiki></code></a></h3>
Sets flags determining which operations should be simulated by the given canvas.
Returns the previous set of flags.
The following flags may show up in the list:
* <code>'line</code>
* <code>'rectangle</code>
* <code>'box</code>
* <code>'arc</code>
* <code>'sector</code>
* <code>'chord</code>
* <code>'polyline</code>
* <code>'polygon</code>
* <code>'text</code>
* <code>'all</code>
* <code>'lines</code>
* <code>'fills</code>
<h3><a id="canvas-attribute"><code><nowiki>(canvas-attribute [canvas canvas?] [name (or/c symbol? string?)]) → (or/c string? #f)</nowiki></code></a></h3>
Retrieves the value of a context specific canvas attribute.
<h3><a id="canvas-attribute-set_"><code>
<nowiki>(canvas-attribute-set! [canvas canvas?] [name (or/c symbol? string?)] [value (or/c string? #f)]) → void?</nowiki><br>
<nowiki>(set! (canvas-attribute [canvas canvas?] [name (or/c symbol? string?)]) [value (or/c string? #f)]) → void?</nowiki>
</code></a></h3>
Sets the value of a context specific canvas attribute.
<h3><a id="canvas-state"><code><nowiki>(canvas-state [canvas canvas?]) → state?</nowiki></code></a></h3>
Extracts a representation of the current state from a canvas.
<h3><a id="canvas-state-set_"><code>
<nowiki>(canvas-state-set! [canvas canvas?] [state state?]) → void?</nowiki><br>
<nowiki>(set! (canvas-state [canvas canvas?]) [state state?]) → void?</nowiki>
</code></a></h3>
Restores the given state of a canvas.
<h3><a id="canvas-clear_"><code><nowiki>(canvas-clear! [canvas canvas?]) → void?</nowiki></code></a></h3>
Clears a canvas to the background color.
<h3><a id="canvas-flush"><code><nowiki>(canvas-flush [canvas canvas?]) → void?</nowiki></code></a></h3>
Flushes all pending drawing operations in a canvas to its backend.
<h2>Coordinate System</h2>
<h3><a id="canvas-size"><code><nowiki>(canvas-size [canvas canvas?]) → (values integer? integer? real? real?)</nowiki></code></a></h3>
Retrieves the width and height of the given canvas in pixels and millimeters.
<h3><a id="canvas-mm->px"><code><nowiki>(canvas-mm->px [canvas canvas?] [x/mm real?] [y/mm real?]) → (values integer? integer?)</nowiki></code></a></h3>
Converts a position given in millimeters into a pixel position in the given
canvas.
<h3><a id="canvas-px->mm"><code><nowiki>(canvas-px->mm [canvas canvas?] [x/px integer?] [y/px integer?]) → (values real? real?)</nowiki></code></a></h3>
Converts a position given in pixels into a physical position in the given
canvas.
<h3><a id="canvas-origin"><code><nowiki>(canvas-origin [canvas canvas?]) → (values integer? integer?)</nowiki></code></a></h3>
Retrieves the position of the canvas' origin.
<h3><a id="canvas-origin-set_"><code><nowiki>(canvas-origin-set! [canvas canvas?] [x integer?] [y integer?]) → void?</nowiki></code></a></h3>
Defines the position of the canvas' origin.
<h3><a id="canvas-transform"><code><nowiki>(canvas-transform [canvas canvas?]) → (or/c (-> real? real? (values integer? integer?)) #f)</nowiki></code></a></h3>
Retrieves the active coordinate transformation of the given canvas.
<h3><a id="canvas-transform-set_"><code>
<nowiki>(canvas-transform-set! [canvas canvas?] [proc (or/c (-> real? real? (values integer? integer?)) #f)]) → void?</nowiki><br>
<nowiki>(set! (canvas-transform [canvas canvas?]) [proc (or/c (-> real? real? (values integer? integer?)) #f)]) → void?</nowiki>
</code></a></h3>
Defines the active coordinate transformation for the given canvas. The given
procedure must represent a linear transformation.
<h3><a id="canvas-transform-compose_"><code><nowiki>(canvas-transform-compose! [canvas canvas?] [proc (-> real? real? (values integer? integer?))]) → void?</nowiki></code></a></h3>
Modifies the active coordinate transformation for the given canvas by
left-multiplication with the given transformation. The given procedure must
represent a linear transformation.
<h3><a id="canvas-transform-translate_"><code><nowiki>(canvas-transform-translate! [canvas canvas?] [dx real?] [dy real?]) → void?</nowiki></code></a></h3>
Modifies the active coordinate transformation for the given canvas applying
a translation.
<h3><a id="canvas-transform-scale!"><code><nowiki>(canvas-transform-scale! [canvas canvas?] [sx real?] [sy real?]) → void?</nowiki></code></a></h3>
Modifies the active coordinate transformation for the given canvas applying
a scaling.
<h3><a id="canvas-transform-rotate!"><code><nowiki>(canvas-transform-rotate! [canvas canvas?] [alpha real?]) → void?</nowiki></code></a></h3>
Modifies the active coordinate transformation for the given canvas applying
a rotation around the origin.
<h2>General Attributes</h2>
<h3><a id="canvas-foreground"><code><nowiki>(canvas-foreground [canvas canvas?]) → integer?</nowiki></code></a></h3>
Retrieves the foreground color of the given canvas.
<h3><a id="canvas-foreground-set_"><code>
<nowiki>(canvas-foreground-set! [canvas canvas?] [color integer?]) → void?</nowiki><br>
<nowiki>(set! (canvas-foreground [canvas canvas?]) [color integer?]) → void?</nowiki>
</code></a></h3>
Sets the foreground color of the given canvas.
<h3><a id="canvas-background"><code><nowiki>(canvas-background [canvas canvas?]) → integer?</nowiki></code></a></h3>
Retrieves the background color of the given canvas.
<h3><a id="canvas-background-set_"><code>
<nowiki>(canvas-background-set! [canvas canvas?] [color integer?]) → void?</nowiki><br>
<nowiki>(set! (canvas-background [canvas canvas?]) [color integer?]) → void?</nowiki>
</code></a></h3>
Sets the background color of the given canvas.
<h3><a id="canvas-write-mode"><code><nowiki>(canvas-write-mode [canvas canvas?]) → symbol?</nowiki></code></a></h3>
Retrieves the write mode of the given canvas.
The mode may be one of the following symbols:
* <code>'replace</code>
* <code>'xor</code>
* <code>'not-xor</code>
<h3><a id="canvas-write-mode-set_"><code>
<nowiki>(canvas-write-mode-set! [canvas canvas?] [mode symbol?]) → void?</nowiki><br>
<nowiki>(set! (canvas-write-mode [canvas canvas?]) [mode symbol?]) → void?</nowiki>
</code></a></h3>
Sets the write mode of the given canvas.
<h2>Clipping</h2>
<h3><a id="canvas-clip-mode"><code><nowiki>(canvas-clip-mode [canvas canvas?]) → (or/c symbol? #f)</nowiki></code></a></h3>
Retrieves the clipping mode of the given canvas.
The mode may be one of the following values:
* <code>'area</code>
* <code>'polygon</code>
* <code>'region</code>
* <code>#f</code>
In fact, <code>#t</code> is never returned but may be used when setting the
clipping mode.
<h3><a id="canvas-clip-mode-set_"><code>
<nowiki>(canvas-clip-mode-set! [canvas canvas?] [mode (or/c symbol? #f)]) → void?</nowiki><br>
<nowiki>(set! (canvas-clip-mode [canvas canvas?]) [mode (or/c symbol? #f)]) → void?</nowiki>
</code></a></h3>
Sets the clipping mode of the given canvas.
<h3><a id="canvas-clip-area"><code><nowiki>(canvas-clip-area [canvas canvas?]) → (values real? real? real? real?)</nowiki></code></a></h3>
Retrieves the current rectangular clipping area of the given canvas.
<h3><a id="canvas-clip-area-set_"><code><nowiki>(canvas-clip-area-set! [canvas canvas?] [x0 double?] [x1 double?] [y0 double?] [y1 double?]) → void?</nowiki></code></a></h3>
Sets the current rectangular clipping area of the given canvas.
<h2>Racket Specifics</h2>
<h3><a id="_canvas"><code>
<nowiki>[_canvas ctype?]</nowiki><br>
<nowiki>[_canvas/null ctype?]</nowiki><br>
</code></a></h3>
Foreign type of CD canvasses, which may optionally be <code>NULL</code>.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="_context"><code>
<nowiki>[_context ctype?]</nowiki><br>
<nowiki>[_context/null ctype?]</nowiki><br>
</code></a></h3>
Foreign type of CD contexts, which may optionally be <code>NULL</code>.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="_state"><code>
<nowiki>[_state ctype?]</nowiki><br>
<nowiki>[_state/null ctype?]</nowiki><br>
</code></a></h3>
Foreign type of CD states, which may optionally be <code>NULL</code>.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h2>CHICKEN Specifics</h2>
The <tt>base</tt> module only exports checking type conversion functions
instead of foreign types since the latter cannot be exported. To define
the types <code>canvas</code>, <code>nonnull-canvas</code>,
<code>context</code>, <code>nonnull-context</code>, <code>state</code> and
<code>nonnull-state</code> in your own module, include the file
<tt>"canvas-draw-types.scm"</tt>.
<h3><a id="canvas-_pointer"><code><nowiki>((canvas->pointer [nonnull? any/c]) [canvas (or/c canvas? #f)]) → (or/c pointer? #f)</nowiki></code></a></h3>
Checking conversion from canvasses to pointers.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="pointer-_canvas"><code><nowiki>((pointer->canvas [nonnull? any/c]) [canvas (or/c pointer? #f)]) → (or/c canvas? #f)</nowiki></code></a></h3>
Checking conversion from pointers to canvasses.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="context-_pointer"><code><nowiki>((context->pointer [nonnull? any/c]) [context (or/c context? #f)]) → (or/c pointer? #f)</nowiki></code></a></h3>
Checking conversion from contexts to pointers.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="pointer-_context"><code><nowiki>((pointer->context [nonnull? any/c]) [context (or/c pointer? #f)]) → (or/c context? #f)</nowiki></code></a></h3>
Checking conversion from pointers to contexts.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="state-_pointer"><code><nowiki>((state->pointer [nonnull? any/c]) [state (or/c state? #f)]) → (or/c pointer? #f)</nowiki></code></a></h3>
Checking conversion from states to pointers.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.
<h3><a id="pointer-_state"><code><nowiki>((pointer->state [nonnull? any/c]) [state (or/c pointer? #f)]) → (or/c state? #f)</nowiki></code></a></h3>
Checking conversion from pointers to states.
Not re-exported from the <tt>[./main.wiki|main]</tt> module.