Classdesc

A 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.

A 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 Web Mercator (EPSG:3857).

The view states

A 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.

The zoom state is actually not saved on the view: all computations internally use the resolution state. Still, the setZoom and getZoom methods are available, as well as getResolutionForZoom and getZoomForResolution to switch from one system to the other.

The constraints

setCenter, setResolution and setRotation can be used to change the states of the view, but any constraint defined in the constructor will be applied along the way.

A View object can have a resolution constraint, a rotation constraint and a center constraint.

The resolution constraint typically restricts min/max values and 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. By default, the view only has a min/max restriction and allow intermediary zoom levels when pinch-zooming for example.

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

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

Changing the view state

It is important to note that setZoom, setResolution, setCenter and setRotation are subject to the above mentioned constraints. As such, it may sometimes not be possible to know in advance the resulting state of the View. For example, calling setResolution(10) does not guarantee that getResolution() will return 10.

A consequence of this is that, when applying a delta on the view state, one should use adjustCenter, adjustRotation, adjustZoom and adjustResolution rather than the corresponding setters. This will let view do its internal computations. Besides, the adjust* methods also take an anchor argument which allows specifying an origin for the transformation.

Interacting with the view

View constraints are usually only applied when the view is at rest, meaning that no interaction or animation is ongoing. As such, if the user puts the view in a state that is not equivalent to a constrained one (e.g. rotating the view when the snap angle is 0), an animation will be triggered at the interaction end to put back the view to a stable state;

Api

Hierarchy (view full)

Constructors

Properties

disposed: boolean

The object has already been disposed.

on: ViewOnSignature<EventsKey>
once: ViewOnSignature<EventsKey>
un: ViewOnSignature<void>

Accessors

  • get padding(): undefined | number[]
  • Padding (in css pixels). If the map viewport is partially covered with other content (overlays) along its edges, this setting allows to shift the center of the viewport away from that content. The order of the values in the array is top, right, bottom, left. The default is no padding, which is equivalent to [0, 0, 0, 0].

    Returns undefined | number[]

    Api

  • set padding(arg): void
  • Parameters

    • arg: undefined | number[]

    Returns void

