SvgCanvas

The main SvgCanvas class that manages all SVG-related functions

Parameters

container	The container HTML element that should hold the SVG root element
config	An object that contains configuration data

Summary

SvgCanvas	The main SvgCanvas class that manages all SVG-related functions
toXml	Converts characters in a string to XML-friendly entities.
fromXml	Converts XML entities in a string to single characters.
Unit conversion functions
convertToNum	Converts given values to numbers.
setUnitAttr	Sets an element’s attribute based on the unit in its current value.
isValidUnit	Check if an attribute’s value is in a valid format
Undo/Redo history management
ChangeElementCommand	History command to make a change to an element.
ChangeElementCommand.apply	Performs the stored change action
ChangeElementCommand.unapply	Reverses the stored change action
ChangeElementCommand.elements	Returns array with element associated with this command
InsertElementCommand	History command for an element that was added to the DOM
InsertElementCommand.apply	Re-Inserts the new element
InsertElementCommand.unapply	Removes the element
InsertElementCommand.elements	Returns array with element associated with this command
RemoveElementCommand	History command for an element removed from the DOM
RemoveElementCommand.apply	Re-removes the new element
RemoveElementCommand.unapply	Re-adds the new element
RemoveElementCommand.elements	Returns array with element associated with this command
MoveElementCommand	History command for an element that had its DOM position changed
MoveElementCommand.unapply	Re-positions the element
MoveElementCommand.unapply	Positions the element back to its original location
MoveElementCommand.elements	Returns array with element associated with this command
BatchCommand	History command that can contain/execute multiple other commands
BatchCommand.apply	Runs “apply” on all subcommands
BatchCommand.unapply	Runs “unapply” on all subcommands
BatchCommand.elements	Iterate through all our subcommands and returns all the elements we are changing
BatchCommand.addSubCommand	Adds a given command to the history stack
BatchCommand.isEmpty	Returns a boolean indicating whether or not the batch command is empty
resetUndoStack	Resets the undo stack, effectively clearing the undo/redo history
undoMgr.getUndoStackSize	Integer with the current size of the undo history stack
undoMgr.getRedoStackSize	Integer with the current size of the redo history stack
undoMgr.getNextUndoCommandText	String associated with the next undo command
undoMgr.getNextRedoCommandText	String associated with the next redo command
undoMgr.undo	Performs an undo step
undoMgr.redo	Performs a redo step
addCommandToHistory	Adds a command object to the undo history stack
beginUndoableChange	This function tells the canvas to remember the old values of the attrName attribute for each element sent in.
finishUndoableChange	This function returns a BatchCommand object which summarizes the change since beginUndoableChange was called.
Selector	Private class for DOM element selection boxes
Functions
Selector.reset	Used to reset the id and element that the selector is attached to
Selector.showGrips	Show the resize grips of this selector
Selector.updateGripCursors	Updates cursors for corner grips on rotation so arrows point the right way
Selector.resize	Updates the selector to match the element’s size
SelectorManager	Public class to manage all selector objects (selection boxes)
SelectorManager.initGroup	Resets the parent selector group element
SelectorManager.requestSelector	Returns the selector based on the given element
SelectorManager.releaseSelector	Removes the selector of the given element (hides selection box)
SelectorManager.getRubberBandBox	Returns the rubberBandBox DOM element.
Helper functions
assignAttributes	Assigns multiple attributes to an element.
cleanupElement	Remove unneeded (default) attributes, makes resulting SVG smaller
addSvgElementFromJson	Create a new SVG element based on the given object keys/values and add it to the current layer The element will be ran through cleanupElement before being returned
getId	Returns the last created DOM element ID string
getNextId	Creates and returns a unique ID string for a DOM element
bind	Attaches a callback function to an event
setIdPrefix	Changes the ID prefix to the given value
sanitizeSvg	Sanitizes the input node and its children It only keeps what is allowed from our whitelist defined above
getUrlFromAttr	i.e.
Selection
clearSelection	Clears the selection.
addToSelection	Adds a list of elements to the selection.
removeFromSelection	Removes elements from the selection.
Serialization
removeUnusedDefElems	Looks at DOM elements inside the <defs> to see if they are referred to, removes them from the DOM if they are not.
svgCanvasToString	Main function to set up the SVG content for output
svgToString	Sub function ran on each SVG element to convert it to a string as desired
embedImage	Converts a given image file to a data URL when possible, then runs a given callback
save	Serializes the current drawing into SVG XML text and returns it to the ‘saved’ handler.
getSvgString	Returns the current drawing as raw SVG XML text.
setSvgString	This function sets the current drawing as the input SVG XML.
importSvgString	This function imports the input SVG XML into the current layer in the drawing
Layers
createLayer	Creates a new top-level layer in the drawing with the given name, sets the current layer to it, and then clears the selection This function then calls the ‘changed’ handler.
deleteCurrentLayer	Deletes the current layer from the drawing and then clears the selection.
getNumLayers	Returns the number of layers in the current drawing.
getLayer	Returns the name of the ith layer.
getCurrentLayer	Returns the name of the currently selected layer.
setCurrentLayer	Sets the current layer.
renameCurrentLayer	Renames the current layer.
setCurrentLayerPosition	Changes the position of the current layer to the new value.
getLayerVisibility	Returns whether the layer is visible.
setLayerVisibility	Sets the visibility of the layer.
moveSelectedToLayer	Moves the selected elements to layername.
getLayerOpacity	Returns the opacity of the given layer.
setLayerOpacity	Sets the opacity of the given layer.
selectAllInCurrentLayer	Clears the selection, then adds all elements in the current layer to the selection.
clear	Clears the current document.
Fill and Stroke
getVersion	Returns a string which describes the revision number of SvgCanvas.

