makeDragZone is an attempt to make setting up drag-and-drop functionality within a Scrawl-canvas stack or canvas as simple as possible. The functionality has been designed to allow multiple drag zones to be set on a canvas or stack element, while limiting the number of event listeners that need to be applied to the element to make the magic happen.
Required attribute of the argument object:
Additional, optional, attributes in the argument object
here objecthere objectAt the heart of the drag zone are a set of functions (or alternatively, objects that can be applied to the selected artefact) which define the actions that happen when a user starts, continues and stops dragging an artefact in the zone. It is possible to set different actions depending on whether the user is pressing the shift button while they perform the drag action:
set object to be applied to the current artefactset object to be applied to the current artefactMultiple drag zones can be defined on a canvas or stack element. When a user presses the mouse button to start a drag the code will interrogate each drag zone in turn to discover if one of them has an artefact which collides with the mouse cursor; if yes, that drag zone takes precedence for the subsequent move and drop actions
If the exposeCurrentArtefact attribute is true, the makeDragZone factory returns a function that can be invoked at any time to get the collision data object (containing x, y, artefact attributes) for the artefact being dragged (false if nothing is being dragged). The function can also be triggered with the following string arguments:
'exit' or 'drop - force the drag action to endIf the exposeCurrentArtefact attribute is false, or omitted, the function returns a kill function that can be invoked (with no arguments) to remove the event listeners from the Stack or Canvas zone’s DOM element.
import * as library from "../core/library.js";
import { xta, isa_fn, isa_boolean, isa_obj, λnull, Ωempty } from "../helper/utilities.js";
import { addListener, removeListener } from "../core/events.js";
import { touchAction } from "../core/user-interaction.js";Shared constants
import { _isArray, $BODY, ACCEPTED_WRAPPERS, DOWN, MOVE, T_CANVAS, T_GROUP, TOUCH_CANCEL, TOUCH_END, TOUCH_MOVE, TOUCH_START, UP } from "../helper/shared-vars.js";Local constants
const DROP = 'drop',
EXIT = 'exit';NOTE: drag-and-drop functionality using this factory function is not guaranteed for artefacts referencing a path, or for artefacts whose reference artefact in turn references another artefact in any way.
const dragZones = {};Generate the drag zone and associate it with the zone element
const processDragZoneData = function (items = Ωempty, doAddListeners, doRemoveListeners) {
let {
zone,
coordinateSource,
collisionGroup,
startOn,
endOn,
updateOnStart,
updateOnEnd,
updateWhileMoving,
updateOnShiftStart,
updateOnShiftEnd,
updateWhileShiftMoving,
updateOnPrematureExit,
exposeCurrentArtefact,
preventTouchDefaultWhenDragging,
resetCoordsToZeroOnTouchEnd,
processingOrder,
} = items; if (!zone) return new Error('dragZone constructor - no zone supplied');
if (zone.substring) zone = library.artefact[zone];
if (!zone || !ACCEPTED_WRAPPERS.includes(zone.type)) return new Error('dragZone constructor - zone object is not a Stack or Canvas wrapper');
const target = zone.domElement;
if (!target) return new Error('dragZone constructor - zone does not contain a target DOM element'); if (!collisionGroup) {
if (zone.type === T_CANVAS) collisionGroup = library.group[zone.base.name];
else collisionGroup = library.group[zone.name];
}
else if (collisionGroup.substring) collisionGroup = library.group[collisionGroup];
if (!collisionGroup || collisionGroup.type !== T_GROUP) return new Error('dragZone constructor - unable to recover collisionGroup group');coordinateSource will be an object containing x and y attributes
here object if (coordinateSource) {
if (coordinateSource.here) coordinateSource = coordinateSource.here;
else if (!xta(coordinateSource.x, coordinateSource.y)) coordinateSource = false;
}
else {
if (zone.type === T_CANVAS) coordinateSource = zone.base.here;
else coordinateSource = zone.here;
}
if (!coordinateSource) return new Error('dragZone constructor - unable to discover a usable coordinateSource object');startOn, endOn - if supplied, then need to be arrays
if (!_isArray(startOn)) startOn = [DOWN];
if (!_isArray(endOn)) endOn = [UP];
if (exposeCurrentArtefact == null) exposeCurrentArtefact = false;
if (preventTouchDefaultWhenDragging == null) preventTouchDefaultWhenDragging = false;
if (resetCoordsToZeroOnTouchEnd == null) resetCoordsToZeroOnTouchEnd = true;updateOnStart, updateOnEnd, updateOnShiftStart, updateOnShiftEnd - if supplied, then needs to be key:value objects which will be applied to the entity (using set) or, alternatively, a callback function
if (isa_obj(updateOnStart)) updateOnStart = function () { current.artefact.set(items.updateOnStart) };
if (!isa_fn(updateOnStart)) updateOnStart = λnull;
if (isa_obj(updateOnShiftStart)) updateOnShiftStart = function () { current.artefact.set(items.updateOnShiftStart) };
if (!isa_fn(updateOnShiftStart)) updateOnShiftStart = updateOnStart;
if (isa_obj(updateOnEnd)) updateOnEnd = function () { current.artefact.set(items.updateOnEnd) };
if (!isa_fn(updateOnEnd)) updateOnEnd = λnull;
if (isa_obj(updateOnShiftEnd)) updateOnShiftEnd = function () { current.artefact.set(items.updateOnShiftEnd) };
if (!isa_fn(updateOnShiftEnd)) updateOnShiftEnd = updateOnEnd;updateWhileMoving, updateWhileShiftMoving - if supplied, needs to be a callback function
if (!isa_fn(updateWhileMoving)) updateWhileMoving = λnull;
if (!isa_fn(updateWhileShiftMoving)) updateWhileShiftMoving = updateWhileMoving;updateOnPrematureExit - if supplied, needs to be a callback function
if (!isa_fn(updateOnPrematureExit)) updateOnPrematureExit = λnull;exposeCurrentArtefact - if supplied, then needs to be a boolean
if (!isa_boolean(exposeCurrentArtefact)) exposeCurrentArtefact = false;
if (processingOrder == null) processingOrder = 0;We can only drag one artefact at a time; that artefact - alongside the hit coordinate’s x and y values - is stored in the current variable
let current = false;
const checkE = function (e) {
if (e && e.cancelable) {
if (preventTouchDefaultWhenDragging && current) {
e.preventDefault();
e.returnValue = false;
}
else if (!preventTouchDefaultWhenDragging) {
e.preventDefault();
e.returnValue = false;
}
}
};
const pickup = function (e = Ωempty) {
checkE(e);
const type = e.type;
if (type === TOUCH_START || type === TOUCH_CANCEL) touchAction(e, resetCoordsToZeroOnTouchEnd);
current = collisionGroup.getArtefactAt(coordinateSource);
if (current) {
current.artefact.pickupArtefact(coordinateSource);
if (e.shiftKey) updateOnShiftStart(e);
else updateOnStart(e);
}
return {
current,
move,
drop,
};
};
const move = function (e = Ωempty) {
if (current) {
checkE(e);
const type = e.type;
if (type === TOUCH_MOVE) touchAction(e);
if (e.shiftKey) updateWhileShiftMoving(e);
else updateWhileMoving(e);
}
};
const drop = function (e = Ωempty) {
if (current) {
checkE(e);
const type = e.type;
if (type === TOUCH_END) {
touchAction(e, resetCoordsToZeroOnTouchEnd);
}
current.artefact.dropArtefact();
if (e.shiftKey) updateOnShiftEnd(e);
else updateOnEnd(e);
current = false;
}
};
if (!dragZones[zone.name]) {
dragZones[zone.name] = [];
doAddListeners(startOn, endOn, target);
}
const kill = function () {
const name = `${zone.name}_${collisionGroup.name}_${processingOrder}`;
dragZones[zone.name] = dragZones[zone.name].filter(z => z.name !== name);
if (!dragZones[zone.name].length) {
doRemoveListeners(startOn, endOn, target);
delete dragZones[zone.name];
}
};
const getCurrent = function (actionKill) {
if (actionKill) {
if (actionKill === EXIT || actionKill === DROP) {
drop();
updateOnPrematureExit();
}
else kill();
}
else return current;
};
const data = {
name: `${zone.name}_${collisionGroup.name}_${processingOrder}`,
exposeCurrentArtefact,
target,
processingOrder,
pickup,
move,
drop,
kill,
getCurrent,
};
dragZones[zone.name].push(data);
dragZones[zone.name].sort((a, b) => a.processingOrder - b.processingOrder);
return {
exposeCurrentArtefact,
getCurrent,
kill,
zone,
};
};Exported function (to modules and the SC object). Add drag-and-drop functionality to a canvas or stack wrapper.
export const makeDragZone = function (items = Ωempty) {The exposed pickup function will search for the target element (if user has started the drag while the mouse cursor was over a child of the Stack wrapper) and then interrogate each drag zone associated with that target until it finds a zone reporting a hit
const pickup = (e = Ωempty) => {
if (e && e.target) {name cannot be ZERO_STR
let myTarget = e.target,
name = '';
while (!name) {
if (dragZones[myTarget.id]) name = myTarget.id;
if (myTarget.tagName === $BODY) break;
myTarget = myTarget.parentElement;
}
const variants = dragZones[name];
if (variants) {
for (let i = 0, iz = variants.length; i < iz; i++) {
const v = variants[i];
const res = v.pickup(e);
if (res.current) {
currentMove = res.move;
currentDrop = res.drop;
break;
}
}
}
}
};The exposed move and drop functions will change to match the equivalent funtions supplied by the zone selected during the pickup stage of the operation
let currentMove = λnull;
const move = (e = Ωempty) => {
currentMove(e);
};
let currentDrop = λnull;
const drop = (e = Ωempty) => {
currentDrop(e);
currentMove = λnull;
currentDrop = λnull;
};Listeners are added to the DOM element when the first drag zone is created for that target
const doAddListeners = (startOn, endOn, target) => {
addListener(startOn, pickup, target);
addListener(MOVE, move, target);
addListener(endOn, drop, target);
};Listeners are only removed from the DOM element when all the drag zones associated with that target have been killed
const doRemoveListeners = (startOn, endOn, target) => {
removeListener(startOn, pickup, target);
removeListener(MOVE, move, target);
removeListener(endOn, drop, target);
};
const processedData = processDragZoneData(items, doAddListeners, doRemoveListeners);Return the appropriate function based on the value of the exposeCurrentArtefact attribute
if (processedData.exposeCurrentArtefact) return processedData.getCurrent;
else return processedData.kill;
};