File canvas-draw/api/base.wiki artifact 01dd0798b9 part of check-in ed10f826ff


base Module

Synopsis

Racket (require (planet murphy/canvas-draw:1:0/base))
CHICKEN (require-extension canvas-draw-base)

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

Data Types

(canvas? [v any/c]) → boolean?

Check whether a value is a CD canvas.

(context? [v any/c]) → boolean?

Check whether a value is a CD driver context.

(state? [v any/c]) → boolean?

Check whether a value is a CD canvas state.

Canvas Management

(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

[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.

(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.

(call-with-canvas [canvas canvas?] [proc (-> canvas? any)]) → any
(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.

(canvas-context [canvas canvas?]) → context?

Retrieves the context from a given canvas.

(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

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

Retrieves the value of a context specific canvas attribute.

(canvas-attribute-set! [canvas canvas?] [name (or/c symbol? string?)] [value (or/c string? #f)]) → void?
(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.

(canvas-state [canvas canvas?]) → state?

Extracts a representation of the current state from a canvas.

(canvas-state-set! [canvas canvas?] [state state?]) → void?
(set! (canvas-state [canvas canvas?]) [state state?]) → void?

Restores the given state of a canvas.

(canvas-clear! [canvas canvas?]) → void?

Clears a canvas to the background color.

(canvas-flush [canvas canvas?]) → void?

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

Coordinate System

(canvas-size [canvas canvas?]) → (values integer? integer? real? real?)

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

(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.

(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.

(canvas-origin [canvas canvas?]) → (values integer? integer?)

Retrieves the position of the canvas' origin.

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

Defines the position of the canvas' origin.

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

Retrieves the active coordinate transformation of the given canvas.

(canvas-transform-set! [canvas canvas?] [proc (or/c (-> real? real? (values integer? integer?)) #f)]) → void?
(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.

(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.

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

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

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

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

(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

(canvas-foreground [canvas canvas?]) → integer?

Retrieves the foreground color of the given canvas.

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

Sets the foreground color of the given canvas.

(canvas-background [canvas canvas?]) → integer?

Retrieves the background color of the given canvas.

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

Sets the background color of the given canvas.

(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

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

Sets the write mode of the given canvas.

Clipping

(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.

(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.

(canvas-clip-area [canvas canvas?]) → (values real? real? real? real?)

Retrieves the current rectangular clipping area of the given canvas.

(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.

Racket Specifics

[_canvas ctype?]
[_canvas/null ctype?]

Foreign type of CD canvasses, which may optionally be NULL.

Not re-exported from the main module.

[_context ctype?]
[_context/null ctype?]

Foreign type of CD contexts, which may optionally be NULL.

Not re-exported from the main module.

[_state ctype?]
[_state/null ctype?]

Foreign type of CD states, which may optionally be NULL.

Not re-exported from the main module.

CHICKEN Specifics

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".

((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.

((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.

((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.

((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.

((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.

((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.