map.action.Manager

Extends IEventEmitter.

Map actions manager. Makes complex movements possible on the map and ensures that complex movements do not overlap each other. Every map already has its own actions manager, available as Map.action. Don't create new instances of this class unless necessary.

See Map.action

Constructor | Fields | Events | Methods

Constructor

map.action.Manager(map)

Parameters:

Parameter

Default value

Description

map*

Type: Map

Map.

* Mandatory parameter/option.

Example:

// Creating a complex movement: every 100 ms, the map
// center shifts a random amount.

// Creating an instance of the complex movement
var action = new ymaps.map.action.Continuous();
// Executing it on the map
myMap.action.execute(action);

// Recalling the pixel map center and zoom level
var center = myMap.getGlobalPixelCenter();
var zoom = myMap.getZoom();
// Generate a random shift every 100 milliseconds
var interval = window.setInterval(function () {
    center[0] += Math.round(Math.random() * 100) - 50;
    center[1] += Math.round(Math.random() * 100) - 50;
    // Generating a new shift in the map
    action.tick({
        globalPixelCenter: center,
       zoom: zoom
    });
}, 100);

// As soon as the user moves the map, our movement
// stops being executed and the "end" event occurs.
var listener = action.events.once('end', function () {
    listener.removeAll();
    window.clearInterval(interval);
});

Fields

Name

Type

Description

events

IEventManager

Event manager.

Inherited from IEventEmitter.

Events

Name

Description

begin

Event that occurs when an action has started. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - Action that has started.

break

Event that occurs when an action step was prematurely stopped (for example, because another action or another step of the action was performed). Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - An action.

end

Event that occurs when an action is stopped. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - Action that has stopped.

tick

Event that occurs when the next step of an action begins to be performed. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - The action being performed at this moment.
  • tick - Description of an action step in the form of an object with the fields "globalPixelCenter", "zoom", "duration" and "timingFunction".

tickcomplete

Event that occurs when an action step has been completed. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - The action being performed at this moment.
  • tick - Description of an action step in the form of an object with the fields "globalPixelCenter", "zoom", "duration" and "timingFunction".

Methods

Name

Returns

Description

breakTick()

Interrupts an action step.

execute(action)

Starts an action on the map. If a different movement is being performed on the map at this time, it is stopped (the "end" method is called). The new movement is started using a "begin" method call.

getCurrentState()

Object

Checks the map state at the time of smooth movement.

getMap()

Map

Returns reference to the map.

setCorrection(userFunction)

Used for making user adjustments to complex movements on the map. When the adjustment is finished, the corrected values must be returned.

stop()

Stops an action being performed on the map.

Events details

begin

Event that occurs when an action has started. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - Action that has started.

break

Event that occurs when an action step was prematurely stopped (for example, because another action or another step of the action was performed). Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - An action.

end

Event that occurs when an action is stopped. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - Action that has stopped.

tick

Event that occurs when the next step of an action begins to be performed. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - The action being performed at this moment.
  • tick - Description of an action step in the form of an object with the fields "globalPixelCenter", "zoom", "duration" and "timingFunction".

Example:

// Tracks all map movement, even user dragging
// and smooth zooming
myMap.action.events.add('tick', function (e) {
    var tick = e.get('tick');
    console.log('Now the map is moving to the point (' +

myMap.options.get('projection').fromGlobalPixels(tick.globalPixelCenter, tick.zoom).join(',') +
        ') during ' + e.get('tick').duration + ' milliseconds');
});

tickcomplete

Event that occurs when an action step has been completed. Instance of the Event class. Names of fields that are available via the Event.get method:

  • action - The action being performed at this moment.
  • tick - Description of an action step in the form of an object with the fields "globalPixelCenter", "zoom", "duration" and "timingFunction".

Methods details

breakTick

{} breakTick()

Interrupts an action step.

execute

{} execute(action)

Starts an action on the map. If a different movement is being performed on the map at this time, it is stopped (the "end" method is called). The new movement is started using a "begin" method call.

Parameters:

Parameter

Default value

Description

action*

Type: IMapAction

Action.

* Mandatory parameter/option.

getCurrentState

{Object} getCurrentState()

Checks the map state at the time of smooth movement.

Returns object with the fields: isTicking - Whether a step of smooth movement is being performed. tickProgress - Which part of the current step has been completed. zoom - The map zoom during the current step. globalPixelCenter - The map center in global pixels during the current step.

Example:

// Logs the current map center.
// Even works during smooth zooming or
// while the user is dragging the map.
window.setInterval(function () {
    console.log(myMap.action.getCurrentState().center.join(', '));
}, 100);

getMap

{Map} getMap()

Returns reference to the map.

setCorrection

{} setCorrection(userFunction)

Used for making user adjustments to complex movements on the map. When the adjustment is finished, the corrected values must be returned.

Parameters:

Parameter

Default value

Description

userFunction*

Type: Function

Custom function for adjusting steps.

* Mandatory parameter/option.

Example:

// Making it impossible for the user to drag the map center
// outside of the Moscow Ring Road.
var mkad = [
    [55.785017, 37.841576],
    [55.861979, 37.765992],
    [55.898533, 37.635961],
    [55.888897, 37.48861],
    [55.83251, 37.395275],
    [55.744789, 37.370248],
    [55.660424, 37.434424],
    [55.5922, 37.526366],
    [55.574019, 37.683167],
    [55.62913, 37.802473],
    [55.712203, 37.837121]
];
var mkadPolygon = new ymaps.Polygon([mkad], {}, {
    fillColor: '#FFFF00',
    opacity: .4
});
myMap.geoObjects.add(mkadPolygon);
myMap.action.setCorrection(function (tick) {
    var projection = myMap.options.get('projection');
    var tickCenter = projection.fromGlobalPixels(tick.globalPixelCenter, tick.zoom);
    // If the map center is not in our area.
    if (!mkadPolygon.geometry.contains(tickCenter)) {
        tick.globalPixelCenter = projection.toGlobalPixels(
            mkadPolygon.geometry.getClosest(tickCenter).position,
            tick.zoom
        );
        tick.duration = 0;
    }
    return tick;
});

stop

{} stop()

Stops an action being performed on the map.