3.9. EspressReport Chart API

3.9.1. Introduction and Setup

In addition to designing and creating chart templates in the EspressReport Designer, EspressReport also provides an easy-to-use application programming interface (API) that enables users to create and customize 2D and 3D charts within their own applications and applets. It is written in 100% Pure Java and thus can be run on any platform with little or no modifications necessary. The chart template is completely customizable using the API. You can use as little as 4 lines of code to add a chart to another chart.

The data for the chart can come from two sources:

  • The data can come from the report section to which the chart template is set. For instance, a Report Footer, which has a chart template in it, will show the entire report's data. If, however, the same template is assigned to the Group Footer, then only the partial data within the group is shown in the chart. Therefore, care must be taken to ensure that the correct data is shown with the chart and that the chart templates are set in the proper locations in the report.

  • The data can come from an independent data source. This data source can be the same as the data source used to create the report or different from the data source. Please note that the chart data will not change depending on its placement within the report. However, multiple charts may appear depending on which section of the report the chart has been added to.

In addition to adding charts to reports, you can also generate and deploy stand-alone charts, independent of a report. You do not necessarily need to add a chart to a report (even a blank one) to show the chart.

The main classes, QbChart and ChartObject (which extends quadbase.ChartAPI.QbChart) are used for creating and adding a chart object to the report. Associated with this component, is a set of auxiliary classes contained within two packages: quadbase.ChartAPI and quadbase.util. The remainder of this document explains the constituents of the API and their usage.

[Tip]Tip

Please note that the complete API documentation is located at help/apidocs/index.html.

To use the API, add EspressAPI.jar and ExportLib.jar (located in the EspressReport/lib directory) to your CLASSPATH. Please note that if you are also using XML (to output the data, or to read in data), you will also need to add xercesImpl.jar and xml-apis.jar (also located in the same directory) to the CLASSPATH as well. If you wish to use to export the chart to SVG or to Flash, you will need to add SVGExport.jar or FlashExport.jar (also located in the same directory) to the CLASSPATH. If you want to use parameterized database queries as your data sources, add jsqlparser.jar to your CLASSPATH. Please note that you will also need to include qblicense.jar in your CLASSPATH. If your application is on a Windows or Solaris machine, you will have to add the following environment variable (depending on the platform):

(For Windows) set PATH=%PATH%;<path to EspressReport root directory>\lib
(For Solaris) export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path to EspressReport root directory>/lib
        

3.9.2. Recommended Approach for Using Chart API

EspressReport provides API through which charts can be generated programmatically from scratch. However, this generally involves a significant amount of code. We recommend using Designer and creating chart templates (.TPL file) first. The chart template can be passed in the QbChart constructor and thus have its look and feel applied to the newly created chart object. Therefore, most of the look and feel will have been set at the time of the chart generation. You can then write code to modify, add, or remove the properties. This approach will save you coding time and improve performance as well.

When using EspressReport Chart API, you have the option of connecting to EspressManager or of not connecting to it. While a connection is required when using Designer, you do not need to connect to EspressManager when running any application that utilizes EspressReport Chart API. We generally recommend that you do not connect to EspressManager and thereby avoid another layer in your architecture. For more details, please refer to the next section.

All examples and code given in the manual follow the above two recommendations: a template based approach and no connection to EspressManager. Unless otherwise noted, all code examples will use a template (can be downloaded in corresponding chapters) and will not connect to EspressManager.

Also note that if you have applets that use EspressReport Chart API, the browser must have at least a 1.5 JVM plugin.

3.9.3. Interaction with EspressManager

EspressReport is generally used in conjunction with EspressManager. The chart component connects to EspressManager in order to read and write files, to access databases, and to perform data pre-processing required for certain advanced features (such as aggregation). However, the chart component can also be used in a stand-alone mode, in which it performs file I/O and database access directly, without the use of EspressManager.

Both approaches have their own advantages. If the chart is contained within an applet, security restrictions prevent it from directly performing file input/output. Database access is also difficult without the presence of a JDBC driver on the client. In such cases, EspressManager provides the above services to the chart. On the other hand, if the chart is used in an application, there are no such restrictions, and performance can be improved by direct access. The application can be run without the necessity of having EspressManager running at a well-known location.

For instance, the applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application may be running on machine Client and may require data from a database on machine DbMachine. However, the machine DbMachine may be behind a firewall or a direct connection and may not be allowed to machine DbMachine from machine Client due to security restrictions. EspressManager can be run on machine Server and the applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file)/application can connect to EspressManager on the machine Server. JDBC can then be used to connect to machine DbMachine from machine Server and get the data. The data is then delivered to machine Client and the chart is generated. This is useful when you want to keep the data secure and non-accessible from your client machines and make all connections come through a server machine (a machine running EspressManager). You can also utilize this option to keep a log of all the clients accessing the data through EspressReport (you can have a log file created when starting EspressManager. The log file is called espressmanager.log ). Note that this functionality comes at a cost. You will face a slight performance overhead because your code is connecting to the data through EspressManager (i.e., another layer has been added).

By default, a chart component requires the presence of EspressManager. To change the mode, use the QbChart class static method at the beginning of your applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file)/application (before any QbChart objects are created):

static public void setEspressManagerUsed(boolean b)

Both applications and applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) can be run with or without accessing EspressManager. Communication is done by using http protocol. The location of the server is determined by an IP address and port number passed in the API code. Below are instructions on how to connect to the EspressManager:

3.9.4. Connecting to EspressManager

3.9.4.1. EspressManager Running as Application

EspressManager is primarily run as an application. If you wish to use ChartAPI to connect to EspressManager running as an application, you can use API methods to specify the IP address or machine name where EspressManager is located, as well as the port number that EspressManager is listening on.

You use the following two API methods to set the connection information:

static void setServerAddress(java.lang.String address);
static void setServerPortNumber(int port);

For example, the following lines of code:

QbChart.setServerAddress("someMachine");
QbChart.setServerPortNumber(somePortNumber);

will connect to EspressManager running on someMachine and listening on somePortNumber.

Please note that if EspressManager connection information is not specified, the code will attempt to connect to EspressManager on the local machine and listening to the default port number (22071).

Please note that these methods exist in QbReport, QbChart, QbReportDesigner, and QbScheduler classes.

3.9.4.2. EspressManager Running as Servlet

EspressManager can also be run as a servlet. If you wish to use Chart API to connect to EspressManager running as a servlet, you will have to use the following methods:

public static void useServlet(boolean b);
public static void setServletRunner(String comm_url);
public static void setServletContext(String context);

For example, the following lines of code:

QbChart.useServlet(true);
QbChart.setServletRunner("http://someMachine:somePortNumber");
QbChart.setServletContext("EspressReport/servlet");

will connect to EspressManager running at http://someMachine:somePortNumber/EspressReport/servlet.

Please note that these methods exist in QbReport, QbChart, QbReportDesigner, and QbScheduler classes.

3.9.5. Using the API

The following section details how to utilize the API. Again, the API examples and code is designed using the above recommendation (template based and no EspressManager).

Note that unless otherwise noted, all examples use the Woodview HSQL database, which is located in the <EspressReportInstall>/help/examples/DataSources/database directory. In order to run the examples, you will need to add database HSQL JDBC driver (hsqldb.jar) to your classpath. The driver is located in the <EspressReportInstall>/lib directory.

Also, all the API examples will show the core code in the manual. To compile the examples, make sure the CLASSPATH includes ReportAPIWithChart.jar and qblicense.jar.

For more information on the API methods, please refer the API documentation.

