
All elements mentioned in this chapter refer to both the Java 2 API and the Java 3D, API unless specifically noted. Using JClass Chart 3D with the Java 3D API is discussed in detail in the chapter entitled Programming with the Java 3D API. If a class name has "Java3d" before the .java extension, it will most likely be specific to the Java 3D API. For instance, the `JCPlotCube` class in the Java 2 API is called JCPlotCube.java, while its counterpart in the Java 3D API, `JCPlotCubeJava3d`, is JCPlotCubeJava3d.java

This chapter covers concepts and vocabulary used in JClass Chart 3D programming, and provides an overview of the JClass Chart 3D class hierarchy.

1.1 Terminology

A JClass Chart 3D chart comprises four components: header, footer, chart area, and legend. The plot cube, contained within the chart area, contains the rendered chart.

The following illustration shows the terms used to describe the main components that make up a chart:

Plot Cube

The plot cube is defined to be the smallest cube which encloses the entire 3D scene (including the axes). Some JClass Chart 3D properties, such as those that specify axis scaling and axis font cube sizes, have definitions that depend on the plot cube size.

The plot cube has properties that include background color, foreground color, floor and ceiling properties, and x, y, and z scaling.

1.2 Startup Checklist

Full details of how to get started with JClass Chart 3D are provided in the JClass DesktopViews Installation Guide. The JClass DesktopViews Installation Guide is provided in PDF and HTML formats, and is automatically installed into JCLASS_HOME/docs/getstarted/ when you install JClass Chart 3D.

Note: A reminder that jcchart3dj2d.jar contains information for the Java 2 API version of JClass Chart 3D, while jcchart3dj3d.jar contains information for both the Java 2 and Java 3D API versions of JClass Chart 3D. Both files are included in JClass Chart 3D.

1.3 Instantiating a Chart in JClass Chart 3D

To instantiate a chart, you may choose to use one of the three available factory methods in JCChart3d:

The createJava2dChart() method creates an instance of the Java 2 version of JClass Chart 3D, which is the class com.klg.jclass.chart.j2d.JCChart3dJava2d.

The createJava3dChart() method creates an instance of the Java 3D version of JClass Chart 3D, which is the class com.klg.jclass.chart.j3d.JCChart3dJava3d

The createJava3dChart(boolean fallback) method creates an instance of the Java 3D version of JClass Chart 3D, which is the class com.klg.jclass.chart.j3d. JCChart3dJava3d. Note that if this class cannot be created (for instance, because Java 3D is not installed) and if the `fallback' parameter is true, then the Java 2 version of JClass Chart 3D will be created.

All three methods will return null if JClass Chart 3D could not create the desired classes.

1.4 Data Types

Point data

Point data comprises one or more series of points. Each of these series can have its own chart style.

Grid data

Grid data comprises an array of X-values, an array of Y-values, and a corresponding array of (x,y) values.

Note that the following figure uses grid data for plotting, and has been rotated so that the X-Y plane is vertical.

1.5 Chart Types

Surface Chart

Bar Chart

Scatter Plot Chart

1.6 Loading Data

Data is loaded into a chart by attaching one or more chart data sources to it. A chart data source is an object that takes real-world data and puts it into a form that JClass Chart 3D can use. Once your data source is attached, you can chart the data in a variety of ways.

Several stock (built-in) data sources are provided with JClass Chart 3D, enabling you to read data from an input stream, a file, and a URL, and databases. Loading data from a database is called `data binding'. In JClass Chart 3D, you are able to get data from a database. You can also create your own data sources. See the Data Sources, in Chapter 5, for more information on loading data and creating your own data sources.

1.7 Setting and Getting Object Properties

Each accessor method changes the chart property whose name matches the method. This manual therefore uses properties to discuss how features work, rather than using the method or Customizer tab that you might use to set that property.

Note: In most cases, you need to understand the chart's object containment hierarchy to access its properties. Use the JClass Chart 3D Object Containment diagram later in this chapter to determine how to access the properties of an object.

