API Docs for: 6.0.1
Show:

window.scrawl_Stacks Class

window.scrawl

scrawlStacks extension adaptions to the scrawl-canvas library object

New library sections

  • scrawl.stack - for Stack objects
  • scrawl.stk - for handles to DOM stack containers
  • scrawl.element - for Element objects
  • scrawl.elm - for handles to DOM elements within a stack

New default attributes

  • PageElement.start - default: {x:0,y:0,z:0};
  • PageElement.delta - default: {x:0,y:0,z:0};
  • PageElement.translate - default: {x:0,y:0,z:0};
  • PageElement.handle - default: {x:'center',y:'center',z:0};
  • PageElement.pivot - default: '';
  • PageElement.stack - default: '';
  • PageElement.path - default: '';
  • PageElement.pathPlace - default: 0;
  • PageElement.deltaPathPlace - default: 0;
  • PageElement.pathSpeedConstant - default: true;
  • PageElement.pathRoll - default: 0;
  • PageElement.addPathRoll - default: false;
  • PageElement.lockX - default: false;
  • PageElement.lockY - default: false;
  • PageElement.rotation - default: {n:1,v:{x:0,y:0,z:0}};
  • PageElement.deltaRotation - default: {n:1,v:{x:0,y:0,z:0}};
  • PageElement.rotationTolerance - default: 0.001;
  • PageElement.visibility - default: true;
  • Device.transform - default: false;

Item Index

Methods

addCanvasToPage

(
  • items
)

A general function to add a visible <canvas> element to the web page, and create a Pad controller and Cell wrappers for it

The argument object should include the following attributes:

  • stackName (String) - STACKNAME of existing or new stack (optional)
  • parentElement - (String) CSS #id of parent element, or the DOM element itself; default: document.body
  • any other legitimate Pad and/or Cell object attribute

(This function replaces the one defined in the core module)

Parameters:

  • items Object

    Object containing new Cell's parameters

Returns:

The new Pad object

Example:

<body>
    <div id="canvasholder"></div>
    <script src="js/scrawlCore-min.js"></script>
    <script>
        scrawl.addCanvasToPage({
            name:   'mycanvas',
            stackName: 'mystack',
            width: 400,
            height: 200,
            }).makeCurrent();
    </script>
</body>

Live demo

addClass

(
  • item
)
chainable

Add a CSS class to the DOM element

Parameters:

  • item String

    String consisting of one or more classes to be added to the DOM element - a space will be prepended to the start of the string automatically

Returns:

This

addCornerTrackers - used only with Frame entitys

() private chainable

Returns:

This

addStackToPage

(
  • items
)

A general function to generates a new Stack object, together with a new DOM <div> element to act as the stack

The argument object should include the following attributes:

  • stackName (String) - STACKNAME of existing or new stack (optional)
  • parentElement - (String) CSS #id of parent element, or the DOM element itself; default: document.body
  • any other legitimate Stack object attribute

Parameters:

  • items Object

    Object containing new Stack's parameters

Returns:

New stack object

domInit

()

A display function to initialize DOM elements with their existing values

Returns:

Always true

domInitialize

() chainable

Reinitialize element with existing values

Returns:

This

dropEntity

(
  • [items]
)
chainable

Revert pickupEntity() actions, ensuring element is left where the user drops it

Parameters:

  • [items] String optional

    Alternative pivot String

Returns:

This

getCanvases

() private

A private function that searches the DOM for canvas elements and generates Pad/Cell/Context objects for each of them

(This function replaces the one defined in the core module)

Returns:

True on success; false otherwise

getElements

() private

A private function that searches the DOM for elements with class="scrawl stack:STACKNAME"; generates Element objects

Returns:

True on success; false otherwise

getReferenceDimensions

(
  • reference
)
W: width, h: height, c: centered private

updateCurrentHandle helper object

Parameters:

  • reference Object

    object - Stack, Pad, Element, Cell or Entity (Block, Wheel, Phrase, Picture, Path, Shape or Frame)

Returns:

W: width, h: height, c: centered:

Object with attributes

getStacks

() private

A private function that searches the DOM for elements with class="scrawlstack"; generates Stack objects

Returns:

True on success; false otherwise

getStacksDeviceData

() private

