Skip to content
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions docs/api-reference/core/map-controller.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,88 @@ new Deck({

See the `Controller` class [documentation](./controller.md#methods) for the methods that you can use and/or override.

## MapState
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each class is typically documented in their own file, however these classes are meant to always be composited into controllers, so this organization could make sense.

It'd be great to have the custom controller example expanded to include the application of this class and https://deck.gl/docs/api-reference/core/controller#example-implementing-a-custom-controller to mention ViewState


The `MapState` class manages the internal state of the map controller. It provides methods for handling user interactions like panning, rotating, and zooming.

### Usage

```js
import {MapState} from '@deck.gl/core';

// Create a MapState instance
const mapState = new MapState({
width: 800,
height: 600,
latitude: 37.7749,
longitude: -122.4194,
zoom: 11,
bearing: 0,
pitch: 0,
makeViewport: (props) => new WebMercatorViewport(props)
});

// Use MapState methods
const newState = mapState.pan({pos: [100, 100]});
const zoomedState = mapState.zoom({pos: [400, 300], scale: 2});
Comment on lines +73 to +92
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think these classes are intended to be used directly like this - rather, they are to be implemented and the Controller uses them. My current understanding is these are for helping users implement extensions of core controllers:

class CustomState extends MapState {

}

class CustomController extends MapController {
  ControllerState = CustomState
}

Usage docs along these lines makes more sense then showing direct function calls

```

### Methods

MapState provides the following interaction methods:

- `panStart({pos})` - Start a pan interaction
- `pan({pos, startPos})` - Pan the map
- `panEnd()` - End a pan interaction
- `rotateStart({pos})` - Start a rotation interaction
- `rotate({pos, deltaAngleX, deltaAngleY})` - Rotate the map
- `rotateEnd()` - End a rotation interaction
- `zoomStart({pos})` - Start a zoom interaction
- `zoom({pos, startPos, scale})` - Zoom the map
- `zoomEnd()` - End a zoom interaction
- `zoomIn(speed)` - Zoom in
- `zoomOut(speed)` - Zoom out
- `moveLeft(speed)`, `moveRight(speed)`, `moveUp(speed)`, `moveDown(speed)` - Move the map
- `rotateLeft(speed)`, `rotateRight(speed)`, `rotateUp(speed)`, `rotateDown(speed)` - Rotate the map

## MapStateProps

The `MapStateProps` type defines the properties for configuring map viewport state.

### Properties

- `width` (number) - The width of the viewport
- `height` (number) - The height of the viewport
- `latitude` (number) - The latitude at the center of the viewport
- `longitude` (number) - The longitude at the center of the viewport
- `zoom` (number) - The tile zoom level of the map
- `bearing` (number, optional) - The bearing of the viewport in degrees. Default `0`
- `pitch` (number, optional) - The pitch of the viewport in degrees. Default `0`
- `altitude` (number, optional) - Specify the altitude of the viewport camera. Unit: map heights. Default `1.5`
- `position` ([number, number, number], optional) - Viewport position. Default `[0, 0, 0]`
- `maxZoom` (number, optional) - Maximum zoom level. Default `20`
- `minZoom` (number, optional) - Minimum zoom level. Default `0`
- `maxPitch` (number, optional) - Maximum pitch in degrees. Default `60`
- `minPitch` (number, optional) - Minimum pitch in degrees. Default `0`
- `normalize` (boolean, optional) - Normalize viewport props to fit map height into viewport. Default `true`

### Usage

```js
import type {MapStateProps} from '@deck.gl/core';

const viewState: MapStateProps = {
width: 800,
height: 600,
latitude: 37.7749,
longitude: -122.4194,
zoom: 11,
bearing: 0,
pitch: 45,
maxZoom: 18,
minZoom: 5
};
```

## Source

Expand Down
3 changes: 2 additions & 1 deletion modules/core/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ export {default as _GlobeView} from './views/globe-view';

// Controllers
export {default as Controller} from './controllers/controller';
export {default as MapController} from './controllers/map-controller';
export {default as MapController, MapState} from './controllers/map-controller';
export {default as _GlobeController} from './controllers/globe-controller';
export {default as FirstPersonController} from './controllers/first-person-controller';
export {default as OrbitController} from './controllers/orbit-controller';
Expand Down Expand Up @@ -143,6 +143,7 @@ export type {
ViewStateChangeParameters,
InteractionState
} from './controllers/controller';
export type {MapStateProps} from './controllers/map-controller';

// INTERNAL, DO NOT USE
// @deprecated internal do not use
Expand Down
Loading