prefuse
Class Visualization

java.lang.Object
  extended by 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.

Author:
jeffrey heer

Field Summary
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
Visualization()
          Create a new, empty Visualization.
 
Method Summary
 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 visbility 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 realizeed 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 realizeed 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 realizeed 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 realizeed 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 retreive 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 visbility 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 retreive 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


Copyright 2007 Regents of the University of California