File canvas-draw/api/primitives.wiki artifact 36cfca72a5 part of check-in 432c02a937


<h1><tt>primitives</tt> Module</h1>

<h2>Synopsis</h2>

<table>
	<tr>
		<th>Racket</th>
		<td><code>(require (planet murphy/canvas-draw:1:0/primitives))</code></td>
	</tr>
	<tr>
		<th>CHICKEN</th>
		<td><code>(require-extension canvas-draw-primitives)</code></td>
	</tr>
</table>

Drawing primitives.

<h2>Points</h2>

<h3><a id="canvas-pixel_"><code><nowiki>(canvas-pixel! [canvas canvas?] [x integer?] [y integer?] [color integer? (canvas-foreground canvas)]) → void?</nowiki></code></a></h3>

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

<h3><a id="canvas-mark!"><code><nowiki>(canvas-mark! [canvas canvas?] [x integer?] [y integer?]) → void?</nowiki></code></a></h3>

Draws a marker symbol on the given canvas.

<h3><a id="canvas-mark-type"><code><nowiki>(canvas-mark-type [canvas canvas?]) → symbol?</nowiki></code></a></h3>

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

  *  <code>'+</code> or <code>'plus</code>
  *  <code>'*</code> or <code>'star</code>
  *  <code>'0</code> or <code>'circle</code>
  *  <code>'O</code> or <code>'hollow-circle</code>
  *  <code>'X</code> or <code>'x</code>
  *  <code>'box</code>
  *  <code>'hollow-box</code>
  *  <code>'diamond</code>
  *  <code>'hollow-diamond</code>

<h3><a id="canvas-mark-type-set_"><code>
	<nowiki>(canvas-mark-type-set! [canvas canvas?] [mark-type symbol?]) → void?</nowiki><br>
	<nowiki>(set! (canvas-mark-type [canvas canvas?]) [mark-type symbol?]) → void?</nowiki>
</code></a></h3>

Sets the current marker symbol type for the given canvas.

<h3><a id="canvas-mark-size"><code><nowiki>(canvas-mark-size [canvas canvas?]) → integer?</nowiki></code></a></h3>

Retrieves the current marker symbol size for the given canvas.

<h3><a id="canvas-mark-size-set_"><code>
	<nowiki>(canvas-mark-size-set! [canvas canvas?] [size integer?]) → void?</nowiki><br>
	<nowiki>(set! (canvas-mark-size [canvas canvas?]) [size integer?]) → void?</nowiki>
</code></a></h3>

Sets the current marker symbol size for the given canvas.

<h2>Lines</h2>

<h3><a id="canvas-line_"><code><nowiki>(canvas-line! [canvas canvas?] [x0 real?] [y0 real?] [x1 real?] [y1 real?]) → void?</nowiki></code></a></h3>

Draws a line on the given canvas.

<h3><a id="canvas-rectangle_"><code><nowiki>(canvas-rectangle! [canvas canvas?] [x0 real?] [x1 real?] [y0 real?] [y1 real?]) → void?</nowiki></code></a></h3>

Draws a hollow rectangle on the given canvas.

<h3><a id="canvas-arc_"><code><nowiki>(canvas-arc! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) → void?</nowiki></code></a></h3>

Draws a hollow ellipsis segment on the given canvas.

<h3><a id="canvas-line-style"><code><nowiki>(canvas-line-style [canvas canvas?]) → symbol?</nowiki></code></a></h3>

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

  *  <code>'continuous</code>
  *  <code>'dashed</code>
  *  <code>'dotted</code>
  *  <code>'dash-dotted</code>
  *  <code>'dash-dot-dotted</code>
  *  <code>'custom</code>

<h3><a id="canvas-line-style-set_"><code>
	<nowiki>(canvas-line-style-set! [canvas canvas?] [line-style (or/c symbol? list?)]) → symbol?</nowiki><br>
	<nowiki>(set! (canvas-line-style [canvas canvas?]) [line-style (or/c symbol? list?)]) → symbol?</nowiki>
