Chart Builder API (beta)

oracle.ord.media.chart.axischart
Class AxisChartInteractive

java.lang.Object
  |
  +--java.awt.Component
        |
        +--oracle.ord.media.chart.Chart
              |
              +--oracle.ord.media.chart.legend.Legend
                    |
                    +--oracle.ord.media.chart.axischart.AxisChart
                          |
                          +--oracle.ord.media.chart.axischart.AxisChartInteractive
All Implemented Interfaces:
java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

public class AxisChartInteractive
extends AxisChart

AxisChartInteractive is a subclass of AxisChart that is used to implement interactive and animated axis charts. This class provides methods for determining mouse entry and exit of series elements, highlighting series elements, and displaying popup labels. This class also provides methods for creating animated charts, such as Strip charts. These methods are most useful in Java Applets and Java Applications.

The methods getSeriesElementEntered(int x, int y), getSeriesElementExited(int x, int y), and getSeriesIndexDesc(int x, int y) are provided to support interactive applications. These calls enable one to detect mouse entry and exit from series elements, such as a bar in a bar chart, and subsequently initiate actions triggered by the series element exit or entry.

getSeriesElementEntered() returns true if the passed (x,y) coordinate triggers a series element entry (such as the entry of a bar of a bar chart). Likewise, getSeriesElementExited() returns true if the passed coordinate (x,y) triggers a series element exit. getSeriesIndexDesc() is used to determine the index of the series element located at coordinate (x,y). The seriesIndex can be subsequently used to initiate chart actions, such as series highlighting or the display of annotations.

Series element highlighting may be triggered by series element events. setSeriesHighlight(String seriesName, int seriesIndex, Color c) alters the color of the series element (identified by seriesName and seriesIndex). setSeriesUnHighlight(String seriesName) restores the series element to its original color. Note that, for a given series, at most one series element may be highlighted an any time.

Displaying annotations associated with the series element may be triggered by series element events. Annotations are controlled by the methods setSeriesAnnotation(String seriesName, int seriesIndex) and setSeriesAnnotationRemove(String seriesName).

An animated chart, such as charts where coordinates are incrementally added, are supported as follows:

After the incremental loading of the series is complete -- that is, an observation has been added for each timestamp -- additional observations can still be added. In this case, the chart can either accommodate more points (increasing the number of observations), or the number of observations can remain fixed by shifting (removing the earliest observations and adding the more recent observations).

Adding additional observations to a "full" chart can be accomplished by invoking setXSeriesAppend(java.util.Date[]) and setYSeriesAppend(String, double[]).

Shifting in new observations to a "full" chart can be accomplished by invoking setXSeriesShift(java.util.Date[]) and setYSeriesAppend(String, double[]).

For applications that require wholesale replacement of a series or sets of series, the methods setDeleteYSeries(String, seriesName) (deletes a named series), setDeleteAllYSeries() (deletes all y series), and setDeleteAllXYSeries() (deletes all x and y series) are provided.

See Also:
Serialized Form

Inner classes inherited from class oracle.ord.media.chart.legend.Legend
Legend.LegendElement
 
Inner classes inherited from class oracle.ord.media.chart.Chart
Chart.ChartLabel
 
Fields inherited from class oracle.ord.media.chart.axischart.AxisChart
AREA, BAR, BAR_HORIZONTAL, BAR_STACKED, CANDLESTICK, HILOCLOSE, HORIZONTAL, LINE, OPENHILOCLOSE, VERTICAL, XAXIS, XYAXIS, YAXIS
 
