Map Events
The Quick Start section shows an example that displays a default non-interactive map. The map is a static picture, the viewer cannot drag it to see a different area, it does not respond to mouse clicks or taps. Map interaction can be implemented, using the events supported by modern web browsers, but the solution would be either browser-specific or otherwise very complex and would require testing in different browsing environments. The Maps API for JavaScript offers help by providing a module named events
that acts as an abstraction layer, hiding browser-specific details (and quirks).
The Event System
The events
module (mapsjs-events.js
) normalizes different browser event systems in a wrapper event system to make it easy to develop interactive cross-browser and cross-platform applications. It draws on the terminology used in Microsoft's pointer events specification, providing a clear abstraction from input devices such as mouse, touch or stylus, but note that it does not implement the Microsoft specification.
The table below presents an overview of the events which the map dispatches when the events
module is enabled:
Events in Maps API for JavaScript Event | Description |
pointerdown | Signals that a pointer (mouse, stylus, touch) has reached the map surface or map object; equivalent to the event types mousedown , touchstart , pointerdown |
pointerup | Signals that a pointer (mouse, stylus, touch) has left the map surface or map object; equivalent to the event types mouseup , touchend , pointerup |
pointermove | Signals that a pointer (mouse, stylus, touch) is moved across the map surface or map object; equivalent to the event types mousemove , touchmove , pointermove |
pointerenter | Signals that a pointer (mouse, stylus, touch) has entered the map object area; equivalent to the event types mouseenter , touchenter , pointerenter |
pointerleave | Signals that a pointer (mouse, stylus, touch) has left the map object area; equivalent to the event types mouseleave , touchleave , pointerleave |
pointercancel | Signals that an ongoing pointer (mouse, stylus, touch) action was cancelled by the browser; equivalent to the event types: touchcancel , pointercancel |
dragstart | Signals that a pointer (mouse, stylus, touch) drag operation started on the map or map object |
drag | Signals that a pointer (mouse, stylus, touch) drag operation on the map or a map object is ongoing |
dragend | Signals that a pointer (mouse, stylus, touch) drag operation on the map or a map object has finished |
tap | Signals that a pointer (mouse, stylus, touch) has briefly touched the map surface or a map object; equivalent to the event types click and tap |
dbltap | Signals that two tap events with the same pointer were executed in short succession |
longpress | Signals that a pointerdown event has occurred on a pointer target, no pointerup was triggered and the pointer stayed in place for a longer period of time |
Map with Event Handling
To make a map event aware and allow it to respond to events:
- Load the module
mapjs-events.js
. - Create a map object.
- Instantiate the
MapEvents
class. - Add an events listener to the map.
The following code shows how to load the events module:
<!DOCTYPE html>
<html>
<head>
...
<meta name="viewport" content="initial-scale=1.0, width=device-width"/>
<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"
type="text/javascript" charset="utf-8"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"
type="text/javascript" charset="utf-8"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"
type="text/javascript" charset="utf-8"></script>
...
</head>
The code block below demonstrates the remaining steps, starting with creating a map object, then instantiating H.mapevents.MapEvents
, and finally adding a listener for tap events to the map. The listener simply logs the event properties in the browser's JavaScript console.
var map = new H.Map(...);
var mapEvents = new H.mapevents.MapEvents(map);
map.addEventListener('tap', function(evt) {
console.log(evt.type, evt.currentPointer.type);
});
Structure of a Pointer Event
Like normal browser events, the pointer events are identified by their type
property. Also, they expose the target
object on which they were dispatched and the original event that triggered them (the property originalEvent
).
Furthermore, a pointer event contains the following details of pointers:
- pointers that are currently on the screen (mouse, stylus or touch)
- pointers that have changed as a result of the current event
- pointers that are on the (event) target
- the pointer that triggered the current event
Note that if an application needs to distinguish between mouse and touch input, each pointer object provides a type property which specifies the input method.
Event Propagation
The event system supports event propagation. Each map object that dispatches events propagates them through the object hierarchy. This means that, for example, event listeners attached to the map are triggered when interaction with a map object occurs – and the event's target correctly points to the map object.
Enabling Default Map Behavior
The Maps API mapevents
module provides full support for map interactions such as pan, zoom and pinch-to-zoom. The implementation resides in the class H.mapevents.Behavior
and makes use of the event system abstraction.
Enabling map interactions is easily achieved by adding another line of code to our last example:
var map = new H.Map(...);
var mapEvents = new H.mapevents.MapEvents(map);
map.addEventListener('tap', function(evt) {
console.log(evt.type, evt.currentPointer.type);
});
var behavior = new H.mapevents.Behavior(mapEvents);
The code above ensures that the map reacts to mouse, stylus, and touch input.