• Wiki
• Download
• Manual
• Eggs
• API
• Tests
• Bugs

Canvas Draw

Description

Bindings to the CanvasDraw graphics library

See the original C library

Author

Thomas Chust

Repository

https://chust.org/repos/scheme-canvas-draw

Documentation

See the official API docs.

Here is a condensed version to be usable with the online and offline Chicken documentation.

main Module

Usage

(import canvas-draw)

This module re-exports most bindings from the base, play and primitives modules.

To create canvasses you also have to import bindings from at least one of the context modules: iup, native, gl, clipboard, printer, picture, server, client, pdf, ps, svg, metafile, debug, cgm, dgn, dxf, emf, wmf.

The foreign types and conversion procedures defined in base are not re-exported.

base Module

Usage

(import canvas-draw-base)

Basic CD library support. Initializes the CD library when loaded.

Data Types

[procedure] (canvas? [v any/c]) -> boolean?

Check whether a value is a CD canvas.

[procedure] (context? [v any/c]) -> boolean?

Check whether a value is a CD driver context.

[procedure] (state? [v any/c]) -> boolean?

Check whether a value is a CD canvas state.

Canvas Management

[procedure] (context-capabilities [context context?]) -> (listof symbol?)

Returns a list of flags describing the capabilities supported by the given context.

The following flags may show up in the list:

• 'flush
• 'clear
• 'play
• 'y-axis
• 'clip-area
• 'clip-polygon
• 'region
• 'rectangle
• 'chord
• 'image/rgb
• 'image/rgba
• 'image/map
• 'get-image/rgb
• 'image/server
• 'background
• 'background-opacity
• 'write-mode
• 'line-style
• 'line-width
• 'fprimtives
• 'hatch
• 'stipple
• 'pattern
• 'font
• 'font-dimensions
• 'text-size
• 'text-orientation
• 'palette
• 'line-cap
• 'line-join
• 'path
• 'bezier

[parameter] (use-context+ (parameter/c any))

A parameter determining whether calls to make-canvas should use extended variants of the passed context drivers.

Defaults to #f.

[procedure] (make-canvas [context context?] [data (or/c string? pointer?)]) -> canvas?

Creates a new canvas with the given driver context. The data is context specific and is either a string describing the setup of the new canvas or a pointer to some native data object. e.g., to create a canvas from an iup canvas, use (make-canvas context:iup iup-canvas)

[procedure] (call-with-canvas [canvas canvas?] [proc (-> canvas? any)]) -> any
[procedure] (call-with-canvas [context context?] [data (or/c string? pointer?)] [proc (-> canvas? any)]) -> any

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.

[procedure] (canvas-context [canvas canvas?]) -> context?

Retrieves the context from a given canvas.

[procedure] (canvas-simulate! [canvas canvas?] [flags (listof symbol?)]) -> (listof symbol?)

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:

• 'line
• 'rectangle
• 'box
• 'arc
• 'sector
• 'chord
• 'polyline
• 'polygon
• 'text
• 'all
• 'lines
• 'fills