Fields inherited from class oracle.ord.media.chart.legend.Legend
DERIVED, EAST, NORTH, NORTHEAST, NORTHWEST, SOUTH, SOUTHEAST, SOUTHWEST, USERDEFINED, WEST
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
AxisChartInteractive()
           
 
Method Summary
 void eraseChart()
          Erase the chart.
 boolean getSeriesElementEntered(int x, int y)
          Return true if the cursor has entered a series element.
 boolean getSeriesElementExited(int x, int y)
          Return true if the cursor has exited a series element.
 int getSeriesIndex(int x, int y)
          Return the index of the y coordinate at screen location (x,y).
 SeriesDesc getSeriesIndexDesc(int x, int y)
          Return a descriptor containing the series name and index of the y coordinate at screen location (x,y).
 void setCandlestickSeries(java.lang.String seriesName)
          Define a Candlestick series that initially has no values.
 void setCandlestickSeriesAppend(java.lang.String seriesName, double[] yopen, double[] yhigh, double[] ylow, double[] yclose)
          Append Y-axis values for a Candlestick chart.
 void setDeleteAllXYSeries()
          Delete all X-axis and Y-axis series, and all subcharts.
 void setDeleteAllYSeries()
          Delete all Y-axis series.
 void setDeleteYSeries(java.lang.String seriesName)
          Delete the named series.
 void setHiLoCloseSeries(java.lang.String seriesName)
          Define a HiLoClose series that initially has no values.
 void setHiLoCloseSeriesAppend(java.lang.String seriesName, double[] yhigh, double[] ylow, double[] yclose)
          Append Y-axis values for a High/Low/Close chart.
 void setOpenHiLoCloseSeries(java.lang.String seriesName)
          Define an OpenHiLoClose series that initially has no values.
 void setOpenHiLoCloseSeriesAppend(java.lang.String seriesName, double[] yopen, double[] yhigh, double[] ylow, double[] yclose)
          Append Y-axis values for a Open/High/Low/Close chart.
 void setSeriesAnnotation(java.lang.String seriesName, int seriesIndex)
          Display an annotation for the specified element of the named series.
 void setSeriesAnnotationRemove()
          Remove the annotation from the series element of any and all series.
 void setSeriesAnnotationRemove(java.lang.String seriesName)
          Remove the annotation from the series element of the named series.
 void setSeriesHighlight(java.lang.String seriesName, int seriesIndex, java.awt.Color c)
          Highlight one element of the named series.
 void setSeriesUnHighlight()
          Remove the highlighting of the series element of any and all series.
 void setSeriesUnHighlight(java.lang.String seriesName)
          Remove the highlighting of the series element of the named series.
 void setXSeriesAppend(java.util.Date[] tstamps)
          Extend the time axis by appending additional Dates.
 void setXSeriesReserve(int numTimestamps)
          Reserve space for the chart's X-axis.
 void setXSeriesReserveLabels(int numLabels)
           
 void setXSeriesShift(java.util.Date[] tstamps)
          Shift the X-axis by appending additional Dates to the tail, deleting Dates from the head.
 void setYSeries(java.lang.String seriesName)
          Define a series that initially has no values.
 void setYSeriesAppend(java.lang.String seriesName, double[] yvalues)
          Append an array of Y-axis values to an existing series.
 void setYSeriesSparseAppend(java.lang.String seriesName, java.util.Date[] tstamps, double[] yvalues)
          Append a sparse array of Y-axis values to an existing sparse series.
 
Methods inherited from class oracle.ord.media.chart.axischart.AxisChart
drawBuffer, getAnnotationDesc, getForeground, getGridDesc, getGridDesc, getImageMapCS, getImageMapSS, getPlotBackground, getPlotEdgeColor, getRenderingHintsLine, getSeriesColor, getSubChartBoundaryColor, paint, setBounds, setBounds, setCandlestickSeries, setCandlestickSeries, setChartAttributes, setChartAttributes, setChartAttributes, setChartAttributes, setChartAttributes, setChartAttributes, setChartBottomWhiteSpace, setChartOrientation, setChartTopWhiteSpace, setEnableImageMapCS, setEnableImageMapSS, setEnableSubChartImageMapCS, setEnableSubChartImageMapSS, setForeground, setHiLoCloseSeries, setHiLoCloseSeries, setOpenHiLoCloseSeries, setOpenHiLoCloseSeries, setPlotBackground, setPlotEdgeColor, setRenderingHintsLine, setSeriesAnnotations, setSeriesColor, setSeriesDwellLabels, setSeriesDwellLabels, setSeriesGraphic, setSeriesGraphic, setSeriesGraphic, setSeriesGraphic, setSeriesGraphic, setSeriesGraphType, setSeriesWidth, setSize, setSize, setSubChart, setSubChartBoundaryColor, setSubChartHeightFraction, setSubChartSeparatorHeight, setUserXLabel, setXSeries, setXSeries, setXSeries, setXSeries, setXSeries, setYAxisLabelsOff, setYAxisLabelsOff, setYSeries, setYSeries, setYSeries, setYSeries, setYSeriesAxis2, setYSeriesSparse
 
