com.sas.graphics.components.linechart
Class LineChart

com.sas.graphics.components.linechart.LineChart

All Implemented Interfaces:

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

public class LineChart

The LineChart component is a Swing component that produces line charts that support the visualization of multiple response variables. Line charts show the relationship of one variable to another, often as movements or trends in the data over a period of time. Typically, each variable value on the horizontal axis has only one corresponding value on the vertical axis.

When generating a graph, a LineChart summarizes the data from a LineChartTableDataModel.

Note. A LineChart is typically used to chart response values against discrete categorical values. For generating more scientifically-oriented graphs that plot continuous values for both an X and a Y variable, the LinePlot is better suited than the LineChart.

Note. This class can be used to render client-side graphs in Java applications or applets. The com.sas.servlet.tbeans.graphics.html.LineChart 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, GraphModel, GraphStyle, NoteModel, LineChartModel, LineChartDataModel, LineChartTableDataModel, LineChartOLAPDataModel, Serialized Form

Field Summary

static java.lang.String	RB_KEY
protected java.awt.event.MouseListener	scrollBarListener

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

footnoteContainer, titleContainer

Constructor Summary

LineChart()
Construct a LineChart applying the default GraphStyle (GraphStyle.STYLE_CONVENTION).

LineChart(LineChartDataModel lineChartDataModel)
Construct a LineChart, assigning lineChartDataModel, and using the default GraphStyle (GraphStyle.STYLE_CONVENTION).

LineChart(LineChartDataModel lineChartDataModel, GraphStyle defaultGraphStyle)
Construct a LineChart assigning lineChartDataModel 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 GraphStyle properties onto the graph.
LineChartDataModel	getDataModel() Returns the LineChartDataModel which provides a handle to the data and associated graph mapping properties.
static com.sas.beans.ExtendedBeanInfo	getExtendedBeanInfo() Returns information used by the com.sas.beans.Introspector to augment the automatically introspected information about this LineChart.
LineChartModel	getGraphModel() Returns the LineChartModel that encapsulates most of the LineChart's display properties.
ChartImageMapInfo	getImageMapInfo() The ChartImageMapInfo class encapsulates the mapping of regions associated with data elements, labels (for both axes and legends) and values (for both axes and legends) as projected onto the display area along with their associated data.
boolean	isAnimationEnabled()
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	setAnimationEnabled(boolean enabled)
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	setDataModel(LineChartDataModel newDataModel) The number and arrangement of line elements, axes and legend is determined by the LineChart's dataModel property (a LineChartDataModel) which provides a handle to the data and associated graph mapping properties.
void	setDisplayPolicy(int newDisplayPolicy) Set how the graph is to utilize the display area.
void	setGraphModel(LineChartModel newLineChartModel) Sets a LineChartModel encapsulating most of the line chart's display properties.
void	setLocale(java.util.Locale locale) Sets the locale of this component.
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

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:

Constant Field Values

scrollBarListener

protected java.awt.event.MouseListener scrollBarListener

Constructor Detail

LineChart

public LineChart()

Construct a LineChart applying the default GraphStyle (GraphStyle.STYLE_CONVENTION).

See Also:

GraphStyle

LineChart

public LineChart(LineChartDataModel lineChartDataModel)

Construct a LineChart, assigning lineChartDataModel, and using the default GraphStyle (GraphStyle.STYLE_CONVENTION). The LineChartDataModel is accessible via the getDataModel method.

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

Parameters:

lineChartDataModel - the data to be used by this graph

See Also:

GraphStyle, LineChartTableDataModel, LineChartOLAPDataModel

LineChart

public LineChart(LineChartDataModel lineChartDataModel,
                 GraphStyle defaultGraphStyle)

