diff --git a/documentation/planet.html b/documentation/planet.html index 129aa8d..2be7023 100644 --- a/documentation/planet.html +++ b/documentation/planet.html @@ -152,6 +152,19 @@ planet.onInit(function(done) { planet.projection.rotate(rotation); });

+

planet.onStop( function(){} )

+

Registers a function to be called when the planet is stopped with the stop method. This can be used to clean up timers and remove references to internal planet properties and plugins, if necessary, so that it can be property garbage collected.

+
+
JavaScript
+ +
var interval = setInterval(function() {
+  addRandomPing(planet); // uses `planet.plugins.pings`
+}, 150);
+
+planet.onStop(function() {
+  clearInterval(interval);
+});
+

planet.withSavedContext( function(context){} )

Calls the function with the current canvas context as a parameter, wrapping the function call in context.save() and context.restore(). Use this function any time you're going to modify the context to ensure it gets put back to the way it was.

@@ -170,7 +183,7 @@ planet.onInit(function(done) {

Begins drawing the globe onto the given canvas. canvas should be a raw DOM element (e.g. as returned by document.getElementById). Specifically, if it is wrapped by D3 or jQuery, you need to unwrap it with something like wrappedCanvas[0].

Calling draw will perform the following operations:

    -
  1. Initialize each loaded plugin by calling the plugin function.
    2. +
  2. Initialize each loaded plugin by calling the plugin function (note: this only happens the first time you call draw).
  3. Set planet.canvas and planet.context to the canvas and the canvas' context, respectively.
  4. Run each registered onInit hook in the order it was registered (note that onInit calls made by plugins will not be made until step 1, after draw has been called).
  5. Start the animation loop, each tick clearing the canvas and calling any registered onDraw hooks in order.
    6. @@ -183,6 +196,15 @@ planet.onInit(function(done) { 
    var canvas = document.getElementById('myCanvas');
 planet.draw(canvas);
    +

+

planet.stop()

+

Stop drawing the planet to the canvas. This disables the internal draw loop. You can register functions to call when the planet is stopped using the onStop method; if you don't plan on reusing the planet, be sure to clean up timers and references to internal properties, if necessary, so that it can be garbage collected.

+

You can draw the planet to a new (or the same) canvas using the draw method as normal. All your plugins' onInit functions will fire, although the plugin function itself will not be called again.

+

Keep in mind that, since the internal draw loop is stopped, your plugins' onDraw functions are not being called. If you have timers or other mechanisms that continually push data into a data structure that an onDraw method cleans up, you should disable or pause it.

+
+
JavaScript
+ +
planet.stop();

diff --git a/download/index.html b/download/index.html index 32f90d5..21d75c7 100644 --- a/download/index.html +++ b/download/index.html @@ -56,40 +56,40 @@ -

Latest Stable Build: v1.0.3

-

Release notes +

Latest Stable Build: v1.1.0

+

Release notes | - GitHub tag

+ GitHub tag

Core library: [ - minified + minified | - unminified + unminified ]
Core library (no plugins): [ - minified + minified | - unminified + unminified ]
Earth TopoJSON data ("land" and "countries" objects): [ - download + download ]
Source code [ - .zip + .zip | - .tar.gz + .tar.gz ]
diff --git a/js/lib/planetaryjs.min.js b/js/lib/planetaryjs.min.js index 03cf248..8460849 100644 --- a/js/lib/planetaryjs.min.js +++ b/js/lib/planetaryjs.min.js @@ -1,2 +1,2 @@ -/*! Planetary.js 1.0.3 | (c) 2013 Brandon Tilley | Released under MIT License */ -!function(n,t){"function"==typeof define&&define.amd?define(["d3","topojson"],t):"object"==typeof exports?module.exports=t(require("d3"),require("topojson")):n.planetaryjs=t(n.d3,n.topojson,n)}(this,function(n,t,o){"use strict";var i=null;o&&(i=o.planetaryjs);var e=[],r=function(t,o,i){n.timer(function(){t.context.clearRect(0,0,o.width,o.height);for(var n=0;n=0;o--)t.unshift(e[o]);for(0===t.length&&(c.plugins.earth&&n.loadPlugin(c.plugins.earth()),c.plugins.pings&&n.loadPlugin(c.plugins.pings())),o=0;o=o.onInit.length?r(n,t,o):e(l)};e(l)}else r(n,t,o)},u=function(n,t,o,i){l(n,o),n.canvas=t,n.context=t.getContext("2d"),a(n,t,i)},c={plugins:{},noConflict:function(){return o.planetaryjs=i,c},loadPlugin:function(n){e.push(n)},planet:function(){var t=[],o={onInit:[],onDraw:[]},i={plugins:{},draw:function(n){u(i,n,t,o)},onInit:function(n){o.onInit.push(n)},onDraw:function(n){o.onDraw.push(n)},loadPlugin:function(n){t.push(n)},withSavedContext:function(n){if(!this.context)throw new Error("No canvas to fetch context for");this.context.save(),n(this.context),this.context.restore()}};return i.projection=n.geo.orthographic().clipAngle(90),i.path=n.geo.path().projection(i.projection),i}};return c.plugins.topojson=function(t){return function(o){o.plugins.topojson={},o.onInit(function(i){if(t.world)o.plugins.topojson.world=t.world,setTimeout(i,0);else{var e=t.file||"world-110m.json";n.json(e,function(n,t){if(n)throw new Error("Could not load JSON "+e);o.plugins.topojson.world=t,i()})}})}},c.plugins.oceans=function(n){return function(t){t.onDraw(function(){t.withSavedContext(function(o){o.beginPath(),t.path.context(o)({type:"Sphere"}),o.fillStyle=n.fill||"black",o.fill()})})}},c.plugins.land=function(n){return function(o){var i=null;o.onInit(function(){var n=o.plugins.topojson.world;i=t.feature(n,n.objects.land)}),o.onDraw(function(){o.withSavedContext(function(t){t.beginPath(),o.path.context(t)(i),n.fill!==!1&&(t.fillStyle=n.fill||"white",t.fill()),n.stroke&&(n.lineWidth&&(t.lineWidth=n.lineWidth),t.strokeStyle=n.stroke,t.stroke())})})}},c.plugins.borders=function(n){return function(o){var i=null,e={internal:function(n,t){return n.id!==t.id},external:function(n,t){return n.id===t.id},both:function(){return!0}};o.onInit(function(){var r=o.plugins.topojson.world,l=r.objects.countries,a=n.type||"internal";i=t.mesh(r,l,e[a])}),o.onDraw(function(){o.withSavedContext(function(t){t.beginPath(),o.path.context(t)(i),t.strokeStyle=n.stroke||"gray",n.lineWidth&&(t.lineWidth=n.lineWidth),t.stroke()})})}},c.plugins.earth=function(n){n=n||{};var t=n.topojson||{},o=n.oceans||{},i=n.land||{},e=n.borders||{};return function(n){c.plugins.topojson(t)(n),c.plugins.oceans(o)(n),c.plugins.land(i)(n),c.plugins.borders(e)(n)}},c.plugins.pings=function(t){var o=[];t=t||{};var i=function(n,i,e){e=e||{},e.color=e.color||t.color||"white",e.angle=e.angle||t.angle||5,e.ttl=e.ttl||t.ttl||2e3;var r={time:new Date,options:e};t.latitudeFirst?(r.lat=n,r.lng=i):(r.lng=n,r.lat=i),o.push(r)},e=function(n,t,i){for(var e=[],l=0;l90&&(e[1]=90),e[1]<-90&&(e[1]=-90),e[0]>=180&&(e[0]-=360),t.projection.rotate(e),l.call(t)});n.select(t.canvas).call(o)})}},c}); \ No newline at end of file +/*! Planetary.js 1.1.0 | (c) 2013 Brandon Tilley | Released under MIT License */ +!function(n,t){"function"==typeof define&&define.amd?define(["d3","topojson"],t):"object"==typeof exports?module.exports=t(require("d3"),require("topojson")):n.planetaryjs=t(n.d3,n.topojson,n)}(this,function(n,t,o){"use strict";var i=null;o&&(i=o.planetaryjs);var e=[],r=function(t,o,i){n.timer(function(){if(t.stopped)return!0;t.context.clearRect(0,0,o.width,o.height);for(var n=0;n=0;o--)t.unshift(e[o]);for(0===t.length&&(c.plugins.earth&&n.loadPlugin(c.plugins.earth()),c.plugins.pings&&n.loadPlugin(c.plugins.pings())),o=0;o=o.onInit.length?r(n,t,o):e(l)};e(l)}else r(n,t,o)},u=function(n,t,o,i){n.canvas=t,n.context=t.getContext("2d"),n.stopped!==!0&&l(n,o),n.stopped=!1,a(n,t,i)},c={plugins:{},noConflict:function(){return o.planetaryjs=i,c},loadPlugin:function(n){e.push(n)},planet:function(){var t=[],o={onInit:[],onDraw:[],onStop:[]},i={plugins:{},draw:function(n){u(i,n,t,o)},onInit:function(n){o.onInit.push(n)},onDraw:function(n){o.onDraw.push(n)},onStop:function(n){o.onStop.push(n)},loadPlugin:function(n){t.push(n)},stop:function(){i.stopped=!0;for(var n=0;n90&&(e[1]=90),e[1]<-90&&(e[1]=-90),e[0]>=180&&(e[0]-=360),t.projection.rotate(e),l.call(t)});n.select(t.canvas).call(o)})}},c}); \ No newline at end of file