com.sas.graphics.components.tilechart
Class TileChart

com.sas.graphics.components.tilechart.TileChart

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class TileChart

The TileChart component is a Swing component that produces a rectangular tree-based representation of data. Tile charts represent requested statistics that are based on a list of categorical variables. They are useful for displaying relative magnitudes within the hierachy.

For example, a tile chart might be used to represent sales data where the tile sizes vary according to the size of product inventories and the tile colors are derived from a color gradient that represents low to high sales figures.

Tile charts are well suited to representing strucured data because they automatically provide the capability to zoom to detail levels in the data. For example, in a tile chart that graphs sales data for the categorical variables Region, Product, and Subsidiary, the top-layer chart would show sales regions. When you select one of the regions, the chart will zoom in to show the products sold within that regions. When you select one of the products, the chart will zoom to show the subsidiaries that sell that product.

Note. This class can be used to render client-side graphs in Java applications or applets. The com.sas.servlet.tbeans.graphics.html.TileChart class can be used to render server-side graphs in Java servlets or JavaServer Pages (JSP). Both classes use the models in the com.sas.graphics.components package.

Topics:

Minimum Specification
Functional Overview
Data Access
Display Properties
Titles and Footnotes
Usage Examples
Behavior

Swing-based Samples

Since:

SAS 9.1

See Also:

Graph, GraphStyle, NoteModel, TileChartModel, TileChartDataModel, TileChartTableDataModel, Serialized Form

Field Summary

Fields inherited from class com.sas.graphics.components.Graph

footnoteContainer, RB_KEY, titleContainer

Constructor Summary

TileChart()
Construct a TileChart using the default GraphStyle (GraphStyle.STYLE_CONVENTION).

TileChart(TileChartDataModel tileChartDataModel)
Construct a TileChart, assigning tileChartDataModel, and using the default GraphStyle (GraphStyle.STYLE_CONVENTION).

TileChart(TileChartDataModel tileChartDataModel, GraphStyle defaultGraphStyle)
Construct a TileChart assigning tileChartDataModel and applying graphStyle.

Method Summary

void	applyColorScheme(ColorScheme scheme) Apply a color scheme to this graph's display attributes.
protected void	applyDataModel() Intended for internalUse only
protected void	applyGraphModel() For internal use only.
void	applyGraphStyle(GraphStyle graphStyle) Apply the display properties in the GraphStyle to the TileChart.
java.lang.String[]	getCurrentRootTile() Deprecated. use getRootPath()
TileChartDataModel	getDataModel() Returns the TileChartDataModel that provides a handle to the data along with any associated mapping properties.
TileChartModel	getGraphModel() Returns the TileChartModel that encapsulates most of the TileChart's display properties.
java.lang.String[]	getIDLabels() Returns a list of TILE labels (either user-set TILE or auto selected).
ChartImageMapInfo	getImageMapInfo() Returns the image mapping of the tile chart.
javax.swing.tree.DefaultMutableTreeNode	getRootNode()
java.lang.String[]	getRootPath() Returns the list of tiles from the base of the data tree to the current visible root tile.
java.lang.String[]	getRootTile() Deprecated. use setCurrentRootTile()
java.lang.String[]	getTileAtPosition(java.awt.geom.Point2D p) Deprecated. Let me know if you need this
java.lang.String[]	getTileValues() Returns a list of lowest level tile values, with duplicate values removed.
boolean	isAutoRepaintEnabled() Returns whether or not the graph automatically repaints when any of its properties (contained in associated models GraphModel, DataModel, NoteModel, etc) has changed.
void	prepareToPaint() Notify this component that an application is about to call paint directly.
protected void	selectionChanged() Internal use only.
void	setAutoRepaintEnabled(boolean b) Sets whether or not the graph automatically repaints when any of its properties (contained in associated models GraphModel, DataModel, NoteModel, etc) has changed.
void	setCurrentRootTile(java.lang.String[] tileValues) Deprecated. use setRootPath()
void	setDataModel(TileChartDataModel newDataModel) Sets the TileChartDataModel which provides a data source along with associated mapping properties to define the number and arrangement of data elements (tiles), legend and axes.
void	setDisplayPolicy(int newDisplayPolicy) setDisplayPolicy is unsupported by TileChart, since it is always assumed to be DISPLAY_FIT_TO_SCREEN.
void	setGraphModel(TileChartModel newTileChartModel) Sets a TileChartModel to define most of the TileChart's display properties.
void	setLocale(java.util.Locale locale) Sets the locale of this component.
void	setRootPath(java.lang.String[] tileValues) Set the tile to display as the root of the chart.
void	setRootTile(java.lang.String[] tileValues) Deprecated. use setCurrentRootTile()
protected void	updateDataModelListeners() Internal use only.

