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.
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
InsertElementCommand.elements	Returns array with element associated with this command
Selection
clearSelection	Clears the selection.
addToSelection	Adds a list of elements to the selection.
removeFromSelection	Removes elements from the selection.
Serialization
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

Undo/Redo history management

ChangeElementCommand

function ChangeElementCommand( 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

function InsertElementCommand( 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

function RemoveElementCommand( elem,
parent,
text )

History command for an element removed from the DOM

Parameters

elem	The removed DOM element
elem	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

function MoveElementCommand( 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

InsertElementCommand.elements

Returns array with element associated with this command

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

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.