Entity mixin

This mixin builds on the base and position mixins to give Canvas entity objects (Scrawl-canvas Block, Grid, Loom, Label, Picture, Shape, Wheel, etc) the ability to act as artefacts.

Entitys differ from non-entity artefacts in that they are restricted to Cell wrappers (though no harm should come if they are included in Stack-related Groups).

• The entity object represents a set of instructions for rendering graphical lines and shapes onto a <canvas> CanvasRenderingContext2D engine, using the Canvas API to do this
• The engine requirements for the render - fillStyle, font, globalAlpha, globalCompositeOperation, lineCap, lineDash, lineDashOffset, lineJoin, lineWidth, miterLimit, shadowBlur, shadowColor, shadowOffsetX, shadowOffsetY, strokeStyle, textAlign, textBaseline - are kept in a separate State object. Note that these attributes are initialized/updated directly on the entity object
• Entitys can act as hotspots within a <canvas> display; we can create hover and click effects for them

Entitys are, nevertheless, full artefact objects which can interact with other artefacts and the mouse/touch cursor in all the normal ways: positioning (pivot and path) and dimensioning (mimic) functionality; collision detection (including drag-and-drop); etc

Imports

Shared constants

Local constants

Export function

Mixins

Shared attributes

method - String value which tells the entity how it will display itself on the canvas. Available options are:

• draw - stroke the entity outline with the entity’s strokeStyle color, gradient or pattern - including shadow
• fill - fill the entity with the entity’s fillStyle color, gradient or pattern - including shadow
• drawAndFill - stroke the entity’s outline, remove shadow, then fill it
• fillAndDraw - fill the entity’s outline, remove shadow, then stroke it
• drawThenFill - stroke the entity’s outline, then fill it (shadow applied twice)
• fillThenDraw - fill the entity’s outline, then stroke it (shadow applied twice)
• clip - use shape to restrict future drawing area (best used in a separate group)
• clear - remove everything that would have been covered if the entity had performed fill (including shadow)
• none - perform all the calculations required, but don’t perform the final stamping

pathObject - Scrawl-canvas holds details of every type of entity’s outline in a Path2D object - used both for draw/fill operations, and for collision detection work

winding - String with value evenodd or nonzero (default)

• Canvas fill (flood) drawing operations can take into account an entity’s winding choice. Two are available: the non-zero rule; and the even-odd rule

flipReverse, flipUpend - Boolean flags which determine the orientation of the entity when it stamps itself on the display.

• a reversed entity is effectively flipped 180° around a vertical line passing through that entity’s rotation-reflection (start) point - a face looking to the right will now look to the left
• an upended entity is effectively flipped 180° around a horizontal line passing through that entity’s rotation-reflection (start) point - a normal face will now appear upside-down

scaleOutline - Boolean flag. When set, the entity will increase its lineWidth value proportionate to the entity’s scale value - an entity of scale = 2 will display lines twice the thickness of the same entity at scale = 1

scaleShadow - Boolean flag. When set, the entity will increase its shadowOffsetX, shadowOffsetY and shadowBlur values proportionate to the entity’s scale value - an entity of scale = 2 will display shadows twice the size of the same entity at scale = 1

lockFillStyleToEntity, lockStrokeStyleToEntity - Boolean flags.

• When set, these flags instruct any gradient-type style (Scrawl-canvas Gradient, RadialGradient) to map their start and end coordinates to the entity’s dimensions
• Default action is for gradient-type styles to map their coordinates to the host Cell’s dimensions

Event listener functions

Entity objects have the ability to act as ‘hotspots’ within a canvas display, reacting to mouse/pointer movements over the canvas. Four mouse-like events are supported:

• enter - triggers when the cursor passes over the entity’s outline into its fillable area
• down - triggers when a user presses their (left) mouse key while inside the entity’s fillable area
• up - triggers when a user releases their (left) mouse key while inside the entity’s fillable area - this can also be used for capturing mouse click and touch tap actions
• leave - triggers when the cursor passes over the entity’s outline away from its fillable area

The events are regular functions.

