v1.0.0 API proposals

This page lists proposed changes to Modest Maps JS v0.x.x that would be require a major API increment. We should coordinate these changes if possible to make sure it's easy to keep up with the latest versions.

setSize

Should be cleaned up to always take a com.modestmaps.Point (or x/y Object and the callback should always pass a MM.Point https://github.com/stamen/modestmaps-js/issues/54

before:

setSize(x, y);
setSize({x: 0, y: 0}); // or setSize(new com.modestmaps.Point(0, 0))

after:

setSize({x: 0, y: 0}); // or setSize(new com.modestmaps.Point(0, 0))

• adding and removing handlers could/should be easier
• adding and removing callbacks could/should be easier
• the callbacks for 'extentset', 'centered', 'panned' and 'zoomed' overlap in their definitions and usage and aren't consistently fired. It might be simplest to rely on a single 'changed' event that fires as soon as centerCoordinate is modified, and the 'drawn' event that fires whenever a frame completes. * provider.outerLimits has always been tricky for people to understand, as it affects tile URL generation and also enforceLimits in the Map. Setting provider limits to describe the tiles that exist on the server should be simple. Setting Map limits to describe the permitted centers and zoom levels should be separate and simple too.

Though it's not currently a published part of the API, it might be useful to review the current MM DOM structure (tile-loaded classes, layer divs, etc.) and version it along with the JS API. There are also several JS functions that are undocumented in the API and could/should be wrapped in a single object or hidden as privately as possible in our current JS architecture (getStats, enforceLimits, draw, getTileComplete, requestRedraw, getRedraw, createOrGetLayer, checkCache, getCenterDistanceCompare, etc.).