Check if device supports CSS3 3d transforms

makeElementGroup

(
  • items
)
private

A factory function to generate new ElementGroup objects

Parameters:

  • items Object

    Key:value Object argument for setting attributes

Returns:

ElementGroup object

makeStack

(
  • items
)
private

A factory function to generate new Stack objects

Parameters:

  • items Object

    Key:value Object argument for setting attributes

Returns:

Stack object

multiSectionBucketSort

(
  • section
  • attribute
  • a
)
private

A utility function for performing bucket sorts on scrawl-canvas string arrays eg Group.elements

Parameters:

  • section Array

    Array of scrawl-canvas library section names

  • attribute String

    on which sort will be performed

  • a Array

    array to be sorted

Returns:

sorted array

newElement

(
  • items
)
private

Alias for makeElement()

Parameters:

  • items Object

    Key:value Object argument for setting attributes

Returns:

Element object

newElementGroup

(
  • items
)
private

Alias for makeElementGroup()

Parameters:

  • items Object

    Key:value Object argument for setting attributes

Returns:

ElementGroup object

newStack

(
  • items
)
private

Alias for makeStack()

Parameters:

  • items Object

    Key:value Object argument for setting attributes

Returns:

Stack object

padStacksSet

() private

Pad set hook function - amended by Stacks module

Returns:

Nothing

PageElement.exchange

(
  • obj
  • item
)
chainable

Swaps the values of an attribute between two objects

Parameters:

  • obj Object

    Object with which this object will swap attribute values

  • item String

    Attribute to be swapped

Returns:

This

PageElement.get

(
  • get
)

Augments Base.get() to retrieve DOM element width and height values, and stack-related attributes (startX, startY, handleX, handleY, deltaX, deltaY, translateX, translateY, translateZ, deltaTranslateX, deltaTranslateY, deltaTranslateZ). Can also be used to retrieve a number of current CSS attributes on the DOM element

(The stack module replaces the core function rather than augmenting it via a hook function)

Parameters:

  • get String

    Attribute key

Returns:

Attribute value

PageElement.renderElement

() chainable

Reposition an element within its stack by changing 'left' and 'top' style attributes; rotate it using matrix3d transform

Returns:

This left

PageElement.reverse

(
  • [item]
)
chainable

Changes the sign (+/-) of specified attribute values

Parameters:

  • [item] String optional

    String used to limit this function's actions - permitted values include 'deltaX', 'deltaY', 'delta', 'deltaPathPlace'; default action: all values are amended

Returns:

This

PageElement.reverseActions (not a function)

() private

reverse helper object

PageElement.revertStart

(
  • [item]
)
chainable

Subtracts delta values from the start vector; subtracts deltaPathPlace from pathPlace

Permitted argument values include

  • 'x' - delta.x subtracted from start.x
  • 'y' - delta.y subtracted from start.y
  • 'path' - deltaPathPlace subtracted from pathPlace
  • undefined: all values are amended

Parameters:

  • [item] String optional

    String used to limit this function's actions - permitted values include 'x', 'y', 'path'; default action: all values are amended

Returns:

This

PageElement.revertStartActions (not a function)

() private

revertStart helper object

PageElement.set

(
  • items
)
chainable