• this refers to the entity object, giving the functions access to any attribute and method set on it.
• They can also use variables defined elsewhere in the script code (though these will need to be rehydrated if the entity is packet stored and resurrected - see Demo Canvas-009 tests for an example of doing this)

Scrawl-canvas will not automatically trigger these functions:

• They can be triggered as part of an Animation object’s function checking for hits on a Group of entitys
• Similar checks can be included in a RenderAnimation hook function
• Alternatively we can set up an event listener on the DOM <canvas> element, which invokes a call to cascade a mouse/touch move event down to its associated entitys - in this case the entitys will check the event themselves and trigger the appropriate function

The functions defined in these attributes will be included in entity packet functionality, and can be safely cloned

onEnter - define tasks to be performed for enter events

onLeave - define tasks to be performed for leave events

onDown - define tasks to be performed for down events

onUp - define tasks to be performed for up events

onOtherInteraction - define tasks to be performed for other interaction events

State object attributes

We can treat the following attributes as if they are entity object attributes, though in fact they are stored and managed by State objects

fillStyle and strokeStyle - color, gradient or pattern used to outline or fill a entity. Can be:

• CSS format color String - #fff, #ffffff, rgb(255 255 255), rgb(255 255 255 / 1), rgb(255,255,255), rgba(255,255,255,1), white, etc
• COLORNAME String
• GRADIENTNAME String
• RADIALGRADIENTNAME String
• PATTERNNAME String

globalAlpha - entity transparency - a value between 0 and 1, where 0 is completely transparent and 1 is completely opaque

globalCompositeOperation - compositing method for applying the entity to an existing Cell (<canvas>) display. Permitted values include

• ‘source-over’
• ‘source-atop’
• ‘source-in’
• ‘source-out’
• ‘destination-over’
• ‘destination-atop’
• ‘destination-in’
• ‘destination-out’
• ‘lighter’
• ‘darker’
• ‘copy’
• ‘xor’
• any other permitted value - be aware that different browsers may render these operations in different ways, and some options are not supported by all browsers.

lineWidth - Number (in pixels)

lineCap - how the ends of lines will display. Permitted values include:

• ‘butt’
• ‘round’
• ‘square’

lineJoin - how line joints will display. Permitted values include:

• ‘miter’
• ‘round’
• ‘bevel’

lineDash - an array of integer Numbers representing line and gap values (in pixels), for example [5,2,2,2] for a long-short dash pattern

lineDashOffset - distance along the entity’s outline at which to start the line dash. Changing this value can be used to create a ‘marching ants effect

miterLimit - affecting the ‘pointiness’ of the line join where two lines join at an acute angle

shadowOffsetX, shadowOffsetY - horizontal and vertical offsets for a entity’s shadow, in Number pixels

shadowBlur - the blur width for a entity’s shadow, in Number pixels

shadowColor - the color used for an entity’s shadow effect. Can be:

• CSS format color String - #fff, #ffffff, rgb(255 255 255), rgb(255 255 255 / 1), rgb(255,255,255), rgba(255,255,255,1), white, etc
• COLORNAME String

font, textAlign, textBaseline - the Canvas API standards for using fonts on a canvas are near-useless, and often lead to a sub-par display of text. The Scrawl-canvas Label and EnhancedLabel entitys use these attributes internally, but have their own set of attributes for defining the font styling used by their text.

filter - the Canvas 2D engine supports the filter attribute on an experimental basis, thus it is not guaranteed to work in all browsers and devices. The filter attribute takes a String value (default: ‘none’) defining one or more filter functions to be applied to the entity as it is stamped on the canvas.

• Be aware that entitys can also take a filters Array - this represents an array of Scrawl-canvas filters to be applied to the entity (or group or Cell). The two filter systems are completely separate - combine their effects at your own risk!

Packet management

Clone management

Shared state

Kill management

No additional kill functionality defined here

Get, Set, deltaSet

group - returns the entity’s latest Group’s String name, not the Group object itself

lockStylesToEntity - a pseudo-attribute which will set the lockFillStyleToEntity and lockStrokeStyleToEntity flags to the same Boolean value

