Module: utilities

Miscellaneous utilities.

Copyright:
  • 2010 Alexis Deveria, 2010 Jeff Schiller
License:
  • MIT
Source:

Interfaces

EditorContext

Members

(static, constant) blankPageObjectURL

Properties:
Name Type Description
blankPageObjectURL string
Source:

(static, constant) isNullish

Whether a value is null or undefined.

Source:

Methods

(static) assignAttributes(elem, attrs, suspendLengthopt, unitCheckopt) → {void}

Assigns multiple attributes to an element.

Parameters:
Name Type Attributes Default Description
elem Element

DOM element to apply new attribute values to
attrs PlainObject.<string, string>

Object with attribute keys/values
suspendLength Integer <optional>

Milliseconds to suspend redraw
unitCheck boolean <optional>
 false

Boolean to indicate the need to use units.setUnitAttr
Source:
Returns:
Type
void

(static) bboxToObj(bbox) → {module:utilities.BBoxObject}

Converts a SVGRect into an object.

Parameters:
Name Type Description
bbox SVGRect

a SVGRect
Source:
Returns:

An object with properties names x, y, width, height.

Type
module:utilities.BBoxObject

(static) cleanupElement(element) → {void}

Remove unneeded (default) attributes, making resulting SVG smaller.

Parameters:
Name Type Description
element Element

DOM element to clean up
Source:
Returns:
Type
void

(static) convertToPath(elem, attrs, addSVGElementsFromJson, pathActions, clearSelection, addToSelection, hstry, addCommandToHistory) → {SVGPathElement|null}

Convert selected element to a path.

Parameters:
Name Type Description
elem Element

The DOM element to be converted
attrs module:utilities.SVGElementJSON

Apply attributes to new path. see canvas.convertToPath
addSVGElementsFromJson module:utilities.EditorContext#addSVGElementsFromJson

Function to add the path element to the current layer. See canvas.addSVGElementsFromJson
pathActions module:path.pathActions

If a transform exists, pathActions.resetOrientation() is used. See: canvas.pathActions.
clearSelection module:draw.DrawCanvasInit#clearSelection | module:path.EditorContext#clearSelection

see canvas.clearSelection
addToSelection module:path.EditorContext#addToSelection

see canvas.addToSelection
hstry module:history

see history module
addCommandToHistory module:path.EditorContext#addCommandToHistory | module:draw.DrawCanvasInit#addCommandToHistory

see canvas.addCommandToHistory
Source:
Returns:

The converted path element or null if the DOM element was not recognized.

Type
SVGPathElement | null

(static) convertToXMLReferences(input) → {string}

Converts a string to use XML references (for non-ASCII).

Parameters:
Name Type Description
input string
Source:
Returns:

Decimal numeric character references

Type
string

(static) copyElem(el, getNextId) → {Element}

Create a clone of an element, updating its ID and its children's IDs when needed.

Parameters:
Name Type Description
el Element

DOM element to clone
getNextId module:utilities.GetNextID

The getter of the next unique ID.
Source:
Returns:

The cloned element

Type
Element

(static) createObjectURL(blob) → {string}

Get object URL for a blob object.

Parameters:
Name Type Description
blob Blob

A Blob object or File object
Source:
Returns:

object URL or empty string

Type
string

(static) dataURLToObjectURL(dataurl) → {string}

Convert dataURL to object URL.

Parameters:
Name Type Description
dataurl string
Source:
Returns:

object URL or empty string

Type
string

(static) decode64(input) → {string}

Converts a string from base64.

Parameters:
Name Type Description
input string

Base64-encoded input
Source:
Returns:

Decoded output

Type
string

(static) decodeUTF8(argString) → {string}

Parameters:
Name Type Description
argString string
Source:
Returns:
Type
string

(static) dropXMLInternalSubset(str) → {string}

Used to prevent the Billion laughs attack.

Parameters:
Name Type Description
str string

String to be processed
Source:
To Do:
  • This might be needed in other places `parseFromString` is used even without LGTM flagging
Returns:

The string with entity declarations in the internal subset removed

Type
string

(static) encode64(input) → {string}

Converts a string to base64.

Parameters:
Name Type Description
input string
Source:
Returns:

Base64 output

Type
string

(static) encodeUTF8(argString) → {string}

Parameters:
Name Type Description
argString string
Source:
Returns:
Type
string

(static) findDefs() → {SVGDefsElement}

Source:
Returns:

The document's <defs> element, creating it first if necessary

Type
SVGDefsElement

(static) getBBox(elem) → {module:utilities.BBoxObject}

Get the given/selected element's bounding box object, convert it to be more usable when necessary.

Parameters:
Name Type Description
elem Element

Optional DOM element to get the BBox for
Source:
Returns:

Bounding box object

Type
module:utilities.BBoxObject

(static) getBBoxOfElementAsPath(elem, addSVGElementsFromJson, pathActions) → {DOMRect|false}

Get the BBox of an element-as-path.

Parameters:
Name Type Description
elem Element

The DOM element to be probed
addSVGElementsFromJson module:utilities.EditorContext#addSVGElementsFromJson

