net.sf.jasperreports.engine

Interface JRBand

All Superinterfaces:

Cloneable, JRChild, JRCloneable, JRElementGroup, JRPropertiesHolder, JRVisitable

All Known Implementing Classes:

JRBaseBand, JRDesignBand, JRFillBand

public interface JRBand
extends JRElementGroup, JRPropertiesHolder

Implementations of this interface represent various bands in the report template.

Report Sections

JasperReports works with templates that are structured into multiple sections, like any traditional reporting tool. A report can contain the following sections: background, title, summary, page header, page footer, last page footer, column header and column footer.

At report-filling time, the engine iterates through the virtual records of the supplied report data source and renders each report section when appropriate, depending on each section's defined behavior.

For instance, the detail section is rendered for each record in the data source. When page breaks occur, the page header and page footer sections are rendered as needed.

Sections are made of one or more bands. Bands are portions of the report template that have a specified height and width and can contain report elements like lines, rectangles, images, and text fields. These bands are filled repeatedly at report-generating time and make up the final document.

When declaring the content and layout of a report section, in an JRXML report design, use the generic element <band>.

Report sections, sometimes referred to as report bands, represent a feature and functionality common to almost all reporting tools.

Band Height

The height attribute in a report band declaration specifies the height in pixels for that particular band and is very important in the overall report design.

The elements contained by a certain report band should always fit the band's dimensions; this will prevent potentially bad results when generating the reports. The engine issues a warning if it finds elements outside the band borders when compiling report designs.

Preventing Band Split

In some cases it is desirable to keep the whole contents of a given band in one piece to prevent page breaks when the band stretches beyond its initial specified height. To do this, use the splitType attribute, as follows:

Stretch

The band never splits within its declared height. The band will not start rendering on the current page if the remaining available space is not at least equal to the band's declared height. However, if the band stretches on the current page, the region that is added to the original height is allowed to split onto the next page.

Prevent

The band starts to render normally, but if the bottom of the page is reached without finishing the band, the whole contents of the band that are already being laid out are moved to the next page. If the band does not fit on the next page, the split occurs normally, as band split prevention is effective only on the first split attempt

Immediate

The band is allowed to split anywhere except above its topmost element

If a split type is not specified, the default is given by the net.sf.jasperreports.band.split.type configuration property.

Skipping Bands

All the report sections allow users to define a report expression that will be evaluated at runtime to decide if that section should be generated or skipped when producing the document. This expression is introduced by the <printWhenExpression> tag, which is available in any <band> element of the JRXML report design and should always return a java.lang.Boolean object or null.

Author:

Teodor Danciu (teodord@users.sourceforge.net)

See Also:

JRSection

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROPERTY_SPLIT_TYPE

Method Summary

Methods

Modifier and Type	Method and Description
int	getHeight()
JRExpression	getPrintWhenExpression() Returns the boolean expression that specifies if the band will be displayed.
List<ExpressionReturnValue>	getReturnValues() Returns the list of values to increment report variables with.
SplitTypeEnum	getSplitTypeValue() Specifies the band split behavior.
void	setSplitType(SplitTypeEnum splitType)

Methods inherited from interface net.sf.jasperreports.engine.JRElementGroup

getChildren, getElementByKey, getElementGroup, getElements

Methods inherited from interface net.sf.jasperreports.engine.JRChild

clone

Methods inherited from interface net.sf.jasperreports.engine.JRVisitable

visit

Methods inherited from interface net.sf.jasperreports.engine.JRCloneable

clone

Methods inherited from interface net.sf.jasperreports.engine.JRPropertiesHolder

getParentProperties, getPropertiesMap, hasProperties

Field Detail

PROPERTY_SPLIT_TYPE

static final String PROPERTY_SPLIT_TYPE

See Also:

Constant Field Values

Method Detail

getHeight

int getHeight()

getSplitTypeValue

SplitTypeEnum getSplitTypeValue()

Specifies the band split behavior.

setSplitType

void setSplitType(SplitTypeEnum splitType)

getPrintWhenExpression

JRExpression getPrintWhenExpression()

Returns the boolean expression that specifies if the band will be displayed.

getReturnValues

List<ExpressionReturnValue> getReturnValues()

Returns the list of values to increment report variables with.

Returns:

the list of returned values.