Entity get, set and deltaSet functions need to take into account the entity State object, whose attributes can be retrieved/amended directly on the entity object

Prototype functions

entityInit - internal function, called by all entity factory constructors

Display cycle functionality

Entitys - as artefacts - take part in the Display cycle at the compile stage, when Cell wrappers trigger a compile action cascade through their associated Group objects to entity objects included in those groups.

The main entity compile-related functions are:

• prepareStamp - a synchronous function called at the start of the compile step where an entity will check its dirty flags and update position, dimensions and other attributes accordingly.
• stamp - this is where the main drawing activity happens. This function calls one of two other functions: filteredStamp; or regularStamp which in turn rely on the regularStampSynchronousActions function where all the drawing magic happens.

The stamp functionality can be triggered outside of the Display cycle, if required - for instance when compiling a Cell display setup as a static background layer, which excludes itself from the Display cycle cascade’s clear and compile steps.

Step 1: prepare the entity for stamping

prepareStamp - all entity objects need to check the following dirty flags and take corrective action when a flag is set.

• The order in which flags get checked is important!
• As part of the checking process, additional dirty flags may be set early in the function, for processing later on in the function.

If an entity relies on another artefact as a pivot, mimic or path reference, those artefacts should be processed earlier in the compile cascade. This can be achieved by:

• Placing the reference artefacts in a different Group, whose order attribute has been set to a lower value than this entity’s Group’s order value
• If both entity and reference artefact are in the same Group, give this entity an order value higher than its reference.
• If both entity and the reference artefact are in the same Group, and have the same order value, then make sure that the reference artefact is defined in code before the entity.

Note that some entity factories need to overwrite this function to meet their particular requirements. Many of the clean functions mentioned below are defined in the position mixin.

dirtyHost - set by a Cell wrapper on the entitys associated with it (via the Cell’s associated Group objects) whenever the Cell’s dimensions change. The entity sets its own dirtyDimensions flag as a result.

A number of updates (scale, dimensions, start, offset, handle) require the entity to recalculate its Path2D object - if any of them are set, then the entity sets its own dirtyPathObject flag as a result.

dirtyScale - triggers cleanScale function - which in turn sets the dirtyDimensions, dirtyHandle and (if required) dirtyPositionSubscribers, dirtyMimicScale flags on the entity.

dirtyDimensions - triggers cleanDimensions function - which in turn sets the dirtyStart, dirtyHandle, dirtyOffset and (if required) dirtyPositionSubscribers, dirtyMimicDimensions flags on the entity.

dirtyLock - triggers cleanLock function - which in turn sets the dirtyStart and dirtyHandle flags on the entity.

dirtyStart - triggers cleanStart function - which in turn sets the dirtyStampPositions flag on the entity.

dirtyOffset - triggers cleanOffset function - which in turn sets the dirtyStampPositions and (if required) dirtyMimicOffset flags on the entity.

dirtyHandle - triggers cleanHandle function - which in turn sets the dirtyStampHandlePositions and (if required) dirtyMimicHandle flags on the entity.

dirtyRotation - triggers cleanRotation function - which in turn sets (if required) dirtyMimicRotation, dirtyPivotRotation, dirtyPositionSubscribers flags on the entity.

To handle situations where the entity position is currently under the influence of the mouse/touch cursor - where true, entity will set its own dirtyStampPositions, dirtyStampHandlePositions flags

Invoke the cleanStampPositions and cleanStampHandlePositions functions, if needed, to update current positional data prior to the stamping operation. Both functions will set the dirtyPositionSubscribers flag if changes to positional values result from the calculations.

If the entity’s Path2D object has been marked as dirty by the dirtyPathObject flag, rebuild it by invoking the cleanPathObject function.

dirtyPositionSubscribers - update any artefacts subscribed to this entity as their pivot or mimic source, if required, by invoking the updatePositionSubscribers function.

prepareStampTabsHelper is defined in the mixin/hidden-dom-elements.js file - handles updates to anchor and button objects