</code></a></h3>

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

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

<h3><a id="canvas-line-width"><code><nowiki>(canvas-line-width [canvas canvas?]) → integer?</nowiki></code></a></h3>

Retrieves the current line width of the given canvas.

<h3><a id="canvas-line-width-set_"><code>
	<nowiki>(canvas-line-width-set! [canvas canvas?] [line-width integer?]) → integer?</nowiki><br>
	<nowiki>(set! (canvas-line-width [canvas canvas?]) [line-width integer?]) → integer?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-line-join"><code><nowiki>(canvas-line-join [canvas canvas?]) → symbol?</nowiki></code></a></h3>

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

  *  <code>'miter</code>
  *  <code>'bevel</code>
  *  <code>'round</code>

<h3><a id="canvas-line-join-set_"><code>
	<nowiki>(canvas-line-join-set! [canvas canvas?] [line-join symbol?]) → symbol?</nowiki><br>
	<nowiki>(set! (canvas-line-join [canvas canvas?]) [line-join symbol?]) → symbol?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-line-cap"><code><nowiki>(canvas-line-cap [canvas canvas?]) → symbol?</nowiki></code></a></h3>

Retrieves the current line cap style of the given canvas.

  *  <code>'flat</code>
  *  <code>'square</code>
  *  <code>'round</code>

<h3><a id="canvas-line-cap-set_"><code>
	<nowiki>(canvas-line-cap-set! [canvas canvas?] [line-cap symbol?]) → symbol?</nowiki><br>
	<nowiki>(set! (canvas-line-cap [canvas canvas?]) [line-cap symbol?]) → symbol?</nowiki>
</code></a></h3>

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

<h2>Filled Areas</h2>

<h3><a id="canvas-box_"><code><nowiki>(canvas-box! [canvas canvas?] [x0 real?] [x1 real?] [y0 real?] [y1 real?]) → void?</nowiki></code></a></h3>

Draws a filled rectangle on the given canvas.

<h3><a id="canvas-sector_"><code><nowiki>(canvas-sector! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) → void?</nowiki></code></a></h3>

Draws a filled ellipsis sector on the given canvas.

<h3><a id="canvas-chord_"><code><nowiki>(canvas-chord! [canvas canvas?] [x real?] [y real?] [width real?] [height real?] [alpha0 real?] [alpha1 real?]) → void?</nowiki></code></a></h3>

Draws a filled ellipsis arc on the given canvas.

<h3><a id="canvas-background-opacity"><code><nowiki>(canvas-background-opacity [canvas canvas?]) → symbol?</nowiki></code></a></h3>

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

  *  <code>'transparent</code>
  *  <code>'opaque</code>

<h3><a id="canvas-background-opacity-set_"><code>
	<nowiki>(canvas-background-opacity-set! [canvas canvas?] [background-opacity symbol?]) → symbol?</nowiki><br>
	<nowiki>(set! (canvas-background-opacity-set! [canvas canvas?]) [background-opacity symbol?]) → symbol?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-fill-mode"><code><nowiki>(canvas-fill-mode [canvas canvas?]) → symbol?</nowiki></code></a></h3>

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

  *  <code>'even-odd</code>
  *  <code>'winding</code>

<h3><a id="canvas-fill-mode-set_"><code>
	<nowiki>(canvas-fill-mode-set! [canvas canvas?] [fill-mode symbol?]) → symbol?</nowiki><br>
	<nowiki>(set! (canvas-fill-mode [canvas canvas?]) [fill-mode symbol?]) → symbol?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-interior-style"><code><nowiki>(canvas-interior-style [canvas canvas?]) → (or/c symbol? list?)</nowiki></code></a></h3>

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

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

<h3><a id="canvas-interior-style-set_"><code>
	<nowiki>(canvas-interior-style-set! [canvas canvas?] [interior-style (or/c symbol? list?)]) → void?</nowiki><br>
	<nowiki>(set! (canvas-interior-style [canvas canvas?]) [interior-style (or/c symbol? list?)]) → void?</nowiki>
