OpenLayers v4.0.1 API - Class: View

# Class: View

This documentation is for OpenLayers v4.0.1. The latest is v.

## ol.View

An ol.View object represents a simple 2D view of the map.

This is the object to act upon to change the center, resolution, and rotation of the map.

### The view states

An `ol.View` is determined by three states: `center`, `resolution`, and `rotation`. Each state has a corresponding getter and setter, e.g. `getCenter` and `setCenter` for the `center` state.

An `ol.View` has a `projection`. The projection determines the coordinate system of the center, and its units determine the units of the resolution (projection units per pixel). The default projection is Spherical Mercator (EPSG:3857).

### The constraints

`setCenter`, `setResolution` and `setRotation` can be used to change the states of the view. Any value can be passed to the setters. And the value that is passed to a setter will effectively be the value set in the view, and returned by the corresponding getter.

But an `ol.View` object also has a resolution constraint, a rotation constraint and a center constraint.

As said above, no constraints are applied when the setters are used to set new states for the view. Applying constraints is done explicitly through the use of the `constrain*` functions (`constrainResolution` and `constrainRotation` and `constrainCenter`).

The main users of the constraints are the interactions and the controls. For example, double-clicking on the map changes the view to the "next" resolution. And releasing the fingers after pinch-zooming snaps to the closest resolution (with an animation).

The resolution constraint snaps to specific resolutions. It is determined by the following options: `resolutions`, `maxResolution`, `maxZoom`, and `zoomFactor`. If `resolutions` is set, the other three options are ignored. See documentation for each option for more information.

The rotation constraint snaps to specific angles. It is determined by the following options: `enableRotation` and `constrainRotation`. By default the rotation value is snapped to zero when approaching the horizontal.

The center constraint is determined by the `extent` option. By default the center is not constrained at all.

#### new ol.View(opt_options)

src/ol/view.js, line 80

  Name | Type | Description
  --- | --- | ---

  `options`

  View options.

  Name | Type | Description
  --- | --- | ---
  `center` | ol.Coordinate | undefined | The initial center for the view. The coordinate system for the center is specified with the `projection` option. Default is `undefined`, and layer sources will not be fetched if this is not set.
  `constrainRotation` | boolean | number | undefined | Rotation constraint. `false` means no constraint. `true` means no constraint, but snap to zero near zero. A number constrains the rotation to that number of values. For example, `4` will constrain the rotation to 0, 90, 180, and 270 degrees. The default is `true`.
  `enableRotation` | boolean | undefined | Enable rotation. Default is `true`. If `false` a rotation constraint that always sets the rotation to zero is used. The `constrainRotation` option has no effect if `enableRotation` is `false`.
  `extent` | ol.Extent | undefined | The extent that constrains the center, in other words, center cannot be set outside this extent. Default is `undefined`.
  `maxResolution` | number | undefined | The maximum resolution used to determine the resolution constraint. It is used together with `minResolution` (or `maxZoom`) and `zoomFactor`. If unspecified it is calculated in such a way that the projection's validity extent fits in a 256x256 px tile. If the projection is Spherical Mercator (the default) then `maxResolution` defaults to `40075016.68557849 / 256 = 156543.03392804097`.
  `minResolution` | number | undefined | The minimum resolution used to determine the resolution constraint. It is used together with `maxResolution` (or `minZoom`) and `zoomFactor`. If unspecified it is calculated assuming 29 zoom levels (with a factor of 2). If the projection is Spherical Mercator (the default) then `minResolution` defaults to `40075016.68557849 / 256 / Math.pow(2, 28) = 0.0005831682455839253`.
  `maxZoom` | number | undefined | The maximum zoom level used to determine the resolution constraint. It is used together with `minZoom` (or `maxResolution`) and `zoomFactor`. Default is `28`. Note that if `minResolution` is also provided, it is given precedence over `maxZoom`.
  `minZoom` | number | undefined | The minimum zoom level used to determine the resolution constraint. It is used together with `maxZoom` (or `minResolution`) and `zoomFactor`. Default is `0`. Note that if `maxResolution` is also provided, it is given precedence over `minZoom`.
  `projection` | ol.ProjectionLike | The projection. Default is `EPSG:3857` (Spherical Mercator).
  `resolution` | number | undefined | The initial resolution for the view. The units are `projection` units per pixel (e.g. meters per pixel). An alternative to setting this is to set `zoom`. Default is `undefined`, and layer sources will not be fetched if neither this nor `zoom` are defined.
  `resolutions` | Array.<number> | undefined | Resolutions to determine the resolution constraint. If set the `maxResolution`, `minResolution`, `minZoom`, `maxZoom`, and `zoomFactor` options are ignored.
  `rotation` | number | undefined | The initial rotation for the view in radians (positive rotation clockwise). Default is `0`.
  `zoom` | number | undefined | Only used if `resolution` is not defined. Zoom level used to calculate the initial resolution for the view. The initial resolution is determined using the `ol.View#constrainResolution` method.
  `zoomFactor` | number | undefined | The zoom factor used to determine the resolution constraint. Default is `2`.

  ##### Fires:

  - `change` (ol.events.Event) - Generic change event. Triggered when the revision counter is increased.
  - `change:center` (ol.Object.Event)
  - `change:resolution` (ol.Object.Event)
  - `change:rotation` (ol.Object.Event)
  - `propertychange` (ol.Object.Event) - Triggered when a property is changed.

