Events

The Yandex Maps API implements its own mechanism for working with events that expands the standard JavaScript facilities for managing events. This means that when working with browser events, standard JavaScript approaches are used for the browser and DOM tree windows, while the Yandex Maps API event model is used for working with API objects.

The API implements a traditional model for working with events. Certain objects can generate events that can be subscribed to and passed to a handler function.

All API objects that can generate events implement the IEventEmitter interface and have the events field. This field contains a reference to the event manager that is used for subscribing to necessary events, or for removing the subscription.

myPlacemark.events.add('click', function () {
    alert('Oh, an event!!');
});

Structure of the event object

Events generated by the Yandex Maps API are objects of the Event class. The exception is map events that are described by the MapEvent class, which expands Event.

The object that describes an event contains information about the event itself and the object that generated it. Data is extracted from the Event and MapEvent objects using the get method, which is passed the name of the field in the internal object of this class that describes the event.

Many events have a geographical anchor that shows which geographical coordinate corresponded to the position of the mouse cursor when the event was triggered.

myMap.events.add('click', function (e) {
    // Getting the click coordinate
    var coords = e.get('coords');
    alert(coords.join(', '));
});

For any event, a reference to the object that generated it can be obtained. This reference is in the target field.

myMap.events.add('click', function (e) {
    var eMap = e.get('target');// Getting a reference to the object that generated the event (map).
    eMap.setType('yandex#hybrid');
});

For any event, the type can be obtained by accessing the type field.

myMap.events.add(['click', 'contextmenu'], function (e) {
    var eType = e.get('type');
    eType == 'click' ? alert('left button') : alert('right button');
});

The domEvent field of the internal object for the API event that triggers a DOM event contains a reference to the API object that describes the DOM event (the [{#T}DomEvent.md]](../../ref/reference/DomEvent.md) class). This object contains a reference to the source DOM event in the originalEvent field.

myPlacemark.events.add('mousedown', function (e) {
    // 0, 1 or 2, depending on which mouse button is held down (in IE, the value can be from 0 to 7).
    alert(e.get('domEvent').originalEvent.button);
});

The DomEvent class provides proxy access to fields and methods in the source DOM event, and is adapted to the peculiarities of various browsers. This is why it is preferable to not access the source DOM event, but use the DomEvent class instead: the get method for getting event properties, and the callMethod method for accessing its method.

myPlacemark.events.add('click', function (e) {
    // Instead of alert(e.get('domEvent').originalEvent.pageX);
   alert(e.get('domEvent').get('pageX'));
});

In addition, DomEvent lets you immediately get the cursor coordinates as an array — get('position').

The architecture of the API is designed so that most of the information contained in an object describing an event can be obtained from the properties of the object that generated this event.

Distributing events

An event that occurs travels up the entire hierarchy of parent objects all the way to the parent collection of the map object (this is known as «propagation»). Events of child elements do not go all the way up to the map object itself.

myPlacemark.events.add('click', function () {
    alert('Oh, an event!');
});
myMap.geoObjects.events.add('click', function (e) {
    alert('Got to the map objects collection');
    // Getting a reference to the child object where the event occurred.
    var object = e.get('target');
});
myMap.events.add('click', function () {
    alert('Event on the map'); // Occurs when the click is on the map, but not on a placemark.
});

To stop event propagation, use the stopPropagation method.

myPlacemark.events.add('click', function (e) {
    alert('Oh, an event!');
    e.stopPropagation();
});
myMap.geoObjects.events.add('click', function () {
    alert('Border closed');
});

Most events have standard actions defined for them, which are performed after an event occurs. These actions can be canceled using the preventDefault method.

myMap.events.add('dblclick', function (e) {
    e.preventDefault(); // Zoom will not occur on double-click.
});

Context for handling events

When using the event manager to set an event handler, you can specify not only the handler function, but the context it will be invoked in, as well. Most often, the context is passed as a reference to an object that has internal information that is needed by the handler function.

function myCounter(start) {
    this.counter = start;
}
myCounter.prototype.go = function () {
    var myMap = new ymaps.Map("map", {
        center: [59.93, 30.31],
        zoom: 12
    });
    myMap.events.add('click', this.up, this);
}
myCounter.prototype.up = function () {
    this.counter++;
    alert(this.counter)
};
var c = new myCounter(2012);
c.go();