/* * JasperReports - Free Java Reporting Library. * Copyright (C) 2001 - 2013 Jaspersoft Corporation. All rights reserved. * http://www.jaspersoft.com * * Unless you have purchased a commercial license agreement from Jaspersoft, * the following license terms apply: * * This program is part of JasperReports. * * JasperReports is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * JasperReports is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with JasperReports. If not, see . */ /** * Contains interfaces for chart plots and chart datasets. *
*

The Built-In Chart Component

* JasperReports provides built-in support for charts using the chart component based on the * JFreeChart library. It exposes a limited set of visual * properties that the charting package actually supports. This limited set should be * sufficient for the majority of users, and in the future it may be extended to accommodate * community feedback and requests. *
* With the built-in chart component, users only have to apply the desired visual settings and * define the expressions that will help the engine build the chart dataset incrementally * during the iteration through the report data source. *
* When including and configuring a chart component, three entities are involved: * * JasperReports currently supports the following types of charts: Pie, Pie 3D, Bar, Bar 3D, * XY Bar, Stacked Bar, Stacked Bar 3D, Line, XY Line, Area, Stacked Area, XY Area, Scatter Plot, * Bubble, Time Series, High-Low-Open-Close, Candlestick and Gantt. *
* For each type of chart there is a special JRXML tag that groups various chart settings, * including the dataset and the plot. *
*

Chart Properties

* 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. *
* Charts resemble text fields and images in that they can postpone their actual rendering * until all the data needed for this operation becomes available to the reporting engine. * Data needed by a chart is gathered by the associated dataset during iteration through the * report data. However, there are situations that require displaying charts at the beginning of a document, * where the necessary data is not yet available, given the way the engine process data and * renders the final document. *
* In such cases, the chart evaluation can be postponed using the evaluationTime and * evaluationGroup attributes, which work in the same manner as for text fields and * images. *
* Chart-specific settings that apply to all types of charts are grouped under a special * JRXML tag called <chart>: * *

Chart Rendering

* In generated reports the output produced by a chart element is an image element. Image elements are drawn using * implementations of the {@link net.sf.jasperreports.engine.JRRenderable JRRenderable} interface. * The renderType attribute 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: * *

Chart Title, Subtitle and Legend

* All charts can have a title, a subtitle and a legend. All of them are optional and can be customized * for color, font, and position. *
*

Chart Customizer and Chart Themes

* 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. *
* 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. *
* A chart customizer is an implementation of the * {@link net.sf.jasperreports.engine.JRChartCustomizer JRChartCustomizer} interface that is associated * with the chart element using the customizerClass attribute. The easiest way to * implement this interface is by extending the * {@link net.sf.jasperreports.engine.JRAbstractChartCustomizer JRAbstractChartCustomizer} class and thus * having access to parameters, fields, and variables, for more flexible chart customization * based on report data. *
* Chart customizer only allow modifying the * JFreeChart object that is created externally and passed in to them. *
* Chart themes give more control over chart output, including * the creation of the JFreeChart object itself. 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. *
* A chart theme can be set globally using a configuration property within the * jasperreports.properties file as follows: *

* net.sf.jasperreports.chart.theme=theme_name *

* The global chart theme can be overridden at report level using the following report * property in the report template: *

* <property name="net.sf.jasperreports.chart.theme" value="theme_name"/> *

* If needed, at chart element level, the chart theme is specified using the theme attribute. *
*

Chart Datasets

* One of the most important considerations when putting a chart element into a report * template is the data mapping. The chart will need to extract its data from whatever data is * available inside the report at runtime. *
* The data-oriented component for mapping report data and retrieving chart data at runtime is * the chart dataset. A chart dataset is an entity that somewhat resembles a report variable because it gets * 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. *
* Several types of chart datasets are available in JasperReports because each type of chart * works with certain datasets: Pie, Category, XY, Time Series, Time Period, XYZ, High-Low and Gantt. *
* The JasperReports object model uses the * {@link net.sf.jasperreports.engine.JRChartDataset JRChartDataset} 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. * Common dataset properties are grouped under the <dataset> tag in JRXML format. *
*

Chart Plot

* 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. *
* Each type of plot comes with its own set of properties or attributes for customizing the * chart's appearance and behavior. *
* There is, however, a subset of plot properties common to all plot types, exposed in the * {@link net.sf.jasperreports.engine.JRChartPlot JRChartPlot} interface. They are grouped * under the <plot> tag in JRXML and can be part of any chart/plot definition in the report * template: *
*
Plot Background Color
*
The backcolor attribute can be used to specify the color used for drawing the plot's area background.
*
Plot Orientation
*
Some types of plots can draw their items either vertically or horizontally. For instance, Bar charts can display * either vertical or horizontal bars. Pie charts do not use this setting, but since the majority of charts do have a * concept of orientation, the attribute was included among the common plot settings.
*
Plot Transparency
*
When filling up the background with a specified color or drawing items on the target device, the plot can use a * customizable degree of transparency, which you can control using the backgroundAlpha and foregroundAlpha * attributes. These attributes accept numeric values ranging from 0 to 1. The default for both attributes is 1, which means * drawings on the plot area are opaque.
*
Label Rotation
*
The text labels on the x axis of a chart can be rotated clockwise or counterclockwise by setting a positive or a * negative numeric value representing the number of degrees to the labelRotation attribute of the plot. This attribute * applies only to charts for which the x axis is not numeric or does not display dates.
*
Series Colors
*
To control the color of each series in a chart displaying multiple series, you can use the <seriesColor> * tag available at the chart-plot level. If only one <seriesColor> tag is specified, it becomes the color * of the first series. If more than one <seriesColor> tag is specified, the chart will cycle through the * supplied colors. *
* Pie charts do not have multiple series, but they do need different colors for each slice, so the specified colors * will be used. Meter and Thermometer charts do not have series and will ignore any <seriesColor> settings. *
* When used in a chart that is part of a Multiaxis chart, the series colors are treated a bit differently. The default * color series to cycle through is defined in the plot of the Multiaxis chart, and the color series for the nested charts * define series colors for that chart only. This is useful when a Multiaxis chart contains several line charts, each with * one series. By default every line will be the first in its plot and will have the first color defined in the Multiaxis * plot, so every line will be the same color. To solve this, a <seriesColor> can be set for each nested * chart to override the default colors. *
* All series colors are sorted by the value of the seriesOrder attribute and appear in that order when coloring the series.
*
* */ package net.sf.jasperreports.charts;