toXml

toXml = function( str )

Converts characters in a string to XML-friendly entities.

Example: “&” becomes “&”

Parameters

str	The string to be converted

Returns

The converted string

fromXml

fromXml = function( str )

Converts XML entities in a string to single characters. Example: “&” becomes “&”

Parameters

str	The string to be converted

Returns

The converted string

Unit conversion functions

convertToNum

convertToNum = function( attr,
val )

Converts given values to numbers. Attributes must be supplied in case a percentage is given

Parameters

attr	String with the name of the attribute associated with the value
val	String with the attribute value to convert

setUnitAttr

setUnitAttr = function( elem,
attr,
val )

Sets an element’s attribute based on the unit in its current value.

Parameters

elem	DOM element to be changed
attr	String with the name of the attribute associated with the value
val	String with the attribute value to convert

isValidUnit

canvas.isValidUnit = function( attr,
val )

Check if an attribute’s value is in a valid format

Parameters

attr	String with the name of the attribute associated with the value
val	String with the attribute value to check

Undo/Redo history management

ChangeElementCommand

var ChangeElementCommand = this.undoCmd.changeElement = function( elem,
attrs,
text )

History command to make a change to an element. Usually an attribute change, but can also be textcontent.

Parameters

elem	The DOM element that was changed
attrs	An object with the attributes to be changed and the values they had before the change
text	An optional string visible to user related to this change

ChangeElementCommand.apply

Performs the stored change action

ChangeElementCommand.unapply

Reverses the stored change action

ChangeElementCommand.elements

Returns array with element associated with this command

InsertElementCommand

var InsertElementCommand = this.undoCmd.insertElement = function( elem,
text )

History command for an element that was added to the DOM

Parameters

elem	The newly added DOM element
text	An optional string visible to user related to this change

InsertElementCommand.apply

Re-Inserts the new element

InsertElementCommand.unapply

Removes the element

InsertElementCommand.elements

Returns array with element associated with this command

RemoveElementCommand

var RemoveElementCommand = this.undoCmd.removeElement = function( elem,
parent,
text )

History command for an element removed from the DOM

Parameters

elem	The removed DOM element
parent	The DOM element’s parent
text	An optional string visible to user related to this change

RemoveElementCommand.apply

Re-removes the new element

RemoveElementCommand.unapply

Re-adds the new element

RemoveElementCommand.elements

Returns array with element associated with this command

MoveElementCommand

var MoveElementCommand = this.undoCmd.moveElement = function( elem,
oldNextSibling,
oldParent,
text )

History command for an element that had its DOM position changed

Parameters

elem	The DOM element that was moved
oldNextSibling	The element’s next sibling before it was moved
oldParent	The element’s parent before it was moved
text	An optional string visible to user related to this change

MoveElementCommand.unapply

Re-positions the element

MoveElementCommand.unapply

Positions the element back to its original location

MoveElementCommand.elements

Returns array with element associated with this command

BatchCommand

var BatchCommand = this.undoCmd.batch = function( text )

History command that can contain/execute multiple other commands

Parameters

text	An optional string visible to user related to this change

BatchCommand.apply

Runs “apply” on all subcommands

BatchCommand.unapply

Runs “unapply” on all subcommands

BatchCommand.elements

Iterate through all our subcommands and returns all the elements we are changing

BatchCommand.addSubCommand

Adds a given command to the history stack

Parameters

cmd	The undo command object to add

BatchCommand.isEmpty

Returns a boolean indicating whether or not the batch command is empty

