Miscellaneous Methods

addErrorListener()

This method adds an Error Listener to monitor error events.

SYNTAX:

void addErrorListener (TDGErrorListener Listener);

INPUT:

TDGErrorListener: a listener object that has defined in the listener interface

RETURN:

void;

A listener interface may receive the following error events:

SCALE_INVERTED // Scale minimum larger that scale maximum
NEGATIVE_AXIS_STEP // Axis assigned a negative step value
AXIS_STEP_LARGE // Axis step larger than data range
AXIS_STEP_SMALL // Axis step too small
INVALID_MINIMUM_SCALE_LOG // Negative/null min invalid for log scale
INVALID_MAXIMUM_SCALE_LOG // Negative/null max invalid for log scale 
MINIMUM_MAXIMUM_SCALE_EQUAL // Scale minimum and maximum are equal
NEGATIVE_AXIS_MINOR_STEP // Negative value for minor axis grid lines
MINOR_STEP_LARGE // Value for minor grid lines larger than data range
MINOR_STEP_SMALL // Value for minor grid lines smaller than data range
EMPTY_CELL // Empty cell in data set.
FTP_MESSAGES // Messages from FTP session.
CALC_MOVING_AVERAGE // Error calculating moving average line.
UNKNOWN_AXIS // Unknown axis.
PROPERTY_NORMALIZATION // Property normalization.
GRAPHTYPE_CHANGE_ATTEMPTED // invalid graph type change requested.
TDG_GENERAL_MESSAGE // General error message
WRITE_ERROR // Failed to write chart to a stream or file.
READ_ERROR // Failed to read from a stream or file.
TEXTUREURLNOTFOUND_ERROR // Error accessing Texture URL from graph look

ALSO SEE:

removeErrorListener()

addPerspectiveListener()

This method adds a Perspective Listener. In the Java environment, a listener is an object that has defined the listener interface for a specific event (in this case, a Perspective event such as the user interface to the chart). See the perspectiveEvent() method later in this chapter for a list of events that are currently provided by Perspective to the listener interface. Also see Chapter 3 for an overview of how events are handled in the Perspective environment.

SYNTAX:

void addPerspectiveListener (TDGListener);

INPUT:

TDGListener: a listener object that has defined the listener interface

RETURN:

void;

ALSO SEE:

perspectiveEvent(), removePerspectiveListener(), addErrorListener()

announceLicense()

This method directs the product licensing information to SysOut.

SYNTAX:

static void announceLicense();

INPUT:

None

RETURN:

void;

askForRelease()

In some cases, not all of the memory associated with Perspective is reclaimed when the Perspective is no longer in use. Under these circumstances, you can give the Java garbage collector a better chance to do its job by calling askForRelease() immediately before setting the instance of Perspective to null.

SYNTAX:

void askForRelease();

INPUT:

None

RETURN:

void;

calcWithoutDrawing()

This method is the Perspective for Java equivalent of the PGSDK DryRunTheGraph() function. It calculates, but does not draw, all graph primitives.

SYNTAX:

void calcWithoutDrawing();

INPUT:

None

RETURN:

void;

copyImageMap()

This function creates a copy of the current chart in a TDG.ImageMap.

SYNTAX:

tdg.TDGImageMap copyImageMap()

INPUT:

None

RETURN:

TDGImageMap; Image map of the current chart.

ALSO SEE:

sendImageMapToStream()

getApplet()

This method returns the current applet or null if being used with an application. If you need to get a context for a getDocumentBase in a Java environment, this method returns the location for this instance of Perspective.

SYNTAX:

Applet getApplet();

INPUT:

None

RETURN:

Applet: the current applet

getChartFromFTP()

This method gets a chart from an FTP server.

SYNTAX:

boolean getChartFromFTP (
    java.lang.String strHost,
    java.lang.String strUser,
    java.lang.String strPass,
    java.lang.String strDir,
    java.lang.String strOrgFile
);

INPUT:

strHost; Host Name

strUser; User Name

strPass; Password

strDir; Directory location

strOrgFile; File Name

RETURN:

boolean; true/false; true = Success, false = Failed

ALSO SEE:

sendChartToFTP(), sendGIFToFTP()

getContainerSize()

This method returns the dimensions of the selected container.

SYNTAX:

Dimension getContainerSize()

INPUT:

None

RETURN:

Dimension; The container dimensions

get/setDisplay()

These methods get/set the visibility of a chart object.

SYNTAX:

boolean getDisplay();
boolean getDisplay (IdentObj id);
void setDisplay (boolean newValue);
void setDisplay (IdentObj id, boolean newValue);

INPUT:

id; object ID returned by a getObject() method (e.g., getTitle())

newValue; true/false; true = Object is visible, false = Object is not visible

RETURN:

boolean; true/false; true = Object is visible, false = Object is not visible

NOTES:

If a specific object is not identified with the input parameter id, these methods get/set the associated value (if any) for the first item in the selection list.

getDocumentBase()

