prefuse

Class Visualization

java.lang.Object

prefuse.Visualization

public class Visualization
extends java.lang.Object

Central data structure representing an interactive Visualization. This class is responsible for managing the mappings between source data and onscreen VisualItems, maintaining a list of Display instances responsible for rendering of and interaction with the contents of this visualization, and providing a collection of named Action instances for performing data processing such as layout, animation, and size, shape, and color assignment.

The primary responsibility of the Visualization class is the creation of visual abstractions of input data. Regardless of the data structure (i.e., Table, Graph, or Tree), this class takes source data such as that loaded from a file (see prefuse.data.io) or from a relational database (see prefuse.data.io.sql) and creates a visual representation of the data. These visual representations of the data are data sets in their own right, providing access to the underlying source data to be visualized while also adding addition data fields specific to a visualization. These fields include spatial location (x, y coordinates and item bounds), color (for stroke, fill, and text), size, shape, and font. For a given input data set of type Table, Graph, or or Tree, a corresponding instance of VisualTable, VisualGraph, or VisualTree is created and stored in the visualization. These data types inherit the data values of the source data (and indeed, manipulate it directly) while additionally providing the aforementioned visual variables unique to that generated visual abstraction. Similarly, all Tuple, Node, or Edge instances used to represent an entry in the source data have a corresponding VisualItem, NodeItem, or EdgeItem representing the interactive, visual realization of the backing data.

The mapping of source data to a visual abstraction is accomplished using add(String, TupleSet) and the other "add" methods. These methods will automatically create the visual abstraction, and store it in this visualization, associating it with a provided data group name . This group name allows for queries to this visualization that consider only VisualItem instances from that particular group. This is quite useful when crafting Action instances that process only a particular group of visual data. The Visualization class provides mechanisms for querying any or all groups within the visualization, using one or both of the group name or a filtering Predicate to determine the items to include (see items(Predicate) for an examples). Source data may be added multiple times to a Visualization under different group names, allowing for multiple representations of the same backing data.

Additionally, the Visualization class supports VisualItem instances that are not directly grounded in backing source data. Examples include DecoratorItem which "decorates" another pre-existing VisualItem with a separate interactive visual object, and AggregateItem which provides an interactive visual representation of an aggregated of other VisualItems. Methods for adding data groups of these kinds include addDecorators(String, String) and addAggregates(String).

All of the examples discussed above are examples of primary, or visual, data groups of VisualItems. Visualizations also support secondary, or focus data groups that maintain additional collections of the VisualItems stored in the primary groups. Examples include a set of focus items (such as those that have been clicked by the user), selected items (items selected by a user), or search items (all matches to a search query). The exact semantics of these groups and the mechanisms by which they are populated is determined by application creators, but some defaults are provided. The Visualization class includes some default group names, namely FOCUS_ITEMS, SELECTED_ITEMS, and SEARCH_ITEMS for the above mentioned tasks. By default, both the FOCUS_ITEMS, SELECTED_ITEMS focus groups are included in the Visualization, represented using DefaultTupleSet instances. Also, some of the interactive controls provided by the prefuse.controls package populate these sets by default. See FocusControl for an example.

Visualizations also maintain references to all the Display instances providing interactive views of the content of this visualization. Display instances registers themselves with the visualization either in their constructor or through the Display.setVisualization(Visualization) method, so they do not otherwise need to be added manually. Displays can be configured to show all or only a subset of the data in the Visualization. A filtering Predicate can be used to control what items are drawn by the displaying, including limiting the Display to particular data groups (for example, using a InGroupPredicate). The Visualization's repaint() method will trigger a repaint on all Displays associated with the visualization.