Methods inherited from class com.sas.graphics.components.Graph

addActionListener, addMouseListener, addMouseMotionListener, addMouseMotionListener, clearSelection, firePropertyChange, getActionProvider, getAppliedColorSchemeName, getAppliedGraphStyleName, getBackground, getBrushBounds, getChannel, getContentsChangedListener, getDefaultGraphStyle, getDefaultHeight, getDefaultWidth, getDisplayPolicy, getFooter, getFootnote, getFootnote1, getFootnote2, getHeader, getListSelectionListener, getLocale, getMessageModel, getMinimumSize, getPreferredSize, getTableModelListener, getTitle, getTitle1, getTitle2, getTitle3, getTitle4, isAppliedGraphStyleModified, paint, paintAll, paintBackground, pick, pick, pickSelected, removeActionListener, select, select, select, select, setActionProvider, setBackground, setBounds, setFooter, setFootnote, setFootnote1, setFootnote2, setHeader, setMessageModel, setPaintContext, setTitle, setTitle1, setTitle2, setTitle3, setTitle4, update, updateDataModelListeners, validateTree

Constructor Detail

TileChart

public TileChart()

Construct a TileChart using the default GraphStyle (GraphStyle.STYLE_CONVENTION).

See Also:

GraphStyle

TileChart

public TileChart(TileChartDataModel tileChartDataModel)

Construct a TileChart, assigning tileChartDataModel, and using the default GraphStyle (GraphStyle.STYLE_CONVENTION). The TileChartDataModel is accessible via the getDataModel method.

A null TileChartDataModel parameter is equivalent to using the default constructor.

Parameters:

tileChartDataModel - the data to be used by this graph

See Also:

GraphStyle, TileChartTableDataModel

TileChart

public TileChart(TileChartDataModel tileChartDataModel,
                 GraphStyle defaultGraphStyle)

Construct a TileChart assigning tileChartDataModel and applying graphStyle. The TileChartDataModel is accessible via the getDataModel method. The TileChartModel (whose properties are affected by the GraphStyle application) is accessible via the getGraphModel method. The NoteModels (whose properties are affected by the GraphStyle application) are accessible via the getTitle and getFootnote methods. A null TileChartDataModel parameter is equivalent to setDataModel(null); If graphStyle is null then GraphStyle.STYLE_CONVENTION will be applied.

Parameters:

tileChartDataModel - provides a data handle with associated mapping properties

defaultGraphStyle - the set of graph display properties

See Also:

NoteModel, TileChartModel, TileChartTableDataModel

Method Detail

prepareToPaint

public void prepareToPaint()

Notify this component that an application is about to call paint directly. This method is useful when attempting to get the Graph to draw into an image (or other application provided GraphicsContext).

As per java standard practices; "paint" should never be called directly by an application. However if it is necessary to render the Graph directly then the use of paintAll(Graphics) or printAll(Graphics) is acceptable.

Graphs asynchronously update to keep their view in sync with their model properties (Graphmodel, DataModel, NoteModel etc.). A direct call to paintAll or printAll does not allow for the graph to asynchronously sync up with their model proeprties. prepareToPaint provides this synchronization point necessary for the Graphs to update their component structure as needed.

Note: Used in a headless environment, Graphs will never asynchronously update and therefore require a call to prepareToPaint to render into a GraphicsContext.

The headless and non-headless cases can be handled slightly differently. In the non-headless case the asynchronous updating needs to be halted. This is done by setting the "autoRepaintEnabled" property to false. The default for autoRepaintEnabled is true, allowing the graph to automatically resync and repaint as model properties are modified.

