rubyvis 0.1.0 → 0.1.1

data/vendor/src/behavior/Point.js

@@ -0,0 +1,157 @@
+/**
+ * Returns a new point behavior to be registered on mousemove events.
+ *
+ * @class Implements interactive fuzzy pointing, identifying marks that are in
+ * close proximity to the mouse cursor. This behavior is an alternative to the
+ * native mouseover and mouseout events, improving usability. Rather than
+ * requiring the user to mouseover a mark exactly, the mouse simply needs to
+ * move near the given mark and a "point" event is triggered. In addition, if
+ * multiple marks overlap, the point behavior can be used to identify the mark
+ * instance closest to the cursor, as opposed to the one that is rendered on
+ * top.
+ *
+ * <p>The point behavior can also identify the closest mark instance for marks
+ * that produce a continuous graphic primitive. The point behavior can thus be
+ * used to provide details-on-demand for both discrete marks (such as dots and
+ * bars), as well as continuous marks (such as lines and areas).
+ *
+ * <p>This behavior is implemented by finding the closest mark instance to the
+ * mouse cursor on every mousemove event. If this closest mark is within the
+ * given radius threshold, which defaults to 30 pixels, a "point" psuedo-event
+ * is dispatched to the given mark instance. If any mark were previously
+ * pointed, it would receive a corresponding "unpoint" event. These two
+ * psuedo-event types correspond to the native "mouseover" and "mouseout"
+ * events, respectively. To increase the radius at which the point behavior can
+ * be applied, specify an appropriate threshold to the constructor, up to
+ * <tt>Infinity</tt>.
+ *
+ * <p>By default, the standard Cartesian distance is computed. However, with
+ * some visualizations it is desirable to consider only a single dimension, such
+ * as the <i>x</i>-dimension for an independent variable. In this case, the
+ * collapse parameter can be set to collapse the <i>y</i> dimension:
+ *
+ * <pre>    .event("mousemove", pv.Behavior.point(Infinity).collapse("y"))</pre>
+ *
+ * <p>This behavior only listens to mousemove events on the assigned panel,
+ * which is typically the root panel. The behavior will search recursively for
+ * descendant marks to point. If the mouse leaves the assigned panel, the
+ * behavior no longer receives mousemove events; an unpoint psuedo-event is
+ * automatically dispatched to unpoint any pointed mark. Marks may be re-pointed
+ * when the mouse reenters the panel.
+ *
+ * <p>Panels have transparent fill styles by default; this means that panels may
+ * not receive the initial mousemove event to start pointing. To fix this
+ * problem, either given the panel a visible fill style (such as "white"), or
+ * set the <tt>events</tt> property to "all" such that the panel receives events
+ * despite its transparent fill.
+ *
+ * <p>Note: this behavior does not currently wedge marks.
+ *
+ * @extends pv.Behavior
+ *
+ * @param {number} [r] the fuzzy radius threshold in pixels
+ * @see <a href="http://www.tovigrossman.com/papers/chi2005bubblecursor.pdf"
+ * >"The Bubble Cursor: Enhancing Target Acquisition by Dynamic Resizing of the
+ * Cursor's Activation Area"</a> by T. Grossman &amp; R. Balakrishnan, CHI 2005.
+ */
+pv.Behavior.point = function(r) {
+  var unpoint, // the current pointer target
+      collapse = null, // dimensions to collapse
+      kx = 1, // x-dimension cost scale
+      ky = 1, // y-dimension cost scale
+      r2 = arguments.length ? r * r : 900; // fuzzy radius
+
+  /** @private Search for the mark closest to the mouse. */
+  function search(scene, index) {
+    var s = scene[index],
+        point = {cost: Infinity};
+    for (var i = 0, n = s.visible && s.children.length; i < n; i++) {
+      var child = s.children[i], mark = child.mark, p;
+      if (mark.type == "panel") {
+        mark.scene = child;
+        for (var j = 0, m = child.length; j < m; j++) {
+          mark.index = j;
+          p = search(child, j);
+          if (p.cost < point.cost) point = p;
+        }
+        delete mark.scene;
+        delete mark.index;
+      } else if (mark.$handlers.point) {
+        var v = mark.mouse();
+        for (var j = 0, m = child.length; j < m; j++) {
+          var c = child[j],
+              dx = v.x - c.left - (c.width || 0) / 2,
+              dy = v.y - c.top - (c.height || 0) / 2,
+              dd = kx * dx * dx + ky * dy * dy;
+          if (dd < point.cost) {
+            point.distance = dx * dx + dy * dy;
+            point.cost = dd;
+            point.scene = child;
+            point.index = j;
+          }
+        }
+      }
+    }
+    return point;
+  }
+
+  /** @private */
+  function mousemove() {
+    /* If the closest mark is far away, clear the current target. */
+    var point = search(this.scene, this.index);
+    if ((point.cost == Infinity) || (point.distance > r2)) point = null;
+
+    /* Unpoint the old target, if it's not the new target. */
+    if (unpoint) {
+      if (point
+          && (unpoint.scene == point.scene)
+          && (unpoint.index == point.index)) return;
+      pv.Mark.dispatch("unpoint", unpoint.scene, unpoint.index);
+    }
+
+    /* Point the new target, if there is one. */
+    if (unpoint = point) {
+      pv.Mark.dispatch("point", point.scene, point.index);
+
+      /* Unpoint when the mouse leaves the root panel. */
+      pv.listen(this.root.canvas(), "mouseout", mouseout);
+    }
+  }
+
+  /** @private */
+  function mouseout(e) {
+    if (unpoint && !pv.ancestor(this, e.relatedTarget)) {
+      pv.Mark.dispatch("unpoint", unpoint.scene, unpoint.index);
+      unpoint = null;
+    }
+  }
+
+  /**
+   * Sets or gets the collapse parameter. By default, the standard Cartesian
+   * distance is computed. However, with some visualizations it is desirable to
+   * consider only a single dimension, such as the <i>x</i>-dimension for an
+   * independent variable. In this case, the collapse parameter can be set to
+   * collapse the <i>y</i> dimension:
+   *
+   * <pre>    .event("mousemove", pv.Behavior.point(Infinity).collapse("y"))</pre>
+   *
+   * @function
+   * @returns {pv.Behavior.point} this, or the current collapse parameter.
+   * @name pv.Behavior.point.prototype.collapse
+   * @param {string} [x] the new collapse parameter
+   */
+  mousemove.collapse = function(x) {
+    if (arguments.length) {
+      collapse = String(x);
+      switch (collapse) {
+        case "y": kx = 1; ky = 0; break;
+        case "x": kx = 0; ky = 1; break;
+        default: kx = 1; ky = 1; break;
+      }
+      return mousemove;
+    }
+    return collapse;
+  };
+
+  return mousemove;
+};

