Graphics.Blank

blank-canvas is a Haskell binding to the complete HTML5 Canvas API. blank-canvas allows Haskell users to write, in Haskell, interactive images onto their web browsers. blank-canvas gives the users a single full-window canvas, and provides many well-documented functions for rendering images.

Starting blank-canvas

blankCanvas :: Options -> (DeviceContext -> IO ()) -> IO ()

blankCanvas is the main entry point into blank-canvas. A typical invocation would be

{-# LANGUAGE OverloadedStrings #-}
module Main where

import Graphics.Blank

main = blankCanvas 3000 $ \ context -> do
        send context $ do
                moveTo(50,50)
                lineTo(200,100)
                lineWidth 10
                strokeStyle "red"
                stroke()

data Options

Constructors

Options

Fields

port :: Int

which port do we issue the blank canvas using

events :: [EventName]

which events does the canvas listen to

debug :: Bool

turn on debugging (default False)

root :: String

location of the static files (default .)

middleware :: [Middleware]

extra middleware(s) to be executed. (default [local_only])

Instances

Num Options

sending to the Graphics DeviceContext

data DeviceContext

Context is our abstact handle into a specific 2d-context inside a browser. Note that the JavaScript API concepts of 2D-Context and Canvas are conflated in blank-canvas. Therefore, there is no getContext method, rather getContext is implied (when using send).

Instances

Image DeviceContext

send :: DeviceContext -> Canvas a -> IO a

Sends a set of Canvas commands to the canvas. Attempts to common up as many commands as possible. Should not crash.

HTML5 Canvas API

See http://www.nihilogic.dk/labs/canvas_sheet/HTML5_Canvas_Cheat_Sheet.pdf for the JavaScript version of this API.

data Canvas :: * -> *

Instances

Monad Canvas

Functor Canvas

Applicative Canvas

Monoid a => Monoid (Canvas a)

Canvas element

height :: (Image image, Num a) => image -> a

width :: (Image image, Num a) => image -> a

toDataURL :: () -> Canvas Text

Turn the canvas into a png data stream / data URL.

"data:image/png;base64,iVBORw0KGgo.."

2D Context

save :: () -> Canvas ()

restore :: () -> Canvas ()

Transformation

scale :: (Double, Double) -> Canvas ()

rotate :: Double -> Canvas ()

translate :: (Double, Double) -> Canvas ()

transform :: (Double, Double, Double, Double, Double, Double) -> Canvas ()

setTransform :: (Double, Double, Double, Double, Double, Double) -> Canvas ()

Image drawing

class Image a

Minimal complete definition

jsImage, width, height

Instances

Image CanvasImage

Image CanvasContext

Image DeviceContext

drawImage :: Image image => (image, [Double]) -> Canvas ()

drawImage' takes 2, 4, or 8 Double arguments. See drawImageAt, drawImageSize, and drawImageCrop for variants with exact numbers of arguments.

Compositing

globalAlpha :: Double -> Canvas ()

globalCompositeOperation :: Text -> Canvas ()

Line styles

lineWidth :: Double -> Canvas ()

lineCap :: LineEndCap -> Canvas ()

lineJoin :: LineJoinCorner -> Canvas ()

miterLimit :: Double -> Canvas ()

data LineEndCap

The style of the caps on the endpoints of a line.

Constructors

ButtCap

Flat edges

RoundCap

Semicircular end caps

SquareCap

Square end caps

Instances

Eq LineEndCap

Read LineEndCap

Show LineEndCap

IsString LineEndCap

Default LineEndCap

JSArg LineEndCap

data LineJoinCorner

The style of corner that is created when two lines join.

Constructors

BevelCorner

A filled triangle with a beveled edge connects two lines.

RoundCorner

A filled arc connects two lines.

MiterCorner

A filled triangle with a sharp edge connects two lines.

Instances

Eq LineJoinCorner

Read LineJoinCorner

Show LineJoinCorner

IsString LineJoinCorner

Default LineJoinCorner

JSArg LineJoinCorner

Colors, styles and shadows

strokeStyle :: Text -> Canvas ()

fillStyle :: Text -> Canvas ()

shadowOffsetX :: Double -> Canvas ()

shadowOffsetY :: Double -> Canvas ()

shadowBlur :: Double -> Canvas ()

shadowColor :: Text -> Canvas ()

createLinearGradient :: (Double, Double, Double, Double) -> Canvas CanvasGradient

createRadialGradient :: (Double, Double, Double, Double, Double, Double) -> Canvas CanvasGradient

createPattern :: (CanvasImage, RepeatDirection) -> Canvas CanvasPattern

addColorStop :: (Double, Text) -> CanvasGradient -> Canvas ()

data RepeatDirection

The direction in which a CanvasPattern repeats.

Constructors

Repeat

The pattern repeats both horizontally and vertically.

RepeatX

The pattern repeats only horizontally.

RepeatY

The pattern repeats only vertically.

NoRepeat

The pattern displays only once and does not repeat.

Instances

Eq RepeatDirection

Read RepeatDirection

Show RepeatDirection

IsString RepeatDirection

Default RepeatDirection

JSArg RepeatDirection

data CanvasGradient

A handle to the CanvasGradient. CanvasGradients can not be destroyed.

Instances

Eq CanvasGradient

Ord CanvasGradient

Show CanvasGradient

JSArg CanvasGradient

Style CanvasGradient

data CanvasPattern

A handle to the CanvasPattern. CanvasPatterns can not be destroyed.

Instances

Eq CanvasPattern

Ord CanvasPattern

Show CanvasPattern

JSArg CanvasPattern

Style CanvasPattern

Paths

beginPath :: () -> Canvas ()

closePath :: () -> Canvas ()

fill :: () -> Canvas ()

stroke :: () -> Canvas ()

clip :: () -> Canvas ()

moveTo :: (Double, Double) -> Canvas ()

lineTo :: (Double, Double) -> Canvas ()

quadraticCurveTo :: (Double, Double, Double, Double) -> Canvas ()

bezierCurveTo :: (Double, Double, Double, Double, Double, Double) -> Canvas ()

arcTo :: (Double, Double, Double, Double, Double) -> Canvas ()

arc :: (Double, Double, Double, Double, Double, Bool) -> Canvas ()

rect :: (Double, Double, Double, Double) -> Canvas ()

isPointInPath :: (Double, Double) -> Canvas Bool

Text

font :: Text -> Canvas ()

textAlign :: TextAnchorAlignment -> Canvas ()

textBaseline :: TextBaselineAlignment -> Canvas ()

fillText :: (Text, Double, Double) -> Canvas ()

strokeText :: (Text, Double, Double) -> Canvas ()

measureText :: Text -> Canvas TextMetrics

data TextAnchorAlignment

The anchor point for text in the current DeviceContext.

Constructors

StartAnchor

The text is anchored at either its left edge (if the canvas is left-to-right) or its right edge (if the canvas is right-to-left).

EndAnchor

The text is anchored at either its right edge (if the canvas is left-to-right) or its left edge (if the canvas is right-to-left).

CenterAnchor

The text is anchored in its center.

LeftAnchor

The text is anchored at its left edge.

RightAnchor

the text is anchored at its right edge.

Instances

Eq TextAnchorAlignment

Read TextAnchorAlignment

Show TextAnchorAlignment

IsString TextAnchorAlignment

Default TextAnchorAlignment

JSArg TextAnchorAlignment

data TextBaselineAlignment

The baseline alignment used when drawing text in the current DeviceContext. The baselines are ordered from highest (Top) to lowest (Bottom).

Constructors

TopBaseline

HangingBaseline

MiddleBaseline

AlphabeticBaseline

IdeographicBaseline

BottomBaseline

Instances

Bounded TextBaselineAlignment

Eq TextBaselineAlignment

Ord TextBaselineAlignment

Read TextBaselineAlignment

Show TextBaselineAlignment

Ix TextBaselineAlignment

IsString TextBaselineAlignment

Default TextBaselineAlignment

JSArg TextBaselineAlignment

data TextMetrics

The width argument of TextMetrics can trivially be projected out.

Constructors

TextMetrics Double

Instances

Show TextMetrics

Rectangles

clearRect :: (Double, Double, Double, Double) -> Canvas ()

fillRect :: (Double, Double, Double, Double) -> Canvas ()

strokeRect :: (Double, Double, Double, Double) -> Canvas ()

Pixel manipulation

getImageData :: (Double, Double, Double, Double) -> Canvas ImageData

Capture ImageDate from the Canvas.

putImageData :: (ImageData, [Double]) -> Canvas ()

putImageData takes 2 or 6 Double arguments. See putImageDataAt and putImageDataDirty for variants with exact numbers of arguments.

data ImageData

ImageData is a transliteration of the JavaScript ImageData, There are two Ints, and one (unboxed) Vector of Word8s. width, height, data can be projected from ImageData, length can be used to find the length.

Note: ImageData lives on the server, not the client.

Constructors

ImageData !Int !Int !(Vector Word8)

Instances

Eq ImageData

Ord ImageData

Show ImageData

JSArg ImageData

blank-canvas Extensions

Reading from Canvas

newImage :: Text -> Canvas CanvasImage

image takes a URL (perhaps a data URL), and returns the CanvasImage handle, _after_ loading. The assumption is you are using local images, so loading should be near instant.

data CanvasImage

A handle to the Image. CanvasImages can not be destroyed.

Instances

Eq CanvasImage

Ord CanvasImage

Show CanvasImage

JSArg CanvasImage

Image CanvasImage

DeviceContext attributes

devicePixelRatio :: DeviceContext -> Double

CanvasContext, and off-screen Canvas.

data CanvasContext

A handle to an offscreen canvas. CanvasContext can not be destroyed.

Instances

Eq CanvasContext

Ord CanvasContext

Show CanvasContext

JSArg CanvasContext

Image CanvasContext

newCanvas :: (Int, Int) -> Canvas CanvasContext

Create a new, off-screen canvas buffer. Takes width and height.

with :: CanvasContext -> Canvas a -> Canvas a

with runs a set of canvas commands in the context of a specific canvas buffer.

myCanvasContext :: Canvas CanvasContext

myCanvasContext returns the current CanvasContent.

deviceCanvasContext :: DeviceContext -> CanvasContext

Syncing

sync :: Canvas ()

Send all commands to the browser, wait for the browser to ack, then continue.

Debugging

console_log :: JSArg msg => msg -> Canvas ()

console_log aids debugging by sending the argument to the browser console.log.

eval :: Text -> Canvas ()

eval executes the argument in JavaScript directly.

class JSArg a where

Methods

showJS :: a -> String

Instances

JSArg Bool

JSArg Double

JSArg Int

JSArg Text

JSArg ImageData

JSArg TextBaselineAlignment

JSArg TextAnchorAlignment

JSArg LineJoinCorner

JSArg LineEndCap

JSArg RepeatDirection

JSArg CanvasPattern

JSArg CanvasGradient

JSArg CanvasImage

JSArg CanvasContext

JSArg (Colour Double)

JSArg (AlphaColour Double)

Drawing Utilities

clearCanvas :: Canvas ()

Clear the screen. Restores the default transformation matrix.

saveRestore :: Canvas a -> Canvas a

Wrap a canvas computation in save / restore.

(#) :: a -> (a -> Canvas b) -> Canvas b infixr 0

The #-operator is the Haskell analog to the .-operator in Javascript. Example:

grd # addColorStop(0, "#8ED6FF");

This can be seen as equivalent of grd.addColorStop(0, "#8ED6FF").

readDataURL :: Text -> FilePath -> IO Text

Read a file, and generate a data URL.

 url <- readDataURL "image/png" "image/foo.png"

dataURLMimeType :: Text -> Text

Find the mime type for a data URL.

> dataURLMimeType "data:image/png;base64,iVBORw..."
"image/png"

writeDataURL :: FilePath -> Text -> IO ()

Write a data URL to a given file.

drawImageAt :: Image image => (image, Double, Double) -> Canvas ()

Draws an image onto the canvas at the given x- and y-coordinates.

drawImageSize :: Image image => (image, Double, Double, Double, Double) -> Canvas ()

Acts like drawImageAt, but with two extra Double arguments. The third and fourth Doubles specify the width and height of the image, respectively.

drawImageCrop :: Image image => (image, Double, Double, Double, Double, Double, Double, Double, Double) -> Canvas ()

Acts like drawImageSize, but with four extra Double arguments before the arguments of drawImageSize. The first and second Doubles specify the x- and y-coordinates at which the image begins to crop. The third and fourth Doubles specify the width and height of the cropped image.

drawImageCrop img 0 0 dw dh dx dy dw dh = drawImageSize = dx dy dw dh

putImageDataAt :: (ImageData, Double, Double) -> Canvas ()

Writes ImageData to the canvas at the given x- and y-coordinates.

putImageDataDirty :: (ImageData, Double, Double, Double, Double, Double, Double) -> Canvas ()

Acts like putImageDataDirty, but with four extra Double arguments that specify which region of the ImageData (the dirty rectangle) should be drawn. The third and fourth Doubles specify the dirty rectangle's x- and y- coordinates, and the fifth and sixth Doubles specify the dirty rectangle's width and height.

putImageDataDirty imgData dx dy 0 0 w h = putImageDataAt imgData dx dy
  where (w, h) = case imgData of ImageData w' h' _ -> (w', h')

Events

trigger :: Event -> Canvas ()

trigger a specific named event, please.

eventQueue :: DeviceContext -> EventQueue

A single (typed) event queue

wait :: DeviceContext -> IO Event

wait for any event. blocks.

flush :: DeviceContext -> IO [Event]

flush all the current events, returning them all to the user. Never blocks.

data Event

Basic Event from Browser; see http://api.jquery.com/category/events/ for details.

Constructors

Event

Fields

eMetaKey :: Bool

ePageXY :: Maybe (Double, Double)

eType :: EventName

eWhich :: Maybe Int

Instances

Show Event

ToJSON Event

FromJSON Event

type EventName = Text

EventName mirrors event names from jquery, and use lower case. Possible named events

• keypress, keydown, keyup
• mouseDown, mouseenter, mousemove, mouseout, mouseover, mouseup

type EventQueue = TChan Event

EventQueue is a STM channel (TChan) of Events. Intentionally, EventQueue is not abstract.

Middleware

local_only :: Middleware