This method returns a document URL.

SYNTAX:

URL getDocumentBase();

INPUT:

None

RETURN:

URL = document URL

getFrameDepthOffset()

This method returns the depth offset of a chart frame where a DepthAngle has been applied to form a 3D affect (2.5D) on a 2D chart.

SYNTAX:

Point getFrameDepthOffset();

INPUT:

None

RETURN:

Point; The frame depth in 2.5D

ALSO SEE:

DepthAngle, DepthRadius

getFrameRect()

This method returns the frame rectangle translated to destination coordinates. It makes the rectangle smaller by one pixel in each dimension and translates it to virtual coordinates.

SYNTAX:

Rectangle getFrameRect (boolean bInner);

INPUT:

bInner; true = Inside edge of frame, false = Outside edge of frame

RETURN:

Rectangle; size of the frame in virtual coordinates

ALSO SEE:

getRect(), setRect()

get/setLegendRect()

These methods get/set the size and location of the legend rectangle. This rectangle is the area in the chart where legend markers and labels are drawn.

SYNTAX:

Rectangle getLegendRect();
void setLegendRect (Rectangle newValue);
void setLegendRect (Rectangle newValue,  boolean bSetRecalc);

INPUT:

newValue: location/size of legend area

bSetRecalc: true = recalculate entire chart based on new legend rectangle, false = do not recalculate

RETURN:

Rectangle; location/size of legend rectangle

ALSO SEE:

LegendAutomatic, LegendDisplay, LegendMarkerPosition, LegendReverse

getMinimumSize()

This method returns the minimum dimensions (height and width) of a Perspective for Java chart.

SYNTAX:

java.awt.Dimension getMinimumSize();

INPUT:

None

RETURN:

Dimension; the minimum size (Height=100, Width=100)

get/setRect()

These methods get/set the bounding rectangle for a user-movable object in virtual coordinates (x, y, width, height). See Chapter 3 for a description of the virtual coordinates and a list of user-movable objects.

SYNTAX:

Rectangle getRect();
Rectangle getRect (IdentObj id);
void setRect (Rectangle newValue);
void setRect (IdentObj id, Rectangle newValue);

INPUT:

id; object ID returned by a getObject() method (e.g., getFrame())

newValue: the bounding rectangle for a user-movable object in virtual coordinates (x, y, width, height)

RETURN:

Rectangle; the bounding rectangle for a user-movable object in virtual coordinates (x, y, width, height)

NOTES:

If a specific object is not identified with the input parameter id, these methods get/set the associated value (if any) for the first item in the selection list.

ALSO SEE:

getFrameRect(), get/setLegendRect()

get/setURL()

These methods get/set a Universal Resource Locator (URL). These methods and get/setURLTarget() methods can be used to include drill-downs in HTML files. They allow any series/group intersection in the chart to be used as a link reference. When the user selects/clicks on an object in a chart where a setURL() is defined, the HTML file provided as an input parameter to the method will automatically be loaded and displayed at the location specified by the setURLTarget().

SYNTAX:

java.lang.String getURL();
java.lang.String getURL (IdentObj id);
java.lang.String getURL (int seriesID);
java.lang.String getURL (int seriesID, int groupID);
void setURL (String newValue);
void setURL (IdentObj id, String newValue);
void setURL (int seriesID, String newValue);
void setURL (int seriesID, int groupID, String newValue);

INPUT:

id; object ID returned by a getObject() method (e.g., getSeries())

seriesID; series ID

groupID; Group ID

newValue; URL string

RETURN:

String; URL string

ALSO SEE:

get/setURLTarget()

get/setURLTarget()

These methods get/set the frame target for the URL associated with any specific object. It is used in conjunction with getURL() and setURL() to create drill-downs in an HTML file.

SYNTAX:

String getURLTarget();
String getURLTarget (IdentObj id);
String getURLTarget (int seriesID);
String getURLTarget (int seriesID, int groupID);
void setURLTarget (String newValue);
void setURLTarget (IdentObj id, String newValue);
void setURLTarget (int seriesID, String newValue);
void setURLTarget (int seriesID, int groupID, String newValue);

INPUT:

id; object ID returned by a getObject() method (e.g., getSeries())

seriesID; Series ID

groupID; Group ID

newValue; URL Target string

RETURN:

String; URL Target string

ALSO SEE:

get/setURL(),

getUserTooltipStrings()

This method is used to create Image Maps with Tooltip strings in them.

SYNTAX:

String[] getUserTooltipStrings (DetObj obj, int nDeadZoneLocation)

INPUT:

obj; tooltip object

nDeadZoneLocation; tooltip map location ID

RETURN:

String[]; An array of tooltip strings

inputParamString()

This method can be used to load a string of parameters into a chart.

SYNTAX:

void inputParamString (java.lang.String);

INPUT:

String = an ASCII string of Perspective for Java properties and methods.

RETURN:

void;

ALSO SEE:

outputParamString()

isPropertySet()