data/vendor/src/behavior/Resize.js

@@ -0,0 +1,104 @@
+/**
+ * Returns a new resize behavior to be registered on mousedown events.
+ *
+ * @class Implements interactive resizing of a selection starting with mousedown
+ * events. Register this behavior on selection handles that should be resizeable
+ * by the user, such for brushing and linking. This behavior can be used in
+ * tandom with {@link pv.Behavior.select} and {@link pv.Behavior.drag} to allow
+ * the selected region to be selected and dragged interactively.
+ *
+ * <p>After the initial mousedown event is triggered, this behavior listens for
+ * mousemove and mouseup events on the window. This allows resizing to continue
+ * even if the mouse temporarily leaves the assigned panel, or even the root
+ * panel.
+ *
+ * <p>This behavior requires that the data associated with the mark being
+ * resized have <tt>x</tt>, <tt>y</tt>, <tt>dx</tt> and <tt>dy</tt> attributes
+ * that correspond to the mark's location and dimensions in pixels. The mark's
+ * positional properties are not set directly by this behavior; instead, the
+ * positional properties should be defined as:
+ *
+ * <pre>    .left(function(d) d.x)
+ *     .top(function(d) d.y)
+ *     .width(function(d) d.dx)
+ *     .height(function(d) d.dy)</pre>
+ *
+ * Thus, the behavior does not resize the mark directly, but instead updates the
+ * size by updating the assigned panel's underlying data. Note that if the
+ * positional properties are defined with bottom and right (rather than top and
+ * left), the resize behavior will be inverted, which will confuse users!
+ *
+ * <p>The resize behavior is bounded by the assigned mark's enclosing panel; the
+ * positional attributes are clamped such that the selection does not extend
+ * outside the panel's bounds.
+ *
+ * <p>The mark being resized is automatically re-rendered for each mouse event
+ * as part of the resize operation. This behavior may be enhanced in the future
+ * to allow more flexible configuration. In some cases, such as with parallel
+ * coordinates, resizing the selection may cause related marks to change, in
+ * which case additional marks may also need to be rendered. This can be
+ * accomplished by listening for the select psuedo-events:<ul>
+ *
+ * <li>resizestart (on mousedown)
+ * <li>resize (on mousemove)
+ * <li>resizeend (on mouseup)
+ *
+ * </ul>For example, to render the parent panel while resizing, thus
+ * re-rendering all sibling marks:
+ *
+ * <pre>    .event("mousedown", pv.Behavior.resize("left"))
+ *     .event("resize", function() this.parent)</pre>
+ *
+ * This behavior may be enhanced in the future to allow more flexible
+ * configuration of the selection behavior.
+ *
+ * @extends pv.Behavior
+ * @see pv.Behavior.select
+ * @see pv.Behavior.drag
+ */
+pv.Behavior.resize = function(side) {
+  var scene, // scene context
+      index, // scene context
+      r, // region being selected
+      m1; // initial mouse position
+
+  /** @private */
+  function mousedown(d) {
+    index = this.index;
+    scene = this.scene;
+    m1 = this.mouse();
+    r = d;
+    switch (side) {
+      case "left": m1.x = r.x + r.dx; break;
+      case "right": m1.x = r.x; break;
+      case "top": m1.y = r.y + r.dy; break;
+      case "bottom": m1.y = r.y; break;
+    }
+    pv.Mark.dispatch("resizestart", scene, index);
+  }
+
+  /** @private */
+  function mousemove() {
+    if (!scene) return;
+    scene.mark.context(scene, index, function() {
+        var m2 = this.mouse();
+        r.x = Math.max(0, Math.min(m1.x, m2.x));
+        r.y = Math.max(0, Math.min(m1.y, m2.y));
+        r.dx = Math.min(this.parent.width(), Math.max(m2.x, m1.x)) - r.x;
+        r.dy = Math.min(this.parent.height(), Math.max(m2.y, m1.y)) - r.y;
+        this.render();
+      });
+    pv.Mark.dispatch("resize", scene, index);
+  }
+
+  /** @private */
+  function mouseup() {
+    if (!scene) return;
+    pv.Mark.dispatch("resizeend", scene, index);
+    scene = null;
+  }
+
+  pv.listen(window, "mousemove", mousemove);
+  pv.listen(window, "mouseup", mouseup);
+  return mousedown;
+};