1.7.1 Setting Properties with Java Code

Every JClass Chart 3D property has a set and get method associated with it, unless it is read-only. For example, to retrieve the value of the AnnotationMethod property of the X-axis, the getAnnotationMethod() method is called:

To set the AnnotationMethod property of the same axis, the setAnnotationMethod is called:

These statements navigate the objects contained in the chart by retrieving the values of successive properties, which are contained objects. In the code above, the value of the Chart3dArea property is a JCChart3dArea object. The chart area has an Axes property, the value of which is a collection of JCAxis objects. The X-axis is indexed using the JCAxis.AXIS_X enum value, and the axis has the desired AnnotationMethod property. Note that for convenience, the JCChart3dArea class has a getXAxis() method.

For detailed information on the properties available for each object, consult the API reference documentation, which is automatically installed into JCLASS_HOME/docs/api/index.html when you install JClass Chart 3D.

1.7.2 Setting Properties with a Java IDE at Design-Time

JClass Chart 3D can be used with a Java Integrated Development Environment (IDE), and its properties can be manipulated at design time. Consult your IDE's documentation for details on how to load third-party JavaBean components into the IDE.

Please refer to the JClass and Your IDE chapter in the JClass DesktopViews Installation Guide, which outlines detailed instructions and important notes. For instance, only the Java 2 version of the JClass Chart 3D JavaBean (chart3dJava2d) works in Borland JBuilder 4 or higher, and you will need to add vecmath.jar to your project. The readme file contains the most current list of supported IDEs.

Most IDEs list a component's properties in a property sheet or dialog. Simply find the property you want to set in this list and edit its value. Again, consult your IDE's documentation for complete details.

1.7.3 Setting Properties Interactively at Run-Time

If enabled by the developer, end-users can manipulate property values on a chart running in your application. Right-clicking the mouse launches the JClass Chart 3D Customizer. The user can navigate through the tabbed dialogs and edit the properties displayed.

1.8 Other Programming Basics

1.8.1 Working with Object Collections

Many chart objects are organized into collections. For example, the contour styles are organized into a java.util.ArrayList. In JavaBeans terminology, these objects are held in indexed properties.

To access a particular element of a collection, you need to retrieve the collection and then specify the index that uniquely identifies this element. For example, the following code changes the line color of the third contour style to red.

1.8.2 Calling Methods

To call a JClass Chart 3D method, access the object that defines the method. For example, the following statement uses the coordToDataCoord() method, defined by the Chart3dDataView collection, to convert a pixel value to its equivalent in data coordinates:

1.8.3 Eliminating Retained JCChart3dJava3d References

When an application or applet that has created an instance of JCChart3dJava3d is terminated, the resources used by Java 3D are automatically released. However, if a JCChart3dJava3d object needs to be garbage collected before the application or applet exits, then steps must be taken to ensure that all references to the JCChart3dJava3d instance are eliminated. At least one of the objects that are passed to Java 3D during the creation of a JCChart3dJava3d instance contains a reference to that instance.

The dispose() method of JCChart3dJava3d eliminates all references to the JCChart3dJava3d objects that are retained by Java 3D. It does this by calling the removeAllLocales() method of the VirtualUniverse object that contains the Chart3d. An application or applet must call the dispose() method at a point where the JCChart3dJava3d object is no longer needed.

1.9 Outputting JClass Chart 3D

Many applications require that the user has a way to get an image or a hard copy of a chart. JClass Chart 3D allows you to output your chart as a GIF, PNG, or JPEG image, to either a file or an output stream. If you are using the Java 3D version of JClass Chart 3D, the chart must be fully visible on the screen to be correctly encoded. This means that if part of the image is obscured, then the obscured portion will not draw to the requested image.

Please note that in order to enable GIF encoding, you must obtain a license from Unisys and send a copy of this license to Quest Software. Quest Software will send the enabling software for GIF encoding upon receipt of a valid proof of license. There are also public sources of Java image to GIF converters.

