Class pv.Mark

Represents a data-driven graphical mark. The Mark class is the base class for all graphical marks in Protovis; it does not provide any specific rendering functionality, but together with Panel establishes the core framework.

Concrete mark types include familiar visual elements such as bars, lines and labels. Although a bar mark may be used to construct a bar chart, marks know nothing about charts; it is only through their specification and composition that charts are produced. These building blocks permit many combinatorial possibilities.

Marks are associated with data: a mark is generated once per associated datum, mapping the datum to visual properties such as position and color. Thus, a single mark specification represents a set of visual elements that share the same data and visual encoding. The type of mark defines the names of properties and their meaning. A property may be static, ignoring the associated datum and returning a constant; or, it may be dynamic, derived from the associated datum or index. Such dynamic encodings can be specified succinctly using anonymous functions. Special properties called event handlers can be registered to add interactivity.

Protovis uses inheritance to simplify the specification of related marks: a new mark can be derived from an existing mark, inheriting its properties. The new mark can then override properties to specify new behavior, potentially in terms of the old behavior. In this way, the old mark serves as the prototype for the new mark. Most mark types share the same basic properties for consistency and to facilitate inheritance.

The prioritization of redundant properties is as follows:

If the width property is not specified (i.e., null), its value is the width of the parent panel, minus this mark's left and right margins; the left and right margins are zero if not specified.
Otherwise, if the right margin is not specified, its value is the width of the parent panel, minus this mark's width and left margin; the left margin is zero if not specified.
Otherwise, if the left property is not specified, its value is the width of the parent panel, minus this mark's width and the right margin.

This prioritization is then duplicated for the height, bottom and top properties, respectively.

While most properties are variable, some mark types, such as lines and areas, generate a single visual element rather than a distinct visual element per datum. With these marks, some properties may be fixed. Fixed properties can vary per mark, but not per datum! These properties are evaluated solely for the first (0-index) datum, and typically are specified as a constant. However, it is valid to use a function if the property varies between panels or is dynamically generated.

See also the Protovis guide.
Defined in: Mark.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	pv.Mark() Constructs a new mark with default properties.

Field Summary
Field Attributes	Field Name and Description
	bottom The bottom margin; the distance, in pixels, between the bottom edge of the enclosing panel and the bottom edge of this mark.
	childIndex The child index.
	cursor The cursor property; corresponds to the CSS cursor property.
	data The data property; an array of objects.
	defaults Default properties for all mark types.
	events The events property; corresponds to the SVG pointer-events property, specifying how the mark should participate in mouse events.
	index The mark index.
	left The left margin; the distance, in pixels, between the left edge of the enclosing panel and the left edge of this mark.
	parent The enclosing parent panel.
	proto The mark prototype, possibly undefined, from which to inherit property functions.
	reverse The reverse property; a boolean determining whether marks are ordered from front-to-back or back-to-front.
	right The right margin; the distance, in pixels, between the right edge of the enclosing panel and the right edge of this mark.
	root The root parent panel.
	scale The current scale factor, based on any enclosing transforms.
	title The title property; corresponds to the HTML/SVG title property, allowing the general of simple plain text tooltips.
	top The top margin; the distance, in pixels, between the top edge of the enclosing panel and the top edge of this mark.
	type The mark type; a lower camelCase name.
	visible The visible property; a boolean determining whether or not the mark instance is visible.

Method Summary
Method Attributes	Method Name and Description
	add(type) Adds a new mark of the specified type to the enclosing parent panel, whilst simultaneously setting the prototype of the new mark to be this mark.
	anchor(name) Returns an anchor with the specified name.
	anchorTarget() Returns the anchor target of this mark, if it is derived from an anchor; otherwise returns null.
	def(name, v) Defines a custom property on this mark.
	event(type, handler) Registers an event handler for the specified event type with this mark.
	extend(proto) Sets the prototype of this mark to the specified mark.
	margin(n) Alias for setting the left, right, top and bottom properties simultaneously.
	mouse() Returns the current location of the mouse (cursor) relative to this mark's parent.
	render() Renders this mark, including recursively rendering all child marks if this is a panel.

Class Detail

pv.Mark()

Constructs a new mark with default properties. Marks, with the exception of the root panel, are not typically constructed directly; instead, they are added to a panel or an existing mark via pv.Mark#add.

Field Detail

{number} bottom

The bottom margin; the distance, in pixels, between the bottom edge of the enclosing panel and the bottom edge of this mark. Note that in some cases this property may be redundant with the top property, or with the conjunction of top and height.

