From 42abdb308ae3aba70fd20654d9b6b009f7110aa7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Lemoine?= Date: Sat, 6 Jul 2013 21:33:59 +0200 Subject: [PATCH 1/2] Better docs for View2DOptions --- src/objectliterals.jsdoc | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) diff --git a/src/objectliterals.jsdoc b/src/objectliterals.jsdoc index 9fe757271c..215f8d1328 100644 --- a/src/objectliterals.jsdoc +++ b/src/objectliterals.jsdoc @@ -88,21 +88,33 @@ /** * Object literal with config options for the view. * @typedef {Object} ol.View2DOptions - * @property {ol.Coordinate|undefined} center The view center in map projection. - * @property {number|undefined} maxResolution The maximum resolution in map - * units per pixel. - * @property {number|undefined} maxZoom The maximum zoom level for this view. - * Zoom level 0 uses the `maxResolution`; subsequent zoom levels are - * calculated by dividing the previous resolution by `zoomFactor`. - * @property {ol.ProjectionLike} projection The map projection. + * @property {ol.Coordinate|undefined} center The initial center for the view. + * The coordinate system for the center is specified with the `projection` + * option. + * @property {number|undefined} maxResolution The maximum resolution used to + * determine the resolution constraint. It is used together with `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. + * @property {number|undefined} maxZoom The maximum zoom level used to determine + * the resolution constraint. It is used together with `maxResolution` and + * `zoomFactor`. Default is 28. + * @property {ol.ProjectionLike} projection The projection. Default is + * `EPSG:3857` (Spherical Mercator). * @property {number|undefined} resolution The initial resolution for the view. - * @property {Array.|undefined} resolutions The resolutions for this - * view. If configured, this is equivalent to specifying `maxResolution` and - * `maxZoom`. - * @property {number|undefined} rotation Initial rotation of the view. - * @property {number|undefined} zoom Initial zoom level of the view. - * @property {number|undefined} zoomFactor Factor to calculate resolutions for - * zoom levels. Default is 2. + * The units are `projection` units per pixel (e.g. meters per pixel). + * @property {Array.|undefined} resolutions Resolutions to determine the + * resolution constraint. If set the `maxResolution`, `maxZoom` and + * `zoomFactor` options are ignored. + * @property {number|undefined} rotation The initial rotation for the view + * in radians (positive rotation clockwise). + * @property {number|undefined} zoom Zoom level used to calculate the initial + * resolution for the view. The initial resolution is determined using the + * `ol.View2D#constrainResolution` method. + * @property {number|undefined} zoomFactor The zoom factor used to determine the + * resolution constraint. It is together with `maxResolution` and `maxZoom`. + * Default is 2. */ /** From daa03b5ef7a33dae659a5ed148d4e4b9355d710b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Lemoine?= Date: Sat, 6 Jul 2013 21:34:17 +0200 Subject: [PATCH 2/2] @class doc for View2D --- src/ol/view2d.js | 48 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/src/ol/view2d.js b/src/ol/view2d.js index 8e465c2407..87c19dad1f 100644 --- a/src/ol/view2d.js +++ b/src/ol/view2d.js @@ -32,13 +32,51 @@ ol.View2DProperty = { /** - * Create a new View2D, a View2D manages properties such as center, - * projection, resolution and rotation. + * @class + * An ol.View2D object represents a simple 2D view of the map. * - * Example: + * This is the object to act upon to change the center, resolution, + * and rotation of the map. * - * // to get the current extent - * map.getView().getView2D().calculateExtent(map.getSize()) + * ### The view states + * + * An `ol.View2D` is determined by three states: `center`, `resolution`, + * and `rotation`. To each state corresponds a getter and a setter. E.g. + * `getCenter` and `setCenter` for the `center` state. + * + * An `ol.View2D` 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.View2D` object also has a *resolution constraint* and a + * *rotation constraint*. There's currently no *center constraint*, but + * this may change in the future. + * + * 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`). + * + * 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). + * + * So 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 {@link ol.View2DOptions} for more information. + * + * The *rotation constaint* is currently not configurable. It snaps the + * rotation value to zero when approaching the horizontal. * * @constructor * @implements {ol.IView2D}