Methods inherited from class oracle.ord.media.chart.legend.Legend
getLegendAlignment, getLegendBackground, getLegendDisable, getLegendDisplaySingleSeries, getLegendEdgeColor, getLegendEdgeDisable, getLegendForeground, getLegendInside, setLegendAlignment, setLegendBackground, setLegendDisable, setLegendDisplaySingleSeries, setLegendEdgeColor, setLegendEdgeDisable, setLegendFont, setLegendForeground, setLegendInside, setLegendOffsetX, setLegendOffsetY
 
Methods inherited from class oracle.ord.media.chart.Chart
getBackground, getBorderBottom, getBorderLeft, getBorderRight, getBorderTop, getEdgeColor, getFootnote, getHeight, getMinimumSize, getPreferredSize, getRenderingHintsChart, getSize, getSubtitle, getTitle, getVersion, getWidth, isSetRenderingHintsChart, setBackground, setBorderBottom, setBorderLeft, setBorderRight, setBorderTop, setEdgeColor, setRenderingHintsChart, setTitlesForeground
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, contains, contains, createImage, createImage, deliverEvent, disable, dispatchEvent, doLayout, enable, enable, enableInputMethods, getAccessibleContext, getAlignmentX, getAlignmentY, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getGraphics, getGraphicsConfiguration, getInputContext, getInputMethodRequests, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFont, setLocale, setLocation, setLocation, setName, setVisible, show, show, size, toString, transferFocus, update, validate
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

AxisChartInteractive

public AxisChartInteractive()
Method Detail

setXSeriesReserve

public void setXSeriesReserve(int numTimestamps)
                       throws ChartException
Reserve space for the chart's X-axis. setXSeriesReserve() is typically used to reserve the specified number of timestamps for the initial strip chart. For example, setXSeriesReserve(30) would be invoked to define an empty chart capable of displaying 30 timestamps. Subsequently, the calls to setXSeriesAppend() and setYSeriesAppend() can be invoked to incrementally add dates and points to the chart.
Parameters:
numTimestamps - Number of timestamps for which to reserve space.
See Also:
setXSeriesAppend(java.util.Date[]), setYSeriesAppend(String, double[])

setXSeriesReserveLabels

public void setXSeriesReserveLabels(int numLabels)
                             throws ChartException

setXSeriesAppend

public void setXSeriesAppend(java.util.Date[] tstamps)
                      throws ChartException
Extend the time axis by appending additional Dates.

setXSeriesShift

public void setXSeriesShift(java.util.Date[] tstamps)
                     throws ChartException
Shift the X-axis by appending additional Dates to the tail, deleting Dates from the head.
Parameters:
tstamps[] - Array of java.util.Date to be appended to the end of the time axis.

setYSeries

public void setYSeries(java.lang.String seriesName)
                throws ChartException
Define a series that initially has no values. Used in conjunction with dynamically updated charts.
Parameters:
seriesName - Name of series.

setHiLoCloseSeries

public void setHiLoCloseSeries(java.lang.String seriesName)
                        throws ChartException
Define a HiLoClose series that initially has no values. Used in conjunction with dynamically updated charts.
Parameters:
seriesName - Name of series.

setOpenHiLoCloseSeries

public void setOpenHiLoCloseSeries(java.lang.String seriesName)
                            throws ChartException
Define an OpenHiLoClose series that initially has no values. Used in conjunction with dynamically updated charts.
Parameters:
seriesName - Name of series.

setCandlestickSeries

public void setCandlestickSeries(java.lang.String seriesName)
                          throws ChartException
Define a Candlestick series that initially has no values. Used in conjunction with dynamically updated charts.
Parameters:
seriesName - Name of series.

setYSeriesAppend

public void setYSeriesAppend(java.lang.String seriesName,
                             double[] yvalues)
                      throws ChartException