</code></a></h3>

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

<h2>Text</h2>

<h3><a id="canvas-text_"><code><nowiki>(canvas-text! [canvas canvas?] [x real?] [y real?] [text string?]) → void?</nowiki></code></a></h3>

Draws a string of text on the given canvas.

<h3><a id="canvas-font"><code><nowiki>(canvas-font [canvas canvas?]) → string?</nowiki></code></a></h3>

Retrieves the current font of the given canvas.

<h3><a id="canvas-font-set_"><code>
	<nowiki>(canvas-font-set! [canvas canvas?] [font string?]) → void?</nowiki><br>
	<nowiki>(set! (canvas-font [canvas canvas?]) [font string?]) → void?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-text-alignment"><code><nowiki>(canvas-text-alignment [canvas canvas?]) → symbol?</nowiki></code></a></h3>

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

  *  <code>'north</code>
  *  <code>'south</code>
  *  <code>'east</code>
  *  <code>'west</code>
  *  <code>'north-east</code>
  *  <code>'north-west</code>
  *  <code>'south-east</code>
  *  <code>'south-west</code>
  *  <code>'center</code>
  *  <code>'base-left</code>
  *  <code>'base-center</code>
  *  <code>'base-right</code>

<h3><a id="canvas-text-alignment-set_"><code>
	<nowiki>(canvas-text-alignment-set! [canvas canvas?] [text-alignment symbol?]) → void?</nowiki><br>
	<nowiki>(set! (canvas-text-alignment [canvas canvas?]) [text-alignment symbol?]) → void?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-text-orientation"><code><nowiki>(canvas-text-orientation [canvas canvas?]) → real?</nowiki></code></a></h3>

Retrieves the current text orientation of the given canvas.

<h3><a id="canvas-text-orientation-set_"><code>
	<nowiki>(canvas-text-orientation-set! [canvas canvas?] [orientation real?]) → void?</nowiki><br>
	<nowiki>(set! (canvas-text-orientation [canvas canvas?]) [orientation real?]) → void?</nowiki>
</code></a></h3>

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

<h3><a id="canvas-font-dimensions"><code><nowiki>(canvas-font-dimensions [canvas canvas?]) → (values integer? integer? integer? integer?)</nowiki></code></a></h3>

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

<h3><a id="canvas-text-size"><code><nowiki>(canvas-text-size [canvas canvas?] [text string?]) → (values integer? integer?)</nowiki></code></a></h3>

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

<h3><a id="canvas-text-box"><code><nowiki>(canvas-text-box [canvas canvas?] [x integer?] [y integer?] [text string?]) → (values integer? integer? integer? integer?)</nowiki></code></a></h3>

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

<h2>Vertices</h2>

<h3><a id="call-with-canvas-in-mode"><code><nowiki>(call-with-canvas-in-mode [canvas canvas?] [mode symbol?] [proc (-> canvas? any)]) → any</nowiki></code></a></h3>

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

Possible modes are

  *  <code>'open-lines</code>
  *  <code>'closed-lines</code>
  *  <code>'fill</code>
  *  <code>'clip</code>
  *  <code>'bezier</code>
  *  <code>'region</code>
  *  <code>'path</code>

<h3><a id="canvas-path-set!"><code><nowiki>(canvas-path-set! [canvas canvas?] [path-action symbol?]) → void?</nowiki></code></a></h3>

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

  *  <code>'new</code>
  *  <code>'move-to</code>
  *  <code>'line-to</code>
  *  <code>'arc</code>
  *  <code>'curve-to</code>
  *  <code>'close</code>
  *  <code>'fill</code>
  *  <code>'stroke</code>
  *  <code>'fill+stroke</code>
  *  <code>'clip</code>

<h3><a id="canvas-vertex!"><code><nowiki>(canvas-vertex! [canvas canvas?] [x real?] [y real?]) → void?</nowiki></code></a></h3>

Sends a vertex to the given canvas.