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:

  1. Load the module mapjs-events.js.
  2. Create a map object.
  3. Instantiate the MapEvents class.
  4. 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.

// Initialize the map: 
var map = new H.Map(...);

// Enable the event system on the map instance:
var mapEvents = new H.mapevents.MapEvents(map);

// Add event listener:
map.addEventListener('tap', function(evt) {
    // Log 'tap' and 'mouse' events:
    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:

// Initialize the map:
var map = new H.Map(...);

// Enable the event system on the map instance:
var mapEvents = new H.mapevents.MapEvents(map);

// Add event listeners:
map.addEventListener('tap', function(evt) {
    // Log 'tap' and 'mouse' events:
    console.log(evt.type, evt.currentPointer.type);
});

// Instantiate the default behavior, providing the mapEvents object:
var behavior = new H.mapevents.Behavior(mapEvents);

The code above ensures that the map reacts to mouse, stylus, and touch input.

results matching ""

    No results matching ""