Mobile Events using HammerJS

This module adds mobile events to the `event-dom` module. It integrates all of HammerJS into the eventsystem.

The loaderfiles combine event, event-dom and event-mobile all into ITSA.Event.

Getting Started

The module event-mobile is a typical browser-module.

For browser-usage, ITSA has a predefined loaderfiles. Once included, a global ITSA object with default features is available. For customized loaderfiles, read: Customized build.

<script src="/itsabuild-min.js"></script>

<script>
    var Event = ITSA.Event;
</script>

When using your own customized build-file, this module-requirement needs to be invoked with the window-object.

The Basics

Gesture events are very complex to manage. That's why we choose the library HammerJS and integrated it into our eventsystem. Once the module is merged into the eventsystem, you can subscribe to all the events that come with HammerJS:

Example: listening to gesture-events

var showMsg = function(e) {
    // e.target is the node that was swiped
    alert(e.target.id + 'got swiped');
};

Event.after('swipe', showMsg, '#go');

Available events

Many gesture-events are available right out of the box. You can even create customized gesture-events: see Extending gesture-events. For updated information, you best look at HammerJS itself. The events are grouped by recognizers:

pan events

see: HammerJS - pan recognizers
Recognized when the pointer is down and moved in the allowed direction.

Option	Default	Description
event	pan	Name of the event.
pointers	1	Required pointers. 0 for all pointers.
threshold	10	Minimal pan distance required before recognizing.
direction	DIRECTION_ALL	Direction of the panning.

Events:

pan, together with all of below
panstart
panmove
panend
pancancel
panleft
panright
panup
pandown

pinch events

see: HammerJS - pinch recognizers
Recognized when two or more pointers are moving toward (zoom-in) or away from each other (zoom-out).

Option	Default	Description
event	pinch	Name of the event.
pointers	2	Required pointers, with a minimal of 2.
threshold	0	Minimal scale before recognizing.

Events:

pinch, together with all of below
pinchstart
pinchmove
pinchend
pinchcancel
pinchin
pinchout

press events

see: HammerJS - press recognizers
Recognized when the pointer is down for x ms without any movement.

Option	Default	Description
event	press	Name of the event.
pointers	1	Required pointers.
threshold	5	Minimal movement that is allowed while pressing.
time	500	Minimal press time in ms.

Events:

press

rotate events

see: HammerJS - rotate recognizers
Recognized when two or more pointer are moving in a circular motion.

Option	Default	Description
event	rotate	Name of the event.
pointers	2	Required pointers, with a minimal of 2.
threshold	0	Minimal rotation before recognizing.

Events:

rotate, together with all of below
rotatestart
rotatemove
rotateend
rotatecancel

swipe events

see: HammerJS - swipe recognizers
Recognized when the pointer is moving fast (velocity), with enough distance in the allowed direction.

Option	Default	Description
event	swipe	Name of the event.
pointers	1	Required pointers.
threshold	10	Minimal distance required before recognizing.
direction	DIRECTION_ALL	Direction of the panning.
velocity	0.65	Minimal velocity required before recognizing, unit is in px per ms.

Events:

swipe, together with all of below
swipeleft
swiperight
swipeup
swipedown

tap events

see: HammerJS - tap recognizers
Recognized when the pointer is doing a small tap/click. Multiple taps are recognized if they occur between the given interval and position. The eventData from the emitted event contains the property tapCount, which contains the amount of multi-taps being recognized.

If an Tap recognizer has a failing requirement, it waits the interval time before emitting the event. This is because if you want to only trigger a doubletap, hammer needs to see if any other taps are comming in. Read more about requireFailure.

Option	Default	Description
event	swipe	Name of the event.
pointers	1	Required pointers.
threshold	10	Minimal distance required before recognizing.
direction	DIRECTION_ALL	Direction of the panning.
velocity	0.65	Minimal velocity required before recognizing, unit is in px per ms.

Events:

tap
doubletap
trippletap

Properties of eventobject

All events that Hammer triggers all receive an event object containing the following properties (bold properties are generated by our Event-system):

Name	Value
target	DOMnode that received the event.
type	eventName. Like `click`.
emitter	emitterName of the emitter. Will always be 'UI' because it is a DOM-event
returnValue	Returnvalue of the default-function
status	Object holding the status about what happened to the event. Has the following properties: e.status.ok --> `true \| false` whether the event got executed (not halted or defaultPrevented) e.status.defaultFn _(optional)_ --> `true` if any defaultFn got invoked e.status.preventedFn _(optional)_ --> `true` if any preventedFn got invoked e.status.halted _(optional)_ --> `reason \| true` if the event got halted and optional the why e.status.defaultPrevented _(optional)_ --> `reason \| true` if the event got defaultPrevented and optional the why e.status.propagationStopped _(optional)_ --> `DOMnode` the DOMnode on which propagation was stopped e.status.immediatePropagationStopped _(optional)_ --> `DOMnode` the DOMnode on which immediatePropagation was stopped e.status.unSilencable _(optional)_ --> `true` if the event cannot be made silent
deltaX	Movement of the X axis.
deltaY	Movement of the Y axis.
deltaTime	Total time in ms since the first input.
distance	Distance moved.
angle	Angle moved.
velocityX	Velocity on the X axis, in px/ms.
velocityY	Velocity on the Y axis, in px/ms
velocity	Highest velocityX/Y value.
direction	Direction moved. Matches the `DIRECTION` constants.
offsetDirection	Direction moved from it's starting point. Matches the `DIRECTION` constants.
scale	Scaling that has been done when multi-touch. 1 on a single touch.
rotation	Rotation that has been done when multi-touch. 0 on a single touch.
center	Center position for multi-touch, or just the single pointer.
srcEvent	Source event object, type `TouchEvent`, `MouseEvent` or `PointerEvent`.
pointerType	Primary pointer type, could be `touch`, `mouse`, `pen` or `kinect`.
eventType	Event type, matches the `INPUT` constants.
isFirst	`true` when the first input.
isFinal	`true` when the final (last) input.
pointers	Array with all pointers, including the ended pointers (`touchend`, `mouseup`).
changedPointers	Array with all new/moved/lost pointers.
preventDefault	Reference to the `srcEvent.preventDefault()` method. Only for experts!

Extending gesture-events

Once this module is integrated, Event has two members that can be used to control gesture-events:

Event.Hammer: reference to the Hammer-Class
Event.hammertime the Hammer-instance which is responsible for handling all gesture-events

These are automaticly created. You can use these to finetune gesture-events or to define new gesture-events.

Add gesture-event

You can add custome gesture-events. Event.hammertime comes with the default set of events with extra doubletap and tripletap events. You can extend the set of events by adding custom gesture-events.

Example adding quadrotap event

quadrotap = new Event.Hammer.Tap({ event: 'quadrotap', taps: 4 });
Event.hammertime.add(quadrotap);

singletap = Event.hammertime.get('tap');
doubletap = Event.hammertime.get('doubletap');
tripletap = Event.hammertime.get('tripletap');

quadrotap.recognizeWith([tripletap, doubletap, singletap]);

Finetuning events

You can finetune your events. Just get them from Event.hammertime and change its properties.

For example, doubletapping will emit a doubletap event and two singletap events. To prevent this, use Event.Hammer.requireFailure on both doubletap and tripletap. Not however, that a tap-event (single) will always wait until it is sure there was no double or tripletap. Therefore the userexperience will be slowered down.

Example doubletap without singletap

singletap = Event.hammertime.get('tap');
doubletap = Event.hammertime.get('doubletap');
tripletap = Event.hammertime.get('tripletap');

singletap.requireFailure([tripletap, doubletap]);

Event.after('tap', showMsgSingle, '#buttongo');
Event.after('doubletap', showMsgDouble, '#buttongo');

HammerJS Documentation

Read more about how to get more out of HammerJS in its API. Remember that you can use all stuff, but should not create your own Hammer-instance. Use the Hammer-instance available at Event.hammertime**.

API Docs

Table of Contents