[procedure] (canvas-attribute [canvas canvas?] [name (or/c symbol? string?)]) -> (or/c string? #f)

Retrieves the value of a context specific canvas attribute.

[procedure] (canvas-attribute-set! [canvas canvas?] [name (or/c symbol? string?)] [value (or/c string? #f)]) -> void?

Alternatively (set! (canvas-attribute [canvas canvas?] [name (or/c symbol? string?)]) [value (or/c string? #f)]) -> void?

Sets the value of a context specific canvas attribute.

[procedure] (canvas-state [canvas canvas?]) -> state?

Extracts a representation of the current state from a canvas.

[procedure] (canvas-state-set! [canvas canvas?] [state state?]) -> void?

Alternatively (set! (canvas-state [canvas canvas?]) [state state?]) -> void?

Restores the given state of a canvas.

[procedure] (canvas-clear! [canvas canvas?]) -> void?

Clears a canvas to the background color.

[procedure] (canvas-flush [canvas canvas?]) -> void?

Flushes all pending drawing operations in a canvas to its backend.

Coordinate System

[procedure] (canvas-size [canvas canvas?]) -> (values integer? integer? real? real?)

Retrieves the width and height of the given canvas in pixels and millimeters.

[procedure] (canvas-mm->px [canvas canvas?] [x/mm real?] [y/mm real?]) -> (values integer? integer?)

Converts a position given in millimeters into a pixel position in the given canvas.

[procedure] (canvas-px->mm [canvas canvas?] [x/px integer?] [y/px integer?]) -> (values real? real?)

Converts a position given in pixels into a physical position in the given canvas.

[procedure] (canvas-origin [canvas canvas?]) -> (values integer? integer?)

Retrieves the position of the canvas' origin.

[procedure] (canvas-origin-set! [canvas canvas?] [x integer?] [y integer?]) -> void?

Defines the position of the canvas' origin.

[procedure] (canvas-transform [canvas canvas?]) -> (or/c (-> real? real? (values integer? integer?)) #f)

Retrieves the active coordinate transformation of the given canvas.

[procedure] (canvas-transform-set! [canvas canvas?] [proc (or/c (-> real? real? (values integer? integer?)) #f)]) -> void?

Alternatively (set! (canvas-transform [canvas canvas?]) [proc (or/c (-> real? real? (values integer? integer?)) #f)]) -> void?

Defines the active coordinate transformation for the given canvas. The given procedure must represent a linear transformation.

[procedure] (canvas-transform-compose! [canvas canvas?] [proc (-> real? real? (values integer? integer?))]) -> void?

Modifies the active coordinate transformation for the given canvas by left-multiplication with the given transformation. The given procedure must represent a linear transformation.

[procedure] (canvas-transform-translate! [canvas canvas?] [dx real?] [dy real?]) -> void?

Modifies the active coordinate transformation for the given canvas applying a translation.

[procedure] (canvas-transform-scale! [canvas canvas?] [sx real?] [sy real?]) -> void?

Modifies the active coordinate transformation for the given canvas applying a scaling.

[procedure] (canvas-transform-rotate! [canvas canvas?] [alpha real?]) -> void?

Modifies the active coordinate transformation for the given canvas applying a rotation around the origin.

General Attributes

[procedure] (canvas-foreground [canvas canvas?]) -> integer?

Retrieves the foreground color of the given canvas.

[procedure] (canvas-foreground-set! [canvas canvas?] [color integer?]) -> void?

Alternatively (set! (canvas-foreground [canvas canvas?]) [color integer?]) -> void?

Sets the foreground color of the given canvas.

[procedure] (canvas-background [canvas canvas?]) -> integer?

Retrieves the background color of the given canvas.

[procedure] (canvas-background-set! [canvas canvas?] [color integer?]) -> void?

Alternatively (set! (canvas-background [canvas canvas?]) [color integer?]) -> void?

Sets the background color of the given canvas.

[procedure] (canvas-write-mode [canvas canvas?]) -> symbol?

Retrieves the write mode of the given canvas.

The mode may be one of the following symbols:

• 'replace
• 'xor
• 'not-xor

[procedure] (canvas-write-mode-set! [canvas canvas?] [mode symbol?]) -> void?

Alternatively (set! (canvas-write-mode [canvas canvas?]) [mode symbol?]) -> void?

Sets the write mode of the given canvas.

Clipping

[procedure] (canvas-clip-mode [canvas canvas?]) -> (or/c symbol? #f)

Retrieves the clipping mode of the given canvas.

The mode may be one of the following values:

• 'area
• 'polygon
• 'region
• #f

In fact, #t is never returned but may be used when setting the clipping mode.

[procedure] (canvas-clip-mode-set! [canvas canvas?] [mode (or/c symbol? #f)]) -> void?

(set! (canvas-clip-mode [canvas canvas?]) [mode (or/c symbol? #f)]) -> void?

Sets the clipping mode of the given canvas.

[procedure] (canvas-clip-area [canvas canvas?]) -> (values real? real? real? real?)

Retrieves the current rectangular clipping area of the given canvas.

[procedure] (canvas-clip-area-set! [canvas canvas?] [x0 double?] [x1 double?] [y0 double?] [y1 double?]) -> void?

Sets the current rectangular clipping area of the given canvas.

The base module only exports checking type conversion functions instead of foreign types since the latter cannot be exported. To define the types canvas, nonnull-canvas, context, nonnull-context, state and nonnull-state in your own module, include the file "canvas-draw-types.scm".

[procedure] ((canvas->pointer [nonnull? any/c]) [canvas (or/c canvas? #f)]) -> (or/c pointer? #f)

Checking conversion from canvasses to pointers.

Not re-exported from the main module.

[procedure] ((pointer->canvas [nonnull? any/c]) [canvas (or/c pointer? #f)]) -> (or/c canvas? #f)

Checking conversion from pointers to canvasses.

Not re-exported from the main module.

[procedure] ((context->pointer [nonnull? any/c]) [context (or/c context? #f)]) -> (or/c pointer? #f)

Checking conversion from contexts to pointers.

Not re-exported from the main module.

[procedure] ((pointer->context [nonnull? any/c]) [context (or/c pointer? #f)]) -> (or/c context? #f)

Checking conversion from pointers to contexts.

Not re-exported from the main module.

[procedure] ((state->pointer [nonnull? any/c]) [state (or/c state? #f)]) -> (or/c pointer? #f)

Checking conversion from states to pointers.

Not re-exported from the main module.

[procedure] ((pointer->state [nonnull? any/c]) [state (or/c pointer? #f)]) -> (or/c state? #f)

Checking conversion from pointers to states.

Not re-exported from the main module.

play Module

Usage

(import canvas-draw-play)

Replay functionality.

Context Content Replay

[procedure] (canvas-play! [canvas canvas?] [context context?] [x0 integer?] [x1 integer?] [y0 integer?] [y1 integer?] [data (or/c string? pointer?)])

-> void?

Replays the drawing contained in the context withe the given data in the given canvas.

primitives Module

Usage

(import canvas-draw-primitives)

Drawing primitives.

Points

[procedure] (canvas-pixel! [canvas canvas?] [x integer?] [y integer?] [color integer? (canvas-foreground canvas)]) -> void?

Draws a single pixel of the given color on the given canvas.

[procedure] (canvas-mark! [canvas canvas?] [x integer?] [y integer?]) -> void?

Draws a marker symbol on the given canvas.

[procedure] (canvas-mark-type [canvas canvas?]) -> symbol?

Retrieves the current marker symbol type for the given canvas. Possible values are

• '+ or 'plus
• '* or 'star
• '0 or 'circle
• 'O or 'hollow-circle
• 'X or 'x
• 'box
• 'hollow-box
• 'diamond
• 'hollow-diamond

[procedure] (canvas-mark-type-set! [canvas canvas?] [mark-type symbol?]) -> void?

Alternatively (set! (canvas-mark-type [canvas canvas?]) [mark-type symbol?]) -> void?

Sets the current marker symbol type for the given canvas.

[procedure] (canvas-mark-size [canvas canvas?]) -> integer?

Retrieves the current marker symbol size for the given canvas.

[procedure] (canvas-mark-size-set! [canvas canvas?] [size integer?]) -> void?

Alternatively (set! (canvas-mark-size [canvas canvas?]) [size integer?]) -> void?

Sets the current marker symbol size for the given canvas.

Lines

[procedure] (canvas-line! [canvas canvas?] [x0 real?] [y0 real?] [x1 real?] [y1 real?]) -> void?

Draws a line on the given canvas.

[procedure] (canvas-rectangle! [canvas canvas?] [x0 real?] [x1 real?] [y0 real?] [y1 real?]) -> void?

Draws a hollow rectangle on the given canvas.

[procedure] (canvas-arc! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) -> void?

Draws a hollow ellipsis segment on the given canvas.

[procedure] (canvas-line-style [canvas canvas?]) -> symbol?

Retrieves the current line style of the given canvas. Possible values are

• 'continuous
• 'dashed
• 'dotted
• 'dash-dotted
• 'dash-dot-dotted
• 'custom

[procedure] (canvas-line-style-set! [canvas canvas?] [line-style (or/c symbol? list?)]) -> symbol?

Alternatively (set! (canvas-line-style [canvas canvas?]) [line-style (or/c symbol? list?)]) -> symbol?

Sets the current line style of the given canvas and returns the previous value.

In addition to the possible return values of canvas-line-style a custom line-style can be fully specified using the form (list 'custom [len integer?] ...).

[procedure] (canvas-line-width [canvas canvas?]) -> integer?

Retrieves the current line width of the given canvas.

[procedure] (canvas-line-width-set! [canvas canvas?] [line-width integer?]) -> integer?

Alternatively (set! (canvas-line-width [canvas canvas?]) [line-width integer?]) -> integer?

Sets the current line width of the given canvas and returns the previous value.

[procedure] (canvas-line-join [canvas canvas?]) -> symbol?

Retrieves the current line join style of the given canvas. Possible values are

• 'miter
• 'bevel
• 'round

[procedure] (canvas-line-join-set! [canvas canvas?] [line-join symbol?]) -> symbol?

Alternatively (set! (canvas-line-join [canvas canvas?]) [line-join symbol?]) -> symbol?

Sets the current line join style of the given canvas and returns the previous value.

[procedure] (canvas-line-cap [canvas canvas?]) -> symbol?

Retrieves the current line cap style of the given canvas.

• 'flat
• 'square
• 'round

[procedure] (canvas-line-cap-set! [canvas canvas?] [line-cap symbol?]) -> symbol?

Alternatively (set! (canvas-line-cap [canvas canvas?]) [line-cap symbol?]) -> symbol?

Sets the current line cap style of the given canvas and returns the previous value.

Filled Areas

[procedure] (canvas-box! [canvas canvas?] [x0 real?] [x1 real?] [y0 real?] [y1 real?]) -> void?

Draws a filled rectangle on the given canvas.

[procedure] (canvas-sector! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) -> void?

Draws a filled ellipsis sector on the given canvas.

[procedure] (canvas-chord! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) -> void?

Draws a filled ellipsis arc on the given canvas.

[procedure] (canvas-background-opacity [canvas canvas?]) -> symbol?

Retrieves the current background opacity of the given canvas. Possible values are

• 'transparent
• 'opaque

[procedure] (canvas-background-opacity-set! [canvas canvas?] [background-opacity symbol?]) -> symbol?

(set! (canvas-background-opacity-set! [canvas canvas?]) [background-opacity symbol?]) -> symbol?

Sets the current background opacity of the given canvas and returns the previous value.

[procedure] (canvas-fill-mode [canvas canvas?]) -> symbol?

Retrieves the current polygon fill mode of the given canvas. Possible values are

• 'even-odd
• 'winding

[procedure] (canvas-fill-mode-set! [canvas canvas?] [fill-mode symbol?]) -> symbol?

Alternatively (set! (canvas-fill-mode [canvas canvas?]) [fill-mode symbol?]) -> symbol?

Sets the current polygon fill mode of the given canvas and returns the previous value.

[procedure] (canvas-interior-style [canvas canvas?]) -> (or/c symbol? list?)

Retrieves the current interior style of the given canvas. Possible values are

• 'solid
• '(hatch horizontal)
• '(hatch vertical)
• '(hatch forward-diagonal)
• '(hatch backward-diagonal)
• '(hatch cross)
• '(hatch diagonal-cross)
• (list 'stipple [width integer?] [height integer?] [data blob?])
• (list 'pattern/rgb [width integer?] [height integer?] [data blob?])
• (list 'pattern/rgba [width integer?] [height integer?] [data blob?])
• #f

[procedure] (canvas-interior-style-set! [canvas canvas?] [interior-style (or/c symbol? list?)]) -> void?

Alternatively (set! (canvas-interior-style [canvas canvas?]) [interior-style (or/c symbol? list?)]) -> void?

Sets the current interior style of the given canvas and returns the previous value.

Text

[procedure] (canvas-text! [canvas canvas?] [x real?] [y real?] [text string?]) -> void?

Draws a string of text on the given canvas.

[procedure] (canvas-font [canvas canvas?]) -> string?

Retrieves the current font of the given canvas.

[procedure] (canvas-font-set! [canvas canvas?] [font string?]) -> void?

Alternatively (set! (canvas-font [canvas canvas?]) [font string?]) -> void?

Sets the current font of the given canvas and returns the previous value.

[procedure] (canvas-text-alignment [canvas canvas?]) -> symbol?

Retrieves the current text alignment of the given canvas. Possible values are

• 'north
• 'south
• 'east
• 'west
• 'north-east
• 'north-west
• 'south-east
• 'south-west
• 'center
• 'base-left
• 'base-center
• 'base-right

[procedure] (canvas-text-alignment-set! [canvas canvas?] [text-alignment symbol?]) -> void?

Alternatively (set! (canvas-text-alignment [canvas canvas?]) [text-alignment symbol?]) -> void?

Sets the current text alignment of the given canvas and returns the previous value.

(canvas-text-orientation [canvas canvas?]) -> real?

Retrieves the current text orientation of the given canvas.

[procedure] (canvas-text-orientation-set! [canvas canvas?] [orientation real?]) -> void?

Alternatively (set! (canvas-text-orientation [canvas canvas?]) [orientation real?]) -> void?

Sets the current text orientation of the given canvas and returns the previous value.

[procedure] (canvas-font-dimensions [canvas canvas?]) -> (values integer? integer? integer? integer?)

Returns the maximum width, height, ascent and descent of the current font of the given canvas.

[procedure] (canvas-text-size [canvas canvas?] [text string?]) -> (values integer? integer?)

Computes the width and height of the given text when drawn on the given canvas.

[procedure] (canvas-text-box [canvas canvas?] [x integer?] [y integer?] [text string?]) -> (values integer? integer? integer? integer?)

Computes the bounding box of the given text when drawn on the given canvas. Returns the minimum and maximum x and y coordinates.

Vertices

[procedure] (call-with-canvas-in-mode [canvas canvas?] [mode symbol?] [proc (-> canvas? any)]) -> any

Calls proc with the given canvas and ready to receive vertex data in the given mode. Returns whatever proc returns.

Possible modes are

• 'open-lines
• 'closed-lines
• 'fill
• 'clip
• 'bezier
• 'region
• 'path

[procedure] (canvas-path-set! [canvas canvas?] [path-action symbol?]) -> void?

Configures the action between sequences of vertex data sent to the given canvas. Possible actions are

• 'new
• 'move-to
• 'line-to
• 'arc
• 'curve-to
• 'close
• 'fill
• 'stroke
• 'fill+stroke
• 'clip

[procedure] (canvas-vertex! [canvas canvas?] [x real?] [y real?]) -> void?

Sends a vertex to the given canvas.

License

BSD license