Function to add the path element to the current layer. See canvas.addSVGElementsFromJson
pathActions module:path.pathActions

If a transform exists, pathActions.resetOrientation() is used. See: canvas.pathActions.
Source:
Returns:

The resulting path's bounding box object.

Type
DOMRect | false

(static) getBBoxWithTransform(elem, addSVGElementsFromJson, pathActions) → {module:utilities.BBoxObject|module:math.TransformedBox|DOMRect}

Get bounding box that includes any transforms.

Parameters:
Name Type Description
elem Element

The DOM element to be converted
addSVGElementsFromJson module:utilities.EditorContext#addSVGElementsFromJson

Function to add the path element to the current layer. See canvas.addSVGElementsFromJson
pathActions module:path.pathActions

If a transform exists, pathActions.resetOrientation() is used. See: canvas.pathActions.
Source:
Returns:

A single bounding box object

Type
module:utilities.BBoxObject | module:math.TransformedBox | DOMRect

(static) getElement(id) → (nullable) {Element}

Get a DOM element by ID within the SVG root element.

Parameters:
Name Type Description
id string

String with the element's new ID
Source:
Returns:
Type
Element

(static) getExtraAttributesForConvertToPath(elem) → {PlainObject.<("marker-start"|"marker-end"|"marker-mid"|"filter"|"clip-path"), string>}

Get a set of attributes from an element that is useful for convertToPath.

Parameters:
Name Type Description
elem Element

The element to be probed
Source:
Returns:

An object with attributes.

Type
PlainObject.<("marker-start"|"marker-end"|"marker-mid"|"filter"|"clip-path"), string>

(static) getFeGaussianBlur(Element) → {any}

Get the reference element associated with the given attribute value.

Parameters:
Name Type Description
Element any
Source:
Returns:

Reference element

Type
any

(static) getHref(elem) → {string}

Parameters:
Name Type Description
elem Element
Source:
Returns:

The given element's xlink:href value

Type
string

(static) getPathBBox(path) → {module:utilities.BBoxObject}

Get correct BBox for a path in Webkit. Converted from code found here.

Parameters:
Name Type Description
path SVGPathElement

The path DOM element to get the BBox for
Source:
Returns:

A BBox-like object

Type
module:utilities.BBoxObject

(static) getPathDFromElement(elem) → {string}

Make a path 'd' attribute from a simple SVG element shape.

Parameters:
Name Type Description
elem Element

The element to be converted
Source:
Returns:

The path d attribute or undefined if the element type is unknown.

Type
string

(static) getPathDFromSegments(pathSegments) → {string}

Create a path 'd' attribute from path segments. Each segment is an array of the form: [singleChar, [x,y, x,y, ...]]

Parameters:
Name Type Description
pathSegments Array.<module:utilities.PathSegmentArray>

An array of path segments to be converted
Source:
Returns:

The converted path d attribute.

Type
string

(static) getRefElem(attrVal) → {Element}

Get the reference element associated with the given attribute value.

Parameters:
Name Type Description
attrVal string

The attribute value as a string
Source:
Returns:

Reference element

Type
Element

(static) getRotationAngle(elemopt, toRadopt) → {Float}

Get the rotation angle of the given/selected DOM element.

Parameters:
Name Type Attributes Default Description
elem Element <optional>

DOM element to get the angle for. Default to first of selected elements.
toRad boolean <optional>
 false

When true returns the value in radians rather than degrees
Source:
Returns:

The angle in degrees or radians

Type
Float

(static) getRotationAngleFromTransformList(tlist, toRad) → {Float}

Get the rotation angle of the given transform list.

Parameters:
Name Type Description
tlist SVGTransformList

List of transforms
toRad boolean

When true returns the value in radians rather than degrees
Source:
Returns:

The angle in degrees or radians

Type
Float

(static) getStrokedBBox(elems, addSVGElementsFromJson, pathActions) → {module:utilities.BBoxObject|module:math.TransformedBox|DOMRect}

Get the bounding box for one or more stroked and/or transformed elements.

Parameters:
Name Type Description
elems Array.<Element>

Array with DOM elements to check
addSVGElementsFromJson module:utilities.EditorContext#addSVGElementsFromJson

Function to add the path element to the current layer. See canvas.addSVGElementsFromJson
pathActions module:path.pathActions

If a transform exists, pathActions.resetOrientation() is used. See: canvas.pathActions.
Source:
Returns:

A single bounding box object

Type
module:utilities.BBoxObject | module:math.TransformedBox | DOMRect

(static) getStrokedBBoxDefaultVisible(elems) → {module:utilities.BBoxObject}

Get the bounding box for one or more stroked and/or transformed elements.

Parameters:
Name Type Description
elems Array.<Element>

Array with DOM elements to check
Source:
Returns:

A single bounding box object

Type
module:utilities.BBoxObject

(static) getUrlFromAttr(attrVal) → {string}

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

  • <circle fill="url(someFile.svg#foo)" />
  • <circle fill="url('someFile.svg#foo')" />
  • <circle fill='url("someFile.svg#foo")' />
Parameters:
Name Type Description
attrVal string

The attribute value as a string
Source:
Returns:

String with just the URL, like "someFile.svg#foo"

Type
string

(static) getVisibleElements(parentElement) → {Array.<Element>}

Get all elements that have a BBox (excludes <defs>, <title>, etc). Note that 0-opacity, off-screen etc elements are still considered "visible" for this function.

Parameters:
Name Type Description
parentElement Element

The parent DOM element to search within
Source:
Returns:

All "visible" elements.

Type
Array.<Element>

(static) init(canvas) → {void}

Parameters:
Name Type Description
canvas module:utilities.EditorContext
Source:
Returns:
Type
void

(static) mock(mockMethods) → {void}

Overwrite methods for unit testing.

Parameters:
Name Type Description
mockMethods PlainObject
Properties
Name Type Description
getHref module:utilities.getHref
setHref module:utilities.setHref
getRotationAngle module:utilities.getRotationAngle
Source:
Returns:
Type
void

(static) preventClickDefault(img) → {void}

Prevents default browser click behaviour on the given element.

Parameters:
Name Type Description
img Element

The DOM element to prevent the click on
Source:
Returns:
Type
void

(static) setHref(elem, val) → {void}

Sets the given element's xlink:href value.

Parameters:
Name Type Description
elem Element
val string
Source:
Returns:
Type
void

(static) snapToGrid(value) → {Integer}

Round value to for snapping.

Parameters:
Name Type Description
value Float
Source:
Returns:
Type
Integer

(static) text2xml(sXML) → {XMLDocument}

Cross-browser compatible method of converting a string to an XML tree. Found this function here.

Parameters:
Name Type Description
sXML string
Source:
Throws:
Error
Returns:
Type
XMLDocument

(static) toXml(str) → {string}

Converts characters in a string to XML-friendly entities.

Parameters:
Name Type Description
str string

The string to be converted
Source:
Returns:

The converted string

Type
string
Example
`&` becomes `&amp;`

(static) walkTree(elem, cbFn) → {void}

Walks the tree and executes the callback on each element in a top-down fashion.

Parameters:
Name Type Description
elem Element

DOM element to traverse
cbFn module:utilities.TreeWalker

Callback function to run on each element
Source:
Returns:
Type
void

(static) walkTreePost(elem, cbFn) → {void}

Walks the tree and executes the callback on each element in a depth-first fashion.

Parameters:
Name Type Description
elem Element

DOM element to traverse
cbFn module:utilities.TreeWalker

Callback function to run on each element
Source:
To Do:
  • Shouldn't this be calling walkTreePost?
Returns:
Type
void

(inner) bBoxCanBeOptimizedOverNativeGetBBox(angle, hasAMatrixTransform) → {boolean}

Can the bbox be optimized over the native getBBox? The optimized bbox is the same as the native getBBox when the rotation angle is a multiple of 90 degrees and there are no complex transforms. Getting an optimized bbox can be dramatically slower, so we want to make sure it's worth it.

The best example for this is a circle rotate 45 degrees. The circle doesn't get wider or taller when rotated about it's center.

The standard, unoptimized technique gets the native bbox of the circle, rotates the box 45 degrees, uses that width and height, and applies any transforms to get the final bbox. This means the calculated bbox is much wider than the original circle. If the angle had been 0, 90, 180, etc. both techniques render the same bbox.

The optimization is not needed if the rotation is a multiple 90 degrees. The default technique is to call getBBox then apply the angle and any transforms.

Parameters:
Name Type Description
angle Float

The rotation angle in degrees
hasAMatrixTransform boolean

True if there is a matrix transform
Source:
Returns:

True if the bbox can be optimized.

Type
boolean

(inner) getStrokeOffsetForBBox(elem) → {Float}

Parameters:
Name Type Description
elem Element
Source:
To Do:
  • This is problematic with large stroke-width and, for example, a single horizontal line. The calculated BBox extends way beyond left and right sides.
Returns:
Type
Float

Type Definitions

BBoxObject

(like DOMRect)

Type:
Properties:
Name Type Description
x Float
y Float
width Float
height Float
Source:

GetNextID() → {string}

Source:
Returns:

The ID

Type
string

PathSegmentArray

Type:
Properties:
Name Type Description
length Integer

2
0 "M" | "L" | "C" | "Z"
1 Array.<Float>
Source:

SVGElementJSON

Object with the following keys/values.

Type:
Properties:
Name Type Attributes Default Description
element string

Tag name of the SVG element to create
attr PlainObject.<string, string>

Has key-value attributes to assign to the new element. An id should be set so that module:utilities.EditorContext#addSVGElementsFromJson can later re-identify the element for modification or replacement.
curStyles boolean <optional>
 false

Indicates whether current style attributes should be applied first
children Array.<module:utilities.SVGElementJSON> <optional>

Data objects to be added recursively as children
namespace string <optional>
 "http://www.w3.org/2000/svg"

Indicate a (non-SVG) namespace
Source:

TreeWalker(elem) → {void}

Parameters:
Name Type Description
elem Element

DOM element being traversed
Source:
Returns:
Type
void

BBox

Type:
Properties:
Name Type Description
x Integer

The x value
y Integer

The y value
width Float
height Float
Source: