Module-documentation

version 1.0.0
module: event-mobile version 0.0.1
size-min gzipped: 11.82 kb (incl. dependencies: kb)
dependencies: polyfill, js-ext/lib/function.js, js-ext/lib/object.js, utils, event, event-dom, hammerjs (npm)
maintanance: Marco Asbreuk
home


all modules

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

With nodejs:

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

In the browser:

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:

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:

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:

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:

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:

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:

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:

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