Example writing to an image. Note for readability exception handling has been ignored.

 static public void main(String args[])
 {
    BufferedImage bi = new BufferedImage(640,480,BufferedImage.TYPE_INT_RGB);
    Graphics ig = bi.createGraphics();

    // Create Graph
    TileChart graph = new TileChart();
 
    // This call is not necessary if you are running in a headless environment.
    graph.setAutoRepaintEnabled(false);
    
    // ... assign data and model properties here ...
    graph.setDataModel(newGraphData());
    
    {// Render sequence
        graph.setBounds(0,0,bi.getWidth(null),bi.getHeight(null)); // Define the size of the Graph
        graph.addNotify(); // Makes the component displayable.
        graph.prepareToPaint(); // do property synchronization
        graph.paintAll(ig); // render into some graphics context
    }
 
    // Dispose of image graphics context
    ig.dispose();                
    
    // Save immage to disk
    File file = new File("graph.jpg");
    try
    {
        ImageIO.write(bi, "jpg", file);
    }
    catch (IOException e)
    {
        System.out.println("ImageIO.write failed.");
    }
 }
 

Specified by:

prepareToPaint in class Graph

setAutoRepaintEnabled

public void setAutoRepaintEnabled(boolean b)

Sets whether or not the graph automatically repaints when any of its properties (contained in associated models GraphModel, DataModel, NoteModel, etc) has changed. The default value is true.

The setting of this property to false implies that the application will be responsible for synchronizing the graph with its models using the prepareToPaint method.

This method was added to suport rendering into an off screen graphics context such as an image.

Specified by:

setAutoRepaintEnabled in class Graph

Parameters:

b - true means to automatically update

See Also:

isAutoRepaintEnabled()

isAutoRepaintEnabled

public boolean isAutoRepaintEnabled()

Returns whether or not the graph automatically repaints when any of its properties (contained in associated models GraphModel, DataModel, NoteModel, etc) has changed.

Specified by:

isAutoRepaintEnabled in class Graph

See Also:

setAutoRepaintEnabled(boolean)

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale of this component. This is a bound property.

Overrides:

setLocale in class java.awt.Component

Parameters:

locale - the locale to become this component's locale

See Also:

Graph.getLocale()

setGraphModel

public void setGraphModel(TileChartModel newTileChartModel)
                   throws java.lang.IllegalArgumentException

Sets a TileChartModel to define most of the TileChart's display properties. Modifying any TileChartModel property triggers the TileChart to update. The update is asynchronous and delayed so modifying multiple properties in quick succession will result in only a single update. Use the FullPaintInterface if greater control over the TileChart's paint behavior is necessary.

Typically applyGraphStyle is used to modify the graphs display properties.

Parameters:

newTileChartModel - the TileChartModel that encapsulates the TileChart's display properties

Throws:

java.lang.IllegalArgumentException - if newTileChartModel is null.

See Also:

getGraphModel(), TileChartModel.apply(com.sas.graphics.components.tilechart.TileChartModel), GraphStyle

getGraphModel

public TileChartModel getGraphModel()

Returns the TileChartModel that encapsulates most of the TileChart's display properties.

Returns:

the TileChartModel that encapsulates most of the TileChart's display properties

See Also:

setGraphModel(com.sas.graphics.components.tilechart.TileChartModel), TileChartModel.apply(com.sas.graphics.components.tilechart.TileChartModel)

applyGraphModel

protected void applyGraphModel()

For internal use only.

Overrides:

applyGraphModel in class Graph

setDataModel

public void setDataModel(TileChartDataModel newDataModel)

Sets the TileChartDataModel which provides a data source along with associated mapping properties to define the number and arrangement of data elements (tiles), legend and axes.

Any change in the TileChartDataModel properties will cause the TileChart to update. The update is asynchronous and delayed so modifying multiple properties in quick succession will result in only a single update. The FullPaintInterface can be used if greater control over the TileChart's paint behavior is needed.

Note: Data value changes will also trigger TileChart to update.

A valid TileChartDataModel is required to draw a graph.

Parameters:

newDataModel - provides a handle to the data along with any associated mapping properties

See Also:

getDataModel(), TileChartTableDataModel

getDataModel

public TileChartDataModel getDataModel()

Returns the TileChartDataModel that provides a handle to the data along with any associated mapping properties.

Returns:

the TileChartDataModel that provides a handle to the data along with any associated mapping properties

See Also:

setDataModel(com.sas.graphics.components.tilechart.TileChartDataModel), TileChartTableDataModel

getImageMapInfo

public ChartImageMapInfo getImageMapInfo()

Returns the image mapping of the tile chart. The ChartImageMapInfo class encapsulates the mapping of regions associated with tile elements, labels and values as projected onto the display area along with their associated data. This is particularly useful with creating html imagemap information if the graph is used to create an image for an html document.

