API Docs for: 6.0.1
Show:

Group Class

Extends Base
Module: scrawlCore

Group

Instantiation

  • scrawl.makeGroup()

Purpose

  • associates entity objects with a cell object, for stamping/compiling the <canvas> scene
  • groups Entity objects for specific purposes
  • (with collisions extension) plays a key role in collision detection between Entitys

Access

  • scrawl.group.GROUPNAME - for the Group object
  • scrawl.cell[scrawl.group.GROUPNAME.cell] - for the Group object's default Cell object

Constructor

Group

(
  • [items]
)

Parameters:

  • [items] Object optional

    Key:value Object argument for setting attributes

Methods

addEntitysToGroup

(
  • item
)
chainable

Add entitys to the Group

Parameters:

  • item Array

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

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

forceStamp

(
  • [method]
  • [cellname]
  • [cell]
  • [mouse]
)
chainable

Tell the Group to ask all of its constituent entitys to draw themselves on a <canvas> element, regardless of their visibility

Parameters:

  • [method] String optional

    Drawing method String

  • [cellname] String optional

    CELLNAME of cell on which entitys are to draw themselves

  • [cell] Object optional

    cell wrapper object

  • [mouse] Vector optional

    coordinates to be used for any entity currently pivoted to a mouse/touch event

Returns:

This

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

getAllEntitysAt

(
  • items
)

Check all entitys in the Group to see if they are colliding with the supplied coordinate. The check is done in reverse order after the entitys have been sorted; all entitys (in the group) colliding with the coordinate are returned as an array of entity objects

Parameters:

  • items Vector

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

Returns:

Array of Entity objects

getEntityAt

(
  • items
)

Check all entitys in the Group to see if they are colliding with the supplied coordinate. The check is done in reverse order after the entitys have been sorted; the entity Object with the highest order value that is colliding with the coordinate is returned

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

getEntitysByMouseIndex

(
  • item
)

Check all entitys 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 objects

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

pivotEntitysTo

(
  • item
)
chainable

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

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

Parameters:

  • item String

    SPRITENAME or POINTNAME String

Returns:

This

removeEntitysFromGroup

(
  • item
)
chainable

Remove entitys from the Group

Parameters:

  • item Array

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

Returns:

This

set

(
  • items
)
chainable

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

set

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

setDirtyHandles

() private chainable

Augments Group.set()

Returns:

This

setDirtyStarts

() private chainable

Augments Group.set()

Returns:

This

setEntitysTo

(
  • items
)
chainable

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

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

sortEntitys

(
  • [force]
)
private

Entity sorting routine - entitys are sorted according to their entity.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 (entitys 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

stamp

(
  • [method]
  • [cellname]
  • [cell]
  • [mouse]
)
chainable

Tell the Group to ask its constituent entitys to draw themselves on a <canvas> element; only entitys whose visibility attribute is set to true will comply

Parameters:

  • [method] String optional

    Drawing method String

  • [cellname] String optional

    CELLNAME of cell on which entitys are to draw themselves

  • [cell] Object optional

    cell wrapper object

  • [mouse] Vector optional

    coordinates to be used for any entity currently pivoted to a mouse/touch event

Returns:

This

updateEntitysBy

(
  • items
)
chainable

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

start delta coordinates can be supplied in the form of x and y attributes in the argument object, in addition to the more normal startX and startY attributes

Parameters:

  • items Object

    Object containing attribute key:value pairs

Returns:

This

Properties

cell

String

CELLNAME of the default Cell object to which this group is associated

Default: ''

comment

String

Comment, for accessibility

Default: ''

entitys

Array

Array of SPRITENAME Strings of entitys that comprise this Group

Default: []

entitySort

Boolean

Sorting flag - when set to true, Groups will sort their constituent entity object according to their entity.order attribute for each iteration of the display cycle

Default: true

name

String

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

order

Number

Group order value - lower order Groups are drawn on <canvas> elements before higher order Groups

Default: 0

regionRadius

Number

Collision checking radius, in pixels - as a first step in a collision check, the Group will winnow potential collisions according to how close the checked entity is to the current reference entity or mouse coordinate; when set to 0, this collision check step is skipped and all entitys move on to the next step

Default: 0

resort

Boolean private

Resort flag

Default: false

timestamp

String

Creation timestamp

Default: ''

title

String

Title, for accessibility

Default: ''

type

String final

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

Default: 'Group'

visibility

Boolean

Visibility flag - Group entitys will (in general) not be drawn on a <canvas> element when this flag is set to false

Default: true