Located in com.klg.jclass.util.swing.encode, the JCEncodeComponent class is used to encode components into different image file formats. When you include this class in your program, you can call one of two methods that allow you to save the chart image as a GIF, PNG, or JPEG file, sending it to either a file or an output stream.

1.9.1 Encode method

The method to output to an output stream is the same, except that the last parameter is OutputStream output, that is ...Component component, OutputStream output)

The component parameter refers to the component to encode (the chart), the encoding parameter refers to the type of encoding to use (a GIF, PNG, or JPEG), and the output parameter refers either to the file to which to write the encoding or to the stream to which to write the encoding.

1.9.2 Encode example

1.10 JClass Chart 3D Inheritance Hierarchy

1.11 JClass Chart 3D Object Containment

When you create (or instantiate) a new chart, several other objects are also created. These objects are contained in and are part of the chart. Chart programmers need to traverse these objects to access the properties of a contained object. The following diagram shows the object containment for JClass Chart 3D.

JCChart3D (the top-level object) manages header and footer JComponent objects, a legend (JCLegend), and the chart area (JCChart3DArea). The chart also contains a collection of data view (Chart3DDataView) objects. Please note that currently only one Chart3dDataView is supported.

The Chart3dArea contains many of the chart's actual properties because it is responsible for charting the data. It also contains and manages an xAxis, yAxis, and zAxis, all of type JCAxis.

The data view collection contains objects and properties (like the chart type) that are tied to the data being charted. Each data view manages two data sources: an elevation data source and a zone data source. The elevation data source is the main data source for plotting surfaces, bars, and scatter plots. Its two values determine the elevation of the surface, bar, or scatter point. It can be set to either grid data or point data.

The zone data source is used to add a fourth dimension to the elevation data via color. It can only be set to grid data and is only used if the elevation data source is also using grid data. Thus, the elevation data source must implement either the Chart3dGridDataModel or the Chart3dPointDataModel, while the zone data source must implement the Chart3dGridDataModel.

Note that the chart does not own the data itself, but instead merely views on the data. The data is owned by the DataSource object. This is an object that your application creates and manages separately from the chart. For more information on JClass Chart 3D's data source model, see Data Sources, in Chapter 5.

1.12 UseDefault Properties

UseDefault properties are Booleans that determine whether JClass Chart 3D should calculate a default value for the property.

For example, if the minIsDefault property of a JCAxis object is true, every time the JClass Chart 3D data is changed, JClass Chart 3D will determine a reasonable default value for the axis minimum. If false, JClass Chart 3D will use the provided axis minimum.

A side effect of setting any property that has a corresponding UseDefault property is that the UseDefault property will be set to false.

The following code will freeze the value of minIsDefault at its current value. It will also have the side effect of setting minIsDefault to false.

The following code will revert back to the default behavior, enabling JClass Chart 3D to calculate a default value for minIsDefault whenever it draws the graph.

For the levels property of JCContourLevels, adding, removing, or setting a level directly will cause the isDefault property to be set to false. Also, when isDefault is false, the numLevels property becomes read-only.

1.13 Batching Property Updates

Normally property changes take effect immediately after the values are set. If you would prefer to make several changes to the chart's properties before causing a repaint, set the setBatched() method to true. The setBatched() method sets the value of the Batched property, which controls whether chart updates are accumulated; if set to true, chart updates will accumulate, and if set to false, the accumulated updates are forced to be processed.

You should normally set setBatched() to true after all your updates are made; this will initiate a repaint.

1.14 Chart Colors

Color can powerfully enhance a chart's visual impact. You can customize chart colors using Java color names or RGB values. Using an interactive tool like the JClass Chart 3D Customizer makes selecting custom colors quick and easy.

Note that the area backgrounds are transparent by default. The foreground colors default to the chart foreground color. Also note that inherited properties of the chart or Chart3dArea components, such as backgroundColor, are not controlled by the Batched property.

