The LiterallyCanvas object

Once initialized, Literally Canvas is controlled and accessed through a LiterallyCanvas() object. See Initializing & Options for information about getting a reference to this object.

class LiterallyCanvas(containerElement, options)
Arguments

  • containerElement – DOM element to put Literally Canvas inside.

  • options – Dictionary of options. See Initializing & Options for possible values.

Note

As of v0.4, the LiterallyCanvas() object no longer uses a single canvas to render. Instead, it keeps multiple canvases inside a container element.

opts

A copy of the options passed to LC.init() with the defaults filled in. For example, if you were to implement your own tool that used a stroke width, you’d want to set your initial value to lc.opts.defaultStrokeWidth.

Saving and loading

getSnapshot(keys=['shapes', 'imageSize', 'colors', 'position', 'scale', 'backgroundShapes'])
Arguments

  • keys – Whitelist of state to save

Returns

a snapshot object

New in version 0.4.9.

Returns the state of the drawing as a JSON-encodable object. This currently includes the shapes, background shapes, colors, image size, pan position, and scale. If you don’t want to restore all of those things, you may pass keys to specify exactly what you want.

To get a snapshot that matches version 0.4.8’s format, which is a strict subset of 0.4.9+’s, you can do this:

lc.getSnapshot(['shapes', 'colors'])

The snapshot format is stable across versions.

loadSnapshot(snapshot)
Arguments

  • snapshot – a snapshot object

New in version 0.4.9.

Replace the current state with whatever is in snapshot.

getSnapshotJSON()
Returns

a JSON-encoded string

Deprecated since version 0.4.9: Use JSON.stringify(lc.getSnapshot()) instead.

Alias for JSON.stringify(lc.getSnapshot()).

This will continue to work until version 0.6.

loadSnapshotJSON(snapshotJSON)
Arguments

  • snapshotJSON – a JSON-encoded string

Deprecated since version 0.4.9: Use lc.loadSnapshot(JSON.parse(snapshotJSON)) instead.

Alias for lc.loadSnapshot(JSON.parse(snapshotJSON)).

This will continue to work until version 0.6.

Exporting images

getImage(options)

Returns the complete drawing rendered to a canvas, regardless of what the view is panned/zoomed to. This method has the same options as LC.renderSnapshotToImage(), as well as:

includeWatermark

If true, render the watermark behind the drawing.

scaleDownRetina

If true, compensate for window.devicePixelRatio by adjusting the scale before rendering. This is probably what you want, since the image will be the same size as what the user sees on their screen, due to being scaled back up by the web browser. Defaults to true.

getSVGString({options})

Returns the drawing as an SVG string that can be inserted into the DOM or downloaded.

This method has the same options as LC.renderSnapshotToSVG().

canvasForExport()

Deprecated since version 0.4: Use getImage() instead.

Returns a canvas object with the current view.

canvasWithBackground(canvasOrImage)

Deprecated since version 0.4: Use getImage() instead.

Returns a canvas object with the current view composited over a background image.

Event subscription

var unsubscribe = lc.on('drawingChange', function() {
  localStorage.setItem('drawing', lc.getSnapshotJSON());
});
unsubscribe();  // stop listening
on(event, callback)
Returns

a function that unsubscribes from the event

Attach an event handler to event. A common use case is to save the drawing when it is changed; see Saving to Local Storage.

See Events for a list of events.

Controlling the view

setPan(x, y)

Move the view’s upper left corner to the given position in drawing space.

setZoom(zoom)

Set the view zoom to the given value.

pan(x, y)

Move the view by the given amount relative to its current position in drawing space.

zoom(amount)

Add the given amount to the zoom level.

setImageSize(width, height)

Change the size of the image away from what was passed to LC.init() as imageSize.

Changing the drawing

saveShape(shape, triggerSaveShapeEvent, previousShapeId)
Arguments

  • shape – Shape to be added

  • triggerSaveShapeEvent – If true, trigger the shapeSave event. Defaults to true. You may want to set this to false if you’re sending and receiving shapes to/from a remote drawing.

  • previousShapeId – ID of the shape just below the new one. Defaults to the most recently added shape.

Add a shape to the drawing. If you’re writing a single-user application, you should only need to pass the first argument. See Shapes for more information.

setColor(colorName, colorValue)
Arguments

  • colorName – 'background', 'primary', or 'secondary'

  • colorValue – Any CSS color

clear()

Remove all shapes from the drawing.

undo()

Undo the last drawing action.

redo()

Redo the last thing to be undone.

setShapesInProgress(shapes)

Declare a list of shapes that are drawn to the canvas but aren’t yet part of the drawing. Tools should use this to show shapes in progress.

drawShapeInProgress(shape)

Draws the given shape to a buffer without clearing or redrawing anything beneath it. If the shape’s renderer supports it, only render the most recently changed part of the shape.

This is most useful as an efficient way to draw line paths that the user is currently drawing.

setWatermarkImage(image)

Set or replace the watermark image behind the drawing. See the watermarkImage option.

Getting information

getColor(colorName)

Get the value of the 'primary', 'secondary', or 'background' color.

getPixel(x, y)

Get the color of the given drawing-space pixel as a CSS color string.

getDefaultImageRect(explicitSize={width: 0, height: 0}, margin={top: 0, right: 0, bottom: 0, left: 0})

Returns the effective bounds of the canvas. Mostly used as a convenient way to limit the scope of a potentially infinite tool. (For example, a paint bucket shouldn’t fill infinite pixels.)

Teardown

teardown()

Completely remove this instance of Literally Canvas from the web page.