resetUndoStack

resetUndoStack = function()

Resets the undo stack, effectively clearing the undo/redo history

undoMgr.getUndoStackSize

Returns

Integer with the current size of the undo history stack

undoMgr.getRedoStackSize

Returns

Integer with the current size of the redo history stack

undoMgr.getNextUndoCommandText

Returns

String associated with the next undo command

undoMgr.getNextRedoCommandText

Returns

String associated with the next redo command

undoMgr.undo

Performs an undo step

undoMgr.redo

Performs a redo step

addCommandToHistory

addCommandToHistory = c.undoCmd.add = function( cmd )

Adds a command object to the undo history stack

Parameters

cmd	The command object to add

beginUndoableChange

c.beginUndoableChange = function( attrName,
elems )

This function tells the canvas to remember the old values of the attrName attribute for each element sent in. The elements and values are stored on a stack, so the next call to finishUndoableChange() will pop the elements and old values off the stack, gets the current values from the DOM and uses all of these to construct the undo-able command.

Parameters

attrName	The name of the attribute being changed
elems	Array of DOM elements being changed

finishUndoableChange

c.finishUndoableChange = function()

This function returns a BatchCommand object which summarizes the change since beginUndoableChange was called. The command can then be added to the command history

Returns

Batch command object with resulting changes

Selector

Private class for DOM element selection boxes

Parameters

id	integer to internally indentify the selector
elem	DOM element associated with this selector

Summary

Functions
Selector.reset	Used to reset the id and element that the selector is attached to
Selector.showGrips	Show the resize grips of this selector
Selector.updateGripCursors	Updates cursors for corner grips on rotation so arrows point the right way
Selector.resize	Updates the selector to match the element’s size

Functions

Selector.reset

Used to reset the id and element that the selector is attached to

Parameters

e	DOM element associated with this selector

Selector.showGrips

Show the resize grips of this selector

Parameters

show	boolean indicating whether grips should be shown or not

Selector.updateGripCursors

Updates cursors for corner grips on rotation so arrows point the right way

Parameters

angle

Float indicating current rotation angle in degrees

Selector.resize

Updates the selector to match the element’s size

SelectorManager

Public class to manage all selector objects (selection boxes)

Summary

SelectorManager.initGroup	Resets the parent selector group element
SelectorManager.requestSelector	Returns the selector based on the given element
SelectorManager.releaseSelector	Removes the selector of the given element (hides selection box)
SelectorManager.getRubberBandBox	Returns the rubberBandBox DOM element.
Helper functions
assignAttributes	Assigns multiple attributes to an element.
cleanupElement	Remove unneeded (default) attributes, makes resulting SVG smaller
addSvgElementFromJson	Create a new SVG element based on the given object keys/values and add it to the current layer The element will be ran through cleanupElement before being returned
getId	Returns the last created DOM element ID string
getNextId	Creates and returns a unique ID string for a DOM element
bind	Attaches a callback function to an event
setIdPrefix	Changes the ID prefix to the given value
sanitizeSvg	Sanitizes the input node and its children It only keeps what is allowed from our whitelist defined above
getUrlFromAttr	i.e.
Selection
clearSelection	Clears the selection.
addToSelection	Adds a list of elements to the selection.
removeFromSelection	Removes elements from the selection.
Serialization
removeUnusedDefElems	Looks at DOM elements inside the <defs> to see if they are referred to, removes them from the DOM if they are not.
svgCanvasToString	Main function to set up the SVG content for output
svgToString	Sub function ran on each SVG element to convert it to a string as desired
embedImage	Converts a given image file to a data URL when possible, then runs a given callback
save	Serializes the current drawing into SVG XML text and returns it to the ‘saved’ handler.
getSvgString	Returns the current drawing as raw SVG XML text.
setSvgString	This function sets the current drawing as the input SVG XML.
importSvgString	This function imports the input SVG XML into the current layer in the drawing
Layers
createLayer	Creates a new top-level layer in the drawing with the given name, sets the current layer to it, and then clears the selection This function then calls the ‘changed’ handler.
deleteCurrentLayer	Deletes the current layer from the drawing and then clears the selection.
getNumLayers	Returns the number of layers in the current drawing.
getLayer	Returns the name of the ith layer.
getCurrentLayer	Returns the name of the currently selected layer.
setCurrentLayer	Sets the current layer.
renameCurrentLayer	Renames the current layer.
setCurrentLayerPosition	Changes the position of the current layer to the new value.
getLayerVisibility	Returns whether the layer is visible.
setLayerVisibility	Sets the visibility of the layer.
moveSelectedToLayer	Moves the selected elements to layername.
getLayerOpacity	Returns the opacity of the given layer.
setLayerOpacity	Sets the opacity of the given layer.
selectAllInCurrentLayer	Clears the selection, then adds all elements in the current layer to the selection.
clear	Clears the current document.
Fill and Stroke
getVersion	Returns a string which describes the revision number of SvgCanvas.