Finally, the Visualization class provides a map of named Action instances that can be invoked to perform processing on the VisualItems contained in the visualization. Using the putAction(String, Action) will add a named Action to the visualization, registering the Action such that a reference to this Visualization will be available within the scope of the Action's Action.run(double) method. Processing Actions can later be invoked by name using the run(String) method and other similar methods. This functionality not only provides a convenient means of organizing a Visualization-specific collection of processing Actions, it also allows for a layer of indirection between an Action and its name. This allows Actions to be dynamically swapped at runtime. For example, an application may make a call to invoke an Action named "layout", but the actual layout processing maybe be dynamically swapped by changing the Action that corresponds to that name. For more information on processing Actions, see the prefuse.action packages and the top-level Action class.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ALL_ITEMS Data group name for indicating all groups
static java.lang.String	FOCUS_ITEMS Default data group name for focus items
static java.lang.String	SEARCH_ITEMS Default data group name for search result items
static java.lang.String	SELECTED_ITEMS Default data group name for selected items

Constructor Summary

Constructors

Constructor and Description
Visualization() Create a new, empty Visualization.

Method Summary

Modifier and Type	Method and Description
VisualTupleSet	add(java.lang.String group, TupleSet data) Add a data set to this visualization, using the given data group name.
VisualTupleSet	add(java.lang.String group, TupleSet data, Predicate filter) Add a data set to this visualization, using the given data group name.
AggregateTable	addAggregates(java.lang.String group) Add a group of aggregates to this visualization.
AggregateTable	addAggregates(java.lang.String group, Schema schema) Add a group of aggregates to this visualization.
protected void	addDataGroup(java.lang.String group, VisualTupleSet ts, TupleSet src)
VisualTable	addDecorators(java.lang.String group, java.lang.String source) Add a group of decorators to an existing visual data group.
VisualTable	addDecorators(java.lang.String group, java.lang.String source, Predicate filter) Add a group of decorators to an existing visual data group.
VisualTable	addDecorators(java.lang.String group, java.lang.String source, Predicate filter, Schema schema) Add a group of decorators to an existing visual data group.
VisualTable	addDecorators(java.lang.String group, java.lang.String source, Schema schema) Add a group of decorators to an existing visual data group.
VisualTable	addDerivedTable(java.lang.String group, java.lang.String source, Predicate filter, Schema override) Add a derived table, a VisualTable that is cascaded from an existing VisualTable.
void	addFocusGroup(java.lang.String group) Add a new secondary, or focus, group to this visualization.
void	addFocusGroup(java.lang.String group, TupleSet tSet) Add a new secondary, or focus, group to this visualization.
VisualGraph	addGraph(java.lang.String group, Graph graph) Adds a graph to this visualization, using the given data group name.
VisualGraph	addGraph(java.lang.String group, Graph graph, Predicate filter) Adds a graph to this visualization, using the given data group name.
VisualGraph	addGraph(java.lang.String group, Graph graph, Predicate filter, Schema nodeSchema, Schema edgeSchema) Adds a graph to this visualization, using the given data group name.
VisualTable	addTable(java.lang.String group) Add an empty VisualTable to this visualization, using the given data group name.
VisualTable	addTable(java.lang.String group, Schema schema) Add an empty VisualTable to this visualization, using the given data group name and table schema.
VisualTable	addTable(java.lang.String group, Table table) Adds a data table to this visualization, using the given data group name.
VisualTable	addTable(java.lang.String group, Table table, Predicate filter) Adds a data table to this visualization, using the given data group name.
VisualTable	addTable(java.lang.String group, Table table, Predicate filter, Schema schema) Adds a data table to this visualization, using the given data group name.
VisualTable	addTable(java.lang.String group, Table table, Schema schema) Adds a data table to this visualization, using the given data group name.
VisualTable	addTable(VisualTable table) Add a VisualTable to this visualization, using the table's pre-set group name.
VisualTree	addTree(java.lang.String group, Tree tree) Adds a tree to this visualization, using the given data group name.
VisualTree	addTree(java.lang.String group, Tree tree, Predicate filter) Adds a tree to this visualization, using the given data group name.
VisualTree	addTree(java.lang.String group, Tree tree, Predicate filter, Schema nodeSchema, Schema edgeSchema) Adds a tree to this visualization, using the given data group name.
Activity	alwaysRunAfter(java.lang.String before, java.lang.String after) Schedule the Action with the given name to always run after another Action finishes running.
Activity	cancel(java.lang.String action) Cancel the Action with the given name, if it has been scheduled.
protected void	checkGroupExists(java.lang.String group)
void	damageReport(VisualItem item, java.awt.geom.Rectangle2D region) Report damage to associated displays, indicating a region that will need to be redrawn.
Action	getAction(java.lang.String name) Get the data processing Action with the given name.
java.awt.geom.Rectangle2D	getBounds(java.lang.String group) Get the bounding rectangle for all items in the given group.
java.awt.geom.Rectangle2D	getBounds(java.lang.String group, java.awt.geom.Rectangle2D r) Get the bounding rectangle for all items in the given group.
Display	getDisplay(int idx) Get the display at the given list index.
int	getDisplayCount() Get the number of displays associated with this visualization.
TupleSet	getFocusGroup(java.lang.String group) Retrieve the focus data group of the given group name.
TupleSet	getGroup(java.lang.String group) Get the TupleSet associated with the given data group name.
Renderer	getRenderer(VisualItem item) Get the renderer for the given item.
RendererFactory	getRendererFactory() Get the RendererFactory used by this Visualization.
TupleSet	getSourceData(java.lang.String group) Get the source data TupleSet backing the given visual data group.
TupleSet	getSourceData(VisualTupleSet ts) Get the source data TupleSet backing the given visual tuple set.
Tuple	getSourceTuple(VisualItem item) Get the Tuple from a backing source data set that corresponds most closely to the given VisualItem.
TupleSet	getVisualGroup(java.lang.String group) Retrieve the visual data group of the given group name.
VisualItem	getVisualItem(java.lang.String group, Tuple t) Get the VisualItem associated with a source data tuple, if it exists.
void	invalidate(java.lang.String group) Invalidate the bounds of all VisualItems in the given group.
void	invalidateAll() Invalidate the bounds of all VisualItems in this visualization.
boolean	isInGroup(VisualItem item, java.lang.String group) Indicates if a given VisualItem is contained in the given visual data group.
java.util.Iterator	items() Get an iterator over all items, visible or not.
java.util.Iterator	items(Predicate filter) Get an iterator over all items which match the given Predicate filter.
java.util.Iterator	items(java.lang.String group) Get an iterator over all items in the specified group.
java.util.Iterator	items(java.lang.String group, Predicate filter) Get an iterator over all items in the given group which match the given Predicate filter.
java.util.Iterator	items(java.lang.String group, java.lang.String expr) Get an iterator over all items in the given group which match the given filter expression.
Action	putAction(java.lang.String name, Action action) Add a data processing Action to this Visualization.
Action	removeAction(java.lang.String name) Remove a data processing Action registered with this visualization.
boolean	removeGroup(java.lang.String group) Removes a data group from this Visualization.
void	repaint() Issue a repaint request, causing all displays associated with this visualization to be repainted.
void	reset() Reset this visualization, clearing out all visualization tuples.
Activity	run(java.lang.String action) Schedule the Action with the given name to run immediately.
Activity	runAfter(java.lang.String action, long delay) Schedule the Action with the given name to run after the specified delay.
Activity	runAfter(java.lang.String before, java.lang.String after) Schedule the Action with the given name to run after another Action finishes running.
Activity	runAt(java.lang.String action, long startTime) Schedule the Action with the given name to run at the specified time.
void	setInteractive(java.lang.String group, Predicate p, boolean value) Sets the interactivity status for all items in a given data group matching a given filter predicate.
void	setRendererFactory(RendererFactory rf) Set the RendererFactory used by this Visualization.
void	setValue(java.lang.String group, Predicate p, java.lang.String field, java.lang.Object val) Set a data field value for all items in a given data group matching a given filter predicate.
void	setVisible(java.lang.String group, Predicate p, boolean value) Sets the visibility status for all items in a given data group matching a given filter predicate.
int	size(java.lang.String group) Get the size of the given visual data group.
java.util.Iterator	visibleItems() Get an iterator over all visible items.
java.util.Iterator	visibleItems(java.lang.String group) Get an iterator over all visible items in the specified group.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALL_ITEMS

