Skip to content

controller.md

Latest commit

 

History

History
153 lines (107 loc) · 7.53 KB

controller.md

File metadata and controls

153 lines (107 loc) · 7.53 KB
Raw

Controller

The base class for all viewport controllers.

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

Options

The base Controller class supports the following options:

  • scrollZoom (boolean | object) - enable zooming with mouse wheel. Default true. If an object is supplied, it may contain the following fields to customize the zooming behavior:
    • speed (number) - scaler that translates wheel delta to the change of viewport scale. Default 0.01.
    • smooth (boolean) - smoothly transition to the new zoom. If enabled, will provide a slightly lagged but smoother experience. Default false.
  • 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. Adds ~300ms latency to click events due to the tap recognizer waiting to distinguish single clicks from double clicks. Set to false for immediate click response. Note: disabling also prevents onClick from firing with tapCount: 2 on double-click.
  • doubleClickDragZoom (boolean) - enable zooming by double clicking/tapping and dragging. Default false. Enabling adds ~300ms latency to click events due to the tap recognizer waiting to distinguish single clicks from double-click-drags.
  • touchZoom (boolean) - enable zooming with multi-touch pinch. Default true
  • multiTouchDrag ('pan' | 'rotate' | null) - behavior of two-pointer translation gestures. In pan mode, two-finger swiping pans the viewport. In rotate mode, horizontal swiping changes bearing and vertical swiping changes pitch. Default null (disabled).
  • trackpadGesture (boolean) - treat trackpad similar to a touch screen instead of a mouse. Default false.
    • When true, two-finger gesture on the trackpad emits multi-touch pinch or drag events.
    • When false, two-finger gesture on the trackpad emits wheel scroll events.
  • keyboard (boolean | object) - enable interaction with keyboard. Default true. If an object is supplied, it may contain the following fields to customize the keyboard behavior:
    • zoomSpeed (number) - speed of zoom using +/- keys. Default 2.
    • moveSpeed (number) - speed of movement using arrow keys, in pixels.
    • rotateSpeedX (number) - speed of rotation using shift + left/right arrow keys, in degrees. Default 15.
    • rotateSpeedY (number) - speed of rotation using shift + up/down arrow keys, in degrees. Default 10.
  • dragMode (string) - drag behavior without pressing function keys, one of pan and rotate.
  • inertia (boolean | number) - Enable inertia after panning/pinching. If a number is provided, indicates the duration of time over which the velocity reduces to zero, in milliseconds. Default false.
  • maxBounds ([min: number[], max: number[]]) - constrain camera to the specified bounding box. Different type of views may handle this constraint differently.
  • maxBoundsPadding ({left, right, top, bottom}) - padding inside the viewport when fitting maxBounds, in the shape of {left, right, top, bottom} where each value is either a relative (e.g. '50%') or absolute pixels. These values support the same CSS-style expressions (numbers/percentages/px with parentheses and calc() addition/subtraction) as view x, y, width, height, and padding. This can be used to move the target rectangle away from the center of the viewport. A non-positive remaining dimension does not contribute a zoom constraint; a negative remaining dimension also disables target constraints. Default 0.

Mobile users: See Optimization for Mobile for CSS and browser event guards that help prevent native selection, tap highlight, and touch callout UI during repeated touch gestures.

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(props) {
    super(props);
  }
}

The constructor takes one argument:

  • props (object) - contains the following options:
    • eventManager- handles events subscriptions
    • makeViewPort (viewState) - creates new Viewport based on provided ViewState, and current view's width and height
    • onStateChange callback function
    • onViewStateChange callback function
    • timeline - an instance of luma.gl animation timeline class

handleEvent(event) {#handleevent}

Called by the event manager to handle pointer events.

See Event object documentation.

setProps(props) {#setprops}

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

updateViewport(newMapState, extraProps, interactionState) {#updateviewport}

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

getCenter(event) {#getcenter}

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

isFunctionKeyPressed(event) {#isfunctionkeypressed}

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

isPointInBounds(pos, [event]) {#ispointinbounds}

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() {#isdragging}

Returns true if the user is dragging the view.

Members

events (string[]) {#events}

In its constructor, a controller class can optionally specify a list of event names that it subscribes to with the events field. Supported events are:

  • click
  • dblclick
  • pan
  • pinch: 2-finger free-form manipulation, used for touch zooming and rotation
  • multipan: 2-finger translation, used for touch panning or rotation
  • keydown
  • keyup
  • pointerdown
  • pointermove
  • pointerup
  • pointerover
  • pointerout
  • pointerleave
  • wheel
  • contextmenu

Note that the following events are always toggled on/off by user options:

  • scrollZoom - ['wheel']
  • dragPan and dragRotate - ['pan']
  • touchZoom - ['pinch']
  • multiTouchDrag - ['multipan'], and ['pinch'] in rotate mode
  • doubleClickZoom - ['dblclick']
  • doubleClickDragZoom - ['pointerdown', 'pointermove', 'pointerup', 'pointercancel']
  • keyboard - ['keydown']

Example: Implementing A Custom Controller

import {Controller} from 'deck.gl';

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

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

Source

modules/core/src/controllers/controller.ts