1

JClass Chart Basics

Chart Areas  Chart Types  Loading Data  Setting and Getting Object Properties

Other Programming Basics  JClass Chart Inheritance Hierarchy  JClass Chart Object Containment

The Chart Customizer  Internationalization 

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

---

1.1 Chart Areas

The following illustration shows the terms used to describe chart areas:

Figure 1 :  Elements contained in a typical chart.

---

1.2 Chart Types

JClass Chart can display data as one of 13 basic chart types: Plot, Scatter Plot, Area, Stacking Area, Bar, Stacking Bar, Pie, Hi-Lo, Hi-Lo-Open-Close, Candle, Polar, Radar, and Area Radar.

It is also possible to simulate more specialized types of charts using one of these basic types.

Use the ChartType property to set the chart type for one ChartDataView. Each data view managed by the chart has its own chart type. The following table lists basic information about each chart type, including the enumeration that sets that type and the data layouts it can display (see the next section for an introduction to data).

Chart Type	Single X-series	Multiple X-series	Notes
			Plot Draws each series as connected points of data. Series appearance determined by chart style line color, symbol shape, size, and color properties.
			Scatter Plot Draws each series as unconnected points of data. Series appearance determined by chart style symbol shape, size, and color properties.
			Bar Draws each series as a bar in a cluster. The number of clusters is the number of points in the data. Each cluster displays the nth point in each series. X-axis generally annotated using Point labels. Series appearance determined by chart style fill color and image properties. 3D effect available using depth, elevation, and rotation properties.
			Stacking Bar Draws each series as a portion of a stacked bar cluster, the number of clusters being the number of data points. Each cluster displays the nth point in each series. Negative Y-values are stacked below the X-axis. X-axis generally annotated using Point labels. Series appearance determined by chart style fill color property. 3D effect available using depth, elevation, and rotation properties.
			Area Draws each series as connected points of data, filled below the points. Each series is layered over the preceding series. Series appearance determined by chart style fill color property.
			Stacking Area Draws each series as connected points of data, filled below the points. Places each Y-series on top of the last one to show the area relationships between each series and the total. Series appearance determined by chart style fill color property.
			Pie Draws each series as a slice of a pie. The number of pies is the number of points in the data (values below a certain threshold can be grouped into an other slice). Each pie displays the nth point in each series. Pies are annotated with Point labels only. Series appearance determined by chart style fill color property. 3D effect available using depth and elevation properties.
			Hi-Lo Draws two series together as a "high-low" bar. The points in each series define one portion of the bar:  1st series - points are the "high" value  2nd series - points are the "low" value Appearance determined by chart style line color property in the first series of each pair.
			Hi-Lo-Open-Close Similar to Hi-Lo, but draws four series together as a "high-low-open-close" bar. The additional series' points make up the other components of the bar:  3rd series - points are the "open" value  4th series - points are the "close" value Appearance determined by chart style line color and symbol size properties in the first series of each set.
			Candle A special type of Hi-Lo-Open-Close chart; draws four series together as a "candle" bar. Simple candle appearance determined by chart style line color, fill color, and symbol size properties in the first series of each set. Complex candle appearance determined by different chart style properties from each series of each set.
			Polar Draws each series as connected points of data on a polar coordinate system (theta,r). X-values represent the amount of rotation and Y-values are the distance from the origin. When using Array data, X-values are shared across series. X-axis bounds cannot be set; Y-axis bounds cannot be set inside the data extents. Appearance determined by ChartStyles' line and symbol properties of each series.
			Radar Draws each series as connected points along radar "sticks" spaced equally apart. The nth stick charts the Y-value of the nth point in each series. X-axis annotated with Point-labels or integer values. Appearance determined by ChartStyles' line and symbol properties of each series.
			Area Radar Draws each series as connected points of data, filled inside the points. The points are the same as they would be for a Radar chart. Each series is drawn "on top" of the preceding series. X-axis annotated with Point-labels or integer values. Appearance determined by ChartStyles' fill and line properties.

