net.sf.jasperreports.engine.JRBand 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 .
*/
package net.sf.jasperreports.engine;
import java.util.List;
import net.sf.jasperreports.annotations.properties.Property;
import net.sf.jasperreports.annotations.properties.PropertyScope;
import net.sf.jasperreports.engine.type.SplitTypeEnum;
import net.sf.jasperreports.properties.PropertyConstants;
/**
* 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
* {@link #PROPERTY_SPLIT_TYPE 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.
* @see net.sf.jasperreports.engine.JRSection
* @author Teodor Danciu ([email protected])
*/
public interface JRBand extends JRElementGroup, JRPropertiesHolder
{
/**
*
*/
@Property(
category = PropertyConstants.CATEGORY_FILL,
valueType = SplitTypeEnum.class,
defaultValue = "Stretch",
scopes = {PropertyScope.CONTEXT, PropertyScope.REPORT},
sinceVersion = PropertyConstants.VERSION_3_5_2
)
public static final String PROPERTY_SPLIT_TYPE = JRPropertiesUtil.PROPERTY_PREFIX + "band.split.type";
/**
*
*/
public int getHeight();
/**
* Specifies the band split behavior.
*/
public SplitTypeEnum getSplitTypeValue();
/**
*
*/
public void setSplitType(SplitTypeEnum splitType);
/**
* Returns the boolean expression that specifies if the band will be displayed.
*/
public JRExpression getPrintWhenExpression();
/**
* Returns the list of values to increment report variables with.
*
* @return the list of returned values.
*/
public List getReturnValues();
}