### Extends

- ol.Object

### Observable Properties

Name | Type | Settable | ol.Object.Event type | Description
--- | --- | --- | --- | ---
`center` | ol.Coordinate | undefined | yes | `change:center` | The center of the view.
`resolution` | number | undefined | yes | `change:resolution` | The resolution of the view.
`rotation` | number | yes | `change:rotation` | The rotation of the view in radians.

### Methods

#### animate(var_args)

src/ol/view.js, line 208

  Animate the view. The view's center, zoom (or resolution), and rotation can be animated for smooth transitions between view states. For example, to animate the view to a new zoom level:

      view.animate({zoom: view.getZoom() + 1});

  By default, the animation lasts one second and uses in-and-out easing. You can customize this behavior by including `duration` (in milliseconds) and `easing` options (see `ol.easing`).

  To chain together multiple animations, call the method with multiple animation objects. For example, to first zoom and then pan:

      view.animate({zoom: 10}, {center: [0, 0]});

  If you provide a function as the last argument to the animate method, it will get called at the end of an animation series. The callback will be called with `true` if the animation series completed on its own or `false` if it was cancelled.

  Animations are cancelled by user interactions (e.g. dragging the map) or by calling `view.setCenter()`, `view.setResolution()`, or `view.setRotation()` (or another method that calls one of these).

  Name | Type | Description
  --- | --- | ---

  `var_args`

  Animation options. Multiple animations can be run in series by passing multiple options objects. To run multiple animations in parallel, call the method multiple times. An optional callback can be provided as a final argument. The callback will be called with a boolean indicating whether the animation completed without being cancelled.

  Name | Type | Description
  --- | --- | ---
  `center` | ol.Coordinate | undefined | The center of the view at the end of the animation.
  `zoom` | number | undefined | The zoom level of the view at the end of the animation. This takes precedence over `resolution`.
  `resolution` | number | undefined | The resolution of the view at the end of the animation. If `zoom` is also provided, this option will be ignored.
  `rotation` | number | undefined | The rotation of the view at the end of the animation.
  `anchor` | ol.Coordinate | undefined | Optional anchor to remained fixed during a rotation or resolution animation.
  `duration` | number | undefined | The duration of the animation in milliseconds (defaults to `1000`).
  `easing` | undefined | function | The easing function used during the animation (defaults to `ol.easing.inAndOut`). The function will be called for each frame with a number representing a fraction of the animation's duration. The function should return a number between 0 and 1 representing the progress toward the destination state.