---

1.3 Loading Data

Data is loaded into a chart by attaching one or more chart data sources to it. A chartable data source is an object that takes real-world data and puts it into a form that JClass Chart 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, enabling you to read data from an input stream, a file, a URL, databases, and HTML applet <PARAM> tags. Loading data from a database is called `data binding'. You can also create your own data sources. See the Data Sources, in Chapter 8 for more information on loading data, data binding, and creating your own data sources.

---

1.4 Setting and Getting Object Properties

There are four ways to set (and retrieve) JClass Chart properties:

• By calling property set and get methods in a Java program.
• By specifying applet properties in an HTML file.
• By using a Java IDE at design-time (JavaBeans).
• By using the Chart Customizer at run-time.

Each method changes the same chart property. This manual therefore uses properties to discuss how features work, rather than using the method, Customizer tab, or HTML parameter 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 Objects contained in a chart - traverse contained objects to access properties. diagram to determine how to access the properties of an object.

1.4.1 Setting Properties with Java Code

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

method = c.getChartArea().getXAxis(0).getAnnotationMethod();

To set the AnnotationMethod property of the same axis:

c.getChartArea().getXAxis(0).setAnnotationMethod(
  JCAxis.POINT_LABELS);

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 ChartArea property is a JCChartArea object. The chart area has an XAxis property, the value of which is a collection of JCAxis objects. The axis also has the desired AnnotationMethod property.

For detailed information on the properties available for each object, consult the online API reference documentation. The API is automatically installed when you install JClass and is found in the JCLASS_HOME/docs/api/ directory.

1.4.2 Setting Applet Properties in an HTML File

Another way to set chart properties, particularly appropriate for applets, is in an HTML file. Applets built with JClass Chart automatically parse applet <PARAM> tags and set the chart properties defined in the file. (A pre-built applet called JCChartApplet.class is provided with JClass Chart.) Even standalone Java applications can save the values of chart properties to an HTML file, which can serve as a useful debugging tool.

Using HTML to set properties has the following benefits:

• Speed - see the effect of different property values quickly without recompiling.
• Flexibility - use a single applet class to create many different kinds of charts simply by varying HTML properties; end-users can modify HTML properties to suit their own needs.

Chart properties are coded in HTML as applet <PARAM> tags. The NAME element of the <PARAM> tag specifies the property name; the VALUE element specifies the property value to set.

This line of code
<PARAM name="chart.dataFile" value="sample_1.dat">
in the following example HTML file supplies the chart's data in the applet.

<HTML>
<HEAD>
<TITLE>Sample Plot Chart</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFCC">
<FONT FACE="ARIAL,VERDANA,HELVETICA" SIZE="-1">
<CENTER><H2>Sample Plot Chart</H2></CENTER>
<P>
<HR COLOR=CC3333>
<P>
<BLOCKQUOTE>
Simple plot chart example.
</BLOCKQUOTE>
<CENTER>
<P>
<APPLET CODEBASE="../../.." WIDTH=400 HEIGHT=300 CODE="com/klg/jclass/chart/applet/JCChartApplet.class">
<PARAM name="chart.dataFile" value="sample_1.dat">
<PARAM name="chart.data.chartType" value="Plot">
<PARAM name="chart.data.series1.label" value="Ser. 1">
<PARAM name="chart.data.series1.symbol.shape" value="triangle">
<PARAM name="chart.data.series2.label" value="Ser. 2">
<PARAM name="chart.data.series2.symbol.shape" value="box">
<PARAM name="chart.data.series3.label" value="Ser. 3">
<PARAM name="chart.data.series3.symbol.shape" value="dot">
<PARAM name="chart.legend.visible" value="true">
<PARAM name="chart.legend.borderType" value="plain">
<PARAM name="chart.yaxis.min" value="5">
<PARAM name="chart.yaxis.max" value="25">
<PARAM name="chart.yaxis.precision" value="0">
<PARAM name="chart.yaxis.tickSpacing" value="2.5">
<PARAM name="chart.xaxis.precision" value="0">
</APPLET>
<P>
<B><I><A HREF="../index.html">More Applet Examples...</A></I></B>
</CENTER>
<!-- copyright information added -->
<P>
<HR COLOR=CC3333>
<P>
<P><FONT FACE="ARIAL,VERDANA,HELVETICA" SIZE=-2><A HREF="http://www.quest.com/corporate/copyright.html">Copyright&#169;
</A>
2002 Quest Software</FONT></FONT>
</BODY>
</HTML>

The easiest way to create a set of HTML properties is to use the JClass Chart Customizer to save the property values to an HTML file. For more details, see the The Chart Customizer section in this chapter.

Another way to load and save JClass Chart HTML properties is to use the convenience methods in JCChartFactory. For example, to create a chart from the above HTML file stored in chart.html, the following code can be used:

LoadProperties loadProps = new LoadProperties();
String inFile = "chart.html";
String chartName = "myChart";
JCChart chart = null;
try {
  chart = JCChartFactory.makeChartFromFile(inFile, loadProps, chartName,
JCChartFactory.HTML);
}
catch (JCIOException e) {
  System.out.println("Error accessing external file:" + e.getMessage());
}
catch (JCParseException e) {
  System.out.println("Error parsing file:" + e.getMessage());
}
catch (IOException e) {
  System.out.println("Error reading " + inFile + ":" + e.getMessage());
}

where

• chartName is the name of the chart, and is the name with which each of the properties begins. If there is more than one chart in the HTML file, only the parameters beginning with that name are assigned to the chart. If there is only one set of chart parameters stored in the file, the name can be dropped and an empty String passed as the third parameter.
• LoadProperties is a class containing properties that specify how to load the chart (see LoadProperties for more details).

When a file is read in, all HTML tags, other than the PARAM tags, are ignored. This means that chart information can be read in from a file that contains only PARAM tags. A full listing of the syntax of JClass Chart properties when used in HTML files can be found in Appendix C, HTML Property Reference. Many example HTML files are located in the JCLASS_HOME/examples/chart/applet directory.

LoadProperties

The LoadProperties class contains properties that tell JCChart what to do when loading the chart from an HTML file. This class is responsible for the following:

• Telling the chart how to access data files and image files, given the filename. Inside an HTML file, the file access can be specified as one of the following:
• DEFAULT_ACCESS: The default access is ABSOLUTE.
• ABSOLUTE: Interprets the filename as an absolute name.
• RESOLVING_CLASS: Specifies a Class object to use as a resolving class for loading the file. This resolving Class must be set on the LoadProperties object. The ClassLoader of the resolving class is used to resolve the name through a call to getResource(filename). In the resolution process, if the filename starts with "/", it is unchanged; otherwise, the package name of the resolving Class is added to the front of the filename after converting "." to "/".
• URL: Interprets the filename as a URL.
• RELATIVE_URL: Interpret the filename as URL after adding a relativeURLPrefix to the beginning of it. One must set the relativeURLPrefix on the LoadProperties object (it defaults to the empty String).
• Identifying what to do when there is an error that resulted from reading a data or image source specified within the HTML file. Normally, JCChart throws a JCIOException when this happens. However, you can tell JCChart to ignore these exceptions and continue loading the chart by setting the ignoreExternalResourceExceptions property to true.
• Allowing the user to specify an object to be passed to an external java class when the external-java-code tag is used.

Other JCChartFactory Methods

Other JCChartFactory methods that create or update JCChart's are:

• makeChartFromStream()
• makeChartFromReader()
• makeChartFromString()
• updateChartFromFile()
• updateChartFromStream()
• updateChartFromReader()
• updateChartFromString()

Each of these methods throws a JCParseException if JCChart fails to parse the HTML file.

1.4.3 Saving a JCChart Instance to HTML

The JCChartFactory class also has methods that save a JCChart instance to a stream, file, or String. For example, to save a chart to the file chart.out.html, use the following code:

String outFile = "chart.out.html";
String outDataFile = "chart.dat";
ChartDataView dv = chart.getDataView(0);
if (dv != null) {
  OutputDataProperties outProps = dv.getOutputDataProperties();
  if (outProps == null) {
    outProps = new OutputDataProperties();
  }
  outProps.setOutputFileName(outDataFile);
  outProps.setPropertyName("file:///C:/jclass_home/" + outDataFile);
  outProps.setSaveType(OutputDataProperties.DATA_FILE_TXT);
  outProps.setFileAccess(OutputDataProperties.URL);
  dv.setOutputDataProperties(outProps);
}
try {
  JCChartFactory.saveChartToFile(chart, outFile,
                  JCChartFactory.HTML);
}
catch (IOException e) {
  System.out.println("Error writing to " + outFile + ":" +
            e.getMessage());
}

In the above code, the instance of OutputDataProperties serves two purposes. First, it causes the chart's HTML output to specify how the data for the given ChartDataView should be read in when it is loaded into a JCChart. This is done by specifying three properties:

• propertyName, which is the name of the data input source. The way this name is interpreted depends on the saveType and fileAccess mechanism.
• saveType, which is one of:
• NO_DATA: This ChartDataView will have no data when the HTML file is loaded into JCChart. Nothing concerning data is written out.
• EMBED_DATA: The data is embedded directly into the HTML file in text format. No external data file is needed.
• DATA_FILE_TXT: The ChartDataView gets its data from a file and it is specified in text format (see Section 8.9, Data Formats, for the proper format).
• DATA_FILE_XML: The ChartDataView gets its data from a file and it is specified in XML format (see Section 8.8, Loading Data from an XML Source, for the proper format).
• fileAccess, mechanism determines how the propertyName is interpreted and dictates which way the data file is accessed when loaded into a JCChart. See the fileAccess types in LoadProperties.

Second, it tells JCChart whether or not it should save the data to a file. If the outputFileName property is non-null and the save type is either DATA_FILE_TXT or DATA_FILE_XML, the data is saved to the specified file based on the save type. Note that outputFileName is an absolute file name.

In the previous example, the data is written as text to chart.dat. In the output file chart.out.html, the data is specified to be read in from the URL as follows:

<param name=dataFile value="file:///C:/jclass_home/chart.dat">
<param name=dataFileType value="Text">
<param name=dataFileAccess value="Url">

Note: Images are saved in a similar fashion to data files, except that an instance of OutputProperties is used instead of OutputDataProperties.

Other methods that save a JCChart are:

• saveChartToStream()
• saveChartToString()

1.4.4 Updating Charts with Data

JCChartFactory also has a method, updateChartWithData(), that updates a chart with a new data set. In the given data view, the old data set is replaced by the new data set, with information provided by a file or an input stream. The method definition is:

public static void
updateChartWithData(JCChart chart, int dataType, Object data,
              int dataViewIndex, LoadProperties)

where

• chart is the chart to update.
• dataType is the type of data (either DATA_FILE_TEXT or DATA_FILE_XML).
• data is the data object (either a Reader, a filename String or an InputStream).
• dataViewIndex is the index of the ChartDataView on which the data is to be set (there is also a method where the ChartDataView can be specified by name).
• LoadProperties is a class containing properties that specify how to load the chart (see LoadProperties for more details).

This method creates a data source from the data object, and sets this new data source on the appropriate ChartDataView on the chart.

1.4.5 Setting Properties with a Java IDE at Design-Time

A JClass Chart Bean 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 Bean components into the IDE.

You can also refer to the JClass and Your IDE chapter in the JClass DesktopViews Installation Guide.

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.4.6 Setting Properties Interactively at Run-Time

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

For details on enabling and using the Customizer, see The Chart Customizer later in this chapter.

---

1.5 Other Programming Basics

Working with Object Collections

Many chart objects are organized into collections. For example, the chart axes are organized into the XAxis collection and the YAxis collection. In Beans terminology, these objects are held in indexed properties.

To access a particular element of a collection, specify the index that uniquely identifies this element. For example, the following code changes the maximum value of the first X-axis to 25.1:

  c.getChartArea().getAxis(0).setMax(25.1);

Note that the index zero refers to the first element of a collection. Also, note that by default, JCChartArea contains one element in XAxis and one in YAxis.

Also note that for a Polar, Radar, and Area Radar chart, there can be only one Y-axis and one X-axis.

Calling Methods

To call a JClass Chart method, access the object that defines the method. For example, the following statement uses the coordToDataCoord() method, defined by the ChartDataView collection, to convert the location of a mouse click event in pixels to their equivalent in data coordinates:

  JCDataCoord dc = c.getDataView(0).coordToDataCoord(10,15);

Details on each method can be found in the API documentation for each class.

---

1.6 JClass Chart Inheritance Hierarchy

The following provides an overview of class inheritance of JClass Chart.

Figure 2 :  Class hierarchy of the com.klg.jclass.chart package.

---

1.7 JClass Chart 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.

Figure 3 :  Objects contained in a chart - traverse contained objects to access properties.

JCChart (the top-level object) manages header and footer JComponent objects, a legend (JCLegend), and the chart area (JCChartArea). The chart also contains a collection of data view (ChartDataView) objects and can contain the ChartLabelManager (JCChartLabelManager) which manages a collection of chart label (JCChartLabel) objects.

The chart area contains most of the chart's actual properties because it is responsible for charting the data. It also contains and manages a collection of X-axis (JCAxis) objects and Y-axis (JCAxis) objects (one of each by default).

The data view collection contains objects and properties (like the chart type) that are tied to the data being charted. Each data view contains a collection of series (ChartDataViewSeries) objects, one for each series of data points, used to store the visual display style of each series (JCChartStyle).

Note that chart does not own the data itself, but instead merely views on the data. Each data view also contains a data source (ChartDataModel) object. 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's data source model, see Data Sources.

---

1.8 The Chart Customizer

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

Figure 4 :  The JClass Chart Customizer.

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.8.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 and Trigger properties, for example:

chart.setAllowUserChanges(true);
chart.setTrigger(0, new EventTrigger(InputEvent.META_MASK,
  EventTrigger.CUSTOMIZE);

To display the Customizer once it has been enabled, move the mouse over the chart and click the secondary mouse button; that is, the button on your system that displays popup menus, for example:

• Windows - Right mouse button
• UNIX - Middle mouse button

1.8.2 Editing and Viewing Properties

1. 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.
2. 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.
3. Select a property and edit its value.

   
   
   

Figure 5 :  Editing a sample chart with the Customizer.

As you change property values, the changes are immediately applied to the chart and displayed. 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.9 Internationalization

Internationalization is the process of making software that is ready for adaptation to various languages and regions without engineering changes. JClass products have been internationalized.

Localization is the process of making internationalized software run appropriately in a particular environment. All Strings used by JClass that need to be localized (that is, Strings that are seen by a typical user) have been internationalized and are ready for localization. Thus, while localization stubs are in place for JClass, this step must be implemented by the developer of the localized software. These Strings are in resource bundles in every package that requires them. Therefore, the developer of the localized software who has purchased source code should augment all .java files within the /resources/ directory with the .java file specific for the relevant region; for example, for France, LocaleInfo.java becomes LocaleInfo_fr.java, and needs to contain the translated French versions of the Strings in the source LocaleInfo.java file. (Usually the file is called LocaleInfo.java, but can also have another name, such as LocaleBeanInfo.java or BeanLocaleInfo.java.)

Essentially, developers of the localized software create their own resource bundles for their own locale. Developers should check every package for a /resources/ directory; if one is found, then the .java files in it will need to be localized.

For more information on internationalization, go to: http://java.sun.com/j2se/1.4.2/docs/guide/intl/index.html.