This chapter describes the functions that are defined in the Perspective abstract interface. If you use any of these interfaces, your application must implement these functions in the format described in this chapter.
The NumberFormatCallBack class defines the following static variables and methods:
- void init (Perspective a PerspectiveInstance); Initialize a perspective instance.
- void setState (int LabelType, int Series, int Group, tdg.AxisTemplate Axis_ID, int Axis_Ord); Reserved for internal use.
- String toString (double dVal); Convert a double value to a string. This function must be implemented by your application.
The NumberFormatCallback class represents an abstract interface to an object that formats the numbers in a Perspective for Java chart. To use this class, do the following:
- subclass NumberFormatCallback
- override the toString() method to format the numbers as required by your application.
- call setNumberFormatCallBack() to register the "number format callback" object
You may also use:
- getNumberFormatCallBack() to determine if a NumberFormatCallBack has been assigned with setNumberFormatCallBack()
- isNumberFormatCallBack() to determine if an object is a number format callback
The following methods can be used to view information that is set by the reserved setState() method:
This method is used to initialize a Perspective instance for the NumberFormatCallback interface.
SYNTAX:
INPUT:
aPerspectiveInstance; a Perspective Instance
RETURN:
void;
EXAMPLE:
public void init (Perspective aPerspectiveInstance) { m_Perspective = aPerspectiveInstance; }
ALSO SEE:
toString(), getNumberFormatCallBack(), isNumberFormatCallBack(), setNumberFormatCallBack()
This function converts the double value identified by dVal to a string using a user-defined criteria. This function must be created by your NumberFormatCallback interface to format numeric labels as required by your application.
SYNTAX:
INPUT:
dVal; a double value
RETURN:
String; string equivalent of dVal
ALSO SEE:
getNumberFormatCallBack(), isNumberFormatCallBack(), setNumberFormatCallBack()
The following example program shows a simple implementation of the NumberFormatCallback interface:
import tdg.NumberFormatCallBack; /* The PfjNumberFormatCallback class. * Class PfjNumberFormatCallback extends the * Perspective NumberFormatCallBack class */ public class PfjNumberFormatCallback extends NumberFormatCallBack { // PfjNumberFormatCallback PUBLIC MEMBER FUNCTIONS public String toString (double dVal) { String labelType; String resultValue; String axisValue; String dataValue; switch (getLabelType()) { // switch on labelType case AXIS_LABEL: labelType = "Axis"; break; case PIE_LABEL: labelType = "Slice"; break; case PIE_TOTAL: labelType = "PieT"; break; case DATA_LABEL: labelType = "Data"; break; case TOOLTIP_VALUE: labelType = "ToolTip"; break; default: labelType = "BadLabelType"; System.out.println (
"Undefined LabelType = " + getLabelType() + "Value = " + dVal ); break; } // switch on labelType if (isAxisLabel()) { if (isY1AxisLabel()) axisValue = "Y1" + ";" + getAxisLabelOrdinalPosition(); else if (isY2AxisLabel()) axisValue = "Y2" + ";" + getAxisLabelOrdinalPosition(); else if (isX1AxisLabel()) axisValue = "X1" + ";" + getAxisLabelOrdinalPosition(); else axisValue = "BadAxis"; } else axisValue = "NA"; if (dVal > 1 || dVal == 0) dataValue = new Double (dVal).toString(); else { dataValue=new Integer ((int) (dVal * 100 + .5)).toString() + "%"; resultValue=labelType + ";" + getSeries() +";" + getGroup() + ";" + axisValue + ":" + dataValue; return resultValue; } } } // PfjNumberFormatCallback
This interface defines a group of methods that can be used to get and set data in a chart when the setDataFromCallBack() method is used to slave chart data to an arbitrary Java Object.
These methods are identical to the methods defined in the TDGDataGrid interface.
TDGDataGrid is an abstract interface. It defines a series of methods that you must implement into an object. The TDGDataGrid interface represents an abstract data model that is one way of preparing data for graphing. Use these methods to enable this interface.
- setDataFromCallBack (TDGDataGrid grid); Enable the chart data to be slaved to an arbitrary Java Object which implements the TDGDataGrid Interface
- setDataFromDataGrid (TDGDataGrid grid); Tell the charting engine to use the TDGDataGrid object to collect data for the chart.
You may also use getDataGridCallback() to get the TDGDataGrid interface defined by setDataFromDataGrid()
The TDGDataGrid interface defines the following methods that must be implemented by your application if you choose to use this interface:
NOTE: TDGPreScaleIF is an optional callback interface that users with large datasets may implement in their existing data callbacks (TDGDataGrid) to expedite processing of data. See the TDGPreScaleIF interface below for details.
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object.This method is used to establish column labels/headings for the column specified by the input parameter c. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
c; a column number
RETURN:
String; Column label at column c.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object. This method is used to get the number of columns in the chart. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
int; The number of columns in the chart.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object.This function is used to establish the chart footnote. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; The chart footnote string.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object. This function is used to establish the chart O1-axis title. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; O1-Axis title string.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object. This function is used to establish the chart O2-axis title. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; O2-Axis title string.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e.g, setDataFromDataGrid(), this method must be implemented by your application in an object. This method is used to get the number of rows in the chart. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
int; The number of rows in the chart.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object. This function is used to establish the chart subtitle. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; Chart subtitle string.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object. This function is used to establish the chart title. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; Chart title string.
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e., setDataFromDataGrid()), this method must be implemented by your application in an object. This function gets the contents of the specified cell (at row (r), column (c)). Note that any type of Object can be returned. Perspective will interpret the Object type as a String or Double. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
r; row number
INPUT:
c; column number
RETURN:
Object; Chart Data at row (r), column (c)
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e.g, setDataFromDataGrid(), this method must be implemented by your application in an object. This function is used to establish the chart X1-axis title. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; The X1-Axis Title String
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e.g, setDataFromDataGrid(), this method must be implemented by your application in an object. This function is used to establish the chart Y1-axis title. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; The Y1-Axis Title String
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e.g, setDataFromDataGrid(), this method must be implemented by your application in an object. This function is used to establish the chart Y2-axis title. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
String; The Y2-Axis Title String
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e.g, setDataFromDataGrid(), this method must be implemented by your application in an object. This function is used to determine if data in the chart has changed: TRUE = data has changed, FALSE = data has not changed. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
None
RETURN:
boolean; true = Chart data has changed, false = Chart data has not changed
ALSO SEE:
setDataFromDataGrid()
This is a required method for the TDGDataGrid object. If you use TDGDataGrid (i.e.g, setDataFromDataGrid(), this method must be implemented by your application in an object. This method is used to establish row labels/headings for the row specified by the input parameter r. The syntax shows the format in which this method must be implemented by your application.
SYNTAX:
INPUT:
r; a row number
RETURN:
String; Row label at row r.
ALSO SEE:
setDataFromDataGrid()
This interface defines a method to get the title string from a Pie-Bar chart.
This method establishes the chart title in a Pie-Bar chart.
SYNTAX:
INPUT:
None
RETURN:
String; chart title
The addPerspectiveListener() method creates an instance of an abstract class or interface to catch high-level events defined by the Perspective for Java integration. This method also tells the charting engine to notify the perspectiveEvent() method defined in the TDGListener interface when a Perspective event occurs.
The perspectiveEvent() method will be called with an event object when an Perspective event occurs. The perspectiveEvent() must be included and defined in the object identified by addPerspectiveListener(). The definition of the perspectiveEvent() method should indicate handling of events that are reported by the charting engine.
SYNTAX:
INPUT:
e: A location to store the event. On return, it will be set to the perspective event. Event codes and methods for getting event information are defined in the TDGEvent class.
RETURN:
void;
EXAMPLE:
See FullMetalListener() in Appendix C
ALSO SEE:
addPerspectiveListener()
This class defines the following static variables and methods that can be used by a Perspective listener interface to get information. The following event codes are defined in this class:
The following public methods are defined in the TDGEvent class:
CONSTRUCTOR:
/** * Constructs a TDGEvent object with the specified source * Perspective and type. * @param source the Perspective where the event originated * @param id the event type */ public TDGEvent (Object source, int id, Object dataObject) { super (source); m_id = id; m_dataObject = dataObject; }
This method returns the source where this event originated.
SYNTAX:
INPUT:
None
RETURN:
Object: source where this event originated
This method returns the ID associated with this event.
SYNTAX:
INPUT:
None
RETURN:
int; ID associated with this event.
This method returns the dataObject associated with this event.
SYNTAX:
INPUT:
None
RETURN:
Object: dataObject associated with this event
This method returns a description string associated with this event.
SYNTAX:
INPUT:
None
RETURN:
String; description string associated with this event.
The TDGNestedLabel Interface defines the following methods:
- java.util.Vector getAllLabels (int nLevel);
- java.lang.String getLabel (int nGroup, int nLevel);
- int getLabelGrouping (int nGroup, int nLevel);
- int getNumLabelsOnLevel (int nLevel);
- int getNumLevels();
Perspective supports nested/multi-dimensional labels on the O1 axis with these properties and methods:
- setO1LabelCallback(): This method assigns a callback function to the nested labels interface.
- getO1LabelCallback(): This method determines if a callback function has been assigned with setO1LabelCallback().
- NestedLabels (true/false): This property enables/disables nested labels.
Use the following procedures to implement the nested labels interface:
- You must create your own version of the nested labels callback. It must implement all of the abstract methods defined in the TDGNestedLabel interface.
- Register the callback with the setO1LabelCallback() method. Example:
m_chart.setO1LabelCallback (TDGNestedLabel cb);
- Enable the NestedLabel property. Example:
m_chart.setNestedLabels (true);Perspective includes a simple example of nested labels in the TDGTestNestedGroupsLabels class. The example class can be enabled by setting the NestedLabels properrty to true.
This method gets all the labels at the specified level (for batch autofitting).
SYNTAX:
INPUT:
nLevel; Level to get the labels from.
RETURN:
Vector; Vector of String objects.
This method gets the string specified by the group and level. If nLevel is zero, the group label is returned. If nLevel is 1, its immediate parent in the hierarchy, etc. is returned.
SYNTAX:
INPUT:
nGroup; a group number.
nLevel; a multi-dimensional label level
RETURN:
String; the label at nGroup, nLevel
This method gets the number of labels grouped at the level specified by the group and level.
SYNTAX:
INPUT:
nGroup; a group number.
nLevel; a multi-dimensional label level
RETURN:
int; Number of labels grouped at nGroup, nLevel
This method returns an integer value that identifies how many labels there are on a given level.
SYNTAX:
INPUT:
nLevel; a multi-dimensional label level
RETURN:
int; Number of labels on nLevel
This method returns an integer value that defines the number levels of nested-labels.
SYNTAX:
INPUT:
None
RETURN:
int; Number of nested label levels.
package tdg; import java.util.Vector; public class TDGTestNestedGroupLabels3 implements TDGNestedLabel { protected Perspectivem_Perspective; protected String[][]m_Labels = { { "Q1", "Q2","Q3", "Q4", "Q5", "Q6", "Q7","Q8" }, { "1997", "1998"}, { "Total" } }; /** Constructor. **/ public TDGTestNestedGroupLabels3 (Perspective perspective) { m_Perspective = perspective; } /* How many nested levels of labels are there? */ public int getNumLevels() { return m_Labels.length; } /* How many labels are there on this level? */ public int getNumLabelsOnLevel (int nLevel) { int nLabels; switch (nLevel) { case 0: nLabels = 8; break; case 1: nLabels = 2; break; case 2: default: nLabels = 1; break; } return nLabels; } /** * Get all the labels at the specified level (for batch * autofitting). Returns a Vector of String objects. **/ public Vector getAllLabels (int nLevel) { Assert.assert3D ((nLevel >= 0) && (nLevel < m_Labels.length)); intnLabels = getNumLabelsOnLevel (nLevel); VectorvLabels = new Vector (nLabels); StringsLabel; for (int i = 0; i<nLabels; i++) { sLabel = getLabel (i, nLevel); if (sLabel != null)vLabels.addElement (sLabel); } return vLabels; } /** * Get the string specified by the group and level; * if nLevel is 0, the group label, if nLevel is 1, its * immediate parent in the hierarchy, etc. **/ public String getLabel (int nGroup, int nLevel) { String sLabel = m_Labels[nLevel][nGroup]; return sLabel; } /** * Get the number of labels grouped at this level * specified by the group and level. **/ public int getLabelGrouping (int nGroup, int nLevel) { int nGrouping; switch (nLevel) { case 0: nGrouping = 4; break; case 1: nGrouping = 2; break; case 2: default: nGrouping = 1; break; } return nGrouping; }
TDGPreScaleIF is an optional callback interface that users with large datasets may implement in their existing data callbacks (TDGDataGrid) to expedite processing of data. There are 2 methods in the interface:
- public double getScaleMinimum (int nAxis, int scaling) throws Exception
- public double getScaleMaximum (int nAxis, int scaling) throws Exception
Based on the axis and scaling parameters, you may decide at runtime NOT to handle this call and choose to throw an Exception. If the call to the callback method results in an exception, Perspective for Java will catch the exception and do the scaling.
SYNTAX:
INPUT:
nAxis; an integer that identifies an axis
scaling; an integer that identifies the type of scaling
RETURN:
double; maximum value to calculate scaling
EXAMPLE:
public double getScaleMaximum (int nAxis, int nScaling) throws Exception { // Stacked,Percent,Histogram scaling too complex, let PFJ do it! if (nScaling == TDGPreScaleIF.SCALING_ABSOLUTE) return max; else throw new Exception ("Sorry, I don't understand this scaling: " + nScaling); }
ALSO SEE:
getScaleMinimum()
Based on the axis and scaling parameters, you may decide at runtime NOT to handle this call and choose to throw an Exception. If the call to the callback method results in an exception, Perspective for Java will catch the exception and do the scaling.
SYNTAX:
INPUT:
nAxis; an integer that identifies an axis
scaling; an integer that identifies the type of scaling
RETURN:
double; minimum value to calculate scaling
EXAMPLE:
public double getScaleMinimum (int nAxis, int nScaling)throws Exception { // Stacked,Percent,Histogram scaling too complex, // let PFJ do it! if (nScaling == TDGPreScaleIF.SCALING_ABSOLUTE) return min; else throw new Exception ("Sorry, I don't understand this scaling: " + nScaling); }
ALSO SEE:
getScaleMaximum()
The following code shows an example implementation of this interface.
EXAMPLE:
package tdg; import tdg.data.in.TDGDataGrid; import tdg.data.in.TDGPreScaleIF; import java.util.Random; public class LargeDefaultData implements TDGDataGrid, TDGPreScaleIF { static final int SMALL_DATASET = 10; static final int LARGE_DATASET = 1000; boolean isDirtyFlag = false; double[][] testdata = new double[LARGE_DATASET] [SMALL_DATASET]; Object data[][]; String[] rowLabels = new String[LARGE_DATASET]; String[] colLabels = {"1", "2", "3", "4", "5", "6","7","8", "9", "10"}; int numCols = SMALL_DATASET; int numRows = LARGE_DATASET; double value; double min = Double.MAX_VALUE; double max = -Double.MAX_VALUE; Random randNum = new Random (1000); public LargeDefaultData() { // Row Labels. for (int i=0;i<numRows;i++)rowLabels[i]="" + (i+1); // Load Data. data = new Object[numRows][numCols]; for (int row = 0; row < numRows; row++) { for (int col = 0; col < numCols; col++) { value = randNum.nextDouble() * 100; data[row][col] = new Double (value); // For dataformats with more than one // numeric axis, e.g. scatter, we // need to check which axis "value" // was associated with. if (value < min)min = value; if (value > max)max = value; } } } public String getTitle() { return "Performance Test Title"; } public String getSubtitle() { return ""; } public String getFootnote() { return ""; } public String getX1AxisTitle() { return ""; } public String getY1AxisTitle() { return ""; } public String getO1AxisTitle() { return ""; } public String getO2AxisTitle() { return ""; } public String getY2AxisTitle() { return ""; } public String columnLabel (int x){return colLabels[x];} public int getColumns() { return numCols; } public String rowLabel (int x) {return rowLabels[x];} public int getRows() { return numRows; } public Object getValue (int row, int col) { return data[row][col]; } public boolean isDirty() { return isDirtyFlag; } // Needed for TDGPreScaleIF interface to speed PFJ scale calculations public double getScaleMinimum (int nAxis,int nScaling)throws Exception { // Stacked,Percent,Histogram scaling too complex, let PFJ do it! if (nScaling == TDGPreScaleIF.SCALING_ABSOLUTE) return min; else throw new Exception ("Sorry, I don't understand this scaling: " + nScaling); } public double getScaleMaximum (int nAxis,int nScaling)throws Exception { // Stacked,Percent,Histogram scaling too, complex let PFJ do it! if (nScaling == TDGPreScaleIF.SCALING_ABSOLUTE) return max; else throw new Exception ("Sorry, I don't understand this scaling: " + nScaling); } }
This interface defines a dynamic callback function to produce a tooltip:
This function is a dynamic callback to produce a tooltip. When this method is called, your application should provide a very fast method that returns the proper string for the object in question.
SYNTAX:
INPUT:
aMouseState; an object of class TDGMouseState which provides all the information about the object for which the tooltip is being generated.
UserOrDeveloper; true = Developer information, false = User information
RETURN:
String; tooltip result string.
NOTES:
getDynamicToolTip() is defined in the ToolTipCallBack interface.
EXAMPLE:
public class TestToolTipCallBack implements ToolTipCallBack { public String getDynamicToolTip ( TDGMouseState aMouseState, boolean UserOrDeveloper ) { String strReturn; // MACROS that are expanded in a CUSTOM Tool Tip // Examples: // [ON] is ([OID])[R]Instance # [OIN][R] /* // MACROS for formatting static final String RETURN_MACRO = "[R]";// A CR // MACROS for OBJECTS and OBJECT IDS static final String OBJECT_NAME_MACRO = "[ON]"; static final String OBJECT_DESCRIPTION_MACRO = "[OD]"; static final String OBJECT_ID_MACRO = "[OID]"; static final String OBJECT_INSTANCE_MACRO = "[OIN]"; static final String SERIES_LABEL_MACRO = "[SL]"; static final String GROUP_LABEL_MACRO = "[GL]"; // MACROS for VALUES static final String CUMULATIVE_STACKED_VALUE_MACRO = "[CUMSTKV]"; static final String CUMULATIVE_PERCENTAGE_VALUE_MACRO = "[CUMPCTV]"; static final String PIE_PERCENTAGE_VALUE_MACRO = "[PIEPCTV]"; static final String HILO_HIGH_VALUE_MACRO = "[HV]"; static final String HILO_LOW_VALUE_MACRO = "[LV]"; static final String HILO_OPEN_VALUE_MACRO = "[OV]"; static final String HILO_CLOSE_VALUE_MACRO = "[CV]"; static final String HILO_VOLUME_VALUE_MACRO = "[VV]"; static final String X_VALUE_MACRO = "[XV]"; static final String Y_VALUE_MACRO = "[YV]"; static final String Z_VALUE_MACRO = "[ZV]"; */ strReturn = "Element ID is (" + aMouseState.getElementObjectID() + ")[R]"; strReturn += "Series = [SL][R]"; strReturn += "Group = [GL][R]"; strReturn += "Cumulative Stacked = [CUMSTKV][R]"; strReturn += "Cumulative Percentage = [CUMPCTV][R]"; strReturn += "Pie Percentage = [PIEPCTV][R]"; strReturn += "High = [HV][R]"; strReturn += "Low = [LV][R]"; strReturn += "Open = [OV][R]"; strReturn += "Close = [CV][R]"; strReturn += "Volume = [VV][R]"; strReturn += "X Value = [XV][R]"; strReturn += "Y Value = [YV][R]"; strReturn += "Z Value = [ZV][R]"; return strReturn; } }
ALSO SEE:
setDynamicToolTip()
TDGError is the root error event class for all perspective-level error events. An error listener defined by addErrorListener() may obtain error codes using the methods defined in this class. The following error codes are defined in TDGError:
The following methods are defined in TDGError.
This method creates a TDGError object with the specified source Perspective and type.
SYNTAX:
INPUT:
source; the Perspective where the error originated
id; error ID
Explanation; error text string
errorObject; error object
This method is defined in the TDGError class. It returns the source where this error originated.
SYNTAX:
INPUT:
None
RETURN:
Object: the source where this error originated.
This method is defined in the TDGError class. It returns an ID associated this error.
SYNTAX:
INPUT:
None
RETURN:
int; error ID
This method is defined in the TDGError class. It returns a string the described this error.
SYNTAX:
INPUT:
None
RETURN:
String; a text string that describes the error code
This method is defined in the TDGError class. It returns the data object associated with this error.
SYNTAX:
INPUT:
None
Return
Object; data object associated with this error.