Each of the following visual elements in the chart has a background and foreground color that you can customize:

Other chart objects have color properties too, including JCGridLines and JCChart3dStyles. You can also specify colors for the top and bottom of the mesh, for surface shading, and for the contour lines and zone fills.

Color Defaults

All chart subcomponents are transparent by default with no background color. If made opaque, the legend and the chart area will inherit background color from the parent chart. The plot cube inherits its colors from the chart area. The same objects will always inherit the foreground color from the chart.

Headers and footers are independent objects that behave according to the rules of whatever object they are.

Please note that once the application sets the colors of an element, they do not change when other elements' colors change.

Specifying Foreground and Background Colors

Each chart element listed above has a Background and Foreground property that specifies the current color of the element. The easiest way to specify a color is to use the built-in color names defined in java.awt.Color. The following table summarizes these colors:


Built-in Colors in java.awt.Color
black	blue	cyan
darkGray	gray	green
lightGray	magenta	orange
pink	red	white
	yellow

Alternately, you can specify a color by its RGB components, useful for matching another RGB color. RGB color specifications are composed of a value from 0 - 255 for each of the red, green and blue components of a color. For example, the RGB specification of Cyan is "0-255-255" (combining the maximum value for both green and blue with no red).

The following example sets the header background using a built-in color, and the footer background to an RGB color (a dark shade of turquoise):

Take care not to choose a background color that is also used to display data in the chart. The default ContourStyles and Chart3dStyles use all of the built-in colors in the following order: Red, Orange, Blue, Light Gray, Magenta, Yellow, Gray, Green, Dark Gray, Cyan, Black, Pink, and White. Note that JClass Chart 3D will skip colors that match background colors. For example, if the chart area background is Red, then the line, fill, and symbol colors will start at Orange.

Transparency

If the JClass Chart 3D component is meant to have a transparent background, set the opaque property to false; then generated JPEGs, GIFs, and PNGs will also contain a transparent background (not currently available in the Java 3D API version of JClass Chart 3D).

1.15 The JClass Chart 3D Customizer

The JClass Chart 3D Customizer enables developers (and end-users if enabled by your program) to view and customize the properties of the chart as it runs.

The Customizer can save developers a lot of time. Charts can be prototyped and shown to potential end-users without having to write any code. Developers can experiment with combinations of property settings, seeing results immediately in the context of a running application, greatly aiding chart debugging.

1.15.1 Displaying the Chart Customizer at Run-Time

By default, the Customizer is disabled at run-time. To enable it, you need to set the chart's AllowUserChanges property to true. For example:

You can also launch the Customizer through the customize action. Please seeProgramming User Interaction, in Chapter 7, for information on how to do this. Installing the default user interactions via the addAllDefaultActions() method causes the Customizer to be deployed when the right mouse button is clicked.

1.15.2 Editing and Viewing Properties

Select the tab that corresponds to the chart element that you want to edit. Tabs contain one or more inner tabs that group related properties together. Select inner tabs to narrow down the type of property you want to edit.
If you are editing an indexed property, select the specific object to edit from the lists displayed in the tabs. The fields in the tab update to display the current property values.
Select a property and edit its value.

As you change property values, the changes are immediately applied to the chart, and will be displayed immediately only if the batched checkbox is not selected. You can make further changes without leaving the Customizer. However, once you have changed a property the only way to "undo" the change is to manually change the property back to its previous value.

To close the Customizer, close its window (the actual steps differ for each platform).

1

JClass Chart 3D Basics

Terminology Startup Checklist Instantiating a Chart in JClass Chart 3D

Data Types Chart Types Loading Data Setting and Getting Object Properties

Other Programming Basics Outputting JClass Chart 3D JClass Chart 3D Inheritance Hierarchy

JClass Chart 3D Object Containment UseDefault Properties Batching Property Updates

Chart Colors The JClass Chart 3D Customizer