diff --git a/site/public/documentation/planet.md b/site/public/documentation/planet.md
index 0eec9c6..d856cbe 100644
--- a/site/public/documentation/planet.md
+++ b/site/public/documentation/planet.md
@@ -94,6 +94,24 @@ planet.onDraw(function() {
```
+**`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
+
+```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.
@@ -119,7 +137,7 @@ Begins drawing the globe onto the given canvas. `canvas` should be a raw DOM ele
Calling `draw` will perform the following operations:
-1. Initialize each loaded plugin by calling the plugin function.
+1. Initialize each loaded plugin by calling the plugin function (note: this only happens the first time you call `draw`).
2. Set `planet.canvas` and `planet.context` to the canvas and the canvas' context, respectively.
3. 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).
4. Start the animation loop, each tick clearing the canvas and calling any registered `onDraw` hooks in order.
@@ -138,3 +156,19 @@ 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
+
+```javascript
+planet.stop();
+```
+
diff --git a/src/body.js b/src/body.js
index bafd8c1..3a13902 100644
--- a/src/body.js
+++ b/src/body.js
@@ -4,6 +4,10 @@
var doDrawLoop = function(planet, canvas, hooks) {
d3.timer(function() {
+ if (planet.stopped) {
+ return true;
+ }
+
planet.context.clearRect(0, 0, canvas.width, canvas.height);
for (var i = 0; i < hooks.onDraw.length; i++) {
hooks.onDraw[i]();
@@ -59,11 +63,14 @@
};
var startDraw = function(planet, canvas, localPlugins, hooks) {
- initPlugins(planet, localPlugins);
-
planet.canvas = canvas;
planet.context = canvas.getContext('2d');
+ if (planet.stopped !== true) {
+ initPlugins(planet, localPlugins);
+ }
+
+ planet.stopped = false;
runOnInitHooks(planet, canvas, hooks);
};
@@ -83,7 +90,8 @@
var localPlugins = [];
var hooks = {
onInit: [],
- onDraw: []
+ onDraw: [],
+ onStop: []
};
var planet = {
@@ -101,10 +109,21 @@
hooks.onDraw.push(fn);
},
+ onStop: function(fn) {
+ hooks.onStop.push(fn);
+ },
+
loadPlugin: function(plugin) {
localPlugins.push(plugin);
},
+ stop: function() {
+ planet.stopped = true;
+ for (var i = 0; i < hooks.onStop.length; i++) {
+ hooks.onStop[i](planet);
+ }
+ },
+
withSavedContext: function(fn) {
if (!this.context) {
throw new Error("No canvas to fetch context for");