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.
- that, when typed singly, trigger a repeat of the last mousemove or actionmove event so that listeners can update metakey information.
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 | number <optional>
true If true, don't generate click events if the mouse moved at all. If a positive number, the distance at which to cancel click events when the mouse moves.
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
, and2
, 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. Iffalse
, it must be up.metakeyMouseEvents
Array.<string> <optional>
A list of meta keys
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.
-
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. -
destroy()
-
Public method that unbinds all events.
-
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 reporttrue
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. -
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, orundefined
to remove all events (in which casearg
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 -
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 ageo.event
object.Returns:
Type Description this -
Bind an event handler to this object that will fire once and then deregister itself.
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 ageo.event
object.Returns:
Type Description function The actual bound handler. This is a wrapper around the handler that was passed to the function. -
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. -
map(val){geo.map|this}
-
Get or set the 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. -
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 -
options(opts){geo.mapInteractor.spec|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. -
Mark a promise as no longer required to resolve before the idle state is reached.
Name Type Description promise
Promise A promise object.
Returns:
Type Description this -
retriggerMouseMove()
-
Retrigger a mouse movement with the current mouse state.
Fires:
-
simulateEvent(type, options){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
, orright
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 movement.
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.