Augments Base.set() to allow the setting of DOM element dimension values, and stack-related attributes (start, startX, startY, handle, handleX, handleY, delta, deltaX, deltaY, translate, translateX, translateY, 'translateZ, deltaTranslate, deltaTranslateX, deltaTranslateY, deltaTranslateZ). Can also be used to set a number of current CSS attributes on the DOM element

(The stack module replaces the core function rather than augmenting it via a hook function)

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

PageElement.setDelta

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values; only Number attributes can be amended using this function

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

PageElement.setDisplayOffsets

() chainable

Calculate the element's display offset values

Returns:

This

PageElement.setStampUsingDomElementPivot

() private

setStampUsingPivot helper function

Returns:

nothing

PageElement.setStampUsingLockTo

() private

setStampUsingPivot helper function

Returns:

nothing

PageElement.setStampUsingPath

() private chainable

Calculate start Vector in reference to a Shape entity object's path

Returns:

This

PageElement.setStampUsingPivot

()

Directly calls the equivalent Position function

PageElement.setStampUsingPivot (not a function)

()

stamp helper object

PageElement.setStyles

(
  • items
)
chainable

Handles the setting of many CSS attributes

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

PageElement.setTransformOrigin

() chainable

Set the transform origin style attribute

Returns:

This

PageElement.update3d

(
  • [items]
)
chainable

Rotate and translate a DOM element around a quaternion rotation

  • Element's initial rotation values should be stored in the deltaRotation attribute quaternion
  • Element's initial translation values should be stored in the deltaTranslate attribute vector

Argument can contain the following (optional) attributes:

  • quaternion - quaternion representing the rotation to be applied to the element
  • distance - distance of element from the rotation origin

Parameters:

  • [items] Object optional
    • Distance between the effective rotation point and the DOM element's start attribute - default: deltaTranslate vector's magnitude

Returns:

This

PageElement.updateStart

(
  • [item]
)
chainable

Adds delta values to the start vector; adds deltaPathPlace to pathPlace

Permitted argument values include

  • 'x' - delta.x added to start.x
  • 'y' - delta.y added to start.y
  • 'path' - deltaPathPlace added to pathPlace
  • undefined: all values are amended

Parameters:

  • [item] String optional

    String used to limit this function's actions - permitted values include 'x', 'y', 'path'; default action: all values are amended

Returns:

This

PageElement.updateStartActions (not a function)

() private

updateStart helper object

pageInit

() private

scrawl.init hook function - modified by stacks module

pickupEntity

(
  • items
)
chainable

Set element's pivot to 'mouse'; set handles to supplied Vector value; set order to +9999

Parameters:

  • items Vector

    Coordinate vector; alternatively an object with {x, y} attributes can be used

Returns:

This

removeClass

(
  • item
)
chainable

Remove a CSS class from the DOM element

Parameters:

  • item String

    String consisting of one or more classes to be removed from the DOM element

Returns:

This

render

(
  • [pads]
)
chainable

A display function to ask Pads to undertake a complete clear-compile-show display cycle, and stacks to undertake a render cycle

(Replaces Core.render)

Parameters:

  • [pads] Array optional

    Array of PADNAMEs - can also be a String

Returns:

The scrawl-canvas library object (scrawl)

renderElements

()

A display function to move DOM elements within a Stack

Returns:

Always true

setCellLocalDimensions

() private

Pad lockTo helper

Returns:

Nothing

setDeltaAttribute

(
  • items
)
chainable

Augments PageElement.set(), to allow users to set the delta attributes using delta, deltaX, deltaY

The scrawlAnimation extension adds a delta attribute to Cells and Entitys - this is an inbuilt delta vector which can be used to automatically animate the start vector of these objects - via the updateStart, revertStart and reverse functions - as part of the animation cycle.

Be aware that this is different to the PageElement.setDelta() function inherited by Cells and Entitys. setDelta is used to add a supplied argument value to the existing values of any numerical attribute of a Cell or Entity object, and is thus not limited to the animation cycle.

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaHandle

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values. This function accepts handle, handleX, handleY

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaRotation

(
  • items
)
chainable

Augments PageElement.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaStart

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values; This function accepts start, startX, startY

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaTranslate

(
  • items
)
chainable

Augments PageElement.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDimensions

() chainable

Overrides PageElement.setDimensions(); <canvas> elements do not use styling to set their drawing region dimensions

Returns:

This

setDimensions

() private chainable

Helper function - set DOM element dimensions (width, height)

Overwritesa core setDimensions()

Returns:

This

setDisplayOffsets

(
  • [item]
)
chainable

A general function to reset display offsets for all pads, stacks and elements

The argument is an optional String - permitted values include 'stack', 'pad', 'element'; default: 'all'

(This function replaces the one defined in the core module)

Parameters:

  • [item] String optional

    Command string detailing which element types are to be set

Returns:

The scrawl-canvas library object (scrawl)

Example:

scrawl.setDisplayOffsets();

setGroupAttribute

(
  • items
)
chainable

Augments PageElement.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setHandle

(
  • items
)
chainable

Augments Base.setHandle(), to allow users to set the handle attributes using handle, handleX, handleY

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setLocalDimensions

() private chainable

Helper function - set local dimensions (width, height)

Returns:

This

setPerspectives

(
  • [stacks]
)
chainable

Set the perspective for all stacks

(Replaces Core.setPerspectives)

Parameters:

  • [stacks] Array optional

    Array of STACKNAMEs - can also be a String - if null, all stacks will be processed

Returns:

The scrawl-canvas library object (scrawl)

setPivotAttribute

(
  • items
)
chainable

Augments PageElement.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setRotation

(
  • items
)
chainable

Augments PageElement.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setStampUsingStacksPivot

()

Stamp helper hook function - amended by stacks module

Returns:

always true

setStart

(
  • items
)
chainable

Augments Base.setStart(), to allow users to set the start attributes using start, startX, startY

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setTranslate

(
  • items
)
chainable

Augments PageElement.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

sortCellsCompile

() private

Pad constructor hook function - amended by Stacks module

Returns:

Nothing

stacksPageElementConstructor

() private

PageElement constructor hook function - modified by stacks module

update

(
  • [items]
)

A display function to update DOM elements' 3d position/rotation

Argument can contain the following (optional) attributes:

  • quaternion - quaternion representing the rotation to be applied to the element
  • distance - distance of element from the rotation origin
  • group - optional String name of ElementGroup on which to commence the operation; the operation will also be performed on the groups of any Stack elements cotained within this group. If this argument is not included in the argument object then all Pads, Stacks and Elements will be updated.

Parameters:

  • [items] Object optional

    Argument object containing key:value pairs

Returns:

Always true

updateCornerTrackers - used only with Frame entitys

() private chainable

Returns:

This

updateCurrentHandle

() private chainable

Convert handle percentage values to numerical values, stored in currentHandle

Returns:

This

updateCurrentStart

(
  • reference
)
private chainable

Convert start percentage values to numerical values, stored in currentStart

Parameters:

  • reference Object

    object - Stack, Pad, Element, Cell or Entity (Block, Wheel, Phrase, Picture, Path, Shape or Frame)

Returns:

This

Properties

drag

Boolean

Drag boolean - indicates the element can be manipulated via mouse/touch events (eg pickup, drop)

Default: false

mouseIndex

String

Index of mouse vector to use when pivot === 'mouse'

The Pad/Stack/Element.mice object can hold details of multiple touch events - when an entity is assigned to a 'mouse', it needs to know which of those mouse trackers to use. Default: mouse (for the mouse cursor vector)

Default: 'mouse'

order

Number

Sorting order - must be a positive integer

Default: 0

PageElement.addPathRoll

Boolean

A flag to determine whether the object will calculate the rotation value of its current position along a Shape path

Default: false

PageElement.bottomLeft

Vector

Corner tracker vector - used only with Frame emtitys

Default: false

PageElement.bottomLeftDiv

DOM element object

Corner tracker div element - used only with Frame entitys

Default: false

PageElement.bottomRight

Vector

Corner tracker vector - used only with Frame emtitys

Default: false

PageElement.bottomRightDiv

DOM element object

Corner tracker div element - used only with Frame entitys

Default: false

PageElement.delta

Vector

A change Vector which can be applied to the object's rotation/flip point

PageElement, and all Objects that prototype chain to PageElement, supports the following 'virtual' attributes for this attribute:

  • deltaX - (Number) a horizontal change value, in pixels
  • deltaY - (Number) a vertical change value, in pixels

PageElement.deltaPathPlace

Number

A change value which can be applied to the object's pathPlace attribute

Default: 0

PageElement.deltaPitch

Number

Element 2d deltaPitch value

Default: 0

PageElement.deltaRoll

Number

Element 2d deltaRoll value

Default: 0

PageElement.deltaRotation

Quaternion

Element's delta (change in) rotation around its transform (start) coordinate

Default: Unit quaternion with no rotation

PageElement.deltaTranslate

Vector

PageElement.deltaYaw

Number

Element 2d deltaYaw value

Default: 0

PageElement.group

String

The element's current ELEMENTGROUPNAME

Default: ''

PageElement.handle

Object

An Object (in fact, a Vector) containing offset instructions from the object's rotation/flip point, where drawing commences.

PageElement, and all Objects that prototype chain to PageElement, supports the following 'virtual' attributes for this attribute:

  • handleX - (Mixed) the horizontal offset, either as a Number (in pixels), or a percentage String of the object's width, or the String literal 'left', 'right' or 'center'
  • handleY - (Mixed) the vertical offset, either as a Number (in pixels), or a percentage String of the object's height, or the String literal 'top', 'bottom' or 'center'

Where values are Numbers, handle can be treated like any other Vector

PageElement.includeCornerTrackers

Boolean

A flag to tell scrawl-canvas to add corner trackers to the element

Corner trackers can be used by the Frame entity to bind its corners to a DOM element within a stack

Default: false

PageElement.lockTo

String

When element is pivoted to another element, determines placement in relation to that element

Permitted values: 'top', 'right', 'bottom', 'left', '' (default)

Default: ''

PageElement.lockX

Boolean

When true, element ignores horizontal placement data via pivot and path attributes

Default: false

PageElement.lockY

Boolean

When true, element ignores vertical placement data via pivot and path attributes

Default: false

PageElement.path

String

The SPRITENAME of a Shape entity whose path is used to calculate this object's start point

Default: ''

PageElement.pathPlace

Number

A value between 0 and 1 to represent the distance along a Shape object's path, where 0 is the path start and 1 is the path end

Default: 0

PageElement.pathRoll

Number

The rotation value (in degrees) of an object's current position along a Shape path

Default: 0

PageElement.pathSpeedConstant

Boolean

A flag to determine whether the object will calculate its position along a Shape path in a regular (true), or simple (false), manner

Default: true

PageElement.pitch

Number

Element 2d pitch value

Default: 0

PageElement.pivot

String

The ENTITYNAME or POINTNAME of a entity or Point object to be used for setting this object's start point

Default: ''

PageElement.roll

Number

Element 2d roll value

Default: 0

PageElement.rotation

Quaternion

Element rotation around its transform (start) coordinate

Default: Unit quaternion with no rotation

PageElement.rotationTolerance

Number

Element's rotation tolerance - all Quaternions need to be unit quaternions; this value represents the acceptable tolerance away from the norm

Default: 0.001

PageElement.start

Vector

The coordinate Vector representing the object's rotation/flip point

PageElement, and all Objects that prototype chain to PageElement, supports the following 'virtual' attributes for this attribute:

  • startX - (Mixed) the x coordinate of the object's rotation/flip point, in pixels, from the left side of the object's stack
  • startY - (Mixed) the y coordinate of the object's rotation/flip point, in pixels, from the top side of the object's stack

This attribute's attributes accepts absolute number values (in pixels), or string percentages where the percentage is relative to the container stack's width or height, or string literals which again refer to the containing stack's dimensions:

  • startX - 'left', 'right' or 'center'
  • startY - 'top', 'bottom' or 'center'

Where values are Numbers, handle can be treated like any other Vector

PageElement.topLeft

Vector

Corner tracker vector - used only with Frame emtitys

Default: false

PageElement.topLeftDiv

DOM element object

Corner tracker div element - used only with Frame entitys

Default: false

PageElement.topRight

Vector

Corner tracker vector - used only with Frame emtitys

Default: false

PageElement.topRightDiv

DOM element object

Corner tracker div element - used only with Frame entitys

Default: false

PageElement.translate

Vector

A change Vector for translating elements away from their start coordinate

PageElement, and all Objects that prototype chain to PageElement, supports the following 'virtual' attributes for this attribute:

  • translateX - (Number) movement along the x axis, in pixels
  • translateY - (Number) movement along the y axis, in pixels
  • translateZ - (Number) movement along the z axis, in pixels

PageElement.viewport

Boolean

A flag to determine whether an element uses the browser viewport for its position and dimensions reference

Default: false

PageElement.visibility

Boolean

A flag to determine whether an element displays itself

Default: true

PageElement.yaw

Number

Element 2d yaw value

Default: 0

PageElement.zIndexIsTranslateZ

Boolean

A flag to determine whether zIndex uses translateZ values (default: true), or if it can be independently set (as style zIndex)

Default: true

scrawl.work.css

Array private

Array of css attributes not requiring prefixes

scrawl.work.xcss

Array private

Array of css attributes that do require prefixes

transform

Boolean

DOM element css3 3d transform support

True if the CSS2 3d functionality is supported; false otherwise

Default: false