SelectorManager.initGroup

Resets the parent selector group element

SelectorManager.requestSelector

Returns the selector based on the given element

Parameters

elem	DOM element to get the selector for

SelectorManager.releaseSelector

Removes the selector of the given element (hides selection box)

Parameters

elem	DOM element to remove the selector for

SelectorManager.getRubberBandBox

Returns the rubberBandBox DOM element. This is the rectangle drawn by the user for selecting/zooming

Helper functions

assignAttributes

var assignAttributes = this.assignAttributes = function( node,
attrs,
suspendLength,
unitCheck )

Assigns multiple attributes to an element.

Parameters

node	DOM element to apply new attribute values to
attrs	Object with attribute keys/values
suspendLength	Optional integer of milliseconds to suspend redraw
unitCheck	Boolean to indicate the need to use setUnitAttr

cleanupElement

var cleanupElement = this.cleanupElement = function( element )

Remove unneeded (default) attributes, makes resulting SVG smaller

Parameters

element

DOM element to clean up

addSvgElementFromJson

var addSvgElementFromJson = this.addSvgElementFromJson = function( data )

Create a new SVG element based on the given object keys/values and add it to the current layer The element will be ran through cleanupElement before being returned

Parameters

data	Object with the following keys/values:

element - DOM element to create
attr - Object with attributes/values to assign to the new element
curStyles - Boolean indicating that current style attributes should be applied first

Returns: The new element

getId

getId = c.getId = function()

Returns the last created DOM element ID string

getNextId

getNextId = c.getNextId = function()

Creates and returns a unique ID string for a DOM element

bind

c.bind = function( event,
f )

Attaches a callback function to an event

Parameters

event	String indicating the name of the event
f	The callback function to bind to the event

Return

The previous event

setIdPrefix

c.setIdPrefix = function( p )

Changes the ID prefix to the given value

Parameters

p	String with the new prefix

sanitizeSvg

var sanitizeSvg = this.sanitizeSvg = function( node )

Sanitizes the input node and its children It only keeps what is allowed from our whitelist defined above

Parameters

node	The DOM element to be checked, will also check its children

getUrlFromAttr

var getUrlFromAttr = this.getUrlFromAttr = function( attrVal )

Extracts the URL from the url(...) syntax of some attributes. Three variants