public static final java.lang.String ALL_ITEMS

Data group name for indicating all groups

FOCUS_ITEMS

public static final java.lang.String FOCUS_ITEMS

Default data group name for focus items

SELECTED_ITEMS

public static final java.lang.String SELECTED_ITEMS

Default data group name for selected items

SEARCH_ITEMS

public static final java.lang.String SEARCH_ITEMS

Default data group name for search result items

Constructor Detail

Visualization

public Visualization()

Create a new, empty Visualization. Uses a DefaultRendererFactory.

Method Detail

add

public VisualTupleSet add(java.lang.String group,
                          TupleSet data)

Add a data set to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

data - the data to visualize

Returns:

a visual abstraction of the input data, a VisualTupleSet instance

add

public VisualTupleSet add(java.lang.String group,
                          TupleSet data,
                          Predicate filter)

Add a data set to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

data - the data to visualize

filter - a filter Predicate determining which data Tuples in the input data set are visualized

Returns:

a visual abstraction of the input data, a VisualTupleSet instance

checkGroupExists

protected void checkGroupExists(java.lang.String group)

addDataGroup

protected void addDataGroup(java.lang.String group,
                            VisualTupleSet ts,
                            TupleSet src)

addTable

public VisualTable addTable(java.lang.String group)

Add an empty VisualTable to this visualization, using the given data group name. This adds a group of VisualItems that do not have a backing data set, useful for creating interactive visual objects that do not represent data. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

