Class pvc.visual.Scene

Class Summary
Constructor Attributes	Constructor Name and Description
	Scene The `Scene` class represents a single point rendered by Protovis marks.

Field Summary
Field Attributes	Field Name and Description
Business Data
	atoms Gets the atoms map of the scene's first data set or first datum.
	datum Gets the first datum represented by the scene, when there is at least one, or `null`, otherwise.
	firstAtoms Gets the atoms map of the scene's first datum.
	group Gets the first data set represented by the scene, when there is at least one, or `null`, otherwise.
	groups Gets the array of data sets represented by the scene, when there is at least one, or `null`, otherwise.
DOM
	childNodes The array of child scenes.
	firstChild The first child scene.
	lastChild The last child scene.
	nextSibling The next sibling scene.
	parent The parent scene.
	previousSibling The previous sibling scene.
	root The root scene.
Interactivity - Active
	isActive Gets a value that indicates if the scene is in an active state.
Visual Data
	vars Gets the variables map of the scene.

Method Summary
Method Attributes	Method Name and Description
Business Data
	datums() Returns an enumerable of all of the represented pvc.data.Datum.
DOM
	childIndex() Gets the index of this scene in relation to its sibling scenes.
	children() An enumerable of the child scenes.
	isRoot() Gets a value that indicates if this scene is a root scene.
	leafs() An enumerable of the leaf scenes.
Interactivity
	anyInteraction() Gets a value that indicates if the scene is in an interactive state.
Interactivity - Active
	active() Gets the active scene of the scene tree to which this scene belongs.
	activeSeries() Gets the value of the `series` variable of the active scene, if any, of the scene tree to which this scene belongs.
	anyActive() Gets a value that indicates if the tree to which this scene belongs has an active scene.
	clearActive() Clears the active scene of this scene's tree, if any.
	isActiveSeries() Gets a value that indicates if this scene's `series` is active.
	setActive(active) Sets this scene as the active scene of its scene tree.
Interactivity - Selected
	anySelected() Gets a value that indicates if any datum is selected.
	isSelected() Gets a value that indicates if at least one of the datums represented by the scene is selected.
Visual Components
	chart() Gets the immediate chart instance.
	panel() Gets the immediate panel instance.
Visual Data
	getCategory() Gets the value of the `category` scene variable (defined in scenes of categorical and pie plots).
	getCategoryLabel() Gets the label of the `category` scene variable.
	getColor() Gets the value of the `color` scene variable (defined in scenes of plots).
	getColorLabel() Gets the label of the `color` scene variable.
	getSeries() Gets the value of the `series` scene variable (defined in scenes of cartesian plots).
	getSeriesLabel() Gets the label of the `series` scene variable.
	getSize() Gets the value of the `size` scene variable (defined in scenes of the heat-grid and the scatter/metric-point plots).
	getSizeLabel() Gets the label of the `size` scene variable.
	getTick() Gets the value of the `tick` scene variable (defined in scenes of the cartesian axis).
	getTickLabel() Gets the label of the `tick` scene variable.
	getValue() Gets the value of the `value` scene variable (defined in scenes of categorical/numeric plots and the legend panel).
	getValueLabel() Gets the label of the `value` scene variable.
	getX() Gets the value of the `x` scene variable (defined in scenes of the scatter/metric-point plot).
	getXLabel() Gets the label of the `x` scene variable.
	getY() Gets the value of the `y` scene variable (defined in scenes of the scatter/metric-point plot).
	getYLabel() Gets the label of the `y` scene variable.

Class Detail

pvc.visual.Scene

The Scene class represents a single point rendered by Protovis marks.

However, a scene is not specific to a given mark, and may actually feed several of them (a pv.Dot, a pv.Line and an pv.Area).

Scenes provide a well defined interface to CCC extension point functions.

Scenes contain participating datums and vars.

Field Detail

{object} atoms

Gets the atoms map of the scene's first data set or first datum. The map's keys are dimension names and the values are the corresponding pvc.data.Atom.

