net.sf.jasperreports.charts.package-info Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
Show all versions of jasperreports Show documentation
Free Java Reporting Library
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2019 TIBCO Software Inc. 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:
*
* - 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 {@link net.sf.jasperreports.engine.Renderable Renderable} 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
* {@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;