#### calculateExtent(opt_size){ol.Extent}

src/ol/view.js, line 496

  Calculate the extent for the current view state and the passed size. The size is the pixel dimensions of the box into which the calculated extent should fit. In most cases you want to get the extent of the entire map, that is `map.getSize()`.

  Name | Type | Description
  --- | --- | ---
  `size` | ol.Size | Box pixel size. If not provided, the size of the first map that uses this view will be used.

  ##### Returns:

  Extent.

#### centerOn(coordinate, size, position)

src/ol/view.js, line 793

  Center on coordinate and view position.

  Name | Type | Description
  --- | --- | ---
  `coordinate` | ol.Coordinate | Coordinate.
  `size` | ol.Size | Box pixel size.
  `position` | ol.Pixel | Position on the view to center on.

#### changed() inherited

src/ol/observable.js, line 58

  Increases the revision counter and dispatches a 'change' event.

#### constrainCenter(center){ol.Coordinate|undefined}

src/ol/view.js, line 425

  Get the constrained center of this view.

  Name | Type | Description
  --- | --- | ---
  `center` | ol.Coordinate | undefined | Center.

  ##### Returns:

  Constrained center.

#### constrainResolution(resolution, opt_delta, opt_direction){number|undefined}

src/ol/view.js, line 438

  Get the constrained resolution of this view.

  Name | Type | Description
  --- | --- | ---
  `resolution` | number | undefined | Resolution.
  `delta` | number | Delta. Default is `0`.
  `direction` | number | Direction. Default is `0`.

  ##### Returns:

  Constrained resolution.

#### constrainRotation(rotation, opt_delta){number|undefined}

src/ol/view.js, line 453

  Get the constrained rotation of this view.

  Name | Type | Description
  --- | --- | ---
  `rotation` | number | undefined | Rotation.
  `delta` | number | Delta. Default is `0`.

  ##### Returns:

  Constrained rotation.

#### dispatchEvent(event) inherited

src/ol/observable.js, line 75

  Dispatches an event and calls all listeners listening for events of this type. The event parameter can either be a string or an Object with a `type` property.

  Name | Type | Description
  --- | --- | ---
  `event` | Object | ol.events.Event | string | Event object.

#### fit(geometryOrExtent, opt_options)

src/ol/view.js, line 692

  Fit the given geometry or extent based on the given map size and border. The size is pixel dimensions of the box to fit the extent into. In most cases you will want to use the map size, that is `map.getSize()`. Takes care of the map angle.

  Name | Type | Description
  --- | --- | ---
  `geometryOrExtent` | ol.geom.SimpleGeometry | ol.Extent | The geometry or extent to fit the view to.

  `options`

  Options.

  Name | Type | Description
  --- | --- | ---
  `size` | ol.Size | undefined | The size in pixels of the box to fit the extent into. Default is the current size of the first map in the DOM that uses this view, or `[100, 100]` if no such map is found.
  `padding` | !Array.<number> | undefined | Padding (in pixels) to be cleared inside the view. Values in the array are top, right, bottom and left padding. Default is `[0, 0, 0, 0]`.
  `constrainResolution` | boolean | undefined | Constrain the resolution. Default is `true`.
  `nearest` | boolean | undefined | Get the nearest extent. Default is `false`.
  `minResolution` | number | undefined | Minimum resolution that we zoom to. Default is `0`.
  `maxZoom` | number | undefined | Maximum zoom level that we zoom to. If `minResolution` is given, this property is ignored.
  `duration` | number | undefined | The duration of the animation in milliseconds. By default, there is no animations.
  `easing` | undefined | function | The easing function used during the animation (defaults to `ol.easing.inAndOut`). The function will be called for each frame with a number representing a fraction of the animation's duration. The function should return a number between 0 and 1 representing the progress toward the destination state.

#### get(key){*} inherited

src/ol/object.js, line 101

  Gets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.

  ##### Returns:

  Value.

#### getCenter(){ol.Coordinate|undefined}

