API Docs for: 6.0.1
Show:

Cell Class

Extends Position
Module: scrawlCore

Cell

Instantiation

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

Purpose

  • Acts as a wrapper for each <canvas> element - whether that canvas is part of the DOM or not
  • Oversees manipulation of the <canvas> element's context engine
  • Responsible clearing <canvas> elements, and for copying one <canvas> to another
  • Includes functionality to pivot, path, flip, lock and roll cell positioning in the display scene
  • Controls scrolling and zoom effects between <canvas> elements
  • Builds <canvas> element collision fields from entity data
  • Undertakes collision detection between entitys and a collision field

Note: A Cell is entirely responsible for determining what portion of its <canvas> element's content will be copied to another <canvas> and where that copy will appear on the destination <canvas>.

Access

  • scrawl.cell.CELLNAME - for the Cell object
  • scrawl.pad[scrawl.cell.CELLNAME.pad] - for the Cell object's Pad object

Constructor

Cell

(
  • [items]
)

Parameters:

  • [items] Object optional

    Key:value Object argument for setting attributes

Methods

animationCellGet

() private

Cell.get hook function - modified by animation extension

animationCellInit

() private

Cell constructor hook function - modified by animation extension

animationCellSet

() private

Cell.set hook function - modified by animation extension

animationPositionClone

() private

Position.setDelta hook function - modified by animation extension

animationPositionGet

() private

Position.get hook function - modified by animation extension

animationPositionInit

() private

Position constructor hook function - modified by animation extension

animationPositionSet

() private

Position.set hook function - modified by animation extension

clear

() chainable

Clear the Cell's <canvas> element using JavaScript ctx.clearRect()

Returns:

This

clearShadow

() private chainable

Entity stamp helper function

Returns:

This

clone

(
  • items
)
chainable

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

Augments Base.clone(), to allow users to set the start and handle attributes using startX, startY, handleX, handleY

Parameters:

  • items Object

    Object consisting of key:value attributes, used to update the clone's attributes with new values

Returns:

Cloned object

collisionsCellInit

() private

Cell constructor hook function - modified by collisions extension

compile

() chainable

Prepare to draw entitys onto the Cell's <canvas> element, in line with the Cell's group Array

(This function is replaced by the Filters extension)

Returns:

This

copyCellToSelf

(
  • cell
)
private chainable

Cell copy helper function

Parameters:

  • cell String

    CELLNAME of cell to be copied onto this cell's <canvas> element

Returns:

This

coreCellInit

() private

Cell constructor hook function - core module

correctCoordinates

(
  • coords
  • [cell]
)

Stamp helper function - correct mouse coordinates if pad dimensions not equal to base cell dimensions

Parameters:

  • coords Object

    An object containing x and y attributes

  • [cell] String optional

    CELLNAME String

Returns:

Amended coordinate object

filtersCellInit

() private

Cell constructor hook function - modified by filters extension

get

(
  • item
)

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

Augments Position.get(), to allow users to get values for sourceX, sourceY, startX, startY, targetX, targetY, handleX, handleY, width, height

Parameters:

  • item String

    Attribute key

Returns:

Attribute value

getImageData

(
  • dimensions
)

Capture an image of the cell's <canvas> element using the JavaScript ctx.getImageData() operation

Argument is an Object in the form:

  • {x:Number, y:Number, width:Number, height:Number}

Default values are:

  • {0, 0, this.actualWidth, this.actualHeight}

Parameters:

  • dimensions Object

    Details of the <canvas> area to be saved

Returns:

String label pointing to where the image has been saved in the scrawl library - scrawl.imageData[STRING]

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

getX

()

Get the current start x coordinate

Returns:

Attribute value

getY

()

Get the current start y coordinate

Returns:

Attribute value

groupSort

() private

groupSort

Returns:

nothing

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

pathPositionInit

() private

Position constructor hook function - modified by path extension

pathPositionSetDelta

() private

Position.setDelta hook function - modified by path extension

pathPrepareToCopyCell

() private

Cell.prepareToCopyCell hook function - modified by path extension

prepareToCopyCell

(
  • engine
)
private chainable

Cell copy helper function

Parameters:

  • engine Object

    Javascript canvas context object

Returns:

This

restoreContext

() chainable

Perform a JavaScript ctx.restore() operation

Returns:

This

restoreShadow

() private chainable

Entity stamp helper function

Returns:

This

rotateDestination

(
  • engine
)
private chainable

Cell copy helper function

