# Package net.sf.jasperreports.charts

Contains interfaces for chart plots and chart datasets.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  ChartContext |
  ChartTheme | Chart themes give more control over chart output, including the creation of the JFreeChart object itself.
  ChartThemeBundle |
  JRAreaPlot | Area charts and Stacked Area charts rely on this plot to render their axes and items.
  JRBar3DPlot | Type of plot used to render Bar 3D and the Stacked Bar 3D charts.
  JRBarPlot | Type of plot used to render Bar, Stacked Bar, and XY Bar charts.
  JRBubblePlot | Only Bubble charts use this type of plot.
  JRCandlestickPlot | The Candlestick plot is also an axis-oriented plot and allows you to customize axis labels using expressions.
  JRCategoryAxisFormat |
  JRCategoryDataset | This dataset accommodates one or more data series consisting of values associated with categories.
  JRCategoryPlot | Type of plot used for rendering category charts.
  JRCategorySeries | Represents the series for any Category dataset.
  JRChartAxis | Describes an axis that can be added to a multiple axis chart.
  JRCommonLinePlot | Type of the plot used to render Line, XY Line and Scatter charts.
  JRDataRange | Represents a numeric range.
  JRGanttDataset | This dataset accommodates one or more data series consisting of values associated with tasks and subtasks.
  JRGanttSeries | Represents the series for the Gantt dataset.
  JRHighLowDataset | Although the name of this dataset is "High-Low", it can actually hold a series of (x, high, low, open, close, volume) items.
  JRHighLowPlot | Used only in combination with High-Low charts, this type of plot lets users customize the labels for both axes, like all the other axis-oriented plots.
  JRItemLabel | Contains the formatting option for the textual representation of item labels in a category plot
  JRLinePlot | Type of plot used to render Line charts.
  JRMeterPlot | This type of plot can be used only for Meter charts and represents the display options of a Meter Chart.
  JRMultiAxisPlot | Represents the display options and nested charts of a multiple axis chart.
  JRPie3DPlot | Type of plot used for rendering Pie 3D charts.
  JRPieDataset | This dataset is useful for rendering Pie or Pie 3D charts.
  JRPiePlot | Type of plot used for rendering Pie charts.
  JRPieSeries | Represents the series for the Pie dataset.
  JRScatterPlot | Scatter plots are used only with Scatter charts.
  JRThermometerPlot | Represents the display options of a Thermometer chart.
  JRTimeAxisFormat |
  JRTimePeriodDataset | The Time Period dataset is very much like the Time Series dataset in that it wraps series consisting of (time period, numeric value) pairs.
  JRTimePeriodSeries | Represents the series for the Time Period dataset.
  JRTimeSeries | Represents the series for the Time Series dataset.
  JRTimeSeriesDataset | This dataset wraps one or multiple time series.
  JRTimeSeriesPlot | This type of plot is similar to the Line plot and Scatter plot in that it lets users configure the labels for both axes, the rendering of lines to connect the item points, and the rendering of the small shapes that mark each item point on the target plot area.
  JRValueAxisFormat |
  JRValueDataset | This class represents a dataset that consists of a single value.
  JRValueDisplay | Represents the formatting option for the textual representation of a value displayed in a Meter or Thermometer chart.
  JRXAxisFormat |
  JRXyDataset | This dataset is a wrapper for data series made of (x, y) value pairs and is used for rendering XY Bar, XY Line, XY Area, and Scatter Plot charts.
  JRXySeries | Represents the series for the XY dataset.
  JRXyzDataset | The XYZ dataset wraps series consisting of (x, y, z) items.
  JRXyzSeries |
  JRYAxisFormat |

## Package net.sf.jasperreports.charts Description

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:

- The overall chart component
- The chart dataset (which groups chart data-related settings)
- The chart plot (which groups visual settings related to the way the chart items are rendered)

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>`:

- `isShowLegend`: flag attribute that specifies if the legend is visible on the chart
- `customizerClass`: attribute that specifies the name of a chart customizer class
- `renderType`: attribute that specifies the chart rendering type
- `theme`: attribute that specifies the name of a custom chart theme
- `chartTitle`: element to customize the chart title
- `chartSubtitle`: element to customize the chart subtitle
- `chartLegend`: element to customize the chart legend

### Chart Rendering

In generated reports the output produced by a chart element is an image element. Image elements are drawn using implementations of the `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:

- `draw`: the chart is drawn directly on the target graphic context using the JFreeChart API
- `image`: an image is first produced from the chart and this image in turn gets rendered onto the target graphic context
- `svg`: the chart is transformed into the SVG format and from that format is then rendered onto the target graphic context

### 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 `JRChartCustomizer` interface that is associated with the chart element using the customizerClass attribute. The easiest way to implement this interface is by extending the `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 `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 `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.

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com