Class: mapInteractor

geo. mapInteractor

new geo.mapInteractor(args){geo.mapInteractor}

The mapInteractor class is responsible for handling raw events from the browser and interpreting them as map navigation interactions. This class will call the navigation methods on the connected map, which will make modifications to the camera directly.

Name Type Description
args geo.mapInterator.spec

Interactor specification object.

Returns:
Type Description
geo.mapInteractor

Extends

Type Definitions

geo.mapInteractor.specobject

Map Interactor specification.

Properties:
Name Type Argument Default Description
throttle number <optional>
30

Mouse events are throttled so that an event occurs no more often that this number of milliseconds.

discreteZoom boolean | number <optional>
false

If true, only allow discrete (integer) zoom levels and debounce with a 400 ms delay. If a positive number, debounce zoom events with the given delay in milliseconds.

actions Array.<geo.actionRecord> <optional>

The list of available actions. See the code for the full default list.

click object <optional>

An object specifying if click events should be handled.

Properties
Name Type Argument Default Description
enabled boolean <optional>
true

Truthy to enable click events.

buttons object <optional>

An object with button names (left, right, middle), each of which is a boolean which indicates if that button triggers a click event.

duration number <optional>
0

If a positive number, the mouse up event must occur within this time in milliseconds of the mouse down event for it to be considered a click.

cancelOnMove boolean <optional>
true

If truthy, don't generate click events if the mouse moved at all.

keyboard object <optional>

An object describing which keyboard events are handled.

Properties
Name Type Argument Default Description
actions object <optional>

An object with different actions that are trigger by the keyboard. Each key is the event that is triggered, with the values a list of keys that trigger the event. See the code for the defaults.

meta object <optional>

Keyboard events can generate actions of different magnitudes. This is an object with keys of 0, 1, and 2, corresponding to small, medium, and large actions. Each entry is an object with keys of the meta keys that are required to be down or up for that scale action to trigger. If the value of the meta key is truthy, it must be down. If false, it must be up.

focusHighlight boolean <optional>
true

If truthy, when the map gains focus, a highlight style is shown around it. This gives an indicator that keyboard events will affect the map, but may not be visuallly desirabel.

alwaysTouch boolean <optional>
false

If true, add touch support even if the browser doesn't apepar to be touch-aware.

wheelScaleX number <optional>
1

A scale multiplier for horizontal wheel interactions.

wheelScaleY number <optional>
1

A scale multiplier for vertical wheel interactions.

zoomScale number <optional>
1

This affects how far the mouse must be dragged to zoom one level. Roughly, the mouse must move zoomScale * 120 pixels per level.

rotateWheelScale number <optional>
0.105

When the mouse wheel is used for rotation, this is the number of radians per wheel step.

zoomrotateMinimumRotation number <optional>
0.087

The minimum angle of rotation in radians before a geo_action.zoomrotate action will allow rotation. Set to 0 to always include rotation.

zoomrotateReverseRotation number <optional>
0.698

The minimum angle of rotation (in radians) before the geo_action.zoomrotate action will reverse the rotation direction. This helps reduce chatter when zooms and pans are combined with rotations.

zoomrotateMinimumZoom number <optional>
0.05

The minimum zoom factor change (increasing or desceasing) before the geo_action.zoomrotate action will allow zoom. Set to 0 to always include zoom.

zoomrotateMinimumPan number <optional>
5

The minimum number of pixels before the geo_action.zoomrotate action will allow panning. Set to 0 to always include panning.

touchPanDelay number <optional>
50

The touch pan delay prevents a touch pan event from immediately following a rotate (including zoom) event. No touch pan event is processed within this number of milliseconds of a non-pan touch event.

momentum object <optional>

Enable momentum when panning and zooming.

Properties
Name Type Argument Default Description
enabled boolean <optional>
true

Truthy to allow momentum.

maxSpeed number <optional>
2.5

Maximum animation speed.

minSpeed number <optional>
0.01

Animations stop when they drop below this speed.

stopTime number <optional>
250

If the mouse hasn't moved in this many milliseconds, don't apply momentum. The movement is a separate action from the preceding movement.

drag number <optional>
0.01

Drag coefficient; larger values slow down faster.

actions Array.<string> <optional>