Append an array of Y-axis values to an existing series. The named series must be previously defined in order to append additional Y-axis values.

Note that the number of timestamps remains fixed. To extend a time series and its associated timestamps, first delete all series with setDeleteAllXYSeries(), then reload the X and Y-axis series with setXSeries() and setYSeries().

Parameters:
seriesName - Name of series.
yvalues[] - Double array of Y-axis values
See Also:
setDeleteAllXYSeries()

setCandlestickSeriesAppend

public void setCandlestickSeriesAppend(java.lang.String seriesName,
                                       double[] yopen,
                                       double[] yhigh,
                                       double[] ylow,
                                       double[] yclose)
                                throws ChartException
Append Y-axis values for a Candlestick chart.
Parameters:
seriesName - Name of the series.
yopen[] - Array of values corresponding to the open observation.
yhigh[] - Array of values corresponding to the high observation.
ylow[] - Array of values corresponding to the low observation.
yclose[] - Array of values corresponding to the close observation.

setOpenHiLoCloseSeriesAppend

public void setOpenHiLoCloseSeriesAppend(java.lang.String seriesName,
                                         double[] yopen,
                                         double[] yhigh,
                                         double[] ylow,
                                         double[] yclose)
                                  throws ChartException
Append Y-axis values for a Open/High/Low/Close chart.
Parameters:
seriesName - Name of the series.
yopen[] - Array of values corresponding to the open observation.
yhigh[] - Array of values corresponding to the high observation.
ylow[] - Array of values corresponding to the low observation.
yclose[] - Array of values corresponding to the close observation.

setHiLoCloseSeriesAppend

public void setHiLoCloseSeriesAppend(java.lang.String seriesName,
                                     double[] yhigh,
                                     double[] ylow,
                                     double[] yclose)
                              throws ChartException
Append Y-axis values for a High/Low/Close chart.
Parameters:
seriesName - Name of the series.
yhigh[] - Array of values corresponding to the high observation.
ylow[] - Array of values corresponding to the low observation.
yclose[] - Array of values corresponding to the close observation.

setDeleteYSeries

public void setDeleteYSeries(java.lang.String seriesName)
                      throws ChartException
Delete the named series. This call is typically used in Applets in order to remove a series from the chart.
Parameters:
seriesName - Name of the series.
See Also:
setDeleteAllXYSeries(), setYSeriesAppend(String, double[]), setYSeriesSparseAppend(String, java.util.Date[], double[])

setDeleteAllYSeries

public void setDeleteAllYSeries()
Delete all Y-axis series.

setDeleteAllXYSeries

public void setDeleteAllXYSeries()
Delete all X-axis and Y-axis series, and all subcharts. All X-axis and Y-axis series and all subcharts are removed from the chart. After setDeleteAllXYSeries() has been called, setXSeries() and setYSeries() must be called prior to invoking paint(). In addition, any subcharts defined (with setSubchart()) should be recreated. This routine is typically used in Applets or Java Applications to support the dynamic update of chart data. For example, when new timestamps/data become available, one may delete all X-axis and Y-axis series from the existing chart, then reload the updated timestamps and series. Note that methods to append data to a series are also available. (See setYSeriesAppend() and setYSeriesAppendSparse()). These append methods are intended to be used in cases where Y-axis values are appended but the number of timestamps remains fixed.
See Also:
setDeleteYSeries(String), setYSeriesAppend(String, double[]), setYSeriesSparseAppend(String, java.util.Date[], double[])

setYSeriesSparseAppend

public void setYSeriesSparseAppend(java.lang.String seriesName,
                                   java.util.Date[] tstamps,
                                   double[] yvalues)
                            throws ChartException
Append a sparse array of Y-axis values to an existing sparse series.
Parameters:
seriesName - Name of series.
tstamps[] - Array of java.util.Date.
yvalues[] - Double array of Y-axis values.
See Also:
AxisChart.setYSeriesSparse(java.lang.String, java.util.Date[], double[])

eraseChart

public void eraseChart()
Erase the chart.

getSeriesElementEntered

public boolean getSeriesElementEntered(int x,
                                       int y)