i.e. <circle fill=”url(someFile.svg#foo)” /> or <circle fill=”url(‘someFile.svg#foo’)” /> or <circle fill=’url(“someFile.svg#foo”)’ />

Parameters

attrVal

The attribute value as a string

Returns

String with just the URL

Selection

clearSelection

this.clearSelection = function( noCall )

Clears the selection. The ‘selected’ handler is then called.

addToSelection

this.addToSelection = function( elemsToAdd,
showGrips )

Adds a list of elements to the selection. The ‘selected’ handler is then called.

Parameters

elemsToAdd	an array of DOM elements to add to the selection
showGrips	a boolean flag indicating whether the resize grips should be shown

removeFromSelection

this.removeFromSelection = function( elemsToRemove )

Removes elements from the selection.

Parameters

elemsToRemove

an array of elements to remove from selection

Serialization

removeUnusedDefElems

var removeUnusedDefElems = this.removeUnusedDefElems = function()

Looks at DOM elements inside the <defs> to see if they are referred to, removes them from the DOM if they are not.

Returns

The amount of elements that were removed

svgCanvasToString

var svgCanvasToString = this.svgCanvasToString = function()

Main function to set up the SVG content for output

Returns

String containing the SVG image for output

svgToString

var svgToString = this.svgToString = function( elem,
indent )

Sub function ran on each SVG element to convert it to a string as desired

Parameters

elem	The SVG element to convert
indent	Integer with the amount of spaces to indent this tag

Returns

String with the given element as an SVG tag

embedImage

this.embedImage = function( val,
callback )

Converts a given image file to a data URL when possible, then runs a given callback

Parameters

val	String with the path/URL of the image
callback	Optional function to run when image data is found, supplies the result (data URL or false) as first parameter.

save

this.save = function( opts )

Serializes the current drawing into SVG XML text and returns it to the ‘saved’ handler. This function also includes the XML prolog. Clients of the SvgCanvas bind their save function to the ‘saved’ event.

Returns

Nothing

getSvgString

this.getSvgString = function()

Returns the current drawing as raw SVG XML text.

Returns

The current drawing as raw SVG XML text.

setSvgString

this.setSvgString = function( xmlString )

This function sets the current drawing as the input SVG XML.

Parameters

xmlString

The SVG as XML text.

Returns

This function returns false if the set was unsuccessful, true otherwise.

importSvgString

This function imports the input SVG XML into the current layer in the drawing

Parameters

xmlString

The SVG as XML text.

Returns

This function returns false if the import was unsuccessful, true otherwise.

Layers

createLayer

this.createLayer = function( name )

Creates a new top-level layer in the drawing with the given name, sets the current layer to it, and then clears the selection This function then calls the ‘changed’ handler. This is an undoable action.

Parameters

name	The given name

deleteCurrentLayer

this.deleteCurrentLayer = function()

Deletes the current layer from the drawing and then clears the selection. This function then calls the ‘changed’ handler. This is an undoable action.

getNumLayers

this.getNumLayers = function()

Returns the number of layers in the current drawing.

Returns

The number of layers in the current drawing.

getLayer

this.getLayer = function( i )

Returns the name of the ith layer. If the index is out of range, an empty string is returned.

Parameters

i	the zero-based index of the layer you are querying.

Returns

The name of the ith layer

getCurrentLayer

this.getCurrentLayer = function()

Returns the name of the currently selected layer. If an error occurs, an empty string is returned.

Returns

The name of the currently active layer.

setCurrentLayer

this.setCurrentLayer = function( name )

Sets the current layer. If the name is not a valid layer name, then this function returns false. Otherwise it returns true. This is not an undo-able action.

Parameters

name	the name of the layer you want to switch to.

Returns

true if the current layer was switched, otherwise false

renameCurrentLayer

this.renameCurrentLayer = function( newname )

Renames the current layer. If the layer name is not valid (i.e. unique), then this function does nothing and returns false, otherwise it returns true. This is an undo-able action.

Parameters

newname

the new name you want to give the current layer. This name must be unique among all layer names.

Returns

true if the rename succeeded, false otherwise.

setCurrentLayerPosition

this.setCurrentLayerPosition = function( newpos )

Changes the position of the current layer to the new value. If the new index is not valid, this function does nothing and returns false, otherwise it returns true. This is an undo-able action.

Parameters

newpos	The zero-based index of the new position of the layer. This should be between
0 and (number of layers	1)

Returns

true if the current layer position was changed, false otherwise.

getLayerVisibility

this.getLayerVisibility = function( layername )

Returns whether the layer is visible. If the layer name is not valid, then this function returns false.

Parameters

layername

the name of the layer which you want to query.

Returns

The visibility state of the layer, or false if the layer name was invalid.

setLayerVisibility

this.setLayerVisibility = function( layername,
bVisible )

Sets the visibility of the layer. If the layer name is not valid, this function return false, otherwise it returns true. This is an undo-able action.

Parameters

layername	the name of the layer to change the visibility
bVisible	true/false, whether the layer should be visible

Returns

true if the layer’s visibility was set, false otherwise

moveSelectedToLayer

this.moveSelectedToLayer = function( layername )

Moves the selected elements to layername. If the name is not a valid layer name, then false is returned. Otherwise it returns true. This is an undo-able action.

Parameters

layername

the name of the layer you want to which you want to move the selected elements

Returns

true if the selected elements were moved to the layer, false otherwise.

getLayerOpacity

this.getLayerOpacity = function( layername )

Returns the opacity of the given layer. If the input name is not a layer, null is returned.

Parameters

layername

name of the layer on which to get the opacity

Returns

The opacity value of the given layer. This will be a value between 0.0 and 1.0, or null if layername is not a valid layer

setLayerOpacity

this.setLayerOpacity = function( layername,
opacity )

Sets the opacity of the given layer. If the input name is not a layer, nothing happens. This is not an undo-able action. NOTE: this function exists solely to apply a highlighting/de-emphasis effect to a layer, when it is possible for a user to affect the opacity of a layer, we will need to allow this function to produce an undo-able action. If opacity is not a value between 0.0 and 1.0, then nothing happens.

Parameters

layername	name of the layer on which to set the opacity
opacity	a float value in the range 0.0-1.0

selectAllInCurrentLayer

this.selectAllInCurrentLayer = function()

Clears the selection, then adds all elements in the current layer to the selection. This function then fires the selected event.

clear

this.clear = function()

Clears the current document. This is not an undoable action.

Fill and Stroke

getVersion

this.getVersion = function()

Returns a string which describes the revision number of SvgCanvas.