Parameters:

  • engine Object

    Javascript canvas context object

Returns:

This

saveContext

() chainable

Perform a JavaScript ctx.save() operation

Returns:

This

set

(
  • items
)
chainable

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

Augments Position.set(), to allow users to set the start, handle, and source attributes using startX, startY, targetX, targetY, handleX, handleY, sourceX, sourceY.

Note - setting the argument attribute resolve to true will force a recalculation of the cell's copy and passte data; this is useful in particular for cells that do not undertake a full display cycle (when their cleared or compiled attributes have been set to false)

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setActualHeight

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setActualWidth

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setCopy

() private chainable

Cell.setCopy update copyData object values

setCopyHeight

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setCopyVector

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setCopyWidth

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDelta

(
  • items
)
chainable

Inherited from Position but overwritten in source\scrawlCore.js:5526

Adds the value of each attribute supplied in the argument to existing values

Augments Position.setDelta to allow changes to be made using attributes: source, sourceX, sourceY, sourceWidth, sourceHeight, start, startX, startY, target, targetX, targetY, targetWidth, targetHeight, globalAlpha

Note - setting the argument attribute resolve to true will force a recalculation of the cell's copy and passte data; this is useful in particular for cells that do not undertake a full display cycle (when their cleared or compiled attributes have been set to false)

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaActualHeight

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaActualWidth

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaCopy

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaCopyHeight

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaCopyWidth

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaGlobalAlpha

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

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

setDeltaHeight

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values. This function accepts height

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaPaste

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaPasteHeight

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaPasteWidth

(
  • items
  • recalc
)
chainable

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setDeltaRoll

(
  • items
)
chainable

Inherited from Position but overwritten in source\scrawlCore.js:5609

Adds the value of each attribute supplied in the argument to existing values

Augments Cell.setDelta

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDeltaScale

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values. This function accepts scale

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

setDeltaWidth

(
  • items
)
chainable

Adds the value of each attribute supplied in the argument to existing values. This function accepts width

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

setDimensions

(
  • [items]
)
chainable

Amend the physical dimensions of the Cell's <canvas> element

Omitting the argument will force the <canvas> to set itself to its Pad object's dimensions

Parameters:

  • [items] Object optional

    Argument with width and/or height attributes, in pixels

Returns:

This

setDirtyHandles

() private chainable

Augments Cell.set()

Returns:

This

setDirtyStarts

() private chainable

Augments Cell.set()

Returns:

This

setEngine

(
  • entity
)
private

Set the Cell's <canvas> context engine to the specification supplied by the entity about to be drawn on the canvas

Parameters:

Returns:

Entity object

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

setPaste

() private chainable

Cell.setPaste update pasteData object values

setPasteHeight

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setPasteVector

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setPasteWidth

(
  • items
  • recalc
)
chainable

Augments Cell.set()

Parameters:

  • items Object

    Object consisting of key:value attributes

  • recalc Boolean

    When true (default), triggers variable recalculation

Returns:

This

setReference

() private

Cell.setPaste helper function

setStampUsingPivot

(
  • [cell]
)
private chainable

Stamp helper function - set this entity, cell or element start values to its pivot entity/point start value, or to the current mouse coordinates

Takes into account lock flag settings

Parameters:

  • [cell] String optional

    CELLNAME String

Returns:

This

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

setToClearShape

() private chainable

Entity stamp helper function

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

actualHeight

Number

DOM <canvas> element's height (not CSS height)

Never change this attribute directly

Default: 150

actualWidth

Number

DOM <canvas> element's width (not CSS width)

Never change this attribute directly

Default: 300

backgroundColor

String

DOM <canvas> element's background color; use any permitted CSS color String

Background colors are achieved via JavaScript canvas API drawing methods. Setting the CSS backgroundColor attribute on a <canvas> element is not recommended

Default: 'rgba(0,0,0,0)'

cleared

Boolean

Display cycle flag - on true (default), the cell will clear itself as part of the display cycle

Default: true

comment

String

Comment, for accessibility

Default: ''

compiled

Boolean

Display cycle flag - on true (default), the cell will compile itself as part of the display cycle

Default: true

compileOrder

Number

Display cycle attribute - order in which the cell will compile itself (if compile attribute = true)

Default: 0

context

String private

CTXNAME of this Cell's Context object

Cells use a Context object to keep track of the settings supplied to its <canvas> element's 2d context engine

Default: ''

copy

Vector

The coordinate Vector representing the Cell's copy source position on its <canvas>

