<html xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://jasperreports.sourceforge.net/jasperreports">
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>JasperReports 4.0.2 - Charts Sample</title>
<style type="text/css">
.title {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 28px;
font-weight: normal;
}
.toc {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.name {
font-family: Courier New, Courier, serif;
font-size: 16px;
font-weight: bold;
}
.label {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: bold;
font-style: italic;
}
.description {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: normal;
}
.value {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.element {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.attribute {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: bold;
}
.code {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.copy {
font-decoration: none;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 8pt;
font-style: normal;
color: #000000;
}
.subtitle {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: bold;
text-decoration: none;
color: inherit;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td colspan="2" align="right"><span class="element"><a href="../../sample.reference.html">Sample Reference</a> - <a href="../../schema.reference.html">Schema Reference</a> - <a href="../../config.reference.html">Configuration Reference</a> - <a href="http://jasperreports.sourceforge.net/api/index.html">API (Javadoc)</a></span>
<br>
</td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
<tr valign="middle">
<td nowrap="true"><span class="title">JasperReports - Charts Sample (version 4.0.2)</span></td><td align="right"><img src="../../resources/jasperreports.png" border="0"></td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
</table>
<br>
<span class="description"><span class="description">Shows how the chart element could be used to render different types of charts.</span></span>
<br>
<br>
<span class="element"><a href="http://sourceforge.net/projects/jasperreports/files/jasperreports/JasperReports%204.0.2/jasperreports-4.0.2-project.zip/download" target="_blank">Download All Sample Source Files</a></span>
<br>
<span class="element"><a href="http://jasperforge.org/scm/viewvc.php/tags/jr-4-0-2/jasperreports/demo/samples/charts/?root=jasperreports" target="_blank">Browse Sample Source Files on SVN</a></span>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td style="width: 20px;">
<br>
</td><td>
<br>
</td>
</tr>
<tr>
<td colspan="2"><span class="label">Main Features in This Sample</span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#charts">Charts</a></span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#chartcustomizers">Altering Charts (Chart Customizers)</a></span></td>
</tr>
<tr>
<td colspan="2">
<br>
</td>
</tr>
<tr>
<td colspan="2"><span class="label">Secondary Features</span></td>
</tr>
<tr>
<td></td><td><span class="element"><a href="../crosstabs/index.html#datasets">Datasets</a></span></td>
</tr>
</table>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td width="80%">
<br>
</td><td width="20%">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="charts"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Charts</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.net" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to render different types of charts using the built-in chart element.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">1.0.0</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Other Samples</span></td><td>
<br>
</td><td colspan="3">
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><span class="element"><a href="../chartthemes/index.html">/demo/samples/chartthemes</a></span></td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<b>Charts in JasperReports</b>
<br>
<br>
The JasperReports library does not produce charts and graphics itself. However, it can easily integrate charts,
barcodes, and graphics produced by other more specialized Java libraries.
<br>
The great majority of available Java libraries that produce charts and graphics can output
to image files or in-memory Java image objects. And such image objects can be integrated into a JasperReports document
using a normal image element.
<br>
To simplify the integration of charts inside reports, JasperReports provides a specialized <span class="code"><code><chart></code></span> element.
<br>
<br>
<b>Chart Properties</b>
<br>
<br>
When including and configuring a chart component, three entities are involved:
<ul>
<li>The overall chart component</li>
<li>The chart dataset (which groups chart data–related settings)</li>
<li>The chart plot (which groups visual settings related to the way the chart items are rendered)</li>
</ul>
JasperReports currently supports the following types of charts: <span class="code"><code>Pie, Pie 3D, Bar, Bar 3D,
XY Bar, Stacked Bar, Stacked Bar 3D, Line, XY Line, Area, XY Area, Stacked Area, Scatter,
Bubble, Time Series, High-Low-Open-Close, Candlestick, Multiple Axis, Meter, Thermometer and Gantt.</code></span>
<br>
All chart types have a common set of properties. Charts are normal report elements, so
they share some of their properties with all the other report elements. Charts are also box
elements and can have hyperlinks associated with them.
<br>
Chart-specific settings that apply to all types of charts are grouped under a special
JRXML tag called <span class="code"><code><chart></code></span>. It contains the following elements:
<ul>
<li>
<span class="code"><code><reportElement /></code></span>
</li>
<li>
<span class="code"><code><box /></code></span>
</li>
<li>
<span class="code"><code><chartTitle /></code></span>
</li>
<li>
<span class="code"><code><chartSubtitle /></code></span>
</li>
<li>
<span class="code"><code><chartLegend /></code></span>
</li>
<li>
<span class="code"><code><anchorNameExpression /></code></span>
</li>
<li>
<span class="code"><code><hyperlinkReferenceExpression /></code></span>
</li>
<li>
<span class="code"><code><hyperlinkAnchorExpression /></code></span>
</li>
<li>
<span class="code"><code><hyperlinkPageExpression /></code></span>
</li>
<li>
<span class="code"><code><hyperlinkTooltipExpression /></code></span>
</li>
<li>
<span class="code"><code><hyperlinkParameter /></code></span>
</li>
</ul>
Attributes available for all chart types are:
<ul>
<li>
<span class="code"><code>isShowLegend</code></span> - indicates whether the legend will be rendered visible</li>
<li>
<span class="code"><code>evaluationTime</code></span> - indicates the moment when chart goes rendered. Default value is <span class="code"><code>Now</code></span>
</li>
<li>
<span class="code"><code>evaluationGroup</code></span> - used to specify the group at which to render the chart, when <span class="code"><code>evaluationTime</code></span> is <span class="code"><code>Group</code></span>
</li>
<li>
<span class="code"><code>hyperlinkType</code></span> - indicates the type of the hyperlink element.</li>
<li>
<span class="code"><code>hyperlinkTarget</code></span> - indicates the target of the hyperlink.</li>
<li>
<span class="code"><code>bookmarkLevel</code></span> - the level of the bookmark corresponding to the anchor.</li>
<li>
<span class="code"><code>customizerClass</code></span> - the name of the chart customizer class.</li>
<li>
<span class="code"><code>renderType</code></span> - represents the specified format used to render the chart.</li>
<li>
<span class="code"><code>theme</code></span> - the name of the chart theme used to draw the chart.</li>
</ul>
<br>
<b>Chart Rendering</b>
<br>
<br>
In generated reports, the output produced by a chart element is an image element. Image elements are drawn using
implementations of the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRRenderable.html" target="_blank">JRRenderable</a></span> interface.
Charts have an attribute called <span class="code"><code>renderType</code></span> which specifies the renderer
implementation that will be used to render the chart during export or report display. By
default, JasperReports recognizes the following values for this attribute:
<ul>
<li>
<span class="code"><code>draw</code></span> - the chart is drawn directly on the target graphic context using the
JFreeChart API.</li>
<li>
<span class="code"><code>image</code></span> - an image is first produced from the chart and this image in turn gets
rendered onto the target graphic context.</li>
<li>
<span class="code"><code>svg</code></span> - the chart is transformed into the Scalable Vector Graphics format and
from that format is then rendered onto the target graphic context.</li>
</ul>
<br>
<b>Chart Title, Subtitle and Legend</b>
<br>
<br>
All charts can have one title and one subtitle. All chart types can display a legend that explains the values represented by the chart.
By default all charts display the legend, but one can suppress this display by setting the
<span class="code"><code>isShowLegend</code></span> flag to <span class="code"><code>false</code></span>.
<br>
Chart titles, subtitles and legends are optional and can be customized
for color, font, and position.
They can be placed at the top of the chart, at the bottom of the chart, or on
the left or right side of the chart, depending on the value of the <span class="code"><code>position</code></span> attribute.
<br>
<br>
<b>Chart Datasets</b>
<br>
<br>
Charts rely on a data-oriented component called the chart dataset for mapping report
data and retrieving chart data at runtime.
<br>
A chart dataset is an entity which can get
initialized and incremented at specified moments during the report-filling process and
iteration through the report data source. Like a report variable, at any moment a chart
dataset holds a certain value, which is a complex data structure that gets incremented and
will be used for rendering the chart at the appropriate moment.
<br>
Several types of chart datasets are available in JasperReports because each type of chart
works with certain datasets: <span class="code"><code>Pie, Category, XY, Time Series, Time Period, XYZ,
High-Low, Value and Gantt</code></span>.
<br>
The JasperReports object model uses the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRChartDataset.html" target="_blank">JRChartDataset</a></span>
interface to define chart datasets.
There are implementations of this interface for each of the aforementioned dataset types.
All chart datasets initialize and increment in the same way, and differ only in the type of
data or data series they map. The increment or reset type and increment or reset groups can be specified by setting the
dataset common attributes below:
<ul>
<li>
<span class="code"><code>resetType</code></span>
</li>
<li>
<span class="code"><code>resetGroup</code></span>
</li>
<li>
<span class="code"><code>incrementType</code></span>
</li>
<li>
<span class="code"><code>incrementGroup</code></span>
</li>
</ul>
Specific dataset types are:
<br>
<br>
<b>Pie Dataset</b>
<br>
<br>
A pie dataset is characterized by the following expressions:
<ul>
<li>
<span class="code"><code><keyExpression /></code></span> - represent the categories that will make up the slices in the pie
chart. This expression can return any <span class="code"><code>java.lang.Comparable object</code></span>.</li>
<li>
<span class="code"><code><valueExpression /></code></span> - produces the values that correspond to each category/key in the dataset.
Values are always <span class="code"><code>java.lang.Number</code></span> objects.</li>
<li>
<span class="code"><code><labelExpression /></code></span> - if this expression is missing, the chart will display default labels for each slice in the pie
chart. Use this expression, which returns <span class="code"><code>java.lang.String</code></span> values, to customize the item labels for the pie chart.</li>
<li>
<span class="code"><code><sectionHyperlink /></code></span> - sets hyperlinks associated with pie sections</li>
</ul>
<br>
<b>Category Dataset</b>
<br>
<br>
A category dataset is characterized by the <span class="code"><code><categorySeries /></code></span> element, which contains:
<ul>
<li>
<span class="code"><code><seriesExpression /></code></span> - indicates the name of the series. This expression can return any <span class="code"><code>java.lang.Comparable</code></span> object.</li>
<li>
<span class="code"><code><categoryExpression /></code></span> - returns the name of the category for each value inside the series
specified by the series expression. Categories are <span class="code"><code>java.lang.Comparable</code></span> objects.</li>
<li>
<span class="code"><code><valueExpression /></code></span> - produces the values that correspond to each category in the dataset.
Values are always <span class="code"><code>java.lang.Number</code></span> objects.</li>
<li>
<span class="code"><code><labelExpression /></code></span> - if this expression is missing, the chart will display default labels for each item in the
chart. Use this expression, which returns <span class="code"><code>java.lang.String</code></span> values, to customize the item labels for the chart.</li>
<li>
<span class="code"><code><itemHyperlink /></code></span> - sets hyperlinks associated with chart items</li>
</ul>
<br>
<b>XY Dataset</b>
<br>
<br>
An XY dataset is characterized by the <span class="code"><code><xySeries /></code></span> element, which contains:
<ul>
<li>
<span class="code"><code><seriesExpression /></code></span> - indicates the name of the series. This expression can return any <span class="code"><code>java.lang.Comparable</code></span> object.</li>
<li>
<span class="code"><code><xValueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value representing the X value from the
(x, y) pair that will be added to the current data series.</li>
<li>
<span class="code"><code><yValueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value representing the Y value from the
(x, y) pair that will be added to the current data series.</li>
<li>
<span class="code"><code><labelExpression /></code></span> - if this expression is missing, the chart will display default labels for each item in the
chart. Use this expression, which returns <span class="code"><code>java.lang.String</code></span> values, to customize the item labels for the chart.</li>
<li>
<span class="code"><code><itemHyperlink /></code></span> - sets hyperlinks associated with chart items</li>
</ul>
<br>
<b>XYZ Dataset</b>
<br>
<br>
An XYZ dataset is characterized by the <span class="code"><code><xyzSeries /></code></span> element, which contains:
<ul>
<li>
<span class="code"><code><seriesExpression /></code></span> - indicates the name of the series. This expression can return any <span class="code"><code>java.lang.Comparable</code></span> object.</li>
<li>
<span class="code"><code><xValueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value representing the X value from the
(x, y, z) item that will be added to the current data series.</li>
<li>
<span class="code"><code><yValueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value representing the Y value from the
(x, y, z) item that will be added to the current data series.</li>
<li>
<span class="code"><code><zValueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value representing the Z value from the
(x, y, z) item that will be added to the current data series.</li>
<li>
<span class="code"><code><labelExpression /></code></span> - if this expression is missing, the chart will display default labels for each item in the
chart. Use this expression, which returns <span class="code"><code>java.lang.String</code></span> values, to customize the item labels for the chart.</li>
<li>
<span class="code"><code><itemHyperlink /></code></span> - sets hyperlinks associated with chart items</li>
</ul>
<br>
<b>Time Series Dataset</b>
<br>
<br>
A time series dataset is characterized by the <span class="code"><code>timePeriod</code></span> attribute, and the <span class="code"><code><timeSeries /></code></span> element.
<br>
The <span class="code"><code>timePeriod</code></span> attribute specifies the type of the data series inside the dataset. Time series can contain numeric
values associated with days, months, years, or other predefined time periods. Possible values are:
<ul>
<li>
<span class="code"><code>Year</code></span>
</li>
<li>
<span class="code"><code>Quarter</code></span>
</li>
<li>
<span class="code"><code>Month</code></span>
</li>
<li>
<span class="code"><code>Week</code></span>
</li>
<li>
<span class="code"><code>Day</code></span> - this is the default value</li>
<li>
<span class="code"><code>Hour</code></span>
</li>
<li>
<span class="code"><code>Minute</code></span>
</li>
<li>
<span class="code"><code>Second</code></span>
</li>
<li>
<span class="code"><code>Millisecond</code></span>
</li>
</ul>
The <span class="code"><code><timeSeries /></code></span> element contains:
<ul>
<li>
<span class="code"><code><seriesExpression /></code></span> - indicates the name of the series. This expression can return any <span class="code"><code>java.lang.Comparable</code></span> object.</li>
<li>
<span class="code"><code><timePeriodExpression /></code></span> - returns a <span class="code"><code>java.util.Date</code></span> value from which the engine will extract the
corresponding time period depending on the value set for the <span class="code"><code>timePeriod</code></span> attribute
mentioned above.</li>
<li>
<span class="code"><code><valueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value to associate with the
corresponding time period value when incrementing the current series of the dataset.</li>
<li>
<span class="code"><code><labelExpression /></code></span> - if this expression is missing, the chart will display default labels for each item in the
chart. Use this expression, which returns <span class="code"><code>java.lang.String</code></span> values, to customize the item labels for the chart.</li>
<li>
<span class="code"><code><itemHyperlink /></code></span> - sets hyperlinks associated with chart items</li>
</ul>
<br>
<b>Time Period Dataset</b>
<br>
<br>
An time period dataset is characterized by the <span class="code"><code><timePeriodSeries /></code></span> element which contains:
<ul>
<li>
<span class="code"><code><seriesExpression /></code></span> - indicates the name of the series. This expression can return any <span class="code"><code>java.lang.Comparable</code></span> object.</li>
<li>
<span class="code"><code><startDateExpression /></code></span> - specifies the beginning of the date interval with which the numeric value will be
associated when it is added to the time period series.</li>
<li>
<span class="code"><code><endDateExpression /></code></span> - specifies the end of the date interval with which the numeric value will be
associated when it is added to the time period series.</li>
<li>
<span class="code"><code><valueExpression /></code></span> - returns the <span class="code"><code>java.lang.Number</code></span> value to associate with the current date
interval specified by the start date and end date expressions.</li>
<li>
<span class="code"><code><labelExpression /></code></span> - if this expression is missing, the chart will display default labels for each item in the
chart. Use this expression, which returns <span class="code"><code>java.lang.String</code></span> values, to customize the item labels for the chart.</li>
<li>
<span class="code"><code><itemHyperlink /></code></span> - sets hyperlinks associated with chart items</li>
</ul>
<br>
<b>High Low Dataset</b>
<br>
<br>
An high low dataset is characterized by the following expressions:
<ul>
<li>
<span class="code"><code><seriesExpression /></code></span> - currently only one series is supported inside a High-Low or Candlestick chart.
However, this single series must be identified by a <span class="code"><code>java.lang.Comparable</code></span>
value returned by this expression, and it must also be used as the series name in the
chart’s legend.</li>
<li>
<span class="code"><code><dateExpression /></code></span> - returns the date to which the current (high, low, open, close, volume) item refers.</li>
<li>
<span class="code"><code><highExpression /></code></span> - returns a <span class="code"><code>java.lang.Number</code></span> value, which will be part of
the data item added to the series when the dataset gets incremented.</li>
<li>
<span class="code"><code><lowExpression /></code></span> - returns a <span class="code"><code>java.lang.Number</code></span> value, which will be part of
the data item added to the series when the dataset gets incremented.</li>
<li>
<span class="code"><code><openExpression /></code></span> - returns a <span class="code"><code>java.lang.Number</code></span> value, which will be part of
the data item added to the series when the dataset gets incremented.</li>
<li>
<span class="code"><code><closeExpression /></code></span> - returns a <span class="code"><code>java.lang.Number</code></span> value, which will be part of
the data item added to the series when the dataset gets incremented.</li>
<li>
<span class="code"><code><volumeExpression /></code></span> - a numeric expression that returns the volume value to use for the current data
item. It is used only for Candlestick charts.</li>
<li>
<span class="code"><code><itemHyperlink /></code></span> - sets hyperlinks associated with chart items</li>
</ul>
<br>
<b>Value Dataset</b>
<br>
<br>
This is a special chart dataset implementation that contains a single value and is used for
rendering Meter and Thermometer charts. The value is collected using the <span class="code"><code><valueExpression /></code></span> expression.
<br>
<br>
<b>Common Settings for Chart Plots</b>
<br>
<br>
The chart plot is the area of the chart on which the axes and items are rendered. Plots
differ based on the type of chart. Some plots specialize in drawing pies; others specialize
in drawing bar items or lines.
<br>
Each type of plot comes with its own set of properties or attributes for customizing the
chart’s appearance and behavior.
<br>
There is, however, a subset of plot properties common to all plot types. They are grouped
under the <plot /> element in JRXML and can be part of any chart/plot definition in the report
template. Common plot attributes are:
<ul>
<li>
<span class="code"><code>backcolor</code></span> - specifies the background color for the plot.</li>
<li>
<span class="code"><code>orientation</code></span> - specifies whether plot items will be rendered horizontally or vertically. Possible values are <span class="code"><code>Horizontal</code></span> and <span class="code"><code>Vertical</code></span>.
The default is <span class="code"><code>Vertical</code></span>.</li>
<li>
<span class="code"><code>backgroundAlpha</code></span> - specifies the background transparency for the plot.</li>
<li>
<span class="code"><code>foregroundAlpha</code></span> - specifies the foreground transparency for the plot.</li>
</ul>
A plot contains also a <seriesColor /> element which customize colors for series, and their position within in the color sequence.
<br>
<br>
<b>Specific Settings for Chart Plots</b>
<br>
<br>
<ul>
<li>
<span class="code"><code>piePlot</code></span> - it has no specific settings</li>
<li>
<span class="code"><code>pie3DPlot</code></span> - contains the <span class="code"><code>depthFactor</code></span> attribute, a numeric value
ranging from 0 to 1 that represents the depth of the pie as a percentage of the height of
the plot area.</li>
<li>
<span class="code"><code>barPlot</code></span> - one can show or hide tick labels, tick marks or item labels, and provides settings for both axis.</li>
<li>
<span class="code"><code>bar3DPlot</code></span> - provides the same settings as the <span class="code"><code>barPlot</code></span>, and generates a 3D effect using the <span class="code"><code>xOffset</code></span> and <span class="code"><code>yOffset</code></span> attributes.</li>
<li>
<span class="code"><code>linePlot</code></span> - one can show or hide lines connecting item points, can show or hide shapes associated with item points, and provides settings for both axis.</li>
<li>
<span class="code"><code>scatterPlot</code></span> - like the <span class="code"><code>linePlot</code></span>, it can show or hide lines connecting item points, can show or hide shapes associated with item points, and provides settings for both axis.</li>
<li>
<span class="code"><code>areaPlot</code></span> - provides settings for both axis.</li>
<li>
<span class="code"><code>bubblePlot</code></span> - one can set the bubble dimensions by setting the <span class="code"><code>scaleType</code></span> attribute, and provides settings for both axis. </li>
<li>
<span class="code"><code>timeSeriesPlot</code></span> - one can show or hide lines connecting item points, can show or hide shapes associated with item points, and provides settings for both axis. </li>
<li>
<span class="code"><code>highLowPlot</code></span> - one can show or hide open ticks, can show or hide close ticks, and provides settings for both axis.</li>
<li>
<span class="code"><code>candlestickPlot</code></span> - one can show or hide the volume, and provides settings for both axis.</li>
<li>
<span class="code"><code>meterPlot</code></span> - contains specific settings for the dial shape, scale angle, measurement units, tick interval, dial color, needle color, tick color,
value display font, color and format pattern, data range and meter intervals.</li>
<li>
<span class="code"><code>thermometerPlot</code></span> - contains specific settings for the value location, mercury color, show/hide value lines, value display font, color and format pattern,
data range, low range, medium range and high range.</li>
<li>
<span class="code"><code>multiAxisPlot</code></span> - contains specific settings for axis included in the plot</li>
</ul>
<br>
<b>Chart Types</b>
<br>
<br>
<ul>
<li>
<span class="code"><code>pieChart</code></span> - a combination of a Pie dataset and a Pie plot.</li>
<li>
<span class="code"><code>pie3DChart</code></span> - groups a Pie dataset and a Pie 3D plot.</li>
<li>
<span class="code"><code>barChart</code></span> - a basic combination of a Category dataset and a Bar plot.</li>
<li>
<span class="code"><code>bar3DChart</code></span> - wraps a Category dataset and a Bar 3D plot.</li>
<li>
<span class="code"><code>xyBarChart</code></span> - supports Time Period datasets, Time Series datasets, and XY datasets, and uses a Bar plot to render the axis and the items.</li>
<li>
<span class="code"><code>stackedBarChart</code></span> - uses data from a Category dataset and renders its content using a Bar plot.</li>
<li>
<span class="code"><code>stackedBar3DChart</code></span> - uses data from a Category dataset and renders its content using a Bar 3D plot.</li>
<li>
<span class="code"><code>lineChart</code></span> - groups a Category dataset and a Line plot.</li>
<li>
<span class="code"><code>xyLineChart</code></span> - groups an XY dataset and a Line plot.</li>
<li>
<span class="code"><code>areaChart</code></span> - items from a Category dataset are rendered using an Area plot.</li>
<li>
<span class="code"><code>stackedAreaChart</code></span> - items from a Category dataset are rendered using an Area plot.</li>
<li>
<span class="code"><code>xyAreaChart</code></span> - uses data from an XY dataset and renders it through an Area plot.</li>
<li>
<span class="code"><code>scatterChart</code></span> - wraps an XY dataset with a Scatter plot.</li>
<li>
<span class="code"><code>bubbleChart</code></span> - combines an XYZ dataset with a Bubble plot.</li>
<li>
<span class="code"><code>timeSeriesChart</code></span> - groups a Time Series dataset and a Time Series plot.</li>
<li>
<span class="code"><code>highLowChart</code></span> - a combination of a High-Low dataset and a High-Low plot.</li>
<li>
<span class="code"><code>candlestickChart</code></span> - uses data from a High-Low dataset but with a special Candlestick plot.</li>
<li>
<span class="code"><code>meterChart</code></span> - displays a single value from a Value dataset on a dial, using rendering options from a Meter plot.</li>
<li>
<span class="code"><code>thermometerChart</code></span> - displays the single value in a Value dataset using rendering options from a Thermometer plot.</li>
<li>
<span class="code"><code>multiAxisChart</code></span> - contains multiple range axes, all sharing a common domain axis.</li>
</ul>
<b>Running the Sample</b>
<br>
<br>
Running the sample requires the <a href="http://ant.apache.org/" target="_blank" class="element">Apache Ant</a> library. Make sure that <span class="code"><code>ant</code></span> is already installed on your system (version 1.5 or later).
<br>
In a command prompt/terminal window set the current folder to <span class="code"><code>demo/hsqldb</code></span> within the JasperReports source project and run the <span class="code"><code>> ant runServer</code></span> command.
It will start the HSQLDB server shipped with the JasperReports distribution package. Let this terminal running the HSQLDB server.
<br>
Open a new command prompt/terminal window and set the current folder to <span class="code"><code>demo/samples/charts</code></span> within the JasperReports source project and run the <span class="code"><code>> ant test view</code></span> command.
<br>
It will generate all supported document types containing the sample report in the <span class="code"><code>demo/samples/charts/build/reports</code></span> directory.
<br>
Then the report will open in the JasperReports internal viewer.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="chartcustomizers"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Altering Charts (Chart Customizers)</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.net" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to make various changes to a generated chart using the <a href="http://jfree.org/jfreechart/" target="_blank" class="element">JFreeChart API</a>,
which is used by JasperReports to draw the charts created with the built-in chart element.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">1.1.1</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Other Samples</span></td><td>
<br>
</td><td colspan="3">
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><span class="element"><a href="../chartthemes/index.html">/demo/samples/chartthemes</a></span></td>
</tr>
</table>
</td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<b>Chart Customizers and Chart Themes</b>
<br>
<br>
Although the JFreeChart library is a fairly complete charting package that offers great
flexibility and a comprehensive range of settings to fully customize the appearance and
the content of the charts it renders, the built-in chart component offered by JasperReports
exposes only a subset of the library’s original charting functionality. This ensures that
JasperReports charts are easily embeddable into reports and that the basic set of
properties exposed through JRXML and the object model is enough for the majority of
use cases.
<br>
In time, other JFreeChart settings will be exposed through the built-in chart component,
but certainly JasperReports will never be able to expose all the JFreeChart settings
through JRXML tags or the API.
<br>
To provide full control over chart customization even when using the built-in chart
component, JasperReports can make use of either a chart theme implementation, or of a
chart customizer implementation associated with the chart element, or both.
<br>
Chart themes are a more recent addition to the library and in a way they deprecate the
chart customizers because they bring enhanced capabilities in controlling chart output.
<br>
A chart customizer is an implementation of the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRChartCustomizer.html" target="_blank">JRChartCustomizer</a></span>
interface that is associated
with the chart element using the <span class="code"><code>customizerClass</code></span> attribute. The easiest way to
implement this interface is by extending the
<span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRAbstractChartCustomizer.html" target="_blank">JRAbstractChartCustomizer</a></span>
having access to parameters, fields, and variables, for more flexible chart customization
based on report data.
<br>
However, it is recommended to implement and work with chart themes instead of
chart customizers, because chart themes give more control over chart output, including
the creation of the JFreeChart object itself. Chart customizer only allow modifying the
JFreeChart object that is created externally and passed in to them. Also, chart themes
affect a whole range of chart types across multiple reports and are not necessarily tied to
a specific chart element within a report. They can even apply globally to all charts within
a given JasperReports deployment, applying a new look and feel to all charts created
within that environment.
<br>
<br>
<b>A Simple Chart Customizer Class Example</b>
<br>
<br>
When one implements the <span class="element"><a href="http://jasperreports.sourceforge.net/api/net/sf/jasperreports/engine/JRChartCustomizer.html" target="_blank">JRChartCustomizer</a></span> interface,
the only method which has to be implemented is:
<br>
<br>
<span class="code"><code>public void customize(JFreeChart chart, JRChart jasperChart);</code></span>
<br>
<br>
The <a href="#charts" target="_blank" class="element">Charts</a> sample contains a very simple customizer class, which sets specific colors for series in a Bar chart.
<br>
First, let's take a look at the BarChartCustomizer class in the <span class="code"><code>src</code></span> directory:
<pre>
import java.awt.Color;
import net.sf.jasperreports.engine.JRChart;
import net.sf.jasperreports.engine.JRChartCustomizer;
import org.jfree.chart.JFreeChart;
import org.jfree.chart.renderer.category.BarRenderer;
public class BarChartCustomizer implements JRChartCustomizer
{
public void customize(JFreeChart chart, JRChart jasperChart)
{
BarRenderer renderer = (BarRenderer) chart.getCategoryPlot().getRenderer();
renderer.setSeriesPaint(0, Color.green);
renderer.setSeriesPaint(1, Color.orange);
}
}
</pre>
The <span class="code"><code>customize()</code></span> method gets applied after the JFreeChart object is already created.
Then, the only thing one have to do is to take this JFreeChart object and modify its characteristics according to some more specific needs.
<br>
In the example above, two older series colors were replaced with new ones in the bar renderer, and so, the color scheme was altered for the Bar chart.
<br>
Now, one have to tell to the JasperReports engine that a given chart should be customized using this customizer class. In the <span class="code"><code>reports/BarChartReport.jrxml</code></span> file
this class is set as chart customizer:
<br>
<br>
<span class="code"><code>
<barChart>
<br>
<chart evaluationTime="Group" evaluationGroup="ChartGroup" customizerClass="BarChartCustomizer">
<br>
...
<br>
</chart>
<br>
...
<br>
</barChart>
</code></span>
<br>
<br>
<b>Note: </b> When running the <a href="#charts" target="_blank" class="element">Charts</a> sample, one can see that the Bar chart generated reports are the only with their items colored in green and orange.
All the other generated reports are sharing another color scheme.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
</table>
<br>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td>
<hr size="1">
</td>
</tr>
<tr>
<td align="center"><span class="copy">© 2001-2010 Jaspersoft Corporation <a href="http://www.jaspersoft.com" target="_blank" class="copy">www.jaspersoft.com</a></span></td>
</tr>
</table>
</body>
</html>