{number} childIndex

The child index. -1 if the enclosing parent panel is null; otherwise, the zero-based index of this mark into the parent panel's children array.

{string} cursor

The cursor property; corresponds to the CSS cursor property. This is typically used in conjunction with event handlers to indicate interactivity.

See:: CSS2 cursor

{array} data

The data property; an array of objects. The size of the array determines the number of marks that will be instantiated; each element in the array will be passed to property functions to compute the property values. Typically, the data property is specified as a constant array, such as

m.data([1, 2, 3, 4, 5]);

However, it is perfectly acceptable to define the data property as a function. This function might compute the data dynamically, allowing different data to be used per enclosing panel. For instance, in the stacked area graph example (see #scene), the data function on the area mark dereferences each series.

{pv.Mark} defaults

Default properties for all mark types. By default, the data array is the parent data as a single-element array; if the data property is not specified, this causes each mark to be instantiated as a singleton with the parents datum. The visible property is true by default, and the reverse property is false.

{string} events

The events property; corresponds to the SVG pointer-events property, specifying how the mark should participate in mouse events. The default value is "painted". Supported values are:

"painted": The given mark may receive events when the mouse is over a "painted" area. The painted areas are the interior (i.e., fill) of the mark if a 'fillStyle' is specified, and the perimeter (i.e., stroke) of the mark if a 'strokeStyle' is specified.

"all": The given mark may receive events when the mouse is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the mark, regardless of the specified fillStyle and strokeStyle.

"none": The given mark may not receive events.

{number} index

The mark index. The value of this field depends on which instance (i.e., which element of the data array) is currently being evaluated. During the build phase, the index is incremented over each datum; when handling events, the index is set to the instance that triggered the event.

{number} left

The left margin; the distance, in pixels, between the left edge of the enclosing panel and the left edge of this mark. Note that in some cases this property may be redundant with the right property, or with the conjunction of right and width.

{pv.Panel} parent

The enclosing parent panel. The parent panel is generally undefined only for the root panel; however, it is possible to create "offscreen" marks that are used only for inheritance purposes.

{pv.Mark} proto

The mark prototype, possibly undefined, from which to inherit property functions. The mark prototype is not necessarily of the same type as this mark. Any properties defined on this mark will override properties inherited either from the prototype or from the type-specific defaults.

{boolean} reverse

The reverse property; a boolean determining whether marks are ordered from front-to-back or back-to-front. SVG does not support explicit z-ordering; shapes are rendered in the order they appear. Thus, by default, marks are rendered in data order. Setting the reverse property to false reverses the order in which they are rendered; however, the properties are still evaluated (i.e., built) in forward order.

{number} right

The right margin; the distance, in pixels, between the right edge of the enclosing panel and the right edge of this mark. Note that in some cases this property may be redundant with the left property, or with the conjunction of left and width.

{pv.Panel} root

The root parent panel. This may be undefined for "offscreen" marks that are created for inheritance purposes only.

{number} scale

The current scale factor, based on any enclosing transforms. The current scale can be used to create scale-independent graphics. For example, to define a dot that has a radius of 10 irrespective of any zooming, say:

dot.radius(function() 10 / this.scale)

Note that the stroke width and font size are defined irrespective of scale (i.e., in screen space) already. Also note that when a transform is applied to a panel, the scale affects only the child marks, not the panel itself.

See:: pv.Panel#transform

{string} title

The title property; corresponds to the HTML/SVG title property, allowing the general of simple plain text tooltips.

{number} top

The top margin; the distance, in pixels, between the top edge of the enclosing panel and the top edge of this mark. Note that in some cases this property may be redundant with the bottom property, or with the conjunction of bottom and height.

{string} type

The mark type; a lower camelCase name. The type name controls rendering behavior, and unless the rendering engine is extended, must be one of the built-in concrete mark types: area, bar, dot, image, label, line, panel, rule, or wedge.

{boolean} visible

The visible property; a boolean determining whether or not the mark instance is visible. If a mark instance is not visible, its other properties will not be evaluated. Similarly, for panels no child marks will be rendered.

Method Detail

{pv.Mark} add(type)

Adds a new mark of the specified type to the enclosing parent panel, whilst simultaneously setting the prototype of the new mark to be this mark.

Parameters:
{function} type: the type of mark to add; a constructor, such as pv.Bar.

Returns:: {pv.Mark} the new mark.

See:: #extend

{pv.Anchor} anchor(name)

Returns an anchor with the specified name. All marks support the five standard anchor names:

top
left
center
bottom
right

In addition to positioning properties (left, right, top bottom), the anchors support text rendering properties (text-align, text-baseline). Text is rendered to appear inside the mark by default.

To facilitate stacking, anchors are defined in terms of their opposite edge. For example, the top anchor defines the bottom property, such that the mark extends upwards; the bottom anchor instead defines the top property, such that the mark extends downwards. See also pv.Layout.Stack.

While anchor names are typically constants, the anchor name is a true property, which means you can specify a function to compute the anchor name dynamically. See the pv.Anchor#name property for details.

Parameters:
{string} name: the anchor name; either a string or a property function.

Returns:: {pv.Anchor} the new anchor.

{pv.Mark} anchorTarget()

Returns the anchor target of this mark, if it is derived from an anchor; otherwise returns null. For example, if a label is derived from a bar anchor,

bar.anchor("top").add(pv.Label);

then property functions on the label can refer to the bar via the anchorTarget method. This method is also useful for mark types defining properties on custom anchors.

Returns:: {pv.Mark} the anchor target of this mark; possibly null.

def(name, v)

Defines a custom property on this mark. Custom properties are currently fixed, in that they are initialized once per mark set (i.e., per parent panel instance). Custom properties can be used to store local state for the mark, such as data needed by other properties (e.g., a custom scale) or interaction state.

WARNING We plan on changing this feature in a future release to define standard properties, as opposed to fixed properties that behave idiosyncratically within event handlers. Furthermore, we recommend storing state in an external data structure, rather than tying it to the visualization specification as with defs.

Parameters:
{string} name: the name of the local variable.
{function} v Optional: an optional initializer; may be a constant or a function.

{pv.Mark} event(type, handler)

Registers an event handler for the specified event type with this mark. When an event of the specified type is triggered, the specified handler will be invoked. The handler is invoked in a similar method to property functions: the context is this mark instance, and the arguments are the full data stack. Event handlers can use property methods to manipulate the display properties of the mark:

m.event("click", function() this.fillStyle("red"));

Alternatively, the external data can be manipulated and the visualization redrawn:

m.event("click", function(d) {
    data = all.filter(function(k) k.name == d);
    vis.render();
  });

The return value of the event handler determines which mark gets re-rendered. Use defs (#def) to set temporary state from event handlers.

The complete set of event types is defined by SVG; see the reference below. The set of supported event types is:

click
mousedown
mouseup
mouseover
mousemove
mouseout

Since Protovis does not specify any concept of focus, it does not support key events; these should be handled outside the visualization using standard JavaScript. In the future, support for interaction may be extended to support additional event types, particularly those most relevant to interactive visualization, such as selection.

TODO In the current implementation, event handlers are not inherited from prototype marks. They must be defined explicitly on each interactive mark. In addition, only one event handler for a given event type can be defined; when specifying multiple event handlers for the same type, only the last one will be used.

Parameters:
{string} type: the event type.
{function} handler: the event handler.

Returns:: {pv.Mark} this.

See:: SVG events

{pv.Mark} extend(proto)

Sets the prototype of this mark to the specified mark. Any properties not defined on this mark may be inherited from the specified prototype mark, or its prototype, and so on. The prototype mark need not be the same type of mark as this mark. (Note that for inheritance to be useful, properties with the same name on different mark types should have equivalent meaning.)

Parameters:
{pv.Mark} proto: the new prototype.

Returns:: {pv.Mark} this mark.

See:: #add

{pv.Mark} margin(n)

Alias for setting the left, right, top and bottom properties simultaneously.

Parameters:
n

Returns:: {pv.Mark} this.

See:: #left; #right; #top; #bottom

{pv.Vector} mouse()

Returns the current location of the mouse (cursor) relative to this mark's parent. The x coordinate corresponds to the left margin, while the y coordinate corresponds to the top margin.

Returns:: {pv.Vector} the mouse location.

render()

Renders this mark, including recursively rendering all child marks if this is a panel. This method finds all instances of this mark and renders them. This method descends recursively to the level of the mark to be rendered, finding all visible instances of the mark. After the marks are rendered, the scene and index attributes are removed from the mark to restore them to a clean state.

If an enclosing panel has an index property set (as is the case inside in an event handler), then only instances of this mark inside the given instance of the panel will be rendered; otherwise, all visible instances of the mark will be rendered.

Classes

Class pv.Mark