Skip to content

Commit

Permalink
Rationalize map view method options
Browse files Browse the repository at this point in the history 
* Map#setView is replaced with Map#jumpTo.
* Map#jumpTo, Map#easeTo, and Map#flyTo now all accept the
  same set of view options.
  • Loading branch information
@jfirebaugh
jfirebaugh committed May 25, 2015
1 parent 1ccd9df commit 575515a
Show file tree
Hide file tree
Showing 7 changed files with 147 additions and 88 deletions.
5 changes: 3 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ An in-progress version being developed in the `master` branch.

* `mapboxgl.Source` is no longer exported. Use `map.addSource()` instead.
* `mapboxgl.util.supported()` moved to `mapboxgl.supported()
* map#setView(latlng, zoom, bearing) changed to map#setView(latlng, zoom, bearing, pitch)
* map#easeTo(latlng, zoom, bearing, options) changed to map#easeTo(latlng, zoom, bearing, pitch, options)
* map#setView(latlng, zoom, bearing) changed to map#jumpTo(options)
* map#easeTo(latlng, zoom, bearing, options) changed to map#easeTo(options)
* map#flyTo(latlng, zoom, bearing, options) changed to map#flyTo(options)



Expand Down
4 changes: 2 additions & 2 deletions docs/_posts/examples/3400-01-03-flyto.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@
function fly() {
// Fly to a random location by offsetting the point 40, -74.50
// by up to 5 degrees.
map.flyTo([
map.flyTo({ center: [
40 + (Math.random() - 0.5) * 10,
-74.50 + (Math.random() - 0.5) * 10]);
-74.50 + (Math.random() - 0.5) * 10] });
}
</script>
68 changes: 30 additions & 38 deletions js/ui/easings.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -267,31 +267,27 @@ util.extend(exports, /** @lends Map.prototype */{
nw = tr.project(bounds.getNorthWest()),
se = tr.project(bounds.getSouthEast()),
size = se.sub(nw),
center = tr.unproject(nw.add(se).div(2)),

scaleX = (tr.width - options.padding * 2 - Math.abs(offset.x) * 2) / size.x,
scaleY = (tr.height - options.padding * 2 - Math.abs(offset.y) * 2) / size.y,
scaleY = (tr.height - options.padding * 2 - Math.abs(offset.y) * 2) / size.y;

zoom = Math.min(tr.scaleZoom(tr.scale * Math.min(scaleX, scaleY)), options.maxZoom);
options.center = tr.unproject(nw.add(se).div(2));
options.zoom = Math.min(tr.scaleZoom(tr.scale * Math.min(scaleX, scaleY)), options.maxZoom);
options.bearing = 0;

return options.linear ?
this.easeTo(center, zoom, 0, this.getPitch(), options) :
this.flyTo(center, zoom, 0, options);
this.easeTo(options) :
this.flyTo(options);
},

/**
* Easing animation to a specified location/zoom/bearing
*
* @param {Object} latlng a `LatLng` object
* @param {Number} zoom
* @param {Number} bearing
* @param {Number} pitch
* @param {animOptions}
* @param {ViewOptions+animOptions} options map view and animation options
* @fires movestart
* @fires moveend
* @returns {this}
*/
easeTo: function(latlng, zoom, bearing, pitch, options) {
easeTo: function(options) {
this.stop();

options = util.extend({
Expand All @@ -302,25 +298,27 @@ util.extend(exports, /** @lends Map.prototype */{

var tr = this.transform,
offset = Point.convert(options.offset).rotate(-tr.angle),
from = tr.point,
startZoom = this.getZoom(),
startBearing = this.getBearing(),
startPitch = this.getPitch();

latlng = LatLng.convert(latlng);
zoom = zoom === undefined ? startZoom : zoom;
bearing = bearing === undefined ? startBearing : this._normalizeBearing(bearing, startBearing);
pitch = pitch === undefined ? startPitch : pitch;
var zoom = 'zoom' in options ? +options.zoom : startZoom;
var bearing = 'bearing' in options ? this._normalizeBearing(options.bearing, startBearing) : startBearing;
var pitch = 'pitch' in options ? startPitch : pitch;

var scale = tr.zoomScale(zoom - startZoom),
from = tr.point,
to = latlng ? tr.project(latlng).sub(offset.div(scale)) : tr.point,
to = 'center' in options ? tr.project(LatLng.convert(options.center)).sub(offset.div(scale)) : from,
around;

if (zoom !== startZoom) {
around = tr.pointLocation(tr.centerPoint.add(to.sub(from).div(1 - 1 / scale)));
this.zooming = true;
}
if (startBearing !== bearing) this.rotating = true;

if (startBearing !== bearing) {
this.rotating = true;
}

this.fire('movestart');

Expand Down Expand Up @@ -353,29 +351,28 @@ util.extend(exports, /** @lends Map.prototype */{
/**
* Flying animation to a specified location/zoom/bearing with automatic curve
*
* @param {Object} latlng a `LatLng` object
* @param {Number} zoom
* @param {Number} bearing
* @param {Object} options
* @param {ViewOptions} options map view options
* @param {Number} [options.speed=1.2] How fast animation occurs
* @param {Number} [options.curve=1.42] How much zooming out occurs during animation
* @param {Function} options.easing
* @param {Function} [options.easing]
* @fires movestart
* @fires moveend
* @returns {this}
* @example
* // fly with default options to null island
* map.flyTo([0, 0], 9, 0);
* map.flyTo({center: [0, 0], zoom: 9});
* // using flyTo options
* map.flyTo([0, 0], 9, 0, {
* map.flyTo({
* center: [0, 0],
* zoom: 9,
* speed: 0.2,
* curve: 1,
* easing: function(t) {
* return t;
* }
* });
*/
flyTo: function(latlng, zoom, bearing, options) {
flyTo: function(options) {
this.stop();

options = util.extend({
Expand All @@ -385,23 +382,18 @@ util.extend(exports, /** @lends Map.prototype */{
easing: util.ease
}, options);

latlng = LatLng.convert(latlng);

var offset = Point.convert(options.offset),
tr = this.transform,
var tr = this.transform,
offset = Point.convert(options.offset),
startZoom = this.getZoom(),
startBearing = this.getBearing();

zoom = zoom === undefined ? startZoom : zoom;
bearing = bearing === undefined ? startBearing : this._normalizeBearing(bearing, startBearing);
var center = 'center' in options ? LatLng.convert(options.center) : this.getCenter();
var zoom = 'zoom' in options ? +options.zoom : startZoom;
var bearing = 'bearing' in options ? this._normalizeBearing(options.bearing, startBearing) : startBearing;

var scale = tr.zoomScale(zoom - startZoom),
from = tr.point,
to = tr.project(latlng).sub(offset.div(scale));

if (options.animate === false) {
return this.setView(latlng, zoom, bearing, this.getPitch());
}
to = tr.project(center).sub(offset.div(scale));

var startWorldSize = tr.worldSize,
rho = options.curve,
Expand Down
6 changes: 5 additions & 1 deletion js/ui/hash.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,11 @@ Hash.prototype = {
_onHashChange: function() {
var loc = location.hash.replace('#', '').split('/');
if (loc.length >= 3) {
this._map.setView([+loc[1], +loc[2]], +loc[0], +(loc[3] || 0), this._map.getPitch());
this._map.jumpTo({
center: [+loc[1], +loc[2]],
zoom: +loc[0],
bearing: +(loc[3] || 0)
});
return true;
}
return false;
Expand Down
68 changes: 43 additions & 25 deletions js/ui/map.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ var Map = module.exports = function(options) {
this._hash = options.hash && (new Hash()).addTo(this);
// don't set position from options if set through hash
if (!this._hash || !this._hash._onHashChange()) {
this.setView(options.center, options.zoom, options.bearing, options.pitch);
this.jumpTo(options);
}

this.sources = {};
Expand Down Expand Up @@ -117,28 +117,49 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
},

/**
* Sets a map position
* @typedef {Object} ViewOptions
* @property {Array} [center] Latitude and longitude (passed as `[lat, lng]`)
* @property {number} [zoom] Map zoom level
* @property {number} [bearing] Map rotation bearing in degrees counter-clockwise from north
* @property {number} [pitch] The angle at which the camera is looking at the ground
*/

/**
* Change any combination of center, zoom, bearing, and pitch, without
* a transition. The map will retain the current values for any options
* not included in `options`.
*
* @param {Array} center Latitude and longitude (passed as `[lat, lng]`)
* @param {number} zoom Map zoom level
* @param {number} bearing Map rotation bearing in degrees counter-clockwise from north
* @param {number} pitch The angle at which the camera is looking at the ground
* @param {ViewOptions} options map view options
* @fires movestart
* @fires moveend
* @returns {Map} `this`
*/
setView: function(center, zoom, bearing, pitch) {
jumpTo: function(options) {
this.stop();

var tr = this.transform,
zoomChanged = tr.zoom !== +zoom,
bearingChanged = tr.bearing !== +bearing,
pitchChanged = tr.pitch !== +pitch;
zoomChanged = false,
bearingChanged = false,
pitchChanged = false;

tr.center = LatLng.convert(center);
tr.zoom = +zoom;
tr.bearing = +bearing;
tr.pitch = +pitch;
if ('center' in options) {
tr.center = LatLng.convert(options.center);
}

if ('zoom' in options && tr.zoom !== +options.zoom) {
zoomChanged = true;
tr.zoom = +options.zoom;
}

if ('bearing' in options && tr.bearing !== +options.bearing) {
bearingChanged = true;
tr.bearing = +options.bearing;
}

if ('pitch' in options && tr.pitch !== +options.pitch) {
pitchChanged = true;
tr.pitch = +options.pitch;
}

return this
.fire('movestart')
Expand All @@ -147,8 +168,7 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
},

/**
* Sets a map location. This is like setView (and calls setView internally)
* but keeps the values for zoom, bearing, and pitch all the same.
* Sets a map location. Equivalent to `jumpTo({center: center})`.
*
* @param {Array} center Latitude and longitude (passed as `[lat, lng]`)
* @fires movestart
Expand All @@ -158,12 +178,11 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
* map.setCenter([-74, 38]);
*/
setCenter: function(center) {
this.setView(center, this.getZoom(), this.getBearing(), this.getPitch());
this.jumpTo({center: center});
},

/**
* Sets a map zoom. This is like setView (and calls setView internally)
* but keeps the values for center, bearing, and pitch all the same.
* Sets a map zoom. Equivalent to `jumpTo({zoom: zoom})`.
*
* @param {number} zoom Map zoom level
* @fires movestart
Expand All @@ -174,12 +193,11 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
* map.setZoom(5);
*/
setZoom: function(zoom) {
this.setView(this.getCenter(), zoom, this.getBearing(), this.getPitch());
this.jumpTo({zoom: zoom});
},

/**
* Sets a map rotation. This is like setView (and calls setView internally)
* but keeps the values for center, zoom, and pitch all the same.
* Sets a map rotation. Equivalent to `jumpTo({bearing: bearing})`.
*
* @param {number} bearing Map rotation bearing in degrees counter-clockwise from north
* @fires movestart
Expand All @@ -190,19 +208,19 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
* map.setBearing(90);
*/
setBearing: function(bearing) {
this.setView(this.getCenter(), this.getZoom(), bearing, this.getPitch());
this.jumpTo({bearing: bearing});
},

/**
* Sets a map angle
* Sets a map angle. Equivalent to `jumpTo({pitch: pitch})`.
*
* @param {number} pitch The angle at which the camera is looking at the ground
* @fires movestart
* @fires moveend
* @returns {Map} `this`
*/
setPitch: function(pitch) {
this.setView(this.getCenter(), this.getZoom(), this.getBearing(), pitch);
this.jumpTo({pitch: pitch});
},

/**
Expand Down
Loading

0 comments on commit 575515a

Please sign in to comment.