API Docs for: 6.0.1
Show:

Element Class

Element

Instantiation

  • Stack.addElementById()
  • Stack.addElementsByClassNames()

Purpose

  • provide a wrapper object for a DOM element

Access

  • scrawl.element.ELEMENTNAME - for the Element object
  • scrawl.elm.ELEMENTNAME - for a handle to the DOM element

Constructor

Element

(
  • [items]
)

Parameters:

  • [items] Object optional

    Key:value Object argument for setting attributes

Methods

addMouseMove

() private chainable

Adds event listeners to the element

Returns:

This

clone

(
  • items
)
chainable

Clone a Scrawl.js object, optionally altering attribute values in the cloned object

Note that any callback or fn attribute functions will be referenced by the clone, not copied to the clone; these can be overwritten with new anonymous functions by including them in the items argument object

(This function is replaced by the path extension)

Parameters:

  • items Object

    Object containing attribute key:value pairs; will overwrite existing values in the cloned, but not the source, Object

Returns:

Cloned object

Example:

var box = scrawl.makeBlock({
    width: 50,
    height: 50
    });
var newBox = box.clone({
    height: 100
    });
newBox.get('width');        //returns 50
newBox.get('height');       //returns 100

get

(
  • get
)

Inherited from Base but overwritten in source\scrawlCore.js:3893

Augments Base.get() to retrieve DOM element width and height values

(The stack extension replaces this core function rather than augmenting it via a hook function)

Parameters:

  • get String

    Attribute key

Returns:

Attribute value

getElement

()

Return the DOM element wrapped by this object

Returns:

Element

getMouse

(
  • item
)

Retrieve details of the Mouse cursor position in relation to the DOM element's top left hand corner. Most useful for determining mouse cursor position over Stack and Pad (visible <canvas>) elements.

This function is also used to retrieve details of touch positions.

Note: if changes are made elsewhere to the web page (DOM) after the page loads, the function .getDisplayOffsets() will need to be called to recalculate the element's position within the page - failure to do so will lead to this function returning incorrect data. getDisplayOffsets() does not need to be called during/after page scrolling.

By default, the function returns a single Vector containing either the first touch position or the current mouse cursor position.

The returned object is a Vector containing the mouse cursor's current x and y coordinates in relation to the DOM element's top left corner, together with the following additional attributes:

  • active - set to true if mouse is hovering over the element; false otherwise
  • id - event vector id (-1: mouse; 0+ touch or pointer)
  • order - event order (0: mouse; 1+ touch or pointer)

If an argument is supplied, then all currently existing mouse/touch vectors are returned as an array, with index 0 representing the mouse pointer, index 1 representing the first touch coordinate and additional indexes representing additional touch coordinates

Parameters:

  • item Boolean
    • true to return the array; false (default) to return either first touch or mouse Vector

Returns:

Vector, or an array of Vectors containing localized coordinates, with additional attributes; if mouse/touch has been disabled for the DOM element, returns false

getMouseIdFromEvent

(
  • item
)

Parameters:

  • item Boolean
    • DOM event object

Returns:

Array - mouse id strings associated with event(s)

handleMouseMove

(
  • e
  • active
)
private

mousemove event listener function

Parameters:

  • e Object

    window.event

  • active Boolean
    • set only by handleMouseIn, handleMouseOut

Returns:

This

handleMouseTilt

(
  • e
)
private

mouseTilt hook function - amended by scrawlStacks extension

Parameters:

  • e Object

    window.event

Returns:

This

numberConvert

(
  • val
  • dim
)
private

Stamp helper function - convert string percentage values to numerical values

Parameters:

  • val String

    coordinate String

  • dim Number

    dimension value

Returns:

Number - value

parse

()

Turn the object into a JSON String

Returns:

object of object's currently set attributes

removeMouseMove

() private chainable

Remove event listeners from the element

Returns:

This

scaleDimensions

(
  • item
)
chainable

Scale DOM element dimensions (width, height)

Parameters:

  • item Number

    Scale value

Returns:

This

set

(
  • items
)
chainable

Inherited from Base but overwritten in source\scrawlCore.js:3919

Augments Base.set() to allow the setting of DOM element dimension values

(The stack extension replaces this core function rather than augmenting it via a hook function)

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setAccessibility

(
  • items
)
chainable

Handles the setting of DOM element title and data-comment attributes

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDimensions

() private chainable

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

Returns:

This

setDisplayOffsets

() chainable

Calculate the DOM element's current display offset values

Returns:

This

setLocalDimensions

() private chainable

Helper function - set local dimensions (width, height)

Returns:

This

stacksPageElementConstructor

() private

PageElement constructor hook function - modified by stacks extension

Properties

comment

String

Comment, for accessibility

Default: ''

displayOffsetX

Number

DOM element's current horizontal offset from the top of the web page

Default: 0

displayOffsetY

Number

DOM element's current vertical offset from the left side of the web page

Default: 0

height

String

Inherited from PageElement but overwritten in source\scrawlStacks.js:3234

Element's default height

Default: 'auto'

interactive

Boolean

Set the interactive attribute to true to track mouse/pointer/touch events on the element. By default Pad and Stack objects set their element's interactivity to true, while Element objects set it to false

Default: true (false for Element objects)

localHeight

Number

DOM element localHeight

Default: 150

localWidth

Number

DOM element localWidth

Default: 300

mice

Object

The mice attribute is an object containing supplemented vectors which hold real-time information about the current coordinates of the mouse pointer and any other pointer or touch instances occurring over the element

mice.mouse - always refers to the mouse pointer mice.ui0, mice.ui1 etc - refers to pointer and touch events

Default: {}

name

String

Unique identifier for each object; default: computer-generated String based on Object's type

position

String

Element CSS position styling attribute

Default: 'static'

propogateTouch

Boolean

Boolean - if set to trye, a touchmove event will be propogated to other stacks, pads and elements; default false

Default: false

scale

Number

The object's scale value - larger values increase the object's size

Default: 1

timestamp

String

Creation timestamp

Default: ''

title

String

Title, for accessibility

Default: ''

type

String final

Inherited from Base but overwritten in source\scrawlStacks.js:3225

Default: 'Element'

width

Number

DOM element width

Default: 300