The dirtyFilters flag is checked and handled by the filteredStamp function.

cleanPathObject - this function will be overwritten by every entity Factory, to meet their individual requirements.

• The function needs to build a Canvas API Path2D object and store it in the pathObject attribute. The Path2D object is used for both entity stamping (see below) and entity collision detection work.

Step 2: invoke the entity’s stamp action

stamp - this is the function invoked by Group objects as they cascade the Display cycle compile step through to their member artefacts.

To note: checkHitIgnoreTransparency is specific to Picture entity

regularStamp - this function coordinates the actions required for an entity to display its output on a Cell wrapper’s <canvas> element.

Scrawl-canvas stamps an entity onto a Cell by moving and rotating the Cell engine’s transformation (its coordinate grid) to match the entity’s start and offset coordinates, alongside any requirements to rotate (roll) and flip (flipReverse, flipUpend) the transformation as set out by the entity object.

• We use the Web API CanvasRenderingContext2D engine’s setTransform method to perform these actions when we invoke the Cell wrapper’s rotateDestination function.
• We never invoke the engine’s translate, rotate or scale methods on the transformation. All positional, rotational and scaling data is kept in the entity object, and calculated as part of its prepareStamp step. This means we don’t need to keep track of the transformation’s current state, and makes the entity stamping operation more efficient.
• Scrawl-canvas does not support skew operations on the transformation - use a more appropriately shaped entity instead.
• Scrawl-canvas does not support non-isometric scaling (applying different scaling factors along the x and y axes) - most entitys include width and height attributes: use those instead.
• We only use the transformation’s save and restore methods where it makes sense to do so - for instance in very limited actions where the save and restore invocations are close enough in the code base that we don’t lose sight of them (and remember to restore after the action completes). They are not used when updating the engine’s attributes to match an entity’s stamping requirements!

Get the Cell wrapper to perform required transformations on its <canvas> element’s 2D engine

Get the Cell wrapper to update its 2D engine’s attributes to match the entity’s requirements

Invoke the appropriate stamping method (below)

filteredStamp - handles stamping functionality for all entitys that have filter functions associated with them.

Clean and sort the Entity-level filters before sending them to the filter engine for application

Save current host data into a set of vars, ready for restoration after web engine completes or fails

Get and prepare a pool Cell for the filter operations

Switch off fast stamp

Handle GCO and GA

Stamp the entity onto the pool Cell

Restore GCO and GA

If we’re using the entity as a stencil, copy the entity cell’s current display over the entity in the pool Cell

To note: checkHitIgnoreTransparency is specific to Picture entity

This is also the point at which we action any requests to stash the Cell output and (optionally) create/update imageAsset objects and associated <img> elements for use elsewhere in the Scrawl-canvas ecosystem.

KNOWN ISSUE - it takes time for the images to load the new dataURLs generated from canvas elements. See demo Canvas-020 for a workaround.

getCellCoverage - internal helper function - calculates the box start and dimensions values for the entity on its current Cell host, to help minimize work required when applying filters to the entity output. Also used when building an image when the scrawl.createImageFromEntity function is invoked.

simpleStamp - an alternative to the stamp function, to get an entity to stamp its output onto a Cell.

• Note that this is a synchronous action, thus cannot be included in a Display cycle cascade.
• Will ignore any filters assigned to the entity

Stamp methods

All actual drawing is achieved using the entity’s pre-calculated Path2D object.

draw - stroke the entity outline with the entity’s strokeStyle color, gradient or pattern - including shadow

fill - fill the entity with the entity’s fillStyle color, gradient or pattern - including shadow

drawAndFill - stamp the entity stroke, then fill, then remove shadow and repeat

drawAndFill - stamp the entity fill, then stroke, then remove shadow and repeat

drawThenFill - stroke the entity’s outline, then fill it (shadow applied twice)

fillThenDraw - fill the entity’s outline, then stroke it (shadow applied twice)

clip - restrict drawing activities to the entity’s enclosed area

clear - remove everything that would have been covered if the entity had performed fill (including shadow)

none - perform all the calculations required, but don’t perform the final stamping