Returns:

the added VisualTable

addTable

public VisualTable addTable(java.lang.String group,
                            Schema schema)

Add an empty VisualTable to this visualization, using the given data group name and table schema. This adds a group of VisualItems that do not have a backing data set, useful for creating interactive visual objects that do not represent data. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

schema - the data schema to use for the VisualTable

Returns:

the added VisualTable

addTable

public VisualTable addTable(java.lang.String group,
                            Table table)

Adds a data table to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

table - the data table to visualize

addTable

public VisualTable addTable(java.lang.String group,
                            Table table,
                            Predicate filter)

Adds a data table to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

table - the data table to visualize

filter - a filter Predicate determining which data Tuples in the input table are visualized

addTable

public VisualTable addTable(java.lang.String group,
                            Table table,
                            Schema schema)

Adds a data table to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

table - the data table to visualize

schema - the data schema to use for the created VisualTable

addTable

public VisualTable addTable(java.lang.String group,
                            Table table,
                            Predicate filter,
                            Schema schema)

Adds a data table to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized data

table - the data table to visualize

filter - a filter Predicate determining which data Tuples in the input table are visualized

schema - the data schema to use for the created VisualTable

addTable

public VisualTable addTable(VisualTable table)

Add a VisualTable to this visualization, using the table's pre-set group name. An exception will be thrown if the group name is already in use. This method allows you to insert custom implementations of VisualTable into a Visualization. It is intended for advanced users and should NOT be used if you do not know what you are doing. In almost all cases, one of the other add methods is preferred.

Parameters:

table - the pre-built VisualTable to add

Returns:

the added VisualTable

addGraph

public VisualGraph addGraph(java.lang.String group,
                            Graph graph)

Adds a graph to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized graph. The nodes and edges will be available in the "group.nodes" and "group.edges" subgroups.

graph - the graph to visualize

addGraph

public VisualGraph addGraph(java.lang.String group,
                            Graph graph,
                            Predicate filter)

Adds a graph to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized graph. The nodes and edges will be available in the "group.nodes" and "group.edges" subgroups.

graph - the graph to visualize

filter - a filter Predicate determining which data Tuples in the input graph are visualized

addGraph

public VisualGraph addGraph(java.lang.String group,
                            Graph graph,
                            Predicate filter,
                            Schema nodeSchema,
                            Schema edgeSchema)

