Class Index | File Index

Classes


Class pv.Behavior.point


Extends pv.Behavior.
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.

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).

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 Infinity.

By default, the standard Cartesian distance is computed. However, with some visualizations it is desirable to consider only a single dimension, such as the x-dimension for an independent variable. In this case, the collapse parameter can be set to collapse the y dimension:

    .event("mousemove", pv.Behavior.point(Infinity).collapse("y"))

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.

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 events property to "all" such that the panel receives events despite its transparent fill.

Note: this behavior does not currently wedge marks.
Defined in: Point.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Returns a new point behavior to be registered on mousemove events.
Method Summary
Method Attributes Method Name and Description
 
Sets or gets the collapse parameter.
Class Detail
pv.Behavior.point(r)
Returns a new point behavior to be registered on mousemove events.
Parameters:
{number} r Optional
the fuzzy radius threshold in pixels
See:
"The Bubble Cursor: Enhancing Target Acquisition by Dynamic Resizing of the Cursor's Activation Area" by T. Grossman & R. Balakrishnan, CHI 2005.
Method Detail
{pv.Behavior.point} collapse(x)
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 x-dimension for an independent variable. In this case, the collapse parameter can be set to collapse the y dimension:
    .event("mousemove", pv.Behavior.point(Infinity).collapse("y"))
Parameters:
{string} x Optional
the new collapse parameter
Returns:
{pv.Behavior.point} this, or the current collapse parameter.

Documentation generated by JsDoc Toolkit 2.3.2 on Sun May 30 2010 18:10:23 GMT-0700 (PDT)