Cell supports the following 'virtual' attributes for this attribute:

  • copyX - (Number) the x coordinate on the source <canvas>
  • copyY - (Number) the y coordinate on the source <canvas>

copyData

Object private

Local source data

Default: false

copyHeight

Number

Copy height, in pixels. Determines which portion of this Cell's <canvas> element will be copied to another <canvas>

Default: 150

copyWidth

Number

Copy width, in pixels. Determines which portion of this Cell's <canvas> element will be copied to another <canvas>

Default: 300

deltaPathPlace

Number

(Added by the path extension) A change value which can be applied to the object's pathPlace attribute

Default: 0

fieldLabel

String

Default: ''

flipReverse

Boolean

Reflection flag; set to true to flip entity, cell or element along the Y axis

Default: false

flipUpend

Boolean

Reflection flag; set to true to flip entity, cell or element along the X axis

Default: false

globalAlpha

Number

Transparency level to be used when copying this Cell's <canvas> element to another <canvas>. Permitted values are between 0 (fully transparent) and 1 (fully opaque)

Default: 1

globalCompositeOperation

String

Composition method to be used when copying this Cell's <canvas> element to another <canvas>. Permitted values include

  • 'source-over'
  • 'source-atop'
  • 'source-in'
  • 'source-out'
  • 'destination-over'
  • 'destination-atop'
  • 'destination-in'
  • 'destination-out'
  • 'lighter'
  • 'darker'
  • 'copy'
  • 'xor'

Be aware that different browsers render these operations in different ways, and some options are not supported by all browsers. The scrawl.device object includes details of which operations the browser supports.

Default: 'source-over'

groups

Array

Array of GROUPNAMES that contribute to building this Cell's scene

Default: []

handle

Object

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

SubScrawl, and all Objects that prototype chain to Subscrawl, 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

height

Number

Entity, cell or element height (in pixels)

Default: 0

lockX

Boolean

Positioning flag; set to true to ignore path/pivot/mouse changes along the X axis

Default: false

lockY

Boolean

Positioning flag; set to true to ignore path/pivot/mouse changes along the Y axis

Default: false

maxDimensions

Object private

An object with the following attributes:

  • left - x coordinate of top-left corner of the enclosing box relative to the current cell's top-left corner
  • top - y coordinate of top-left corner of the enclosing box relative to the current cell's top-left corner
  • bottom - x coordinate of bottom-right corner of the enclosing box relative to the current cell's top-left corner
  • left - y coordinate of bottom-right corner of the enclosing box relative to the current cell's top-left corner

Default: null

mouseIndex

String

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

The Pad.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'

name

String

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

pad

String

PADNAME of the Pad object to which this Cell belongs

Default: ''

pasteData

Object private

Local target data

Default: false

pasteHeight

Number

Paste height, in pixels. Determines where, and at what scale, the copied portion of this Cell's <canvas> will appear on the target Cell's <canvas>

Default: 150

pasteWidth

Number

Paste width, in pixels. Determines where, and at what scale, the copied portion of this Cell's <canvas> will appear on the target Cell's <canvas>

Default: 300

path

String

(Added by the path extension) The ENTITYNAME of a Shape entity whose path is used to calculate this object's start point

Default: ''

pathPlace

Number

(Added by the path extension) A value between 0 and 1 to represent the distance along a Path object's path, where 0 is the path start and 1 is the path end

Default: 0

pathSpeedConstant

Boolean

(Added by the path extension) 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

pivot

String

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

Default: null

rendered

Boolean

Display cycle flag - on true (default), the cell will take part in the display cycle

Default: true

roll

Number

Current rotation of the entity, cell or element (in degrees)

Default: 0

scale

Number

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

Default: 1

shown

Boolean

Display cycle flag - on true (default), the cell will show itself as part of the display cycle

Default: true

showOrder

Number

Display cycle attribute - order in which the cell will show itself (if show attribute = true)

Default: 0

start

Vector

Inherited from Position but overwritten in source\scrawlCore.js:4895

The coordinate Vector representing the Cell's target position on the <canvas> to which it is to be copied

Cell supports the following 'virtual' attributes for this attribute:

  • startX or targetX - (Number) the x coordinate on the destination <canvas>
  • startY or targetY - (Number) the y coordinate on the destination <canvas>

timestamp

String

Creation timestamp

Default: ''

title

String

Title, for accessibility

Default: ''

type

String final

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

Default: 'Cell'

width

Number

Entity, cell or element width (in pixels)

Default: 0