When the scene represents data sets, gets the {pvc.data.Complex#atoms} map of #group. Otherwise, when the scene directly represents datums, gets the {pvc.data.Complex#atoms} map of #datum. Ultimately, gets an empty map.

Note that when the scene represents one or more data sets, its atoms map will generally not contain an pvc.data.Atom for each dimension, but instead will only contain an atom for each dimension in which all of the scene's datums have the same value (ensured due to a group by operation having been performed). Contrast this with #firstAtoms.

Use atoms when you need access to the business data that is common to all datums that are represented in a scene. You'll typically only use this for interfacing with external components. For internal use, it's usually best to use #vars, which expose "visual data".

Example pvc.options.charts.BasicChart#clickAction handler, accessing the value of the "productFamily" dimension:


function(scene) {
  window.alert("Clicked on: " + scene.atoms.productFamily.value);
}

See:: #datums; #vars; #firstAtoms

{pvc.data.Data} datum

Gets the first datum represented by the scene, when there is at least one, or null, otherwise.

A scene may visually represent a single datum, a series of datums, a single data set or a series of data sets. In any case, this property contains the first datum.

See:: #datums

{object} firstAtoms

Gets the atoms map of the scene's first datum. The map's keys are dimension names and the values are the corresponding pvc.data.Atom.

When the scene represents at least one datum, gets its pvc.data.Complex#atoms map. Ultimately, gets an empty map.

See:: #datums; #atoms

{pvc.data.Data} group

Gets the first data set represented by the scene, when there is at least one, or null, otherwise.

A scene may visually represent a single datum, a series of datums, a single data set or a series of data sets.

See:: #datums; #groups

{pvc.data.Data[]} groups

Gets the array of data sets represented by the scene, when there is at least one, or null, otherwise.

A scene may visually represent a single datum, a series of datums, a single data set or a series of data sets.

See:: #datums; #group

{!pvc.visual.Scene[]} childNodes

The array of child scenes.

This array is empty for leaf scenes. An easy way to check if child scenes exist is to query #firstChild.

See:: #children

{pvc.visual.Scene} firstChild

The first child scene.

This is is null for leaf scenes.

{pvc.visual.Scene} lastChild

The last child scene.

This is is null for leaf scenes.

{pvc.visual.Scene} nextSibling

The next sibling scene.

This is null for the last child scene.

{pvc.visual.Scene} parent

The parent scene.

This is null for root scenes.

{pvc.visual.Scene} previousSibling

The previous sibling scene.

This is null for the first child scene.

{!pvc.visual.Scene} root

The root scene.

See:: #isRoot

isActive

Gets a value that indicates if the scene is in an active state.

A scene becomes active while the user hovers-over any of the the visual elements that represent it.

{object} vars

Gets the variables map of the scene. The map's keys are variable names and the values are the corresponding Variable.

Each chart and plot visual role usually has a corresponding scene variable with its name. Just like with atoms, a scene variable contains the properties value and label.

Use it to obtain the value of a visual role, like, for example: scene.vars.series.value.

In the scene trees of some panels, such as the legend panel and the cartesian axes panels, scene variables are not named after the corresponding plot visual role. This is because they can show information which comes from more than one plot visual role.

In the discrete color legend panel, the main variable is named value.

In cartesian axes panels, the main variable is named tick.

In the following example, a mark's fillStyle extension point is calculated based on the value of the category variable:


function(scene) {

  switch(scene.vars.category.value) {
    case "cars":   return "red";
    case "plains": return "green";
    case "boats":  return "blue";
  }

  return "orange";
}

In the following example, the pvc.options.charts.BasicChart#clickAction handler is used to display to the user the category variable's label of the clicked-on scene:


function(scene) {
  window.alert("The category is: " + scene.vars.category.label);
}

See:: #atoms; #getColor; #getCategory; #getSeries; #getValue; #getTick; #getX; #getY; #getSize

Method Detail

{!def.Query} datums()

Returns an enumerable of all of the represented pvc.data.Datum.

When the scene represents no datums, an empty enumerable is returned.

Returns:: {!def.Query} An enumerable of pvc.data.Datum.

See:: #datum; #group; #groups

{number} childIndex()

Gets the index of this scene in relation to its sibling scenes.

This index is 0-based.

When the node is a root node, -1 is returned.

Returns:: {number} The child index.

{!def.Query} children()

An enumerable of the child scenes.

Returns:: {!def.Query} An enumerable of Scene.

See:: #childNodes; #leafs

{boolean} isRoot()

Gets a value that indicates if this scene is a root scene.

Returns:: {boolean} true if the scene is a root scene; false otherwise.

See:: #root

{!def.Query} leafs()

An enumerable of the leaf scenes.

Returns:: {!def.Query} An enumerable of Scene.

See:: #children

{boolean} anyInteraction()

Gets a value that indicates if the scene is in an interactive state.

A scene is in an interactive state if it is active, #isActive and/or if it represents at least one datum which is selected.

Returns:: {boolean} true if the scene is in an interactive state; false otherwise.

{pvc.visual.Scene} active()

Gets the active scene of the scene tree to which this scene belongs.

Returns:: {pvc.visual.Scene} The active scene, if any; null, otherwise.

{any} activeSeries()

Gets the value of the series variable of the active scene, if any, of the scene tree to which this scene belongs.

Returns:: {any} The active series value.

{boolean} anyActive()

Gets a value that indicates if the tree to which this scene belongs has an active scene.

A scene becomes active while the user hovers-over any of the the visual elements that represent it.

Returns:: {boolean} true if there is an active scene; false otherwise.

{boolean} clearActive()

Clears the active scene of this scene's tree, if any.

This scene may not be the active scene.

Returns:: {boolean} `true` if the scene tree's active scene changed, `false`, otherwise.

{boolean} isActiveSeries()

Gets a value that indicates if this scene's series is active.

A scene's series is said to be active if it has a series variable and it has the same value as that returned by #activeSeries.

Returns:: {boolean} true if this scene's series is active; false otherwise.

setActive(active)

Sets this scene as the active scene of its scene tree.

When a scene is activated, any previously active scene of the same scene tree is deactivated. To update the chart, you should also execute this.panel().renderInteractive().

Arguments:
{boolean} active Optional, Default: false: The new active state of the scene.

{boolean} anySelected()

Gets a value that indicates if any datum is selected. The selected datum does not need to be represented by a scene in this scene's tree.

Returns:: {boolean} true if there is any selected datum; false, otherwise.

See:: pvc.data.Datum#isSelected; #isSelected

{boolean} isSelected()

Gets a value that indicates if at least one of the datums represented by the scene is selected.

Returns:: {boolean} true if there is one selected datum; false otherwise.

See:: pvc.data.Datum#isSelected

{!pvc.BaseChart} chart()

Gets the immediate chart instance.

In multi-chart scenarios, this is the chart that is closest to where the scene belongs.

To be sure to get the root chart, get its pvc.BaseChart#root property.

Returns:: {!pvc.BaseChart} The chart instance.

See:: pvc.visual.Context#chart

{!pvc.BasePanel} panel()

Gets the immediate panel instance.

This is the panel that is closest to where the scene belongs. Ultimately, this is the root chart's base panel.

Returns:: {!pvc.BasePanel} The panel instance.

See:: pvc.visual.Context#panel

{any} getCategory()

Gets the value of the category scene variable (defined in scenes of categorical and pie plots).

This method is sugar for scene.vars.category.value.

Returns:: {any} The variable's value.

See:: #getCategoryLabel

{any} getCategoryLabel()

Gets the label of the category scene variable.

This method is sugar for scene.vars.category.label.

Returns:: {any} The variable's label.

See:: #getCategory

{any} getColor()

Gets the value of the color scene variable (defined in scenes of plots).

This method is sugar for scene.vars.color.value.

This is not a color value (like a color string or a pv.Color object), but, instead, the business value that is passed to a color scale to obtain a color.

Returns:: {any} The variable's value.

See:: #getColorLabel

{any} getColorLabel()

Gets the label of the color scene variable.

This method is sugar for scene.vars.color.label.

Returns:: {any} The variable's label.

See:: #getColor

{any} getSeries()

Gets the value of the series scene variable (defined in scenes of cartesian plots).

This method is sugar for scene.vars.series.value.

Returns:: {any} The variable's value.

See:: #getSeriesLabel

{any} getSeriesLabel()

Gets the label of the series scene variable.

This method is sugar for scene.vars.series.label.

Returns:: {any} The variable's label.

See:: #getSeries

{any} getSize()

Gets the value of the size scene variable (defined in scenes of the heat-grid and the scatter/metric-point plots).

This method is sugar for scene.vars.size.value.

Returns:: {any} The variable's value.

See:: #getSizeLabel

{any} getSizeLabel()

Gets the label of the size scene variable.

This method is sugar for scene.vars.size.label.

Returns:: {any} The variable's label.

See:: #getSize

{any} getTick()

Gets the value of the tick scene variable (defined in scenes of the cartesian axis).

This method is sugar for scene.vars.tick.value.

Returns:: {any} The variable's value.

See:: #getTickLabel

{any} getTickLabel()

Gets the label of the tick scene variable.

This method is sugar for scene.vars.tick.label.

Returns:: {any} The variable's label.

See:: #getTick

{any} getValue()

Gets the value of the value scene variable (defined in scenes of categorical/numeric plots and the legend panel).

This method is sugar for scene.vars.value.value.

Returns:: {any} The variable's value.

See:: #getValueLabel

{any} getValueLabel()

Gets the label of the value scene variable.

This method is sugar for scene.vars.value.label.

Returns:: {any} The variable's label.

See:: #getValue

{any} getX()

Gets the value of the x scene variable (defined in scenes of the scatter/metric-point plot).

This method is sugar for scene.vars.x.value.

Returns:: {any} The variable's value.

See:: #getXLabel

{any} getXLabel()

Gets the label of the x scene variable.

This method is sugar for scene.vars.x.label.

Returns:: {any} The variable's label.

See:: #getX

{any} getY()

Gets the value of the y scene variable (defined in scenes of the scatter/metric-point plot).

This method is sugar for scene.vars.y.value.

Returns:: {any} The variable's value.

See:: #getYLabel

{any} getYLabel()

Gets the label of the y scene variable.

This method is sugar for scene.vars.y.label.

Returns:: {any} The variable's label.

See:: #getY

Types By Namespace

cdo

def

pvc

pvc.data

pvc.options

pvc.options.axes

pvc.options.charts

pvc.options.ext

pvc.options.format

pvc.options.marks

pvc.options.panels

pvc.options.plots

pvc.options.varia

pvc.options.visualRoles

pvc.visual

Class pvc.visual.Scene