Adds a graph to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized graph. The nodes and edges will be available in the "group.nodes" and "group.edges" subgroups.

graph - the graph to visualize

filter - a filter Predicate determining which data Tuples in the input graph are visualized

nodeSchema - the data schema to use for the visual node table

edgeSchema - the data schema to use for the visual edge table

addTree

public VisualTree addTree(java.lang.String group,
                          Tree tree)

Adds a tree to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized tree. The nodes and edges will be available in the "group.nodes" and "group.edges" subgroups.

tree - the tree to visualize

addTree

public VisualTree addTree(java.lang.String group,
                          Tree tree,
                          Predicate filter)

Adds a tree to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized tree. The nodes and edges will be available in the "group.nodes" and "group.edges" subgroups.

tree - the tree to visualize

filter - a filter Predicate determining which data Tuples in the input graph are visualized

addTree

public VisualTree addTree(java.lang.String group,
                          Tree tree,
                          Predicate filter,
                          Schema nodeSchema,
                          Schema edgeSchema)

Adds a tree to this visualization, using the given data group name. A visual abstraction of the data will be created and registered with the visualization. An exception will be thrown if the group name is already in use.

Parameters:

group - the data group name for the visualized tree. The nodes and edges will be available in the "group.nodes" and "group.edges" subgroups.

tree - the tree to visualize

filter - a filter Predicate determining which data Tuples in the input graph are visualized

nodeSchema - the data schema to use for the visual node table

edgeSchema - the data schema to use for the visual edge table

addAggregates

public AggregateTable addAggregates(java.lang.String group)

Add a group of aggregates to this visualization. Aggregates are used to visually represent groups of VisualItems.

Parameters:

group - the data group name for the aggregates.

Returns:

the generated AggregateTable

See Also:

AggregateTable

addAggregates

public AggregateTable addAggregates(java.lang.String group,
                                    Schema schema)

Add a group of aggregates to this visualization. Aggregates are used to visually represent groups of VisualItems.

Parameters:

group - the data group name for the aggregates.

schema - the data schema to use for the AggregateTable

Returns:

the generated AggregateTable

See Also:

AggregateTable

addDerivedTable

public VisualTable addDerivedTable(java.lang.String group,
                                   java.lang.String source,
                                   Predicate filter,
                                   Schema override)

Add a derived table, a VisualTable that is cascaded from an existing VisualTable. This is useful for creating VisualItems that inherit a set of visual properties from another group of VisualItems. This might be used, for example, in the creation of small multiples where only a few visual attributes vary across the multiples.

Parameters:

group - the data group to use for the derived table

source - the source data group to derive from

filter - a Predicate filter indicating which tuples of the source group should be inheritable by the new group

override - a data schema indicating which data fields should not be inherited, but managed locally by the derived group

Returns:

the derived VisualTable

addDecorators

public VisualTable addDecorators(java.lang.String group,
                                 java.lang.String source)

Add a group of decorators to an existing visual data group. Decorators are VisualItem instances intended to "decorate" another VisualItem, such as providing a label or dedicated interactive control, and are realized as DecoratorItem instances that provide access to the decorated item in addition to the standard VisualItem properties. The generated table is created using the addDerivedTable(String, String, Predicate, Schema) method, but with no VisualItem properties inherited from the source group.

Parameters:

group - the data group to use for the decorators

source - the source data group to decorate

Returns:

the generated VisualTable of DecoratorItem instances

addDecorators

public VisualTable addDecorators(java.lang.String group,
                                 java.lang.String source,
                                 Schema schema)

Add a group of decorators to an existing visual data group. Decorators are VisualItem instances intended to "decorate" another VisualItem, such as providing a label or dedicated interactive control, and are realized as DecoratorItem instances that provide access to the decorated item in addition to the standard VisualItem properties.

Parameters:

group - the data group to use for the decorators

source - the source data group to decorate

schema - schema indicating which variables should not be inherited from the source data group and instead be managed locally by the generated VisualTable

Returns:

the generated VisualTable of DecoratorItem instances