Methods

  • Parameters

    • key: string

      Key name.

    • listener: Listener

      Listener.

    Returns void

  • Parameters

    • type: string

      Type.

    • listener: Listener

      Listener.

    Returns void

  • Adds relative coordinates to the center of the view. Any extent constraint will apply.

    Parameters

    • deltaCoordinates: Coordinate

      Relative value to add.

    Returns void

    Api

  • Adds relative coordinates to the center of the view. Any extent constraint will apply.

    Parameters

    • deltaCoordinates: Coordinate

      Relative value to add.

    Returns void

  • Multiply the view resolution by a ratio, optionally using an anchor. Any resolution constraint will apply.

    Parameters

    • ratio: number

      The ratio to apply on the view resolution.

    • Optional anchor: Coordinate

      The origin of the transformation.

    Returns void

    Api

  • Multiply the view resolution by a ratio, optionally using an anchor. Any resolution constraint will apply.

    Parameters

    • ratio: number

      The ratio to apply on the view resolution.

    • Optional anchor: Coordinate

      The origin of the transformation.

    Returns void

  • Adds a value to the view rotation, optionally using an anchor. Any rotation constraint will apply.

    Parameters

    • delta: number

      Relative value to add to the zoom rotation, in radians.

    • Optional anchor: Coordinate

      The rotation center.

    Returns void

    Api

  • Parameters

    • delta: number

      Relative value to add to the zoom rotation, in radians.

    • Optional anchor: Coordinate

      The rotation center.

    Returns void

  • Adds a value to the view zoom level, optionally using an anchor. Any resolution constraint will apply.

    Parameters

    • delta: number

      Relative value to add to the zoom level.

    • Optional anchor: Coordinate

      The origin of the transformation.

    Returns void

    Api

  • 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 module: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).

    Parameters

    • Rest ...args: (AnimationOptions | ((arg0) => void))[]

    Returns void

    Api

  • Parameters

    • Rest ...args: (AnimationOptions | ((arg0) => void))[]

    Returns void

  • Set up the view with the given options.

    Parameters

    • options: ViewOptions

      View options.

    Returns void

  • Protected

    Apply any properties from another object without triggering events.

    Parameters

    • source: Object

      The source object.

    Returns void

  • Notify the View that an interaction has started. The view state will be resolved to a stable one if needed (depending on its constraints).

    Returns void

    Api

  • Parameters

    • rotation: number

      Target rotation.

    • anchor: Coordinate

      Rotation anchor.

    Returns undefined | Coordinate

    Center for rotation and anchor.

  • Calculates the shift between map and viewport center.

    Parameters

    • center: Coordinate

      Center.

    • resolution: number

      Resolution.

    • rotation: number

      Rotation.

    • size: Size

      Size.

    Returns undefined | number[]

    Center shift.

  • Parameters

    • resolution: number

      Target resolution.

    • anchor: Coordinate

      Zoom anchor.

    Returns undefined | Coordinate

    Center for resolution and anchor.

  • 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().

    Parameters

    • Optional size: Size

      Box pixel size. If not provided, the size of the map that uses this view will be used.

    Returns Extent

    Extent.

    Api

  • Parameters

    • Optional size: Size

      Box pixel size. If not provided, the map's last known viewport size will be used.

    Returns Extent

    Extent.

  • Cancel any ongoing animations.

    Returns void

    Api

  • Center on coordinate and view position.

    Parameters

    • coordinate: Coordinate

      Coordinate.

    • size: Size

      Box pixel size.

    • position: Pixel

      Position on the view to center on.

    Returns void

    Api

  • Parameters

    • coordinate: Coordinate

      Coordinate.

    • size: Size

      Box pixel size.

    • position: Pixel

      Position on the view to center on.

    Returns void

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

    Returns void

    Api

  • 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.

    Parameters

    • event: string | BaseEvent

      Event object.

    Returns undefined | boolean

    false if anyone called preventDefault on the event object or if any of the listeners returned false.

    Api

  • Clean up.

    Returns void

  • Protected

    Extension point for disposable objects.

    Returns void

  • Notify the View that an interaction has ended. The view state will be resolved to a stable one if needed (depending on its constraints).

    Parameters

    • Optional duration: number

      Animation duration in ms.

    • Optional resolutionDirection: number

      Which direction to zoom.

    • Optional anchor: Coordinate

      The origin of the transformation.

    Returns void

    Api

  • Notify the View that an interaction has ended. The view state will be resolved to a stable one if needed (depending on its constraints).

    Parameters

    • Optional duration: number

      Animation duration in ms.

    • Optional resolutionDirection: number

      Which direction to zoom.

    • Optional anchor: Coordinate

      The origin of the transformation.

    Returns void

  • 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.

    Parameters

    • geometryOrExtent: Extent | SimpleGeometry

      The geometry or extent to fit the view to.

    • Optional options: FitOptions

      Options.

    Returns void

    Api

  • Parameters

    • geometry: SimpleGeometry

      The geometry.

    • Optional options: FitOptions

      Options.

    Returns void

  • Gets a value.

    Parameters

    • key: string

      Key name.

    Returns any

    Value.

    Api

  • Determine if the view is being animated.

    Returns boolean

    The view is being animated.

    Api

  • Get the view center.

    Returns undefined | Coordinate

    The center of the view.

    Observable

    Api

  • Get the view center without transforming to user projection.

    Returns undefined | Coordinate

    The center of the view.

  • Returns boolean

    Resolution constraint is set

  • Get a valid position for the view center according to the current constraints.

    Parameters

    • targetCenter: undefined | Coordinate

      Target center position.

    • Optional targetResolution: number

      Target resolution. If not supplied, the current one will be used. This is useful to guess a valid center position at a different zoom level.

    Returns undefined | Coordinate

    Valid center position.

  • Get a valid resolution according to the current view constraints.

    Parameters

    • targetResolution: undefined | number

      Target resolution.

    • Optional direction: number

      Indicate which resolution should be used by a renderer if the view resolution does not match any resolution of the tile source. If 0, the nearest resolution will be used. If 1, the nearest lower resolution will be used. If -1, the nearest higher resolution will be used.

    Returns undefined | number

    Valid resolution.

  • Get a valid zoom level according to the current view constraints.

    Parameters

    • targetZoom: undefined | number

      Target zoom.

    • Optional direction: number

      Indicate which resolution should be used by a renderer if the view resolution does not match any resolution of the tile source. If 0, the nearest resolution will be used. If 1, the nearest lower resolution will be used. If -1, the nearest higher resolution will be used.

    Returns undefined | number

    Valid zoom level.

  • Returns Constraints

    Constraints.

  • Parameters

    • Optional hints: number[]

      Destination array.

    Returns number[]

    Hint.

  • Determine if the user is interacting with the view, such as panning or zooming.

    Returns boolean

    The view is being interacted with.

    Api

  • Get a list of object property names.

    Returns string[]

    List of property names.

    Api

  • Get the listeners for a specified event type. Listeners are returned in the order that they will be called in.

    Parameters

    • type: string

      Type.

    Returns undefined | Listener[]

    Listeners.

  • Get the maximum resolution of the view.

    Returns number

    The maximum resolution of the view.

    Api

  • Get the maximum zoom level for the view.

    Returns number

    The maximum zoom level.

    Api

  • Get the minimum resolution of the view.

    Returns number

    The minimum resolution of the view.

    Api

  • Get the minimum zoom level for the view.

    Returns number

    The minimum zoom level.

    Api

  • Get the view projection.

    Returns Projection

    The projection of the view.

    Api

  • Get an object of all property names and values.

    Returns {
        [x: string]: any;
    }

    Object.

    • [x: string]: any

    Api

  • Get an object of all property names and values.

    Returns null | {
        [x: string]: any;
    }

    Object.

  • Get the view resolution.

    Returns undefined | number

    The resolution of the view.

    Observable

    Api

  • Get the resolution for a provided extent (in map units) and size (in pixels).

    Parameters

    • extent: Extent

      Extent.

    • Optional size: Size

      Box pixel size.

    Returns number

    The resolution at which the provided extent will render at the given size.

    Api

  • Get the resolution for a provided extent (in map units) and size (in pixels).

    Parameters

    • extent: Extent

      Extent.

    • Optional size: Size

      Box pixel size.

    Returns number

    The resolution at which the provided extent will render at the given size.

  • Return a function that returns a value between 0 and 1 for a resolution. Exponential scaling is assumed.

    Parameters

    • Optional power: number

      Power.

    Returns ((arg0) => number)

    Resolution for value function.

      • (arg0): number
      • Parameters

        • arg0: number

        Returns number

  • Get the resolution for a zoom level.

    Parameters

    • zoom: number

      Zoom level.

    Returns number

    The view resolution for the provided zoom level.

    Api

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

    Returns undefined | number[]

    The resolutions of the view.

    Api

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

    Returns number

    Revision.

    Api

  • Get the view rotation.

    Returns number

    The rotation of the view in radians.

    Observable

    Api

  • Returns State

    View state.

  • Get an updated version of the view options used to construct the view. The current resolution (or zoom), center, and rotation are applied to any stored options. The provided options can be used to apply new min/max zoom or resolution limits.

    Parameters

    • newOptions: ViewOptions

      New options to be applied.

    Returns ViewOptions

    New options updated with the current view state.

  • Return a function that returns a resolution for a value between 0 and 1. Exponential scaling is assumed.

    Parameters

    • Optional power: number

      Power.

    Returns ((arg0) => number)

    Value for resolution function.

      • (arg0): number
      • Parameters

        • arg0: number

        Returns number

  • Returns ViewStateLayerStateExtent

    Like FrameState, but just viewState and extent.

  • Get the current zoom level. This method may return non-integer zoom levels if the view does not constrain the resolution, or if an interaction or animation is underway.

    Returns undefined | number

    Zoom.

    Api

  • Get the zoom level for a resolution.

    Parameters

    • resolution: number

      The resolution.

    Returns undefined | number

    The zoom level for the provided resolution.

    Api

  • Parameters

    • Optional type: string

      Type. If not provided, true will be returned if this event target has any listeners.

    Returns boolean

    Has listeners.

  • Returns boolean

    The object has properties.

  • Returns boolean

    Is defined.

  • Parameters

    • key: string

      Key name.

    • oldValue: any

      Old value.

    Returns void

  • Protected

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0) => unknown)

      Listener.

        • (arg0): unknown
        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns EventsKey | EventsKey[]

    Event key.

  • Protected

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0) => unknown)

      Listener.

        • (arg0): unknown
        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns EventsKey | EventsKey[]

    Event key.

  • Parameters

    • key: string

      Key name.

    • listener: Listener

      Listener.

    Returns void

  • Parameters

    • type: string

      Type.

    • listener: Listener

      Listener.

    Returns void

  • If any constraints need to be applied, an animation will be triggered. This is typically done on interaction end. Note: calling this with a duration of 0 will apply the constrained values straight away, without animation.

    Parameters

    • Optional duration: number

      The animation duration in ms.

    • Optional resolutionDirection: number

      Which direction to zoom.

    • Optional anchor: Coordinate

      The origin of the transformation.

    Returns void

  • Calculate rotated extent

    Parameters

    Returns Extent

    The rotated extent for the geometry.

  • Sets a value.

    Parameters

    • key: string

      Key name.

    • value: any

      Value.

    • Optional silent: boolean

      Update without triggering an event.

    Returns void

    Api

  • Set the center of the current view. Any extent constraint will apply.

    Parameters

    • center: undefined | Coordinate

      The center of the view.

    Returns void

    Observable

    Api

  • Set the center using the view projection (not the user projection).

    Parameters

    • center: undefined | Coordinate

      The center of the view.

    Returns void

  • Set whether the view should allow intermediary zoom levels.

    Parameters

    • enabled: boolean

      Whether the resolution is constrained.

    Returns void

    Api

  • Parameters

    • hint: any

      Hint.

    • delta: number

      Delta.

    Returns number

    New value.

  • Set a new maximum zoom level for the view.

    Parameters

    • zoom: number

      The maximum zoom level.

    Returns void

    Api

  • Set a new minimum zoom level for the view.

    Parameters

    • zoom: number

      The minimum zoom level.

    Returns void

    Api

  • 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).

    Parameters

    • values: {
          [x: string]: any;
      }

      Values.

      • [x: string]: any
    • Optional silent: boolean

      Update without triggering an event.

    Returns void

    Api

  • Set the resolution for this view. Any resolution constraint will apply.

    Parameters

    • resolution: undefined | number

      The resolution of the view.

    Returns void

    Observable

    Api

  • Set the rotation for this view. Any rotation constraint will apply.

    Parameters

    • rotation: number

      The rotation of the view in radians.

    Returns void

    Observable

    Api

  • Stores the viewport size on the view. The viewport size is not read every time from the DOM to avoid performance hit and layout reflow. This should be done on map size change. Note: the constraints are not resolved during an animation to avoid stopping it

    Parameters

    • Optional size: Size

      Viewport size; if undefined, [100, 100] is assumed

    Returns void

  • Zoom to a specific zoom level. Any resolution constrain will apply.

    Parameters

    • zoom: number

      Zoom level.

    Returns void

    Api

  • Protected

    Unlisten for a certain type of event.

    Parameters

    • type: string | string[]

      Type.

    • listener: ((arg0) => unknown)

      Listener.

        • (arg0): unknown
        • Parameters

          • arg0: Event | BaseEvent

          Returns unknown

    Returns void

  • Unsets a property.

    Parameters

    • key: string

      Key name.

    • Optional silent: boolean

      Unset without triggering an event.

    Returns void

    Api

  • Update all animations.

    Returns void