data/vendor/src/behavior/Select.js

@@ -0,0 +1,100 @@
+/**
+ * Returns a new select behavior to be registered on mousedown events.
+ *
+ * @class Implements interactive selecting starting with mousedown events.
+ * Register this behavior on panels that should be selectable by the user, such
+ * for brushing and linking. This behavior can be used in tandom with
+ * {@link pv.Behavior.drag} to allow the selected region to be dragged
+ * interactively.
+ *
+ * <p>After the initial mousedown event is triggered, this behavior listens for
+ * mousemove and mouseup events on the window. This allows selecting to continue
+ * even if the mouse temporarily leaves the assigned panel, or even the root
+ * panel.
+ *
+ * <p>This behavior requires that the data associated with the mark being
+ * dragged have <tt>x</tt>, <tt>y</tt>, <tt>dx</tt> and <tt>dy</tt> attributes
+ * that correspond to the mark's location and dimensions in pixels. The mark's
+ * positional properties are not set directly by this behavior; instead, the
+ * positional properties should be defined as:
+ *
+ * <pre>    .left(function(d) d.x)
+ *     .top(function(d) d.y)
+ *     .width(function(d) d.dx)
+ *     .height(function(d) d.dy)</pre>
+ *
+ * Thus, the behavior does not resize the mark directly, but instead updates the
+ * selection by updating the assigned panel's underlying data. Note that if the
+ * positional properties are defined with bottom and right (rather than top and
+ * left), the drag behavior will be inverted, which will confuse users!
+ *
+ * <p>The select behavior is bounded by the assigned panel; the positional
+ * attributes are clamped such that the selection does not extend outside the
+ * panel's bounds.
+ *
+ * <p>The panel being selected is automatically re-rendered for each mouse event
+ * as part of the drag operation. This behavior may be enhanced in the future to
+ * allow more flexible configuration of select behavior. In some cases, such as
+ * with parallel coordinates, making a selection may cause related marks to
+ * change, in which case additional marks may also need to be rendered. This can
+ * be accomplished by listening for the select psuedo-events:<ul>
+ *
+ * <li>selectstart (on mousedown)
+ * <li>select (on mousemove)
+ * <li>selectend (on mouseup)
+ *
+ * </ul>For example, to render the parent panel while selecting, thus
+ * re-rendering all sibling marks:
+ *
+ * <pre>    .event("mousedown", pv.Behavior.drag())
+ *     .event("select", function() this.parent)</pre>
+ *
+ * This behavior may be enhanced in the future to allow more flexible
+ * configuration of the selection behavior.
+ *
+ * @extends pv.Behavior
+ * @see pv.Behavior.drag
+ */
+pv.Behavior.select = function() {
+  var scene, // scene context
+      index, // scene context
+      r, // region being selected
+      m1; // initial mouse position
+
+  /** @private */
+  function mousedown(d) {
+    index = this.index;
+    scene = this.scene;
+    m1 = this.mouse();
+    r = d;
+    r.x = m1.x;
+    r.y = m1.y;
+    r.dx = r.dy = 0;
+    pv.Mark.dispatch("selectstart", scene, index);
+  }
+
+  /** @private */
+  function mousemove() {
+    if (!scene) return;
+    scene.mark.context(scene, index, function() {
+        var m2 = this.mouse();
+        r.x = Math.max(0, Math.min(m1.x, m2.x));
+        r.y = Math.max(0, Math.min(m1.y, m2.y));
+        r.dx = Math.min(this.width(), Math.max(m2.x, m1.x)) - r.x;
+        r.dy = Math.min(this.height(), Math.max(m2.y, m1.y)) - r.y;
+        this.render();
+      });
+    pv.Mark.dispatch("select", scene, index);
+  }
+
+  /** @private */
+  function mouseup() {
+    if (!scene) return;
+    pv.Mark.dispatch("selectend", scene, index);
+    scene = null;
+  }
+
+  pv.listen(window, "mousemove", mousemove);
+  pv.listen(window, "mouseup", mouseup);
+  return mousedown;
+};