src/ol/view.js, line 465

  Get the view center.

  ##### Returns:

  The center of the view.

#### getKeys(){Array.<string>} inherited

src/ol/object.js, line 115

  Get a list of object property names.

  ##### Returns:

  List of property names.

#### getMaxResolution(){number}

src/ol/view.js, line 514

  Get the maximum resolution of the view.

  ##### Returns:

  The maximum resolution of the view.

#### getMinResolution(){number}

src/ol/view.js, line 524

  Get the minimum resolution of the view.

  ##### Returns:

  The minimum resolution of the view.

#### getProjection(){ol.proj.Projection}

src/ol/view.js, line 534

  Get the view projection.

  ##### Returns:

  The projection of the view.

#### getProperties(){Object.<string, *>} inherited

src/ol/object.js, line 125

  Get an object of all property names and values.

  ##### Returns:

  Object.

#### getResolution(){number|undefined}

src/ol/view.js, line 545

  Get the view resolution.

  ##### Returns:

  The resolution of the view.

#### getResolutions(){Array.<number>|undefined}

src/ol/view.js, line 557

  Get the resolutions for the view. This returns the array of resolutions passed to the constructor of the {ol.View}, or undefined if none were given.

  ##### Returns:

  The resolutions of the view.

#### getRevision(){number} inherited

src/ol/observable.js, line 84

  Get the version number for this object. Each time the object is modified, its version number will be incremented.

  ##### Returns:

  Revision.

#### getRotation(){number}

src/ol/view.js, line 605

  Get the view rotation.

  ##### Returns:

  The rotation of the view in radians.

#### getZoom(){number|undefined}

src/ol/view.js, line 657

  Get the current zoom level. Return undefined if the current resolution is undefined or not within the "resolution constraints".

  ##### Returns:

  Zoom.

#### on(type, listener, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 99

  Listen for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.
  `this` | Object | The object to use as `this` in `listener`.

  ##### Returns:

  Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

#### once(type, listener, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 124

  Listen once for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.
  `this` | Object | The object to use as `this` in `listener`.

  ##### Returns:

  Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

#### rotate(rotation, opt_anchor)

src/ol/view.js, line 827

  Rotate the view around a given coordinate.

  Name | Type | Description
  --- | --- | ---
  `rotation` | number | New rotation value for the view.
  `anchor` | ol.Coordinate | The rotation center.

#### set(key, value, opt_silent) inherited

src/ol/object.js, line 150

  Sets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `value` | * | Value.
  `silent` | boolean | Update without triggering an event.

#### setCenter(center)

src/ol/view.js, line 842

  Set the center of the current view.

  Name | Type | Description
  --- | --- | ---
  `center` | ol.Coordinate | undefined | The center of the view.

#### setProperties(values, opt_silent) inherited

src/ol/object.js, line 170

  Sets a collection of key-value pairs. Note that this changes any existing properties and adds new ones (it does not remove any existing properties).

  Name | Type | Description
  --- | --- | ---
  `values` | Object.<string, *> | Values.
  `silent` | boolean | Update without triggering an event.

#### setResolution(resolution)

src/ol/view.js, line 868

  Set the resolution for this view.

  Name | Type | Description
  --- | --- | ---
  `resolution` | number | undefined | The resolution of the view.

#### setRotation(rotation)

src/ol/view.js, line 882

  Set the rotation for this view.

  Name | Type | Description
  --- | --- | ---
  `rotation` | number | The rotation of the view in radians.

#### setZoom(zoom)

src/ol/view.js, line 895

  Zoom to a specific zoom level.

  Name | Type | Description
  --- | --- | ---
  `zoom` | number | Zoom level.

#### un(type, listener, opt_this) inherited

src/ol/observable.js, line 147

  Unlisten for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.
  `this` | Object | The object which was used as `this` by the `listener`.

#### unset(key, opt_silent) inherited

src/ol/object.js, line 184

  Unsets a property.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `silent` | boolean | Unset without triggering an event.