Return true if the cursor has entered a series element. This method is typically used in the context of MouseMoved events in order to determine if the mouse has entered a series element, such as a bar of a bar chart. (Note that this call is provided because series elements are not represented as individual Components.)
Parameters:
x - The screen x coordinate.
y - The screen y coordinate.
Returns:
True if the cursor has entered a new series element.
See Also:
getSeriesElementExited(int, int)

getSeriesElementExited

public boolean getSeriesElementExited(int x,
                                      int y)
Return true if the cursor has exited a series element. This method is typically used in the context of MouseMoved events in order to determine if the mouse has exited a series element, such as a bar of a bar chart. (Note that this call is provided because series elements are not represented as individual Components.)
Parameters:
x - The screen x coordinate.
y - The screen y coordinate.
Returns:
True if the cursor has exited a new series element.
See Also:
getSeriesElementEntered(int, int)

getSeriesIndex

public int getSeriesIndex(int x,
                          int y)
Return the index of the y coordinate at screen location (x,y). If coordinate (x,y) is contained in the series, the index of the series is returned. Otherwise, -1 is returned.

getSeriesIndex is similar to getSeriesIndexDesc. Use getSeriesIndex for charts with a single series, and getSeriesIndexDesc when it is necessary to determine which of a number of series was selected.

Parameters:
x - The screen x coordinate.
y - The screen y coordinate.
Returns:
The index of the series
See Also:
getSeriesIndexDesc(int, int)

getSeriesIndexDesc

public SeriesDesc getSeriesIndexDesc(int x,
                                     int y)
Return a descriptor containing the series name and index of the y coordinate at screen location (x,y). If coordinate (x,y) is contained in any series, the series name and series index are returned in the SeriesDesc object. Otherwise, the returned series index is -1.

This call is typically used in the context of mouse events in order to determine which series element has been selected.

Parameters:
x - The screen x coordinate.
y - The screen y coordinate.
Returns:
SeriesDesc
See Also:
getSeriesIndex(int, int)

setSeriesUnHighlight

public void setSeriesUnHighlight()
                          throws ChartException
Remove the highlighting of the series element of any and all series.
See Also:
setSeriesHighlight(String, int, Color), setSeriesUnHighlight(String)

setSeriesHighlight

public void setSeriesHighlight(java.lang.String seriesName,
                               int seriesIndex,
                               java.awt.Color c)
                        throws ChartException
Highlight one element of the named series.
Parameters:
seriesName - Name of series.
seriesIndex - Index identifying the series element.
c - Color to set series element.
Returns:
The index of the series name. -1 is returned if the series name is undefined.
Throws:
ChartException - for an invalid series element index.
See Also:
setSeriesUnHighlight(String)

setSeriesUnHighlight

public void setSeriesUnHighlight(java.lang.String seriesName)
                          throws ChartException
Remove the highlighting of the series element of the named series.
Parameters:
seriesName - Name of series.
See Also:
setSeriesHighlight(String, int, Color)

setSeriesAnnotation

public void setSeriesAnnotation(java.lang.String seriesName,
                                int seriesIndex)
                         throws ChartException
Display an annotation for the specified element of the named series. The annotation, the value of the y coordinate, will be displayed within a rectangular window attached to the series element. This call is normally used to implement popup text, triggered by mouse clicks or mouse overs. The font, background color, and foreground color of the annotation can be altered by using getAnnotationDesc().
Parameters:
seriesName - Name of series.
seriesIndex - Index identifying the series element.
Returns:
The index of the series name. -1 is returned if the series name is undefined.
Throws:
ChartException - for an invalid series element index.
See Also:
setSeriesAnnotationRemove(String), AxisChart.getAnnotationDesc(), AnnotationDesc

setSeriesAnnotationRemove

public void setSeriesAnnotationRemove(java.lang.String seriesName)
                               throws ChartException
Remove the annotation from the series element of the named series.
Parameters:
seriesName - Name of series.
See Also:
setSeriesAnnotation(String, int)

setSeriesAnnotationRemove

public void setSeriesAnnotationRemove()
                               throws ChartException
Remove the annotation from the series element of any and all series.
See Also:
setSeriesAnnotation(String, int)

Chart Builder API (beta)