3.9.5.1. Loading a Chart

Charts can be saved to a file using the PAC, CHT or TPL formats (both proprietary formats). A TPL file stores all of the chart information, except for the actual data; PAC or CHT file stores the actual data as well. These formats can be used to reconstruct a chart object. The data is automatically reloaded from the original data source each time the TPL file is opened. When PAC or CHT file is opened, the data used to create it is shown (although the option to fetch data from the data source also exists).

It is important to note that the TPL file, by default, does NOT contain the data. It contains, along with the chart template information (i.e., the look and feel of the chart), the specified data source. Therefore, when loading a TPL file, the data for the chart is obtained by querying the data source. The CHT file, on the other hand, does NOT query the data source when it is opened. It shows the data used to create the chart to begin with. Both formats can be obtained by using Designer or the export() method provided in the QbChart class.

The following example, which can run as a Java Web Start Application, reads a CHT file and reconstructs a chart:

Component doOpeningTemplate(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "../templates/OpeningChartTemplate.cht"); // template

      // Show chart in Viewer

      return chart;

}

Full Source Code

Exported Results

The constructor in this example is:

public QbChart(Applet applet, String file);

where applet is the applet container and file is a CHT/TPL file name.

[Tip]Tip

File names may be specified either as URL strings or by using relative/absolute paths. Path names are interpreted as being relative to the current directory of EspressManager or to the current application if EspressManager is not used.

3.9.5.1.1. Parameterized Charts

Charts can also contain parameters to either limit the data in some form. Typically, query (or IN) parameters are used by the data source to limit the data.

Query parameters can be both single-value and multi-value parameter types.

When a parameterized template is opened using following constructor:

QbChart(Applet parent, String templateName);

a dialog box appears, asking for the value(s) of the parameter(s). This dialog box is the same as the one that appears in Designer when the template is opened.

3.9.5.1.1.1. Object Array

A parameterized chart can also be opened without the dialog box prompting for any value(s). This can be done by passing in an object arrays. Each element in the array represents the value for that particular parameter.

The order of the array must match the order in which the parameters were created in Designer. For correct results, the data type of the value must also match the data type of the parameter.

Query parameters can also be multi-value parameter types. For multi-value parameters, a vector is passed to the object array. The vector contains all the values for the multi-value parameter.

The following example, which can run as a Java Web Start Application, passes in the parameter values when opening a chart template:

Component doObjectArray(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Object array for Query Parameters
      Vector vec = new Vector();
      vec.addElement("CA");
      vec.addElement("NY");

      // Object array for Query Parameters
      Object queryParams[] = new Object[3];
      queryParams[0] = vec;
      queryParams[1] = new Date(101, 0, 4);
      queryParams[2] = new Date(103, 01, 12);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "../templates/ObjectArray.cht", // template
                      queryParams); // Query Parameters

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

3.9.5.2. Applying a Chart Template

When a QbChart object is created from scratch (see Appendix 3.C - Creating the Chart), the chart is created using default attributes. However, you can use a chart template (.tpl) to specify user defined attributes during chart construction. Almost all the attributes (except for data source and chart type) are extracted from the template and applied to the QbChart object. The template name usually appears as the last argument in the QbChart constructors.

You can also specify the template name using the applyTemplateFile(String fileName) method in the QbChart class.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, applies a template onto the QbChart object:

