Chevron DownAPI Reference

Controller

The base class for all viewport controllers.

A controller class can be passed to the Deck.controller or View.controller prop to specify viewport interactivity.

Options

The base Controller class supports the following options:

  • scrollZoom (Boolean) - enable zooming with mouse wheel. Default true
  • dragPan (Boolean) - enable panning with pointer drag. Default true
  • dragRotate (Boolean) - enable rotating with pointer drag. Default true
  • doubleClickZoom (Boolean) - enable zooming with double click. Default true
  • touchZoom (Boolean) - enable zooming with multi-touch. Default true
  • touchRotate (Boolean) - enable rotating with multi-touch. Default false
  • keyboard (Boolean) - enable interaction with keyboard. Default true

Methods

A controller is not meant to be instantiated by the application. The following methods are documented for creating custom controllers that extend the base Controller class.

constructor
import {Controller} from 'deck.gl';

class MyController extends Controller {
    constructor(options = {}) {
        super(MyViewState, options);
    }
}

The constructor takes two arguments:

  • ViewState - a class that implements the following methods:
    • getViewportProps() - returns an object that describes the view state
    • getInteractiveState() - returns an object that contains the internal state of the ongoing interaction
    • shortestPathFrom(viewState) - returns an object that describes another view state that is closest to this view state. This is used by viewport transition when there are multiple equivalent ways to define a view state (e.g. bearing: 240 and bearing: -120)
    • methods that return a new ViewState with updated props:
      • panStart
      • pan
      • panEnd
      • rotateStart
      • rotate
      • rotateEnd
      • zoomStart
      • zoom
      • zoomEnd
      • zoomIn
      • zoomOut
      • moveLeft
      • moveRight
      • moveUp
      • moveDown
      • rotateLeft
      • rotateRight
      • rotateUp
      • rotateDown
  • options (Object) - options and view state props
handleEvent(event)

Called by the event manager to handle pointer events. This method delegate to the following methods to handle the default events:

  • _onPanStart(event)
  • _onPan(event)
  • _onPanEnd(event)
  • _onPinchStart(event)
  • _onPinch(event)
  • _onPinchEnd(event)
  • _onDoubleTap(event)
  • _onWheel(event)
  • _onKeyDown(event)
setProps(props)

Called by the view when the view state updates. This method handles adding/removing event listeners based on user options.

updateViewport(newMapState, extraProps, extraState)

Called by the event handlers, this method updates internal state, and invokes onViewStateChange callback with a new map state.

getCenter(event)

Utility used by the event handlers, returns pointer position [x, y] from any event.

isFunctionKeyPressed(event)

Utility used by the event handlers, returns true if ctrl/alt/meta key is pressed during any event.

isPointInBounds(pos, [event])

Utility used by the event handlers, returns true if a pointer position [x, y] is inside the current view.

If event is provided, returns false if the event is already handled, and mark the event as handled if the point is in bounds. This can be used to make sure that certain events are only handled by one controller, when there are overlapping viewports.

isDragging()

Returns true if the user is dragging the view.

Event Handling

A controller can specify a list of additional event names that this control subscribes to by adding them to the events field.

import {Controller} from 'deck.gl';

class MyController extends Controller{
    constructor(options = {}) {
        super(MyViewState, options);
        this.events = ['pointermove'];
    }

    handleEvent(event) {
        if (event.type === 'pointermove') {
            // do something
        } else {
            super.handleEvent(event);
        }
    }
}

Available events: click, dblclick, tap, doubletap, press, pinch, pinchin, pinchout, pinchstart, pinchmove, pinchend, pinchcancel, rotate, rotatestart, rotatemove, rotateend, rotatecancel, pan, panstart, panmove, panup, pandown, panleft, panright, panend, pancancel, swipe, swipeleft, swiperight, swipeup, swipedown, pointerdown, pointermove, pointerup, touchstart, touchmove, touchend, mousedown, mousemove, mouseup, keydown, and keyup.

The following events are toggled on/off based on user options:

  • scrollZoom - ['wheel']
  • dragPan and dragRotate - ['panstart', 'panmove', 'panend']
  • touchZoomRotate - ['pinchstart', 'pinchmove', 'pinchend']
  • doubleClickZoom - ['doubletap']
  • keyboar - ['keydown']

Event object is generated by mjolnir.js. It always has the following properties:

  • type (string) - The event type to which the event handler is subscribed, e.g. 'click' or 'pointermove'
  • center (Object {x, y}) - The center of the event location (e.g. the centroid of a touch) relative to the viewport (basically, clientX/Y)
  • offsetCenter (Object {x, y}) - The center of the event location relative to the map.
  • target (Object) - The target of the event, as specified by the original srcEvent
  • srcEvent (Object) - The original event object dispatched by the browser to the JS runtime

Additionally, event objects for different event types contain a subset of the following properties:

  • key (number) - The keycode of the keyboard event
  • leftButton (boolean) - Flag indicating whether the left button is involved during the event
  • middleButton (boolean) - Flag indicating whether the middle button is involved during the event
  • rightButton (boolean) - Flag indicating whether the right button is involved during the event
  • pointerType (string) - A string indicating the type of input (e.g. 'mouse', 'touch', 'pointer')
  • delta (number) - The scroll magnitude/distance of a wheel event

Source

modules/core/src/controllers/controller.js