API Docs for: 6.0.1
Show:

ElementGroup Class

Extends Base
Module: scrawlStacks

ElementGroup

Instantiation

  • scrawl.makeElementGroup()

Purpose

  • associates DOM elements with a Stack object, for rendering the stack scene
  • groups DOM elements for specific purposes

Access

  • scrawl.group.GROUPNAME - for the ElementGroup object
  • scrawl.stack[scrawl.group.ELEMENTGROUPNAME.stack] - for the ElementGroup object's default Stack object

Constructor

ElementGroup

(
  • [items]
)

Parameters:

  • [items] Object optional

    Key:value Object argument for setting attributes

Methods

addElementsToGroup

(
  • item
)
chainable

Add elements to the Group

Parameters:

  • item Array

    Array of ELEMENTNAME Strings; alternatively, a single ELEMENTNAME String can be supplied as the argument

Returns:

This

addEntitysToGroup

()

Directly calls the equivalent Group function

checkEqualDimensions

()

check whether this.equalHeight or this.equalWidth has been set to true

Returns:

True if either equalWidth or equalHeight is true; false otherwise

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

domInit

() chainable

Reinitialize group elements with existing values

Returns:

This

filtersGroupInit

()

Directly calls the equivalent Group function

forceStamp

()

Directly calls the equivalent Group function

get

(
  • item
)

Retrieve an attribute value. If the attribute value has not been set, then the default value for that attribute will be returned.

Parameters:

  • item String

    Attribute key

Returns:

Attribute value

Example:

var box = scrawl.makeBlock({
    width: 50,
    });
box.get('width');               //returns 50
box.get('height');              //returns 0
box.get('favouriteAnimal');     //returns undefined

getAllAt

(
  • items
)

Check all entitys and elements in the Group to see if they are colliding with the supplied coordinate.

Parameters:

  • items Vector

    Coordinate vector; alternatively an Object with x and y attributes can be used

Returns:

Entity object, or false if no entitys are colliding with the coordinate

getAllElementsAt

(
  • items
)

Check all elements in the Group to see if they are colliding with the supplied coordinate.

Parameters:

  • items Vector

    Coordinate vector; alternatively an Object with x and y attributes can be used

Returns:

Array of Stack, Pad and Element objects

getAllEntitysAt

()

Directly calls the equivalent Group function

getAt

(
  • items
  • if
)

Return the entity or element at a given coordinate (in that order)

Parameters:

  • items Vector

    Coordinate vector; alternatively an Object with x and y attributes can be used

  • if Boolean

    true, elements are checked first; default is false

Returns:

entity or element, or false

getByMouseIndex

(
  • item
)

Check all entitys and elements in the Group to see which one(s) are associated with a particular mouse index

Parameters:

  • item String

    Mouse index string

Returns:

Array of Entity, Stack, Pad and Element objects

getElementAt

(
  • items
)

Return the element at a given coordinate (in that order)

Parameters:

  • items Vector

    Coordinate vector; alternatively an Object with x and y attributes can be used

Returns:

element, or false

getElementGroupDimensions

()

Get collective dimensions of ElementGroup elements

Returns:

Object with width and height attributes

getElementsByMouseIndex

(
  • item
)

Check all elements in the Group to see which one(s) are associated with a particular mouse index

Parameters:

  • item String

    Mouse index string

Returns:

Array of Stack, Pad and Element objects

getEntityAt

()

Directly calls the equivalent Group function

getEntitysByMouseIndex

()

Directly calls the equivalent Group function

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

pivotElementsTo

(
  • item
)
chainable

Require all elements in the Group to set their pivot attribute to the supplied STACKNAME, PADNAME, ELEMENTNAME, POINTNAME or SPRITENAME string, and set their handle Vector to reflect the current vector between that object's start Vector and their own Vector

This has the effect of turning a set of disparate eelements into a single, coordinated group.

Parameters:

  • item String

    STACKNAME, PADNAME, ELEMENTNAME, POINTNAME or SPRITENAME String

Returns:

This

pivotEntitysTo

()

Directly calls the equivalent Group function

removeElementsFromGroup

(
  • item
)
chainable

Remove elements from the Group

Parameters:

  • item Array

    Array of ELEMENTNAME Strings; alternatively, a single ELEMENTNAME String can be supplied as the argument

Returns:

This

removeEntitysFromGroup

()

Directly calls the equivalent Group function

render

() chainable

Tell the Group to ask its constituent elements to render

Returns:

This

renderPads

() chainable

Tell the Group to ask its constituent pads to render - will cascade through to sub-stacks

Returns:

This

set

()

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

Directly calls the equivalent Group function

setDirtyHandles

() private chainable

Augments ElementGroup.set()

Returns:

This

setDirtyStarts

() private chainable

Augments ElementGroup.set()

Returns:

This

setElementsTo

(
  • items
)
chainable

Ask all elements in the Group to perform a set() operation

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

setEntitysTo

()

Directly calls the equivalent Group function

setEntitysTo

(
  • items
)
chainable

Ask all elements and entitys in the Group to perform a set() operation

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

sortElements

(
  • [force]
)
private

Element sorting routine - elements are sorted according to their element.order attribute value, in ascending order

Order values are treated as integers. The sort routine is a form of bucket sort, and should be stable (elements with equal order values should not be swapped)

Parameters:

  • [force] Boolean optional

    Force a resort, whatever the settings of the group's entitySort and resort attributes

Returns:

Nothing

sortEntitys

()

Directly calls the equivalent Group function

stamp

()

Directly calls the equivalent Group function

update

(
  • items
)
chainable

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

Parameters:

  • items Object

    Object consisting of key:value attributes

Returns:

This

updateBy

(
  • items
)
chainable

Ask all elements and entitys in the Group to perform a setDelta() operation

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

updateDimensions

(
  • items
)
chainable

Ask all elements in the Group to perform a dimension update operation

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

updateElementsBy

(
  • items
)
chainable

Ask all elements in the Group to perform a setDelta() operation

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

updateEntitysBy

()

Directly calls the equivalent Group function

Properties

comment

String

Comment, for accessibility

Default: ''

currentHeight

Number

Current value of takkest element height

Default: 0

currentWidth

Number

current value of widest element width

Default: 0

elements

Array

Array of ELEMENTNAME Strings of elements that complement this ElementGroup

Default: []

entitys

Array

Array of SPRITENAME Strings of entitys that complement this ElementGroup

Default: []

equalHeight

Boolean

When true, forces all elements (including stacks, pads) to use the height of the currently tallest element; default: false

Default: false

equalWidth

Boolean

When true, forces all elements (including stacks, pads) to use the width of the currently widest element; default: false

Default: false

name

String

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

recalculateDimensions

Boolean

STACKNAME of the default Stack object to which this group is associated

Default: false

stack

String

STACKNAME of the default Stack object to which this group is associated

Default: ''

timestamp

String

Creation timestamp

Default: ''

title

String

Title, for accessibility

Default: ''

type

String final

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

Default: 'ElementGroup'