Returns:

the mapping of regions associated with graph elements

setRootPath

public void setRootPath(java.lang.String[] tileValues)

Set the tile to display as the root of the chart.

Parameters:

tileValues - a String array with one level name contained in each string, from the base of the tree to the desired, current root tile.

See Also:

getRootPath()

getRootPath

public java.lang.String[] getRootPath()

Returns the list of tiles from the base of the data tree to the current visible root tile.

Returns:

a String array with one level name contained in each string, from general to specific.

See Also:

setRootPath(java.lang.String[])

getRootNode

public javax.swing.tree.DefaultMutableTreeNode getRootNode()

setCurrentRootTile

public void setCurrentRootTile(java.lang.String[] tileValues)

Deprecated. use setRootPath()

getCurrentRootTile

public java.lang.String[] getCurrentRootTile()

Deprecated. use getRootPath()

setRootTile

public void setRootTile(java.lang.String[] tileValues)

Deprecated. use setCurrentRootTile()

getRootTile

public java.lang.String[] getRootTile()

Deprecated. use setCurrentRootTile()

getTileAtPosition

public java.lang.String[] getTileAtPosition(java.awt.geom.Point2D p)

Deprecated. Let me know if you need this

applyDataModel

protected void applyDataModel()

Description copied from class: Graph

Intended for internalUse only

Specified by:

applyDataModel in class Graph

applyGraphStyle

public void applyGraphStyle(GraphStyle graphStyle)

Apply the display properties in the GraphStyle to the TileChart. The use of this method is a convenient way to quickly and easily affect the TileChart's appearance is strongly encouraged.

Some GraphStyle properties like the background fill style will be applied to the TileChart's TileChartModel (thus affecting the TileChartAppearance). Other GraphStyle properties like the title1 text style will be applied to properties on other TileChart models such as the TileChart's title1 NoteModel.

The GraphStyle enforces certain constraints that are not enforced on a Graph. For example the TileChart supports setting different value text styles at different id levels, whereas a GraphStyle only supports a single display value text style property. When a GraphStyle is applied to a TileChart all of the TileChart's display values use the GraphStyle axis value setting (thus easily enforcing that all display values are represented in the same font and color). The use of the GraphStyle allows for easier graph customizations while the TileChart models allow for greater customization when desired.

Modifying any of the properties in the GraphStyle after this call will have no affect on the TileChart. Likewise modifying any TileChart properties after this call will have no affect on the GraphStyle. This method simply conveys the properties in the GraphStyle onto the TileChart properties.

A blind PropertyChangeEvent will be fired by the TileChart after the apply is made.

No action will be taken if a null GraphStyle is passed in.

Overrides:

applyGraphStyle in class Graph

Parameters:

graphStyle - the GraphStyle whose properties are conveyed to the TileChart

applyColorScheme

public void applyColorScheme(ColorScheme scheme)

Apply a color scheme to this graph's display attributes. Note: ColorScheme is currently geared towards solid fill colors only.

Overrides:

applyColorScheme in class Graph

Parameters:

scheme - ColorScheme object containing a set of colors for the charts.

getTileValues

public java.lang.String[] getTileValues()

Returns a list of lowest level tile values, with duplicate values removed. Mainly for use of the UI.

Returns:

a String array with one tile value per entry.

getIDLabels

public java.lang.String[] getIDLabels()

Returns a list of TILE labels (either user-set TILE or auto selected). Mainly for use of the UI.

Returns:

a String array with one TILE level per entry.

selectionChanged

protected void selectionChanged()

Internal use only.

Specified by:

selectionChanged in class Graph

updateDataModelListeners

protected void updateDataModelListeners()

Internal use only.

Specified by:

updateDataModelListeners in class Graph

See Also:

Graph.updateDataModelListeners(Object model, Object selectionModel)

setDisplayPolicy

public void setDisplayPolicy(int newDisplayPolicy)
                      throws java.lang.IllegalArgumentException

setDisplayPolicy is unsupported by TileChart, since it is always assumed to be DISPLAY_FIT_TO_SCREEN.

Overrides:

setDisplayPolicy in class Graph

Parameters:

newDisplayPolicy - how the Graph should utilize the dislay area

Throws:

java.lang.IllegalArgumentException - if newDisplayPolicy is invalid.

See Also:

Graph.getDisplayPolicy()