API Docs for: 6.0.1
Show:

Pad Class

Extends PageElement
Module: scrawlCore

Pad

Instantiation

  • created automatically for any <canvas> element found on the web page when it loads
  • also, scrawl.addCanvasToPage()
  • should not be instantiated directly by users

Purpose

  • controller (not wrapper) object for canvas elements included in the DOM
  • coordinates activity between visible canvas element and other (non-DOM) canvas elements that contribute to it

Because the Pad constructor calls the Cell constructor as part of the construction process (Cell objects wrap <canvas> elements; Pad objects control <canvas> elements), Cell attributes can be included in the Pad constructor object and picked up by the resultant Cell objects.

Access

  • scrawl.pad.PADNAME - for the Pad object
  • scrawl.canvas.PADNAME - for the Pad object's visible (display) <canvas> element
  • scrawl.context.PADNAME - for the visible (display) &ltcanvas> element's 2d context engine (CanvasRenderingContext2D interface)
  • scrawl.cell[scrawl.pad.PADNAME.display] - for the Pad object's display cell
  • scrawl.cell[scrawl.pad.PADNAME.base] - for the Pad object's base cell

Constructor

Pad

(
  • [items]
)

Parameters:

  • [items] Object optional

    Key:value Object argument for setting attributes

Methods

addCells

(
  • items
)
chainable

Associate existing <canvas> elements, and their Cell wrappers, with this Pad

Parameters:

  • items String

    One or more CELLNAME Strings

Returns:

This

addMouseMove

() private chainable

Adds event listeners to the element

Returns:

This

addNewCell

(
  • data
)

Create a new (hidden) <canvas> element and associated Cell wrapper, and add it to this Pad

Parameters:

  • data Object

    Object containing attribute data for the new canvas

Returns:

New Cell object; false on failure

Example:

scrawl.addCanvasToPage({
    name: 'mycanvas',
    width: 200,
    height: 200,
    });
scrawl.pad.mycanvas.addNewCell({
    name: 'background',
    width: 400,
    });

clear

() chainable

Display function - requests Cells to clear their <canvas> element

Cells with cleared = true will clear theid displays in preparation for compile/stamp operations

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

compile

() chainable

Display function - requests Cells to compile their <canvas> element

Cells will compile in ascending order of their compileOrder attributes, if their compiled attribute = true

By default:

  • the initial base canvas has a compileOrder of 9999 and compiles last
  • the initial display canvas has compiled = false and will not compile

(This function is replaced by the Filters extension)

Returns:

This

deleteCell

(
  • cell
)
chainable

Remove a Cell wrapper object from this Pad

Note: does not delete the canvas, or the Cell object, from the scrawl library

Parameters:

  • cell String

    CELLNAME String

Returns:

This

filtersPadInit

() private

Pad constructor hook function - modified by filters extension

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

() private

Retrieve Pad's visible <canvas> element object

Returns:

DOM element object

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

makeCurrent

() chainable

Set scrawl.currentPad attribute to this Pad's PADNAME String

Returns:

This

Example:

scrawl.addCanvasToPage({
    name: 'mycanvas',
    width: 200,
    height: 200
    }).makeCurrent();

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

padStacksConstructor

() private

Pad constructor hook function - amended by Stacks extension

Returns:

Nothing

padStacksSet

() private

Pad set hook function - amended by Stacks extension

Returns:

Nothing

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

render

() chainable

Display function - Pad tells its associated Cell objects to undertake a complete clear-compile-show display cycle

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:4526

Augments PageElement.set(), to cascade scale, backgroundColor, globalAlpha and globalCompositeOperation changes to associated Cell objects

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setAccessibility

(
  • items
)
chainable

Inherited from PageElement but overwritten in source\scrawlCore.js:4818

Augments PageElement.setAccessibility(); handles the setting of <canvas> element title and data-comment attributes

  • Title text is assigned to the display canvas's title attribute
  • Comments are placed between the display canvas element's tags, within <p> tags - this will remove any existing content between the canvas tags

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDimensions

() chainable

Inherited from PageElement but overwritten in source\scrawlCore.js:4845

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

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

show

() chainable

Display function - requests Cells to show their <canvas> element

Cells will show in ascending order of their showOrder attributes, if their show attribute = true

By default, the initial base and display canvases have shown = false:

  • 'show' involves a cell copying itself onto the base cell; it makes no sense for the base cell to copy onto itself
  • the last action is to copy the base cell onto the display cell

(This function is replaced by the Filters extension)

Returns:

This

sortCellsCompile

() private

Display function sorting routine - cells are sorted according to their compileOrder attribute value, in ascending order

Returns:

Nothing

sortCellsShow

() private

Display function sorting routine - cells are sorted according to their showOrder attribute value, in ascending order

Returns:

Nothing

stacksPadInit

() private

Pad constructor hook function - modified by stacks extension

stacksPageElementConstructor

() private

PageElement constructor hook function - modified by stacks extension

Properties

base

String

Pad's base (hidden) <canvas> element - CELLNAME

Default: ''

cells

Array

Array of CELLNAME Strings associated with this Pad

Default: []

comment

String

Comment, for accessibility

Default: ''

current

String deprecated

Pad's currently active <canvas> element - CELLNAME

//not convinced there's any point in keeping this attribute anymore - take it out?

Default: ''

display

String

Pad's display (visible) <canvas> element - CELLNAME

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

Number

DOM element height

Default: 150

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\scrawlCore.js:4490

Default: 'Pad'

width

Number

DOM element width

Default: 300