addDecorators

public VisualTable addDecorators(java.lang.String group,
                                 java.lang.String source,
                                 Predicate filter)

Add a group of decorators to an existing visual data group. Decorators are VisualItem instances intended to "decorate" another VisualItem, such as providing a label or dedicated interactive control, and are realized as DecoratorItem instances that provide access to the decorated item in addition to the standard VisualItem properties.

Parameters:

group - the data group to use for the decorators

source - the source data group to decorate

filter - a Predicate filter indicating which tuples of the source group should be inheritable by the new group

Returns:

the generated VisualTable of DecoratorItem instances

addDecorators

public VisualTable addDecorators(java.lang.String group,
                                 java.lang.String source,
                                 Predicate filter,
                                 Schema schema)

Add a group of decorators to an existing visual data group. Decorators are VisualItem instances intended to "decorate" another VisualItem, such as providing a label or dedicated interactive control, and are realized as DecoratorItem instances that provide access to the decorated item in addition to the standard VisualItem properties.

Parameters:

group - the data group to use for the decorators

source - the source data group to decorate

filter - a Predicate filter indicating which tuples of the source group should be inheritable by the new group

schema - schema indicating which variables should not be inherited from the source data group and instead be managed locally by the generated VisualTable

Returns:

the generated VisualTable of DecoratorItem instances

removeGroup

public boolean removeGroup(java.lang.String group)

Removes a data group from this Visualization. If the group is a focus group, the group will simply be removed, and any subsequent attempts to retrieve the group will return null. If the group is a primary group, it will be removed, and any members of the group will also be removed from any registered focus groups.

Parameters:

group - the data group to remove

Returns:

true if the group was found and removed, false if the group was not found in this visualization.

reset

public void reset()

Reset this visualization, clearing out all visualization tuples. All data sets added using the "addXXX" methods will be removed from the visualization. All registered focus groups added using the addFocusGroup() methods will be retained, but will be cleared of all tuples.

getSourceData

public TupleSet getSourceData(java.lang.String group)

Get the source data TupleSet backing the given visual data group.

Returns:

the backing source data set, or null if there is no such data set

getSourceData

public TupleSet getSourceData(VisualTupleSet ts)

Get the source data TupleSet backing the given visual tuple set.

Returns:

the backing source data set, or null if there is no such data set

getSourceTuple

public Tuple getSourceTuple(VisualItem item)

Get the Tuple from a backing source data set that corresponds most closely to the given VisualItem.

Parameters:

item - the VisualItem for which to retrieve the source tuple

Returns:

the data source tuple, or null if no such tuple could be found

getVisualItem

public VisualItem getVisualItem(java.lang.String group,
                                Tuple t)

Get the VisualItem associated with a source data tuple, if it exists.

Parameters:

group - the data group from which to lookup the source tuple, only primary visual groups are valid, focus groups will not work

t - the source data tuple

Returns:

the associated VisualItem from the given data group, or null if no such VisualItem exists

getGroup

public TupleSet getGroup(java.lang.String group)

Get the TupleSet associated with the given data group name.

Parameters:

group - a visual data group name

Returns:

the data group TupleSet

isInGroup

public boolean isInGroup(VisualItem item,
                         java.lang.String group)

Indicates if a given VisualItem is contained in the given visual data group.

Parameters:

item - the VisualItem instance

group - the data group to check for containment

Returns:

true if the VisualItem is in the group, false otherwise

addFocusGroup

public void addFocusGroup(java.lang.String group)

Add a new secondary, or focus, group to this visualization. By default the added group is an instance of DefaultTupleSet.

Parameters:

group - the name of the focus group to add

addFocusGroup

public void addFocusGroup(java.lang.String group,
                          TupleSet tSet)

Add a new secondary, or focus, group to this visualization.

Parameters:

group - the name of the focus group to add

tSet - the TupleSet for the focus group

size

public int size(java.lang.String group)

Get the size of the given visual data group.

Parameters:

group - the visual data group

Returns:

the size (number of tuples) of the group

