Canvas support == Description == HOP supports //client-side canvas//. A Canvas is a drawing area that can be included in HTML pages. Canvas are supported on many Web browsers, in particular Safari and Firefox. ~~ Canvases are introduced by the ++++ markup that is documented on the ,( "HTML markups" "html.wiki") page. ~~ Although the native traditional //object-oriented// Canvas can be used in HOP programs, a //functional-oriented// is provided because in some situations it yields to more compact programs. This documentation focuses on the //functional// interface. The //object// interface documentation can be found in Firefox [[http://developer.mozilla.org/en/docs/Canvas_tutorial|tutorial]] or Safari [[http://developer.apple.com/documentation/AppleApplications/Reference/SafariJSRef/Classes/Canvas.html|documentation]]. ~~ As of November 2007, the canvas is known to work on **Firefox**, **Safari**, **Opera**, **Konqueror**, and **Webkit**. == Synopsis == === Client === (canvas-get-context canvas context-name) (canvas-properties ctx) (canvas-properties-set! ctx ...) (canvas-restore ctx) (canvas-save ctx) (canvas-rotate ctx angle) (canvas-scale ctx sx sy) (canvas-translate ctx tx ty) (canvas-transform ctx m11 m12 m21 m22 dx dy) (canvas-set-transform ctx m11 m12 m21 m22 dx dy) (canvas-arc ctx x y r sa ea clockwise) (canvas-arc-to ctx x0 y0 x1 y1 r) (canvas-arrow-to ctx x0 y0 x1 y1 ...)* (canvas-begin-path ctx) (canvas-close-path ctx) (canvas-bezier-curve ctx x0 y0 ...)* (canvas-bezier-curve-to ctx c1x c1y c2x c2y x y) (canvas-quadratic-arrow-to x0 y0 ctx cx cy x1 y1) (canvas-quadratic-curve ctx x y ...)* (canvas-quadratic-curve-to ctx cx cy x y) (canvas-clip ctx) (canvas-line ctx x0 y0 x1 y1 ...)* (canvas-line-to ctx x y) (canvas-move-to ctx x y) (canvas-stroke-rect ctx x y w height) (canvas-fill-rect ctx x y w height) (canvas-shadow-rect ctx x y w height) (canvas-clear-rect ctx x y w height) (canvas-fill ctx) (canvas-stroke ctx) (canvas-create-linear-gradient ctx x1 y1 x2 y2) (canvas-create-radial-gradient ctx x1 y1 r1 x2 y2 r2) (canvas-add-color-stop gradient position color) (canvas-create-pattern gradient image type) (canvas-draw-image ctx image x y ...) (canvas-get-image-data ctx image x y w h) (canvas-put-image-data ctx frame x y) (canvas-fill-text ctx text x y ...) (canvas-stroke-text ctx text x y ...) (canvas-measure-text ctx text) (canvas-path-text ctx font) (canvas-text-along-path ctx text stroke) === Requirements === Client codes using the //canvas// functional API need to load the script ++hop-canvas.scm++. This can be achieved with: ( :include "hop-canvas") == Examples == canvas-, == Context and Global Properties == === ++(canvas-get-context canvas context)++ === canvas-get-context ^ arguments ^ type ^ description ^ | canvas | canvas | A DOM node. | | context | string | The name of the context. | The function ++canvas-get-context++ retrieves the graphical context associated with a //canvas//. Currently only the "2d" context is supported. Hence, the only meaningful calls to this function look like: (canvas-get-context (dom-get-element-by-id "my-canvas") "2d") === ++(canvas-properties ctx)++ === canvas-properties ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Returns a list describing the current global properties assigned to the canvas context. === ++(canvas-properties-set! ctx ...)++ === canvas-properties-set! ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Sets global context properties. Here is a list of supported properties. * ++:fillstyle++: a color used to fill shapes. * ++:global-alpha++: a float value in the range ++[0..1]++ that specifies the transparency of the drawing. * ++:global-composite-operation++: a string. The supported composite operations are: * ++"copy"++ * ++"darker"++ * ++"destination-atop"++ * ++"destination-in"++ * ++"destination-out"++ * ++"destination-over"++ * ++"lighter"++ * ++"source-atop"++ * ++"source-in"++ * ++"source-out"++ * ++"source-over"++ * ++"xor"++ * ++:line-cap++: a string that specifies the end style when drawing lines. * ++"butt"++ * ++"round"++ * ++"square"++ * ++:line-join++: a string that specifies the join style between lines. * ++"round"++ * ++"bevel"++ * ++"miter"++ * ++:line-width++: a integer that specifies the line width (default to ++1++). * ++:miter-limit++: A float value with the new miter limit. * ++:shadow-blur++: Specifies the width that a shadow should cover. * ++:shadow-color++: the color of the shadow. * ++:shadow-offset-x++, ++:shadow-offset-y++: the offset of the shadows. * ++:stroke-style++: the color used to paint lines. * ++:font++: the font (a CSS font specification) used to draw texts. * ++:text-align++: text alignment. * ++:text-baseline++: text baseline. ~~ Example: (apply canvas-properties-set! ctx (canvas-properties txt) :stroke-style "#ff0000" :fill-style "rgba(255, 0, 0, 0.9)" :font "20pt Arial") == State Methods == === ++(canvas-restore ctx)++ === === ++(canvas-save ctx)++ === canvas-restore canvas-save ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Save and restore the current drawing state. The drawing state includes the //rotate//, //scale//, and //translate// attributes. === ++(canvas-rotate ctx angle)++ === canvas-rotate ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | angle | float | The angle of the rotation. | === ++(canvas-scale ctx sx sy)++ === canvas-scale ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | sx | float | The horizontal scale. | | sy | float | The vertical scale. | === ++(canvas-translate ctx sx sy)++ === canvas-translate ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | sx | float | The horizontal translate. | | sy | float | The vertical translate. | === ++(canvas-transform ctx m11 m12 m21 m22 dx dy)++ === === ++(canvas-set-transform ctx m11 m12 m21 m22 dx dy)++ === canvas-transform canvas-set-transform ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | m11 | float | | | m12 | float | | | m21 | float | | | m22 | float | | | dx | float | The horizontal translate. | | dy | float | The vertical translate. | The function ++canvas-transform++ //multiplies// the current transformation matrix with the provided arguments. The function ++canvas-set-transform++ //sets// the transformation matrix. == Paths == === ++(canvas-arc ctx x y r sa ea clockwise)++ === canvas-arc ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x | integer | The horizontal coordinate of the center of the circle. | | y | integer | The vertical coordinate of the center of the circle. | | r | integer | The radius of the circle. | | sa | float | The start angle of the arc. | | ea | float | The end angle of the arc. | | clockwise | bool | The orientation of the arc. | === ++(canvas-arc-to ctx x0 y0 x1 y1 r)++ === canvas-arc-to ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x0 | integer | The horizontal coordinate of start point. | | y0 | integer | The vertical coordinate of start point. | | x1 | integer | The horizontal coordinate of end point. | | y1 | integer | The vertical coordinate of end point. | | radius | integer | The radius of the circle. | === ++(canvas-arrow-to ctx x0 y0 x1 y1 ...)^*++ === canvas-arrow-to ~~ ^*: This procedure does not exist in the traditional //object// API. ~~ ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x0 | integer | The horizontal coordinate of the start point. | | y0 | integer | The vertical coordinate of the start point. | | x1 | integer | The horizontal coordinate of the end point. | | y1 | integer | The vertical coordinate of the end point. | | ... | | | This procedure draws a arrow from the start point to the end point. It accepts the following keyword optional arguments: * ++:angle++: a float. The angle of the arrow head (default to ++0.4++). * ++:length++: an integer. The length of the arrow head (default to 5 times the current line width style). * ++:to++: a bool. If true, draws an arrow head at the end of the line. Defaults to ++#t++. * ++:from++: a bool. If true, draws an arrow head at the start of the line. Defaults to ++#f++. Example: (let ((props (canvas-properties ctx))) (canvas-properties-set! ctx :fill-style "#000000" :stroke-style "#ff0000") (canvas-arrow-to ctx 10 10 20 20 :from #t :to #t) (apply canvas-properties-set! ctx props)) === ++(canvas-begin-path ctx)++ === === ++(canvas-close-path ctx)++ === canvas-begin-path canvas-close-path ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | ~~ The procedure ++canvas-begin-path++ starts a new empty path. The notion of //current point// only exists within a path. ~~ The procedure ++canvas-close-path++ closes the current path. This draws a line to the start point of the path. === ++(canvas-bezier-curve ctx x0 y0 cx cy x y ...)^*++ === canvas-bezier-curve ~~ ^*: This procedure does not exist in the traditional //object// API. ~~ ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Moves the current point to ++x0, y0++ and draws successive bezier curves. === ++(canvas-bezier-curve-to ctx c1x c1y c2x c2y x y)++ === canvas-bezier-curve-to ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | === ++(canvas-quadtratic-arrow-to ctx x0 y0 cpx cpy x1 y1 ...)^*++ === canvas-quadratic-arrow-to ~~ ^*: This procedure does not exist in the traditional //object// API. ~~ ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x0 | integer | The horizontal coordinate of the start point. | | y0 | integer | The vertical coordinate of the start point. | | cpx | integer | The horizontal coordinate of the control point. | | cpy | integer | The vertical coordinate of the control point. | | x1 | integer | The horizontal coordinate of the end point. | | y1 | integer | The vertical coordinate of the end point. | | ... | | | This procedure draws a arrow from the start point to the end point. It accepts the following keyword optional arguments: * ++:angle++: a float. The angle of the arrow head (default to ++0.4++). * ++:length++: an integer. The length of the arrow head (default to 5 times the current line width style). * ++:to++: a bool. If true, draws an arrow head at the end of the line. Defaults to ++#t++. * ++:from++: a bool. If true, draws an arrow head at the start of the line. Defaults to ++#f++. Example: (let ((props (canvas-properties ctx))) (canvas-properties-set! ctx :fill-style "#000000" :stroke-style "#ff0000") (canvas-quadratic-to ctx 10 10 15 15 20 20 :from #t :to #t) (apply canvas-properties-set! ctx props)) === ++(canvas-quadratic-curve ctx x0 y0 cx cy x y ...)^*++ === canvas-quadratic-curve ~~ ^*: This procedure does not exist in the traditional //object// API. ~~ ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Moves the current point to ++x0, y0++ and draws successive quadratic curves. === ++(canvas-quadratic-curve-to ctx cx cy x y)++ === canvas-quadratic-curve-to ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | === ++(canvas-clip ctx)++ === canvas-clip ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Sets the current clipping path. === ++(canvas-line ctx x0 y0 x1 y1 ...)^*++ === canvas-line ~~ ^*: This procedure does not exist in the traditional //object// API. ~~ ^ arguments ^ type ^ description ^ ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x0 | integer | | | y0 | integer | | | x1 | integer | | | y1 | integer | | | ... | ... | ... | Moves the current point and draws lines. (canvas-begin-path ctx) (canvas-line ctx 10 10 20 10 20 20 10 20) (canvas-close-path) === ++(canvas-line-to ctx x y)++ === canvas-line-to ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x | integer | | | y | integer | | Draws a line from the current point to the pointer ++++. Sets the coordinates of the current point. === ++(canvas-move-to ctx x y)++ === canvas-move-to ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x | integer | | | y | integer | | Sets the coordinates of the current point. == Stroke and Fill == === ++(canvas-stroke-rect ctx x y w h)++ === canvas-stroke-rect ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x | integer | The horizontal coordinate of the top-left corner. | | y | integer | The vertical coordinate of the top-left corner. | | w | integer | The width of the rectangle. | | h | integer | The height of the rectangle. | Strokes (i.e., draw the contour of) a rectangle. === ++(canvas-clear-rect ctx x y w h)++ === canvas-clear-rect ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x | integer | The horizontal coordinate of the top-left corner. | | y | integer | The vertical coordinate of the top-left corner. | | w | integer | The width of the rectangle. | | h | integer | The height of the rectangle. | Clears the area defined by a rectangle. === ++(canvas-fill-rect ctx x y w h)++ === canvas-fill-rect ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x | integer | The horizontal coordinate of the top-left corner. | | y | integer | The vertical coordinate of the top-left corner. | | w | integer | The width of the rectangle. | | h | integer | The height of the rectangle. | Fills a rectangle. === ++(canvas-shadow-rect ctx width x y w h)++ === canvas-shadow-rect ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | width | integer | The shadow width. | | x | integer | The horizontal coordinate of the top-left corner. | | y | integer | The vertical coordinate of the top-left corner. | | w | integer | The width of the rectangle. | | h | integer | The height of the rectangle. | Draw a shadow-box on the right and bottom sides of the rectangle. === ++(canvas-fill ctx)++ === canvas-fill ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Fills inside a path. === ++(canvas-stroke ctx)++ === canvas-stroke ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | Strokes along a path. == Gradients and Patterns == === ++(canvas-create-linear-gradient ctx x1 y2 x2 y2)++ === canvas-create-linear-gradient ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x1 | integer | | | y1 | integer | | | x2 | integer | | | y2 | integer | | Creates a linear gradient. === ++(canvas-create-radial-gradient ctx x1 y1 r1 x2 y2 r2)++ === canvas-create-radial-gradient ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | x1 | integer | | | y1 | integer | | | r1 | integer | | | x2 | integer | | | y2 | integer | | | r2 | integer | | Creates a linear gradient. === ++(canvas-add-color-stop gradient position color)++ === canvas-add-color-stop ^ arguments ^ type ^ description ^ | gradient | gradient | A gradient. | | position | float | a float in the range [0..1] | | color | color | | Add a color to a gradient defined by ++canvas-create-line-gradient++ or ++canvas-create-radial-gradient++. === ++(canvas-create-pattern gradient image type)++ === canvas-create-pattern ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | image | image | The image used as a pattern. | | type | string | The pattern type. | The pattern type can be one of: * ++"repeat"++, * ++"repeat-x"++, * ++"repeat-y"++. * ++"no-repeat"++. The pattern created by ++canvas-create-pattern++ can be used to fill a area. That is, the value returned by ++canvas-create-pattern++ can be set to the ++:fill-style++ property. == Images == === ++(canvas-draw-image ctx image x y ...)++ === === ++(canvas-draw-image ctx image x y w h)++ === === ++(canvas-draw-image ctx image sx sy sw sh dx dy dw dh)++ === canvas-draw-image ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | image | image | An image. | | x | integer | | | y | integer | | Draws an image at point ++++. The second form clips the image on the canvas. The third form clips an image and draws it on canvas. === ++(canvas-get-image-data ctx image x y w h)++ === === ++(canvas-put-image-data ctx frame x y)++ === canvas-get-image-data canvas-put-image-data ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | image | image | An image. | | x | integer | | | y | integer | | | w | integer | | | h | integer | | | frame | integer array | An image frame. | * The function ++canvas-get-image-data++ returns the frame composing the image. A frame is a integer array representing the red, green, blue, alpha value of each pixel. For the sake of security function ++canvas-get-image-data++ can only be applied to //same-origin// images. * The function ++canvas-put-image-data++ draw a frame on the canvas. == Text == === ++(canvas-fill-text ctx text x y ...)++ === === ++(canvas-stroke-text ctx text x y ...)++ === canvas-fill-text canvas-stroke-text ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | text | string | A string. | | x | integer | | | y | integer | | Fills (respectively strokes) at point ++++ the specified ++text++ using the text style specified by the font attribute, the alignment specified by the ++text-align++ attribute, and the baseline specified by ++:text-baseline++. The current ++:stroke-style++ is used when stroking the text. (See ++canvas-properties++) Example: (let ((ctx (canvas-get-context can "2d"))) (canvas-fill-text ctx "A left-hand-side text" 0 30) (let* ((t "A right-hand-side text") (w (canvas-measure-text ctx t))) (canvas-fill-text ctx t (- $can.width w 0) 40))) === ++(canvas-measure-text ctx text)++ === canvas-measure-text ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | text | string | A string. | Returns the pixel width of ++text++. === ++(canvas-path-text ctx text)++ === canvas-path-text ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | text | string | A string. | Adds the strokes from the specified text to the current path. This allows you to stroke text instead of filling it if you wish. Example: (canvas-properties-set! ctx :fill-style "green" :stroke-style "black") (canvas-path-text ctx "Sample String") (canvas-fill ctx) (canvas-stroke ctx) === ++(canvas-text-along-path ctx text stroke)++ === canvas-text-along-path ^ arguments ^ type ^ description ^ | ctx | context | A canvas context. | | text | string | A string. | | stroke | boolean | if true test is stroked otherwise added to path. | Adds (or draws) the specified text along the current path. == See also ==