data/vendor/src/behavior/Zoom.js

@@ -0,0 +1,85 @@
+/**
+ * Returns a new zoom behavior to be registered on mousewheel events.
+ *
+ * @class Implements interactive zooming using mousewheel events. Register this
+ * behavior on panels to allow zooming. This behavior can be used in tandem with
+ * {@link pv.Behavior.pan} to allow both panning and zooming:
+ *
+ * <pre>    .event("mousedown", pv.Behavior.pan())
+ *     .event("mousewheel", pv.Behavior.zoom())</pre>
+ *
+ * The zoom behavior currently supports only mousewheel events; support for
+ * keyboard shortcuts and gesture events to improve accessibility may be added
+ * in the future.
+ *
+ * <p>The implementation of this behavior relies on the panel's
+ * <tt>transform</tt> property, which specifies a matrix transformation that is
+ * applied to child marks. Note that the transform property only affects the
+ * panel's children, but not the panel itself; therefore the panel's fill and
+ * stroke will not change when the contents are zoomed. The built-in support for
+ * transforms only supports uniform scaling and translates, which is sufficient
+ * for panning and zooming.  Note that this is not a strict geometric
+ * transformation, as the <tt>lineWidth</tt> property is scale-aware: strokes
+ * are drawn at constant size independent of scale.
+ *
+ * <p>Panels have transparent fill styles by default; this means that panels may
+ * not receive mousewheel events to zoom. To fix this problem, either given the
+ * panel a visible fill style (such as "white"), or set the <tt>events</tt>
+ * property to "all" such that the panel receives events despite its transparent
+ * fill.
+ *
+ * <p>The zoom behavior has optional support for bounding. If enabled, the user
+ * will not be able to zoom out farther than the initial bounds. This feature is
+ * designed to work in conjunction with the pan behavior.
+ *
+ * @extends pv.Behavior
+ * @see pv.Panel#transform
+ * @see pv.Mark#scale
+ * @param {number} speed
+ */
+pv.Behavior.zoom = function(speed) {
+  var bound; // whether to bound to the panel
+
+  if (!arguments.length) speed = 1 / 48;
+
+  /** @private */
+  function mousewheel() {
+    var v = this.mouse(),
+        k = pv.event.wheel * speed,
+        m = this.transform().translate(v.x, v.y)
+            .scale((k < 0) ? (1e3 / (1e3 - k)) : ((1e3 + k) / 1e3))
+            .translate(-v.x, -v.y);
+    if (bound) {
+      m.k = Math.max(1, m.k);
+      m.x = Math.max((1 - m.k) * this.width(), Math.min(0, m.x));
+      m.y = Math.max((1 - m.k) * this.height(), Math.min(0, m.y));
+    }
+    this.transform(m).render();
+    pv.Mark.dispatch("zoom", this.scene, this.index);
+  }
+
+  /**
+   * Sets or gets the bound parameter. If bounding is enabled, the user will not
+   * be able to zoom out farther than the initial panel bounds. Bounding is not
+   * enabled by default. If this behavior is used in tandem with the pan
+   * behavior, both should use the same bound parameter.
+   *
+   * <p>Note: enabling bounding after zooming has already occurred will not
+   * immediately reset the transform. Bounding should be enabled before the zoom
+   * behavior is applied.
+   *
+   * @function
+   * @returns {pv.Behavior.zoom} this, or the current bound parameter.
+   * @name pv.Behavior.zoom.prototype.bound
+   * @param {boolean} [x] the new bound parameter.
+   */
+  mousewheel.bound = function(x) {
+    if (arguments.length) {
+      bound = Boolean(x);
+      return this;
+    }
+    return Boolean(bound);
+  };
+
+  return mousewheel;
+};