getVisualGroup

public TupleSet getVisualGroup(java.lang.String group)

Retrieve the visual data group of the given group name. Only primary visual groups will be considered.

Parameters:

group - the visual data group

Returns:

the requested data group, or null if not found

getFocusGroup

public TupleSet getFocusGroup(java.lang.String group)

Retrieve the focus data group of the given group name. Only secondary, or focus, groups will be considered.

Parameters:

group - the focus data group

Returns:

the requested data group, or null if not found

invalidate

public void invalidate(java.lang.String group)

Invalidate the bounds of all VisualItems in the given group. This will cause the bounds to be recomputed for all items upon the next redraw.

Parameters:

group - the visual data group to invalidate

invalidateAll

public void invalidateAll()

Invalidate the bounds of all VisualItems in this visualization. This will cause the bounds to be recomputed for all items upon the next redraw.

visibleItems

public java.util.Iterator visibleItems()

Get an iterator over all visible items.

Returns:

an iterator over all visible items.

visibleItems

public java.util.Iterator visibleItems(java.lang.String group)

Get an iterator over all visible items in the specified group.

Parameters:

group - the visual data group name

Returns:

an iterator over all visible items in the specified group

items

public java.util.Iterator items()

Get an iterator over all items, visible or not.

Returns:

an iterator over all items, visible or not.

items

public java.util.Iterator items(Predicate filter)

Get an iterator over all items which match the given Predicate filter.

Parameters:

filter - a Predicate indicating which items should be included in the iteration

Returns:

a filtered iterator over VisualItems

items

public java.util.Iterator items(java.lang.String group)

Get an iterator over all items in the specified group.

Parameters:

group - the visual data group name

Returns:

an iterator over all items in the specified group.

items

public java.util.Iterator items(java.lang.String group,
                                java.lang.String expr)

Get an iterator over all items in the given group which match the given filter expression.

Parameters:

group - the visual data group to iterate over

expr - an expression string that should parse to a Predicate indicating which items should be included in the iteration. The input string will be parsed using the ExpressionParser class. If a parse error occurs, an empty iterator is returned.

Returns:

a filtered iterator over VisualItems

items

public java.util.Iterator items(java.lang.String group,
                                Predicate filter)

Get an iterator over all items in the given group which match the given Predicate filter.

Parameters:

group - the visual data group to iterate over

filter - a Predicate indicating which items should be included in the iteration.

Returns:

a filtered iterator over VisualItems

setValue

public void setValue(java.lang.String group,
                     Predicate p,
                     java.lang.String field,
                     java.lang.Object val)

Set a data field value for all items in a given data group matching a given filter predicate.

Parameters:

group - the visual data group name

p - the filter predicate determining which items to modify

field - the data field / column name to set

val - the value to set

setVisible

public void setVisible(java.lang.String group,
                       Predicate p,
                       boolean value)

Sets the visibility status for all items in a given data group matching a given filter predicate.

Parameters:

group - the visual data group name

p - the filter predicate determining which items to modify

value - the visibility value to set

setInteractive

public void setInteractive(java.lang.String group,
                           Predicate p,
                           boolean value)

Sets the interactivity status for all items in a given data group matching a given filter predicate.

Parameters:

group - the visual data group name

p - the filter predicate determining which items to modify

value - the interactivity value to set

putAction

public Action putAction(java.lang.String name,
                        Action action)

Add a data processing Action to this Visualization. The Action will be updated to use this Visualization in its data processing.

Parameters:

name - the name of the Action

action - the Action to add

getAction

public Action getAction(java.lang.String name)

Get the data processing Action with the given name.

Parameters:

name - the name of the Action

Returns:

the requested Action, or null if the name was not found

removeAction

public Action removeAction(java.lang.String name)

Remove a data processing Action registered with this visualization. If the removed action is currently running, it will be canceled. The visualization reference held by the removed Action will be set to null.
NOTE: Errors may occur if the removed Action is included in an "always run after" relation with another registered Action that has not been removed from this visualization. It is the currently the responsibility of clients to avoid this situation.