Construct a LineChart assigning lineChartDataModel and applying graphStyle. The LineChartDataModel is accessible via the getDataModel method. The LineChartModel (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 LineChartDataModel parameter is equivalent to setDataModel(null); If graphStyle is null then GraphStyle.STYLE_CONVENTION will be applied.

Parameters:

lineChartDataModel - provides a data handle with associated mapping properties

defaultGraphStyle - the set of graph display properties

See Also:

NoteModel, LineChartModel, LineChartTableDataModel, LineChartOLAPDataModel

Method Detail

setAnimationEnabled

public void setAnimationEnabled(boolean enabled)

isAnimationEnabled

public boolean isAnimationEnabled()

setDisplayPolicy

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

Set how the graph is to utilize the display area. The graph will always utilize all the display area supplied to it however there are occasions when the display area provided to the graph is less than optimal size to draw the graph well. Various factors can contribute to this including font selection, data assignments, number of data observations, the type of graph, wheter or not legends are displayed, etc.

On the occasion when insufficient display area is available, the graph has to decide whether to use scroll bars and only display a portion of the graph or to draw the entire graph into the available space (shrinking and adjusting portions of the graph as best it can).

To allow scroll bars use the GraphConstants.DISPLAY_SCROLL_AS_NEEDED or specify GraphConstants.DISPLAY_FIT_TO_SCREEN to force the entire graph into the available display area. Specify GraphConstants.DISPLAY_SCROLL_ENABLED shows zoom scrollbars which appear when the display area is moused over and the chart is forced to show the entire graph in the available display area, however the use can then zoom and scroll to investigate the data further.

The default value is GraphConstants.DISPLAY_AUTOMATIC. Valid values are:
GraphConstants.DISPLAY_FIT_TO_SCREEN GraphConstants.DISPLAY_SCROLL_AS_NEEDED GraphConstants.DISPLAY_SCROLL_ENABLED: GraphConstants.DISPLAY_AUTOMATIC:

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()

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
    LineChart graph = new LineChart();
 
    // 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)

getExtendedBeanInfo

public static com.sas.beans.ExtendedBeanInfo getExtendedBeanInfo()

Returns information used by the com.sas.beans.Introspector to augment the automatically introspected information about this LineChart.

Returns:

the ExtendedBeanInfo for this class

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(LineChartModel newLineChartModel)
                   throws java.lang.IllegalArgumentException

Sets a LineChartModel encapsulating most of the line chart's display properties. Modifying any graph model property triggers the graph to asynchronously update.

The graph will always have a non-null graph model. It is expected that for most situations this method will never be called but rather the graph model's properties will be modified. Note: applying a GraphStyle via the applyGraphStyle method will modify all appropriate graph model properties.

Parameters:

newLineChartModel - a LineChartModel that encapsulates the LineChart's display properties

Throws:

java.lang.IllegalArgumentException - if newLineChartModel is null.

See Also:

getGraphModel(), applyGraphStyle(com.sas.graphics.components.GraphStyle)

getGraphModel

public LineChartModel getGraphModel()

Returns the LineChartModel that encapsulates most of the LineChart's display properties.

Returns:

the LineChartModel that encapsulates most of the LineChart's display properties

See Also:

setGraphModel(com.sas.graphics.components.linechart.LineChartModel)

setDataModel

public void setDataModel(LineChartDataModel newDataModel)

The number and arrangement of line elements, axes and legend is determined by the LineChart's dataModel property (a LineChartDataModel) which provides a handle to the data and associated graph mapping properties.

Any change in the data model properties will cause the graph to asynchronously update.

Any data value changes detected will also trigger the graph to asynchronously update to reflect the new data values.

Invalid data model properties:
Invalid data model properties are ignored. For instance: using a LineChartTableDataModel, specifying a responseVariable property that designates a non-existent data column would cause an error message to be written to the error log and the responseVariable property would not be used by the graph.

Minimum data requirements:
The LineChart requires that at a minimum there is some data applicable to its category axis. For instance: using a LineChartTableDataModel would require that the categoryVariable property identify a valid data column in the TableModel.

Automatic data selection:
If the required information is not specified the graph will attempt to satify the minimum requirements through automatic selection.

A null data model will cause the graph to not draw a graph.

Parameters:

newDataModel - provides a handle to the data along with any necessary properties to describe how the data is to be mapped onto the graph.

See Also:

getDataModel(), LineChartTableDataModel, LineChartOLAPDataModel

getDataModel

public LineChartDataModel getDataModel()

Returns the LineChartDataModel which provides a handle to the data and associated graph mapping properties.

Returns:

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

See Also:

setDataModel(com.sas.graphics.components.linechart.LineChartDataModel), LineChartTableDataModel, LineChartOLAPDataModel

applyDataModel

protected void applyDataModel()

Description copied from class: Graph

Intended for internalUse only

Specified by:

applyDataModel in class Graph

applyGraphModel

protected void applyGraphModel()

For internal use only.

Overrides:

applyGraphModel in class Graph

getImageMapInfo

public ChartImageMapInfo getImageMapInfo()

The ChartImageMapInfo class encapsulates the mapping of regions associated with data elements, labels (for both axes and legends) and values (for both axes and legends) as projected onto the display area along with their associated data.

Returns:

the mapping of regions associated with line elements, labels (for both axes and legends) and values (for both axes and legends) as projected onto the display area along with their associated data.

applyColorScheme

public void applyColorScheme(ColorScheme scheme)

Apply a color scheme to this graph's display attributes.

Overrides:

applyColorScheme in class Graph

Parameters:

scheme - class containing a set of colors for the charts.

applyGraphStyle

public void applyGraphStyle(GraphStyle graphStyle)

Apply GraphStyle properties onto the graph. The use of this method is a convenient way to quickly and easily affect the graph's appearance. The graph model (a LineChartModel accessible via the getGraphModel method) properties and NoteModel properties (accessible via the getTitle and getFootnote methods) are modified by this method.

Note: The GraphStyle class was designed to be a simpler way to modify graph appearances. It enforces certain constraints that are not enforced by the graph's display attribute models (LineChartModel and NoteModels). For instance the GraphStyle contains a single value text color property whereas the LineChartModel contains several (to supports setting different value text colors on different axes and/or legend). This greater level of control may be useful in some cases but in many cases it may also prove to be quite tedious. Applying a GraphStyle will cause all appropriate properties in the display models to be updated.

The graph does not retain a link to the GraphStyle. Modifying any of the GraphStyle properties after this method has been called will have no affect on the graph. Similarly modifying any of graph's display properties after this method has been called will have no affect on the GraphStyle properties.

A PropertyChangeEvent is fired by this graph after the apply is made.

No action is taken if a null graphStyle parameteris passed.

Overrides:

applyGraphStyle in class Graph

Parameters:

graphStyle - the GraphStyle whose properties are conveyed to the graph

See Also:

NoteModel, LineChartModel

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)