A list of actions on which to apply momentum. Defaults to pan and zoom.

spring object <optional>

Enable spring clamping to screen edges.

Properties
Name Type Argument Default Description
enabled boolean <optional>
true

Truthy to allow edge spring back.

springConstant number <optional>
0.00005

Higher values spring back faster.

zoomAnimation object <optional>

Enable zoom animation for both discrete and continuous zoom.

Properties
Name Type Argument Default Description
enabled boolean <optional>
true

Truthy to allow zoom animation.

duration number <optional>
500

The time it takes for the final zoom to be reached.

ease function <optional>

The easing function for the zoom. The default is (2 - t) * t.

Members

inherited idle

Getter for the idle state. Read only.

Properties:
Name Type Description
idle boolean

true if the object is idle (onIdle would call a handler immediately).

innerm_queue

Store queued map navigation commands (due to throttling) here { kind: 'move' | 'wheel', // what kind of mouse action triggered this method: function () {}, // the throttled method scroll: {x: ..., y: ...} // accumulated scroll wheel deltas }

Methods

addAction(action, toEnd)

Add an action to the list of handled actions.

Name Type Description
action object

An object defining the action. This must have action and input properties, and may have modifiers, name, and owner. Use action, name, and owner to make this entry distinct if it will need to be removed later.

toEnd boolean optional

The action is added at the beginning of the actions list unless truthy. Earlier actions prevent later actions with similar input and modifiers.

inherited addPromise(promise){this}

Add a new promise object preventing idle event handlers from being called until it is resolved.

Name Type Description
promise Promise

A promise object.

Returns:
Type Description
this

cancel(action, keepQueue){boolean}

Immediately cancel an ongoing action.

Name Type Description
action string nullable

The action type, if null cancel any action.

keepQueue boolean optional

If truthy, keep the queue event if an action is canceled.

Returns:
Type Description
boolean Set if an action was canceled.

Public method that unbinds all events.

inherited geoIsOn(event, handler){boolean}

Report if an event handler is bound to this object.

Name Type Description
event string | Array.<string>

An event or list of events to check.

handler function optional

A function that might be bound. If undefined, this will report true if there is any handler for the specified event.

Returns:
Type Description
boolean true if any of the specified events are bound to the specified handler.

inherited geoOff(event, arg){this}

Remove handlers from one event or an array of events. If no event is provided all handlers will be removed.

Name Type Description
event string | Array.<string> optional

An event or a list of events from geo.event or defined by the user, or undefined to remove all events (in which case arg is ignored).

arg function | Array.<function()> optional nullable

A function or array of functions to remove from the events or a falsy value to remove all handlers from the events.

Returns:
Type Description
this

inherited geoOn(event, handler){this}

Bind an event handler to this object.

Name Type Description
event string

An event from geo.event or a user-defined value.

handler function

A function that is called when event is triggered. The function is passed a geo.event object.

Returns:
Type Description
this

inherited geoTrigger(event, args){this}

Trigger an event (or events) on this object and call all handlers.

Name Type Description
event string | Array.<string>

An event or list of events from geo.event or defined by the user.

args object optional

Additional information to add to the geo.event object passed to the handlers.

Returns:
Type Description
this

hasAction(action, name, owner){object|null}

Check if an action is in the actions list. An action matches if the action, name, and owner match. A null or undefined value will match all actions. If using an action object, this is the same as passing (action.action, action.name, action.owner).

Name Type Description
action object | string

Either an action object or the name of an action.

name string

Optional name associated with the action.

owner string

Optional owner associated with the action.

Returns:
Type Description
object | null The first matching action or null.

hasTouchSupport(){boolean}

Check if this browser has touch support. Copied from https://github.com/hammerjs/touchemulator under the MIT license.

Returns:
Type Description
boolean true if there is touch support.

keyboard(newValue){object|this}

Get/set current keyboard information.

Name Type Description
newValue object optional

Either a object with new options for the keyboard actions or undefined to get the current options.

Returns:
Type Description
object | this Either the current keyboard options or this mapInteractor class instance.

Sets or gets map for this interactor, adds draw region layer if needed.

Name Type Description
val geo.map optional

Either a new map object for undefined to return the current map object.

Returns:
Type Description
geo.map | this Either the current map object or the mapInteractor class instance.

inherited modified(){this}

Update the timestamp to the next global timestamp value.

Returns:
Type Description
this

mouse(){object}

Get current mouse information.

Returns:
Type Description
object The current mouse state.

inherited onIdle(handler){this}

Bind a handler that will be called one time when all internal promises are resolved. If there are no outstanding promises, this is invoked synchronously.

Name Type Description
handler function

A function taking no arguments.

Returns:
Type Description
this

Gets/sets the options object for the interactor.

Name Type Description
opts geo.mapInteractor.spec

Options to set.

Returns:
Type Description
geo.mapInteractor.spec | this

pause(value){boolean|this}

Get or set the pause state of the interactor, which ignores all native mouse and keyboard events.

Name Type Description
value boolean optional

The pause state to set or undefined to return the current state.

Returns:
Type Description
boolean | this The current pause state or this class instance.

removeAction(action, name, owner){number}

Remove all matching actions. Actions are matched as with hasAction.

Name Type Description
action object | string

Either an action object or the name of an action.

name string

Optional name associated with the action.

owner string

Optional owner associated with the action.

Returns:
Type Description
number The number of actions that were removed.

retriggerMouseMove()

Retrigger a mouse movement with the current mouse state.

Fires:

simulateEvent(type, options, button, modifiers, wheelDelta, wheelMode, touch, rotation, scale, pointers, pointerType){mapInteractor}

Simulate a DOM mouse event on connected map. Not all options are required for every event type.

Name Type Description
type string

Event type mousemove, mousedown, mouseup, etc. keyboard is treated separately from other types.

options object

Options for the simulated event.

Name Type Description
shift boolean optional

A boolean if a keyboard event has the shift key down or explicitly up.

shiftKey boolean optional

Alternate name to shift.

ctrl boolean optional

A boolean if a keyboard event has the control key down or explicitly up.

ctrlKey boolean optional

Alternate name to ctrl.

alt boolean optional

A boolean if a keyboard event has the alt key down or explicitly up.

altKey boolean optional

Alternate name to alt.

meta boolean optional

A boolean if a keyboard event has the meta key down or explicitly up.

metaKey boolean optional

Alternate name to meta.

keys string optional

A Mousetrap-style key sequence string for keyboard events.

page geo.screenPosition optional

The position of the event on the window. Overridden by map.

map geo.screenPosition optional

The position of the event on the map in pixels relative to the map's div.

center geo.screenPosition optional

The position of a touch event center relative to the window.

button string optional

One of left, middle, or right for mouse events.

modifiers string optional

A space-separated list of metakeys that are down on mouse events.

wheelDelta geo.screenPosition optional

The amount the wheel moved in both directions for wheel events. One step is often 20 units of vement.

wheelMode number optional

The wheel delta mode. See https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent .

touch boolean optional

truthy if this is a touch event.

rotation number optional

Touch event rotation in degrees.

scale number optional

Touch event scale. Initial events should have a scale of 1; subsequent events should increase or decrease this to simulate spread and pinch actions.

pointers Array.<number> optional

A list of pointer numbers involved in a touch event. Pointers are number from one up, so [1] is the first touch point, [1, 2] are two touch points, and [2] is when the first point was released but the second is still touching.

pointerType string optional

mouse if this is a mouse action rather than a touch action.

Returns:
Type Description
mapInteractor

protectedspringBack(initialVelocity, origAction)

Start up a spring back action when the map bounds are out of range. Not to be user callable.

Name Type Description
initialVelocity boolean

Truthy if the mouse's current velocity should be used as the initial velocity. False to assume no initial velocity.

origAction object

The original action that started the spring back. If this was a zoom action, the spring back includes zoom; otherwise it only includes panning.

state(){geo.interactorState}

Get the current interactor state.

Returns:
Type Description
geo.interactorState

inherited timestamp(){number}

Get time.

Returns:
Type Description
number The timestamp. This is 0 if the timestamp has never been modified.

innerdebounced_zoom(){function}

Private wrapper around the map zoom method that is debounced to support discrete zoom interactions.

Returns:
Type Description
function A function to handle zooms that debounces such events. This function is passed the zoom level and the mouse state.