Parameters:

name - the name of the Action

Returns:

the removed Action, or null if no action was found

run

public Activity run(java.lang.String action)

Schedule the Action with the given name to run immediately. The running of all Actions is managed by the ActivityManager, which runs in a dedicated thread.

Parameters:

action - the name of the Action to run

Returns:

the Action scheduled to run

runAfter

public Activity runAfter(java.lang.String action,
                         long delay)

Schedule the Action with the given name to run after the specified delay. The running of all Actions is managed by the ActivityManager, which runs in a dedicated thread.

Parameters:

action - the name of the Action to run

delay - the amount of time to wait, in milliseconds, before running the Action

Returns:

the Action scheduled to run

runAt

public Activity runAt(java.lang.String action,
                      long startTime)

Schedule the Action with the given name to run at the specified time. The running of all Actions is managed by the ActivityManager, which runs in a dedicated thread.

Parameters:

action - the name of the Action to run

startTime - the absolute system time, in milliseconds since the epoch, at which to run the Action.

Returns:

the Action scheduled to run

runAfter

public Activity runAfter(java.lang.String before,
                         java.lang.String after)

Schedule the Action with the given name to run after another Action finishes running. This relationship will only hold for one round of scheduling. If the "before" Action is run a second time, the "after" action will not be run a second time. The running of all Actions is managed by the ActivityManager, which runs in a dedicated thread.

Parameters:

before - the name of the Action to wait for

after - the name of the Action to run after the first one finishes

Returns:

the Action scheduled to run after the first one finishes

alwaysRunAfter

public Activity alwaysRunAfter(java.lang.String before,
                               java.lang.String after)

Schedule the Action with the given name to always run after another Action finishes running. The running of all Actions is managed by the ActivityManager, which runs in a dedicated thread.

Parameters:

before - the name of the Action to wait for

after - the name of the Action to run after the first one finishes

Returns:

the Action scheduled to always run after the first one finishes

cancel

public Activity cancel(java.lang.String action)

Cancel the Action with the given name, if it has been scheduled.

Parameters:

action - the name of the Action to cancel

Returns:

the canceled Action

setRendererFactory

public void setRendererFactory(RendererFactory rf)

Set the RendererFactory used by this Visualization. The RendererFactory is responsible for providing the Renderer instances used to draw the VisualItems.

Parameters:

rf - the RendererFactory to use.

getRendererFactory

public RendererFactory getRendererFactory()

Get the RendererFactory used by this Visualization.

Returns:

this Visualization's RendererFactory

getRenderer

public Renderer getRenderer(VisualItem item)

Get the renderer for the given item. Consults this visualization's RendererFactory and returns the result.

Parameters:

item - the item to retrieve the renderer for

Returns:

the Renderer for drawing the given item

repaint

public void repaint()

Issue a repaint request, causing all displays associated with this visualization to be repainted.

getBounds

public java.awt.geom.Rectangle2D getBounds(java.lang.String group)

Get the bounding rectangle for all items in the given group.

Parameters:

group - the visual data group

Returns:

the bounding box of the items

getBounds

public java.awt.geom.Rectangle2D getBounds(java.lang.String group,
                                           java.awt.geom.Rectangle2D r)

Get the bounding rectangle for all items in the given group.

Parameters:

group - the visual data group name

r - a rectangle in which to store the computed bounding box

Returns:

the input rectangle r, updated to hold the computed bounding box

getDisplayCount

public int getDisplayCount()

Get the number of displays associated with this visualization.

Returns:

the number of displays

getDisplay

public Display getDisplay(int idx)

Get the display at the given list index. Displays are numbered by the order in which they are added to this visualization.

Parameters:

idx - the list index

Returns:

the Display at the given index

damageReport

public void damageReport(VisualItem item,
                         java.awt.geom.Rectangle2D region)

Report damage to associated displays, indicating a region that will need to be redrawn.

Parameters:

item - the item responsible for the damage

region - the damaged region, in item-space coordinates