Component doApplyingTemplate(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      String templateLocation = "..";

      // Apply the template
      QbChart chart = new QbChart (parent, // container
                      QbChart.VIEW2D, // chart dimension
                      QbChart.BAR, // chart type
                      data, // data
                      columnMapping, // column mapping
                      templateLocation); // template

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is only there as a guide. However, the link contains a complete application code that can be run.

You can also take the column mapping from the template and have it applied on the QbChart object being created. This is done by passing in null instead of a ColInfo object.

3.9.5.3. Modifying Data Source

You can create chart templates in Designer and open those templates using the API. The QbChart object created uses the same data source as the template and attempts to fetch the data. However, it may be that while the template has all the look and feel needed, the data source may be an incorrect one. The following sections show how to switch the data source, without recreating the entire chart.

Please note that for best results, the number of columns and the data type of each column must match between the two data sources (i.e., the one used to create the template in Designer and the new data source).

After switching the data source, the QbChart object must be forced to fetch the new data. This can be done by calling the refresh method in the QbChart class.

3.9.5.3.1. Data from a Database

Switching the data source to point to a database is simple. All you would need to do is provide the database connection information as well as the query to be used and pass that to the QbChart object. You can provide the database connection information (as well as the query) in a DBInfo object (for more information on creating a DBInfo object, please refer to Appendix 3.B.1 - Data from a Database).

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, switches the data source of the QbChart object to a database:

Component doChartSwitchToDatabase(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "SwitchToDatabase.cht"); // template

      // New database connection information
      DBInfo newDatabaseInfo = new DBInfo(.....);

      try {
            // Switch data source
            chart.gethInputData().setDatabaseInfo(newDatabaseInfo);

            // Refresh the chart
            chart.refresh();

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is only there as a guide. However, the link contains a complete application code that can be run.

3.9.5.3.1.1. JNDI

You can also change the data source to a JNDI data source. This is done by specifying the JNDI connection information in a DBInfo object and then passing it to the QbChart object.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, switches the data source of the QbChart object to a JNDI database:

Component doChartSwitchToDatabaseJNDI(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "ChartSwitchToDatabaseJNDI.cht"); // template

      // New database connection information
      DBInfo newDatabaseInfo = new DBInfo(.....);

      try {
            // Switch data source
            chart.gethInputData().setDatabaseInfo(newDatabaseInfo);

            // Refresh the chart
            chart.refresh();

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is there only as a guide. However, the link contains a complete application code that can be run. Note that for the application code to run, the Woodview database needs to be set up as a JNDI data source in the Tomcat environment and the application code changed to match the connection information.

3.9.5.3.2. Data from a Data File (TXT/DAT/XML)

You can switch the data source to a text file as long as the text file follows the Quadbase guidelines (for more details, please refer to Appendix 3.B.2 - Data from a Data file (TXT/DAT/XML)).

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, switches the data source of the QbChart object to a text file:

Component doChartSwitchToDataFile(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "../templates/ChartSwitchToDataFile.cht"); // template

      try {
            // Switch data source
            chart.gethInputData().setDataFile(....);

            // Refresh the chart
            chart.refresh();

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is there only as a guide. However, the link contains a complete application code that can be run.

3.9.5.3.3. Data from an XML Data Source

You can switch the data source to your custom XML data as long as there is a .dtd or .xml schema accompanying your data. The XML data information is specified (for more details, please refer to Appendix 3.B.3 - Data from a XML Data Source) and then passed to the QbChart object.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, switches the data source of the QbChart object to XML data:

Component doSwitchToXMLData(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template

      QbChart chart = new QbChart (parent, // container
                      "../templates/ChartSwitchToXMLData.cht"); // template

      // XML data source information
      XMLFileQueryInfo newData = new XMLFileQueryInfo(...);

      try {
            // Switch data source
            chart.gethInputData().setXMLFileQueryInfo(newData);

            // Refresh the chart
            chart.refresh();

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      // Show Chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is there only as a guide. However, the link contains a complete application code that can be run.

3.9.5.3.4. Data from Custom Implementation

In addition to the regular data sources, you can also pass in your own custom data. The custom data is passed to the QbChart object using the IDataSource interface (for more details, please refer to Appendix 3.B.5 - Data Passed in your Custom Implementation).

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, switches the data source to a custom implementation:

Component doSwitchToCustomData(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "ChartSwitchToCustomData.cht"); // template

      try {
            // Switch data source
            chart.gethInputData().setClassFile(..);

            // Refresh the chart
            chart.refresh();

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is there only as a guide. However, the link contains a complete application code that can be run.

3.9.5.3.5. Data passed in an Array in Memory

You can also pass in data using arrays. The array data is usually stored is memory and passed to the QbChart object (for more details, please refer to Appendix 3.B.4 - Data Passed in an Array in Memory).

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, switches the data source to an array in memory:

Component doSwitchToArrayData(Applet parent) {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      // Open the template
      QbChart chart = new QbChart (parent, // container
                      "ChartSwitchToArrayData.cht"); // template

      // Create array data
      DbData newData = new DbData(...);

      try {
            // Switch data source
            chart.gethInputData().setData(newData);

            // Refresh the chart
            chart.refresh();

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      // Show chart in Viewer
      return chart;

}

Full Source Code

Exported Results

Please note that the above code is not complete and is there as a guide. However, the link contains a complete application code that can be run.

3.9.5.4. Modifying Chart Attributes

EspressReport has hundreds of properties, which provide a fine control over various elements of a chart. In order to facilitate ease-of-use, most properties have been categorized into groups and exposed in the form of interfaces. An application first obtains a handle to a group interface using a gethXXX method and then manipulates the chart's properties directly by calling methods on that interface. Most interfaces are contained in the quadbase.util and quadbase.ChartAPI packages.

3.9.5.4.1. Modifying Color, Font, ...

A chart is comprised of different elements (for instance, the canvas, the axis, the legend, the chart data, etc). Each element can be modified independently of the other by getting the appropriate interface and changing the properties by calling the methods therein.

For instance, the following code sets the background color of the chart to white:

chart.gethCanvas().setBackgroundColor(Color.white);    // chart being an object of type QbChart

while the code given below changes the color of the X axis to black:

chart.gethXAxis().setColor(Color.black);              // chart being an object of type QbChart

You can also set the color of the data elements of the chart based on the series or based on the category (if no series is defined). For example, if the chart is a Column chart with 5 elements in the series, the following code sets the columns colors in the series, to be yellow, orange, red, green and blue.

Color dataColors[] = {Color.yellow, Color.orange, Color.red, Color.green, Color.blue};
chart.gethDataPoints().setColors(dataColors);        // chart being an object of type QbChart

Note that the number of colors defined must match the number of unique elements in the series (or the category if the series is not defined).

Similarly, the font styles can be set by calling the appropriate interface and using the method. The following code sets the text used in the legend to be of Arial, bold type and size 15.

Font legendFont = new Font("Arial", Font.BOLD, 15);
chart.gethLegend().setFont(legendFont);             // chart being an object of type QbChart

while the following code sets the font and color of the labels used in the Y Axis:

Font YAxisFont = new Font("Helvetica", Font.ITALIC, 15);
chart.gethYAxis().gethLabel().setFont(YAxisFont);    // chart being an object of type QbChart
chart.gethYAxis().gethLabel().setColor(Color.blue);  // chart being an object of type QbChart

Similarly, other properties can be set using the methods in the interfaces.

3.9.5.4.2. Setting Predefined Patterns

The class QbPattern is a subclass of java.awt.Color, so there is no new method introduced to set patterns explicitly. You create a QbPattern object first, and then use it as if it is a Color object. The pattern feature is only applicable to data points. For other chart elements (such as axis, canvas), EspressReport will ignore the QbPattern properties, and use it just like a Color.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, shows how to set a pattern to a data point:

Color[] dataColors = chart.gethDataPoints().getColors();
QbPattern dataPattern = new QbPattern(colors[2], QbChart.PATTERN_THICK_FORWARD_DIAGONAL);
dataColors[2] = dataPattern;
chart.gethDataPoints().setColors(dataColors);

Full Source Code

Exported Results

There are totally 30 predefined patterns available for you to use. The pattern ID range from 0 to 29. If the user passes an integer beyond this range, it will be considered as ID = 0, which is a solid color block. The Pattern ID is defined in quadbase.ChartAPI.IMiscConstants class as well as in quadbase.common.swing.color.PatternImage class. Since QbChart implements the IMiscConstants interface, you can obtain these IDs directly from QbChart. You can also see what each pattern looks like in the pattern palette Designer.

3.9.5.4.3. Setting Customized Patterns

You can also set up your own pattern (texture) images. This feature is only available via API and the modification will not be saved to the template. This feature is mainly for those who want to modify the chart during the run time.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, shows how to set a custom pattern to a data point:

Color[] dataColors = chart.gethDataPoints().getColors();
QbPattern dataPattern = new QbPattern(dataColors[2]);
File customImageFile = new File("Quadbase_Logo.png");
BufferedImage customImage = ImageIO.read(customImageFile);
dataPattern.setPatternImage(customImage);
dataColors[2] = dataPattern;
chart.gethDataPoints().setColors(dataColors); 

Full Source Code

Exported Results

In the above code, a QbPattern object is created without specifying the pattern ID. The newly created object is equivalent to a java.awt.Color object. The developer is responsible for providing an image so as to avoid the NullPointerException prompting in the procedure. An existing image (from a file) is then passed as the pattern for data point 2.

3.9.5.4.4. Modifying Size

There are two sizes to be considered when creating a chart:

Relative Size

This size is defined relative to the chart canvas. For instance, the chart plot height might be set as .7 and the chart plot width set as .8 . In the case where the canvas is 300 by 300 pixels, the height of the chart plot becomes 210 (.7 x 300) pixels and the width becomes 240 pixels (or .8 x 300). If the canvas size is increased to 500 by 600 pixels, the height of the chart plot becomes 420 pixels (.7 * 600) and the width becomes 400 pixels (.8 * 500). Relative sizes depend on the canvas height and width.

Absolute Size

This size denotes an absolute size of the canvas in pixels.

Every element of the chart (where the size parameter is used) is defined relative to the chart canvas. A float is used to represent the relative size of the chart element. For instance, the following code sets the chart plot height to .85 and the chart plot width to .65:

chart.gethChartPlot().setRelativeHeight(.85f);    // chart being an object of type QbChart
chart.gethChartPlot().setRelativeWidth(.65f);     // chart being an object of type QbChart

The code given below sets the canvas size of the chart:

Dimension canvasSize = new Dimension(500, 450);
chart.gethCanvas().setSize(canvasSize);           // chart being an object of type QbChart

Similarly, the sizes of the other elements can be set using the methods in the interfaces.

3.9.5.4.5. Modifying Date/Time Zoom Charts

You can modify the properties (such as scale and starting/ending time perion) of a Date/Time Zoom template created in the Designer. This is done by getting a handle to the Zoom properties (using the IZoomInfo interface) and using the various methods there to change the presentation.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, shows how to modify a Date/Time Zoom chart:

// Modify starting and ending period and scale
IZoomInfo zoomInfo = chart.gethZoomInfo();

// Begin Date
Calendar beginDate = new GregorianCalendar(2001, 0, 1);

// End Date
Calendar endDate = new GregorianCalendar(2003, 11, 31);

zoomInfo.setLowerBound(beginDate.getTime());
zoomInfo.setUpperBound(endDate.getTime());

zoomInfo.setScale(6, IZoomInfo.MONTH);

chart.refresh();

Full Source Code

Exported Results

In the above code, chart is an object of type QbChart. Note that after modifying the chart's zoom properties, the chart must be refreshed for the modified properties to take effect.

3.9.5.4.6. Modifying Chart in Report

While stand-alone charts can be modified directly using the API, any charts in a report (whether the chart is independent or not) cannot be modified as easily. You can change the look and feel of a chart (in a report) by implementing IChartModifier interface to create a class that invokes the desired changes. Note that the actual chart template is not changed, merely the chart's appearance within the report.

The following example, which can be run as a applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application, shows how to modify a chart in a report:

ReportChartObject[] reportCharts = report.getReportChartObjects();
for (int i = 0; i < reportCharts.length; ++i)
{

      reportCharts[i].setChartModifier(new ModifyChart());

}

public class ModifyChart implements IChartModifier {

      public IChart modifyChart(Object chartInfo) {
            ChartObject chart = new ChartObject(chartInfo); // Get actual ChartObject
            chart.gethCanvas().setBackgroundColor(Color.white);
            return chart; }

}
                

Full Source Code

Exported Results Before Modification

Exported Results After Modification

3.9.5.5. Exporting the Chart

Any charts included in the report can be exported into JPEG, GIF and PNG formats as well; although by default, the charts in the report are exported as JPEG's. The format for the chart can be changed, when creating the ReportChartObject object, by specifying the image type use the method setImageType(int).

The EspressReport API has the capability to export stand-alone charts in a variety of formats. These include GIF, JPEG, PNG, BMP and PDF formats. In addition, a chart may be exported to the proprietary .cht or .tpl formats. A .cht stores all the chart information and can be considered the EspressReport equivalent of a static image file. A .cht file differs from a static image file in that its data can be refreshed from the data source and it allows additional functionality such as zooming, drill-down etc A .tpl file is identical to a .cht file except it doesn't store actual data. For a .tpl file, the data is automatically reloaded from the original data source at the time of chart reload. Both .cht and .tpl files can be viewed using the EspressReport Viewer or EspressReport API. When using stand-alone charts, you can specify the format by creating a QbChart object and using the various export methods within the class.

There are different methods available for exporting a stand-alone chart in a variety of formats with different options. The simplest method would be:

public export(int format, String filename)

In the above method, format is one of the format constants and filename is the output filename (with or without an extension).

The following is a list of the constants used for exporting the chart components:

Bitmap

QbChart.BMP

GIF

QbChart.GIF

JPEG

QbChart.JPEG

PNG

QbChart.PNG

PDF

QbChart.PDF

Flash

QbChart.FLASH

Scalable Vector Graphics

QbChart.SVG

Text Data

QbChart.TXTFORMAT

XML Data

QbChart.XMLFORMAT

Windows Meta File

QbChart.WMF

Depending on the format selected, additional options are also available. For example, exporting a chart object as a jpeg gives you the choice of the image quality (represented as number from 0 - 99) while export a chart object as a PNG gives you the choice of specifying the compression used. The options can be specified using the following method:

public export(int format, String filename, int option)

The following code, which can be run as an applet or application, shows how to construct and export a chart:

// Open the template
QbChart chart = new QbChart(parent, "ExportChart.cht");

try {

      chart.export(QbChart.PNG, "ExportChart");

} catch (Exception ex) {

      ex.printStackTrace();

}

Full Source Code

Exported Results

Please note that when you export the chart to a text file, the default delimiter is a tab space. However, you can set another delimiter (available delimiters are ,, ; and ) by using the following method:

chart.exportDataFile("TextData", QbChart.COMMA, QbChart.TXTFORMAT);    // where chart is an object of type QbChart

If you plan on exporting the chart object without viewing it, setting the following static method to true would improve performance slightly:

QbChart.setForExportOnly(boolean);

Calling this method before constructing the QbChart object would result in better performance.

You can also export the QbChart object to a byte array using the following method:

public byte[] exportChartToByteArray();

This will give the .cht equivalent in the form of a byte array. This is useful if you need to serialize the QbChart object.

3.9.5.5.1. Record File Exporting

EspressReport also has record file exporting to handle large amounts of data. In record file exporting, you specify the number of records to be held in memory and a temp directory. When the number of records in the data exceeds the number specified to be held in memory, the data is stored on disk in the temp directory specified.

There are certain conditions that have to be met before you can use this feature. You must:

  • make sure that EspressManager is not used;

  • make sure that the data is NOT from a XML source;

  • make sure that the data is sorted;

To use record file export, the following code must be added before calling the QbChart constructor:

QbChart.setEspressManagerUsed(false);
QbChart.setTempDirectory(<specify the temp directory to store data. Default is ./temp>);
QbChart.setMaxCharForRecordFile(<specify the maximum character length. Default is 40>);
QbChart.setMaxRecordInMemory(<specify the maximum number of rows to be kept in memory. Default is -1 i.e., store all records in memory>);
QbChart.setFileRecordBufferSize(<specify the number of rows to be retrieved at one time from disk. Default is 10,000>); 
3.9.5.5.2. Streaming Charts

In addition to exporting to local drives, charts can also be exported as a byte stream and streamed directly to a web browser. Note that server side code typically exports the image only in a binary format. You are responsible for creating a wrapper (i.e., DHTML/HTML content) around the exported image.

Given below is an example that exports a chart to PNG and streams it to the browser. In order to run the example, you will need to configure and compile the source code, then deploy the class file in the servlet directory of your servlet runner. Replace the chartTemplate variable with either an absolute path or a path relative to the working directory of your application server.

public void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {

      // Do not use EspressManager
      QbChart.setEspressManagerUsed(false);

      String chartTemplate = "StreamingChart.cht";

      // Open template
      QbChart chart = new QbChart((Applet)null, chartTemplate);

      // Export the chart to PNG and stream the bytes
      ByteArrayOutputStream chartBytes = new ByteArrayOutputStream();

      try {
            chart.export(QbChart.PNG, chartBytes); 

      } catch (Exception ex)
      {
            ex.printStackTrace();

      }

      resp.setContentType("image/x-png");
      resp.setContentLength(chartBytes.size());

      OutputStream toClient = resp.getOutputStream();
      chartBytes.writeTo(toClient);
      toClient.flush();
      toClient.close();

}

Full Source Code

To run the example, make sure to copy the chart template to the location accessed by the code. If using a relative path (as shown in the example), remember that the current directory is the working directory of your application server. For example, since the working directory in Tomcat is <Tomcat>/bin, you will need to create the directory <Tomcat>/templates/ and copy the chart template there to run the code. The resulting chart is shown below.

Streaming Chart

3.9.6. API Only Features

While EspressReport API can reproduce all the functionality of Chart Designer, the API also has additional functionalities. These additional features will be described below. Please note that some of the features are for stand-alone charts only.

[Note]Note

Note that in the snippets of code provided, chart is an object of type QbChart.

3.9.6.1. Visual

The features, shown below, deal with the presentation of the chart and its components. Each feature below changes the chart, in some manner, visually. These changes are also carried forth when exported to a static image.

3.9.6.1.1. Canvas/Plot

The following features describe the various visual changes that can be made to the chart plot and/or canvas using the API. Note that the features below deal with general changes to the chart plot and/or canvas. Any component specific change is described in its own section.

3.9.6.1.1.1. Customizable Message for No-Data-In-Plot

EspressReport allows the message, which gets displayed when there is no data or not enough data to be plotted, to be changed. This can be done by getting a handle to the INoDataToPlotMessage and specifying the new message.

INoDataToPlotMessage noData = chart.gethNoDataToPlotMessage();
noData.setMessage("Not enough data to plot chart");

Please refer to the online API documentation for more information (quadbase.util.INoDataToPlotMessage).

3.9.6.1.1.2. Set Chart to Fit Canvas

EspressReport allows charts to be resized and fit into the canvas correctly, taking into account all the text and labels associated with the chart. To correctly fit a chart onto its canvas, use the method setFitOnCanvas(boolean b) in the ICanvas interface.

ICanvas canvas = chart.gethCanvas();
canvas.setFitOnCanvas(true);

Please refer to the online API documentation for more information (quadbase.util.ICanvas).

3.9.6.1.1.3. Set Chart Invisible

A chart can be made invisible so that only the plot data in table form is shown. This is accomplished by getting a handle to the ICanvas interface and using the setChartVisible method.

ICanvas canvas = chart.gethCanvas();
canvas.setChartVisible(false);

Please refer to the online API documentation for more information (quadbase.util.ICanvas).

3.9.6.1.1.4. Applying Different Graphics Rendering

EspressReport allows you to apply different rendering techniques (such as anti-aliasing) to the chart. This allows you to draw the chart to your specifications.

To utilize this feature in the API, call the setRenderingHint method in QbChart and pass in the hint key and hint value parameters.

chart.setRenderingHint(java.awt.RenderingHints.KEY_ANTIALIASING, java.awt.RenderingHints.VALUE_ANTIALIAS_ON);

You can also specify the horizontal text to be anti-aliased only.

chart.forceApplyAntiAliasToHorizontalText(true);

Please refer to the online API documentation for more information (quadbase.ChartAPI.QbChart).

This functionality is only available for stand-alone charts.

3.9.6.1.1.5. Chart Plot Position

EspressReport allows the chart position to be placed down to -0.5 (x and y position relative to the canvas). This allows the chart to be placed right along the edge of the canvas.

To utilize this feature using the API, get a handle to IPlot and use the setPosition method.

IPlot chartPlot = chart.gethChartPlot();
chartPlot.setPosition(new Position(-0.5, -0.5));

Please refer to the online API documentation for more information (quadbase.util.IPlot).

3.9.6.1.1.6. Drawing Multiple Charts in same Plot

EspressReport allows multiple charts to be overlapped and shown one above the other (using the primary chart's axes). The canvas of the primary chart is used and therefore 2D charts cannot be added to 3D charts and vice versa. All charts overlapped onto the primary chart will have any text and canvas information removed. Please note that since resulting chart will use the primary chart's category and scale, add on charts must also use the similar categories and scales to be displayed correctly. For Scatter and Surface charts, both x and y axis scales should be taken into consideration.

To utilize this feature using the API, you would use the setAddOnChart method in QbChart.

The following code, which can be run as an applet or application, shows how to overlap 3 charts in one plot:

// Open the template
QbChart primaryChart = new QbChart(parent,                                        // container
                                   "../templates/AddOnChart1.cht"); // template

// Open other two templates
QbChart chart2 = new QbChart(parent, "../templates/AddOnChart2.cht");
QbChart chart3 = new QbChart(parent, "../templates/AddOnChart3.cht");

primaryChart.setAddOnChart(new QbChart[] {chart2, chart3});

Full Source Code

Exported Results

Please refer to the online API documentation for more information (quadbase.ChartAPI.QbChart).

3.9.6.1.2. Hint Box

The following features describe the various visual changes that can be made to the chart hint box using the API. These include modifying the content as well as look of the hint box.

3.9.6.1.2.1. Modify Hint Box

EspressReport allows the Hint Box to be modified, i.e., you can dictate what the Hint Box says when it is viewed. This is done by creating a class that implements IHintBoxInfo and assigning that class using the method setHintBoxInfo in IHint.

The following code, which can be run as an applet or application, shows how to modify the hint box info:

// Open the template
QbChart chart = new QbChart(parent,                                          // container
                            "../templates/ModifyHintBox.cht"); // template

IHintBoxInfo hintBoxInfo = new Hint();
chart.gethDataPoints().gethHint().setHintBoxInfo(hintBoxInfo);

...

class Hint implements IHintBoxInfo {

      public Vector getHint(PickData pickData) {
            Vector vec = new Vector();

            if (pickData.series != null)
                  vec.addElement("(" + pickData.seriesName+ ") " + pickData.s_series);

            if (pickData.category != null)
                  vec.addElement("(" + pickData.categoryName + ") " + pickData.s_category);

            if (pickData.s_value != null)
                  vec.addElement("(" + pickData.valueName + ") " + pickData.s_value + (pickData.value > 7 ? ":Good" : ":Restock"));

            return vec;

      }

}

Full Source Code

Exported Results

Please refer to the online API documentation for more information (quadbase.util.IHintBoxInfo).

This functionality is only available for stand-alone charts.

3.9.6.1.2.2. Data and Hyperlink Hint Box Offset

EspressReport allows an offset to be set for the Data and the HyperLink hint box so that it doesn't overlap the chart or any other component in the chart.

To utilize this feature in the API, get a handle to IHint (from either the chart object or the IHyperLinkSet object) and then use the setOffset method.

IHint dataHints = chart.gethDataPoints().gethHint();
dataHints.setoffset(new Dimension (30, 20));

Please refer to the online API documentation for more information (quadbase.util.IHint).

3.9.6.1.2.3. Hint Box Border Color

EspressReport allows the color of the Hint box border to be set using the API. This can be done by getting a handle to IHint and using the setBorderColor method.

IHint chartHintBox = chart.gethHint();
chartHintBox.setBorderColor(Color.red);

Please refer to the online API documentation for more information (quadbase.util.IHint).

3.9.6.1.2.4. Customize Image Map Hint Box

EspressReport allows the customization of the hint box text when exporting the chart to a map file. When the map file is included in a DHTML/HTML file, the customized hint box is visible when the mouse is moved over the data points of the chart. You can create a customized image map hint box by creating a class that implements ICustomizedImageDataMapHintBox and assign that class to the setImageMapDataHintBoxHandle method in QbChart.

The following code, which can be run as an applet or application, shows how to customize the image map hint box:

// Open the template
QbChart chart = new QbChart(parent,                                          // container
                            "../templates/CustomizeImageMapHintBox.cht"); // template

chart.setImageMapDataHintBoxHandle(new customizeImageMap());

try {

      chart.export(QbChart.PNG, "../export/CustomizeImageMapHintBox", "../export/CustomizeImageMapHintBox", 0, 0, true);

} catch (Exception ex) {

      ex.printStackTrace();

}

...

class customizeImageMap implements ICustomizeImageMapDataHintBox {

      public String customizeHintBox(String str) {
            return str.substring(6, 11) + " " + str.substring(str.length()-3);

      }

}

Full Source Code

Exported Map

Exported Image

Please refer to the online API documentation for more information (quadbase.util.ICustomizeImageMapDataHintBox).

3.9.6.1.3. Legend/Annotation

The following features describe the various visual changes that can be made to the chart legend and/or any annotation using the API. These include modifying the content as well as look of the chart legend/annotations.

3.9.6.1.3.1. Annotation with Symbol

EspressReport allows symbols to be included with an Annotation thus allowing symbols and strings to be placed in the chart. One of the applications of this feature is to create your own legend in place of the default legend created by EspressReport.

A new constructor has been created for IAnnotation, which can be used for adding symbols and text.

The following code, which can be run as an applet or application, shows how to combine symbols with an Annotation:

// Open the template
QbChart chart = new QbChart(parent,                                                 // container
                            "../templates/AnnotationWithSymbol.cht"); // template

// Create custom legend
IAnnotationSet set = chart.gethAnnotations();
String[] text = {"New Legend", "Hello World", "ABC", "I got It"};
int[] shape = {QbChart.PLUS, QbChart.NOSYMBOL, QbChart.SQUARE, QbChart.DASH};
Color[] color = {Color.red, Color.black, Color.blue, Color.white};
IAnnotation anno = set.newAnnotation(text, shape, color);
Point_2D newPosition = new Point_2D(.7f, .7f);
anno.setRelativePosition(newPosition);
set.addAnnotation(anno);

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.IAnnotationSet and quadbase.util.IAnnotation).

3.9.6.1.3.2. Set Relative Shift of Annotation Border

EspressReport allows shift of Annotation border from Relative Position of Annotation and Annotation text. The following methods allows you to set Shift in x,y axis in pixels.

void setxShift(int x);
void setyShift(int y);

Please refer to the online API documentation for more information (quadbase.util.IAnnotation).

3.9.6.1.3.3. Set Reference Position of Legend and Annotation Text

EspressReport allows the reference positions of legend and any annotation texts to be set at either the upper left corner or default position (lower left corner). To change the reference position to the upper left position, you would use the setReferenceAtTop method in ICanvas.

ICanvas canvas = chart.gethCanvas();
canvas.setReferenceAtTop(true);

Please refer to the online API documentation for more information (quadbase.util.ICanvas).

3.9.6.1.4. Misc.

The following features describe the various visual changes that can be made to the different components of the chart. These include modifying the content as well as look of the chart and its elements.

3.9.6.1.4.1. Ticker Label Replacement

EspressReport allows ticker labels to be replaced by user-defined strings. This enables the users to put in their own ticker values.

To replace ticker labels, use the method setTickerLabels in IAxis.

IAxis hXAxis=chart.gethXAxis();
hXAxis.setTickerLabels(new String[] {new String("a"), new String("b"), new String("c")});

Please refer to the online API documentation for more information (quadbase.util.IAxis).

3.9.6.1.4.2. Customizable Data Top Label

EspressReport allows data top labels for both primary and secondary charts to be customized. You can do this by creating a class that implements IDataLabelInfo and passing that class using the setDataLabelInfo method in IDataPointSet.

The following code, which can be run as an applet or application, shows how to combine symbols with an Annotation:

// Open the template
QbChart chart = new QbChart(parent,                                                  // container
                            "../templates/CustomizeDataTopLabel.cht"); // template

chart.gethDataPoints().setDataLabelInfo(new customizeDataTopLabel());

...

class customizeDataTopLabel implements IDataLabelInfo {

      public String getDataLabel(PickData pickData, String originalDataLabel) {
            return (pickData.toString() + " (" + originalDataLabel + ")")

      }

}

Full Source Code

Exported Image

Note that any customization to the data top labels will not be evident unless they are visible.

Please refer to the online API documentation for more information (quadbase.util.IDataLabelInfo).

3.9.6.1.4.3. Show Axis as Date/Time/Timestamp

EspressReport allows the value axis to be shown in units of time/date (instead of numeric units) for any chart, which has a value axis. Note that the data for the value axis must still be numeric.

To utilize this feature using the API, get a handle to IAxis and use the setDisplayLabelAsDate method.

IAxis chartYAxis = chart.gethXAxis();
chartXAxis.setDisplayLabelAsDate(true);

Please refer to the online API documentation for more information (quadbase.util.IAxis).

3.9.6.1.4.4. Selective String Rendering

Strings, which are drawn horizontally or vertically, look better when not anti-aliased. However, strings at other angles look better when anti-aliased. EspressReport allows certain text to be anti-aliased and other strings (0 and 90 degree angles) to be drawn without anti-aliasing.

To utilize this feature using the API, get a handle to IDataPointSet and use the setDisableJava2DForStraightText method.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.setDisableJava2DForStraightText(true);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.1.4.5. Drawing Data Points above Horizonval/Vertical/Trend Lines

EspressReport allows the data points to be drawn on top of any horizontal/vertical/trend lines i.e., it appears like the data points are resting on top of the line instead of being overshadowed by the line.

To utilize this feature using the API, get a handle to ILinePropertySet and use the method setDataDrawnOnTop.

ILinePropertySet lineProperties = chart.gethLineProperties();
lineProperties.setDataDrawnOnTop(true);

Please refer to the online API documentation for more information (quadbase.util.ILinePropertySet).

3.9.6.2. Data

The features, shown below, deal with the data in the chart and its components. Each feature below changes data shown (typically the presentation of the data shown) or obtains the data in the chart. These changes are also carried forth when exported to a static image.

3.9.6.2.1. Getting the Coordinates

EspressReport allows you to get the information of a datapoint based on a specified pixel position. This returns the category, value, series and sumby (if they are there) of the data point at the specified pixel location and otherwise returns null.

To get pickData, use the method getPickData(width, height) in IHint.

IDataPointSet dataPoints=chart.gethDataPoints();
IHint hint=dataPoints.gethHint();
PickData pickdata=hint.getPickData(200, 300)        // pixel at width=200 and height=300

Please refer to the online API documentation for more information (quadbase.util.IHint).

3.9.6.2.2. Set Data Limit at Axis Scale

When a manual axis is applied, EspressReport gives you the option to truncate data points that are beyond the maximum value on the axis. You can set the data limit by using the method setLimitAtAxisScale in IDataPointSet.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.setLimitAtAxisScale(true);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.2.3. Set Null Data as Zero

EspressReport can now represent any null data as zero data (i.e., datapoints with an associated 0 value). To accomplish this, use the setNullDataAsZero method in IDataPointSet.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.setNullDataAsZero(true);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.2.4. Additional Trend Line Options

EspressReport allows you to get the minimum, the maximum, the probability as well as the inverse normal in addition to the mean value for the normal curve trend line as well as draw standard deviation trend lines, by calling ITrendLine and using the appropriate method.

To utilize this feature in the API, you need to call ITrendLine and use the appropriate methods.

[Note]Note

You can only draw standard deviation trend lines for a normal curve if the chart is a histogram chart with setLinearScale and setRounded true.

The following code, which can be run as an applet or application, shows how to get information from a normal curve trendline in the chart:

ITrendLine normalCurve = (ITrendLine)chart.gethDataLines().elements().nextElement();
System.out.println("Mean = " + normalCurve.getMean());
System.out.println("St. Dev = " + normalCurve.getStandardDev());
System.out.println("Min = " + normalCurve.getMin());
System.out.println("Max = " + normalCurve.getMax());
System.out.println("Dev of 1.0, Prob = " + normalCurve.getProbability(1.0));
System.out.println("Back Calculated Dev = " + normalCurve.getInverseNorm(normalCurve.getProbability(1.0)));

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.ITrendLine).

3.9.6.2.5. Adding Multiple Control Lines to Stack Type Chart

EspressReport allows you to draw the minimum, the maximum, the average in addition to the stand deviation lines of any level exsisting in the stack data together, by calling newControlLine(int linetype, String label, int level) method with proper parameters setting.

To utilize this feature in the API, you need to set the right parameter value, for the parameter of linetype: MINIMUM = 12, MAXIMUM = 13, CONTROL_AVERAGE = 10, STANDARD_DEVIATION = 11.

The parameter of label is the text dispaly in the legend.

The last parameter of level is the level of the data display int the stack chart.

[Note]Note

This feature only works for Stack Type Chart, i.e., stack column, stack bar and stack area. For stack column chart with combo type is stack area, this feature only works for the main axis data, that is, stack column chart.

The following code, which can be run as an applet or application, shows how to draw multiple control lines to a stack area chart:

QbChart chart = new QbChart(this, QbChart.VIEW2D, QbChart.STACKAREA, "sample.dat",colInfo);

IDataLineSet hDataLines = chart.gethDataLines();

IControlLine clLine1 = hDataLines.newControlLine(13, "Max4", 4);  
IControlLine clLine2 = hDataLines.newControlLine(13, "Max3", 3);
IControlLine clLine3 = hDataLines.newControlLine(13, "Max2", 2);  
IControlLine clLine4 = hDataLines.newControlLine(13, "Max1", 1);
IControlLine clLine5 = hDataLines.newControlLine(10, "Avg4", 4);
clLine1.setColor(Color.RED);
clLine2.setColor(Color.YELLOW);
clLine3.setColor(Color.GREEN);
clLine4.setColor(Color.BLUE);
clLine5.setColor(Color.GRAY);
hDataLines.add(clLine1);
hDataLines.add(clLine2);
hDataLines.add(clLine3);
hDataLines.add(clLine4);
hDataLines.add(clLine5);

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.IControlLine).

3.9.6.3. Chart Specific

The features, shown below, deal with the specific chart types. Each feature below shows additional functionality available to the chart, depending on the chart type. These changes are also carried forth when exported to a static image.

3.9.6.3.1. Column/Bar Charts

The following features describe the various changes that can be made to column/bar charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.1.1. Color Separator

EspressReport allows different colors to be shown for the columns based on defined category values. To use color separator, use the method setColorSeparators in IDataPointSet.

The following code, which can be run as an application or applet, shows how to set up the color separator:

IDataPointSet hDataPoints=chart.gethDataPoints();
hDataPoints.setColorSeparators(new Color[]{Color.green, Color.red, Color.blue},
                               new Integer[]{new Integer((int)Math.rint(9)), new Integer((int)Math.rint(14))},
                               QbChart.ASCENDING);

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.1.2. Disabling Shadow

EspressReport allows the shadow that appears for the columns/bars to be rendered visible or invisible. You can use this feature by getting a handle to IDataPointSet and use the setShowShadowOnPoint method.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.setShowShadowOnPoint(false);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.2. Pie Charts

The following features describe the various changes that can be made to pie charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.2.1. Drawing Pie Slices Clockwise/Counter Clockwise

EspressReport now allows the slices in a pie chart to be drawn in clockwise as well as counter clockwise order. To set the clockwise/counter clockwise option, use the reverseOrder method in IDataPointSet.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.reverseOrder(QbChart.CATEGORY);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.2.2. Pie Border for 0% and 100% Slices

EspressReport offers the option of removing the pie border for slices that are 0% or 100% of the whole pie. You can do this by getting a handle to IPiePropertySet and use the setRadialBorderDrawnForZero method.

IPiePropertySet pieProperties = chart.gethPieProperties();
pieProperties.setRadialBorderForZero(true);

Please refer to the online API documentation for more information (quadbase.util.IPiePropertySet).

3.9.6.3.2.3. Customize Separator between Category and Percent Value Strings in Pie Legend

EspressReport allows user-defined separators to be placed between the Category and Percent Value Strings in the legends for Pie Charts. This can be done by getting a handle to IPiePropertySet and use the setSepSymbol method.

IPiePropertySet pieProperties = chart.gethPieProperties();
pieProperties.setSepSymbol(",");

Please refer to the online API documentation for more information (quadbase.util.IPiePropertySet).

3.9.6.3.2.4. Pie Border Color Customizable

EspressReport allows the user to specify the color for the pie border. This is accomplished by using the setBorderColor method in IPiePropertySet.

IPiePropertySet pieProperties = chart.gethPieProperties();
pieProperties.setBorderColor(Color.red);

Please refer to the online API documentation for more information (quadbase.util.IPiePropertySet).

3.9.6.3.3. Line Charts

The following features describe the various changes that can be made to line charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.3.1. Line Area

EspressReport allows you to create line areas between a horizontal line and the data line to denote the change. For example, you could have a horizontal line at 25 and a data line. All areas enclosed by the data line and horizontal line and above the horizontal line can be one color and all areas enclosed by the horizontal line and data line and below the horizontal line can be another color. Please note that this feature is only available for 2D Line charts with no series. Also note that you need to set the color above and below the horizontal line in order to use this feature.

To use this feature in the API, you must get a handle to ILinePropertySet and use the setAreaVisible and setAreaColors methods.

The following code, which can be run as an applet or application, shows how to use line area:

ILinePropertySet lineProperties = chart.gethLineProperties();
lineProperties.setAreaVisible(true);
lineProperties.setAreaColors(Color.green, Color.yellow);

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.ILinePropertySet).

3.9.6.3.4. Scatter Charts

The following features describe the various changes that can be made to scatter charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.4.1. Show Series in Top Label

EspressReport allows series to be shown in the top labels for scatter charts. This can be done by using the method showSeriesInTopLabel in IDataPointSet.

IDataPointSet dataPoints=chart.gethDataPoints();
dataPoints.showSeriesInTopLabel(true);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.4.2. Drawing Order

EspressReport allows the connecting lines for a Scatter chart to be drawn in the order of the dataset. For example, if the data contains the following points (0, 2), (3, 4), (1, 2), (2, 5), the default presentation for the connecting lines would generate a line from (0, 2) to (1, 2) to (2, 5) and finally (3, 4). However, you can generate the connecting lines in the order of the data.

To utilize this feature using the API, get a handle to IDataPointSet and use the setConnectLinesInOriginalOrder method.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.setConnectLinesInOriginalOrder(true);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.4.3. Scatter Chart Cube Width

EspressReport allows the cube width of 3D Scatter charts to be changed to any size. To modify the cube width, first get a handle to IDataPointSet and use the setScatterCubeWidth method.

IDataPointSet dataPoints = chart.gethDataPoints();
dataPoints.setScatterCubeWidth(15);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.5. Overlay Charts

The following features describe the various changes that can be made to overlay charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.5.1. Multiple Axes Titles

EspressReport allows the setting of a different title for each axis in an overlay chart. This can be done by getting a handle to each individual axis and using the gethTitle().setValue method. You get the handle to the individual axis by specifying the layer.

IAxis axis0 = chart.gethYAxis();
axis0.gethTitle().setValue("XYZ");

IAxis axis1 = chart.gethAxis(1); // Get axis of Layer 1
axis1.gethTitle().setValue("ABC");

IAxis axis2 = chart.gethAxis(2); // Get axis of Layer 2
axis2.gethTitle().setValue("DEF");

Please note that before you set the titles, you need to draw the chart in the background.

Please refer to the online API documentation for more information (quadbase.util.IAxis).

3.9.6.3.6. Dial Charts

The following features describe the various changes that can be made to dial charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.6.1. Control Area Scale Labels

EspressReport allows the starting and ending scale of a control area to be shown as labels. This can be done by obtaining a handle to a control area and use the setShowLabel method.

ControlRange cr1 = chart.gethControlRanges().elementAt(0);
cr1.setShowLabel(true);

Please refer to the online API documentation for more information (quadbase.util.ControlRange).

3.9.6.3.7. HLCO Charts

The following features describe the various changes that can be made to HLCO charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.7.1. Changing Candle Stick Color

EspressReport allows you to change the candlestick color for HLCO charts using the API only. To do so, you will need to get a handle to IDataPointSet and use setCandleStickColors method.

IDataPointSet dataPoints = chart.gethDataPoints();
// Up color is green, Down color is red
dataPoints.setCandleStickColors(Color.green, Color.red);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.7.2. Changing Candle Stick Wicker Width

EspressReport allows you to change the candlestick wicker width (the upper and lower extensions of candlesticks) for HLCO charts using the API only. To do so, you will need to get a handle to IDataPointSet and use the method setCandleStickWidth. The number passed is the ratio of the candle wicker width to the candle width.

IDataPointSet dataPoints = chart.gethDataPoints();
// Set width to 0.5
dataPoints.setCandleStickWidth((float)0.5);

Please refer to the online API documentation for more information (quadbase.util.IDataPointSet).

3.9.6.3.8. Surface Charts

The following features describe the various changes that can be made to surface charts using the API. These include modifying the content as well as look of the chart.

3.9.6.3.8.1. Heat Map

EspressReport allows users to draw a surface chart like a contour map. Basically, the surface chart can be drawn in sections, with different colors according to the threshold values specified.

The following code, which can be run as an applet or application, shows how to create a surface chart with a heat map:

double [] heatMapValues = {3, 6};
Color [] heatMapColors = { Color.green, Color.yellow, Color.red};
ColorSpectrum heatMapColorSpectrum = new ColorSpectrum(heatMapColors, heatMapValues);
I3DPropertySet set = chart.geth3DProperties();
set.setColorSpectrum(heatMapColorSpectrum);

The code above creates a 3D surface chart with 3 color sections, green, yellow and red. The threshold values determining the colors are 3 and 6.

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.ColorSpectrum and quadbase.util.I3DPropertySet).

3.9.6.4. Performance

The features, shown below, deal with improving the performance of the chart generation and export. Each feature below shows additional functionality available to the chart, to decrease memory resources and time needed to generate the chart.

3.9.6.4.1. BufferedImage or Frame

EspressReport allows the choice of using either java.awt.image.BufferedImage or java.awt.Frame during export to improve performance. By default, EspressReport uses java.awt.Frame to create the chart object. Using java.awt.Frame gives better performance as the number of data points increases while using java.awt.image.BufferedImage yields better performance on larger chart dimensions. This is done by using the setBufferedImageUsed method in QbChart.

chart.setBufferedImageUsed(true);

Please refer to the online API documentation for more information (quadbase.ChartAPI.QbChart).

This functionality is only available for stand-alone charts.

3.9.6.4.2. Chart Generation Order

EspressReport allows you to choose the order in which the chart is generated and even add elements in the generation of the chart using the API only. For example, you can now draw a background, and then a circle and have the chart generated in the center of the circle to create a chart. You can do this by creating a class that implements the IChartGraphics interface and then assigning the class to the setChartGraphics method in QbChart. In essence, the IChartGraphics interface allows you to add or modify any graphics information before or after drawing the chart.

The following code, which can be run as an applet or application, shows how to generate charts and graphics in a specific order:

// Open the template
QbChart chart = new QbChart(parent,                                          // container
                            "../templates/ChartGeneration.cht"); // template

chart.setChartGraphics(new chartGenerationGraphics());;

...

class chartGenerationGraphics implements IChartGraphics {

      public void initializeGraphics(Graphics g, int w, int h) {
            g.setColor(Color.red);
            g.fillOval(50, 50, 400, 400);

      }

      public void finalizeGraphics(Graphics g, int w, int h) {
            g.setColor(Color.white);
            g.fillOval(125, 225, 50, 50);
            g.setColor(Color.orange);
            g.drawString("HELLO WORLD", 150, 250);

      }

}

Full Source Code

Exported Image

Please refer to the online API documentation for more information (quadbase.util.IChartGraphics).

This functionality is only available for stand-alone charts.

3.9.6.5. Viewer

The features, shown below, deal with the Viewer when viewing the chart in either a java application or java applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file). Each feature below shows additional functionality available to Chart Viewer.

3.9.6.5.1. Call Back Mechanism

EspressReport has a call back mechanism for higher levels to handle the event. When a data object in the chart is selected by the viewer, an action event is generated. The event argument contains an instance of PickData, which provides information of the series, category, value, etc of the data point selected.

The following code, which can be run as an applet or application, shows how to capture an event:

static TextField textField;

// Open the template
QbChart chart = new QbChart(parent,                                   // container
                            "../templates/CallBack.cht"); // template

chart.setActionListener(new callBackActionListener());;

...

class callBackActionListener implements ActionListener {

      public void actionPerformed(ActionEvent e) {
            Object arg = ((QbChart) e.getSource()).getArgument();

            String click;

            switch (e.getModifiers()) {

            case QbChart.LEFT_SINGLECLICK:
                  click = "Left single click";
                  break;

            case QbChart.LEFT_DOUBLECLICK:
                  click = "Left double click";
                  break;

            case QbChart.RIGHT_SINGLECLICK:
                  click = "Right single click";
                  break;

            case QbChart.RIGHT_DOUBLECLICK:
                  click = "Right double click";
                  break;

            default: // shall not happen
                  click = "Error !";

            }

            if (arg instanceof PickData)
                  textField.setText(((PickData) arg).toString() + " " + click);

            else
                  textField.setText((String) arg + " " + click);

      }

}

Full Source Code

Exported Image

This functionality is only available for stand-alone charts.

3.9.6.5.2. Disable/Enable Tool Tips Text

EspressReport allows the tool tips text for the navigation panel to be enabled and disabled. This can be done by using the method setToolTipEnabled in I3DControlPanel. Note that this option is for 3D charts only.

I3DControlPanel controlPanel = chart.geth3DControlPanel();
controlPanel.setToolTipEnabled(true);

Please refer to the online API documentation for more information (quadbase.util.I3DControlPanel).

3.9.6.5.3. Canvas Area

EspressReport allows the viewpanel containing the canvas to be selected so that more event properties (i.e., user defined event properties) can be added. You can do this by getting a handle to ICanvas and using the getCanvasArea() method to return the component.

ICanvas chartCanvas = chart.gethCanvas();
Component chartCanvasComponent = chartCanvas.getCanvasArea();

Please refer to the online API documentation for more information (quadbase.util.ICanvas).

3.9.7. Changing Chart Viewer Options

At times, you may want to configure what users can or cannot do when they are viewing the chart using the Chart Viewer.

When the user is using Chart Viewer to view the chart, right clicking on the chart causes a menu to pop up. Using this menu, the user can select chart options such as changing chart type, changing chart dimension etc The user can also choose to export the chart and the type of the static image. While the default pop-up menu lists all available choices, API methods exist that control what options are available in the pop-up menu of Chart Viewer.

These API calls are available in IPopupMenu:

IPopupMenu popupMenu = chart.gethPopupMenu();
popupMenu.setDimMenuEnabled(boolean b);
popupMenu.setPopupMenuEnabled(boolean b);
popupMenu.setTypeMenuEnabled(boolean b); 

Please refer to the online API documentation for more information (quadbase.util.IPopupMenu).

3.9.8. Javadoc

Javadoc for the entire API is provided along with EspressReport. The API covers both the Chart and the Charting API. It is located at Quadbase website.

3.9.9. Swing Version

1.1 JFC/Swing versions of the EspressReport charting API is also available. For more details, please refer to quadbase.ChartAPI.swing package.

3.9.10. Summary

The EspressReport API provides an easy-to-use, yet powerful charting library for business applications. Combined with Chart Designer, programming is as simple as adding one line of code to your applet(More in: Section 1.2.7 - Run Applets in WebStart with JNLP file) or application. All of the attributes of a chart may be set in a template file, which can be created with the EspressReport Designer.