This method can be used to determine if a property has been set for a specified chart object.

SYNTAX:

boolean isPropertySet (IdentObj id, Attr AttrID)

INPUT:

id: IdentObj returned by a getObject() method.

AttrID: property ID

RETURN:

boolean; true = The property is set, false = The property is not set

load()

This method loads a saved chart from a Java input stream or URL. If bMerge is true, the contents of the file will be merged with the methods and properties that define the current chart. If bMerge is false, the contents of the file will replace the definition of the current file. Note that the Java input stream or URL must identify an ASCII text file that contains the properties and methods that are supported by Perspective.

SYNTAX:

void load  (java.io.InputStream is, boolean bMerge); throws java.io.IOException
void load (java.lang.String szURL, boolean bMerge);

INPUT:

is: a Java Input Stream

szURL: URL string

bMerge: true = merge loaded file with current chart definition / false = replace current chart with the loaded file

RETURN:

void;

ALSO SEE:

save()

outputParamString()

This method can be used to obtain a string of parameters that defines a chart. It will return a string buffer with all changes from the "default" settings of the chart.

SYNTAX:

java.lang.String outputParamString();

INPUT:

None

RETURN:

String = a string of parameters that define a chart

ALSO SEE:

inputParamString()

removeErrorListener()

This method removes an error listener that was previously created with addErrorListener().

SYNTAX:

void removeErrorListener (TDGErrorListener Listener)

INPUT:

Listener: a listener object that is defined in the listener interface

RETURN:

void;

ALSO SEE:

addErrorListener()

removeLineWidths()

This method removes a range of line widths from the chart look.

SYNTAX:

void removeLineWidths (int nSeriesStart, int nSeriesEnd)

INPUT:

nSeriesStart: first series at which to remove line width

nSeriesEnd: last series at which to remove line width

RETURN:

void;

ALSO SEE:

getLineWidth(), getSelectionLineWidth(), setLineWidth(), setLineWidthAllSeries()

removeMarkerShapes()

This method removes a range of assigned marker shapes from the chart look.

SYNTAX:

void removeMarkerShapes (int nSeriesStart, int nSeriesEnd)

INPUT:

nSeriesStart: first series at which to remove marker shapes

nSeriesEnd: last series at which to remove marker shapes

RETURN:

void;

ALSO SEE:

getMarkerShape(), setMarkerShape()

removePerspectiveListener()

This method removes a Perspective Listener. In the Java environment, a listener is an object that has defined the listener interface for a specific event (in this case, a Perspective event such as the user interface to the chart). See the perspectiveEvent() method later in this chapter for a list of events that are currently provided by Perspective to the listener interface. Also see Chapter 3 for an overview of how events are handled in the Perspective environment.

SYNTAX:

void removePerspectiveListener (TDGListener);

INPUT:

TDGListener: a listener object that has defined the listener interface

RETURN:

None

ALSO SEE:

addPerspectiveListener(), perspectiveEvent()

restoreDefaults()

This method can be used to restore a chart to Perspective default values. It restores the default chart type (17, a vertical clustered bar graph) and the sample data associated with this chart type.

SYNTAX:

void restoreDefaults();

INPUT:

None

RETURN:

None

ALSO SEE:

outputParamString()

save()

This method saves a chart to an output stream. It will save all of the properties and methods required to recreate the chart in ASCII text file format. The contents of the file can be viewed or edited with any text editor.

Syntax:

void save (java.io.OutputStream os);
void save (java.io.OutputStream os, String ChartObjectName);

INPUT:

os; a Java OutputStream

ChartObjectName; Chart object name

RETURN:

void

ALSO SEE:

load()

sendChartToFTP()

This method sends a chart to an FTP server as an ASCII text file.

SYNTAX:

boolean sendChartToFTP (
     String strHost,
     String strUser,
     String strPass,
     String strDir,
     String strDestFile
);

INPUT:

strHost; Host Name string

strUser; User Name string

strPass; Password string

strDir; Directory name string

strDestFile; Destination file name string

RETURN:

boolean; TRUE = success/FALSE = failed

ALSO SEE:

getChartFromFTP(), sendGIFToFTP()

setLineWidthAllSeries()

This method assigns equal line widths for all series in a chart.

SYNTAX:

void setLineWidthAllSeries (int newValue)

INPUT:

newValue;

RETURN:

void;

setSize()

This method resizes the chart to the specified height and width in pixels.

SYNTAX:

void setSize (Dimension d)
void setSize (int width, int height)

INPUT:

d; dimension object

width; width of size

height; height of size

RETURN:

void;

toggleEditControls()

If the Three |D| Graphics user interface (i.e., the Perspective Editor) is being used, this method changes the user interface from the full-screen chart state to the chart with the User Interface controls. If the User Interface controls are not displayed, calling this method will show the User Interface controls. If the User Interface controls are displayed, calling this method will show the full-screen chart without the user interface controls.

SYNTAX:

void toggleEditControls();

INPUT:

None

RETURN:

void