net.sf.jasperreports.engine.JRElement 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 net.sf.jasperreports.engine.type.PositionTypeEnum;
import net.sf.jasperreports.engine.type.StretchTypeEnum;
/**
* An abstract representation of a report element. All report elements implement this interface. The interface contains
* constants and methods that apply to all report elements.
*
* The properties that are common to all types of report elements are grouped in the
* <reportElement>
tag, which appears in the declaration of all report elements.
* Element Key
* Unlike variables and parameters, report elements are not required to have a name,
* because normally you do not need to obtain any individual element inside a report
* template. However, in some cases it is useful to be able to locate an element to alter one
* of its properties before using the report template.
*
* This could be the case in an application for which the color of some elements in the
* report template needs to change based on user input. To locate the report elements that
* need to have their colors altered, the caller program could use the
* {@link JRBand#getElementByKey(String)} method available at band level. A key value must be
* associated with the report element and it must be unique within the overall band for the
* lookup to work.
* Element Position
*
* - Absolute position
* - The
x
and y
attributes of any report element are mandatory and represent the x and y
* coordinates, measured in pixels, that mark the absolute position of the top-left corner of
* the specified element within its parent report section.
* - Relative position
* - Some report elements, such as text fields, have special properties that allow them to
* stretch downward to acquire all the information they have to display. Their height is
* calculated at runtime and may affect the neighboring elements in the same report section,
* especially those placed immediately below them.
*
* The positionType
attribute specifies the behavior that the report element will have if
* the layout of the report section in which it is been placed is stretched.
*
* There are three possible values for the positionType
attribute:
*
* Float
- The element floats in its parent section if it is pushed downward
* by other elements found above it. It tries to conserve the distance between it and
* the neighboring elements placed immediately above it
* FixRelativeToTop
- The current report element
* simply ignores what happens to the other section elements and tries to conserve the
* y offset measured from the top of its parent report section
* FixRelativeToBottom
- If the height of the parent
* report section is affected by elements that stretch, the current element tries to
* conserve the original distance between its bottom margin and the bottom of the
* band
*
* A report element called e2 will float when another report element e1 stretches only if
* these three conditions are met:
*
* - e2 has
positionType="Float"
* e1.y + e1.height <= e2.y
* e1.width + e2.width > max(e1.x + e1.width, e2.x + e2.width) - min(e1.x, e2.x)
*
* The second and third conditions together imply that the element e2 must be placed
* below the e1. By default, all elements have a fixed position relative to the top of the
* band.
* Skipping Element Display
* The engine can decide at runtime if it really should display a report element when a
* <printWhenExpression>
is used, which is available for all types of report elements.
*
* If present, this report expression should return a java.lang.Boolean
object or null. It
* is evaluated every time the section containing the current element is generated, in order
* to see whether this particular element should appear in the report or not. If the expression
* returns null, it is equivalent to returning java.lang.Boolean.FALSE
. If the
* expression is missing, then the report element will get printed every time - that is, if
* other settings do not intervene.
* Reprinting Elements on Section Overflows
* When generating a report section, the engine might be forced to start a new page or
* column because the remaining space at the bottom of the current page or column is not
* sufficient for all the section elements to fit in, probably because some elements have
* stretched. In such cases, you might want to reprint some of the already displayed
* elements on the new page or column to recreate the context in which the page/column
* break occurred.
*
* To achieve this, set isPrintWhenDetailOverflows="true"
for all report elements
* you want to reappear on the next page or column.
* Suppressing Repeated Values Display
* First, let's see what exactly a "repeating value" is. It very much depends on the type of
* the report element we are talking about. For textfield elements, this is very intuitive.
* For instance, in an ordinary phone book, one can see that
* for some consecutive lines, the value of the Family Name column repeats itself. You might want
* to suppress the repeating Family Name values and print only their first occurrence. To
* do that, set the following for the text field that displays the family name:
*
* isPrintRepeatedValues="false"
*
* The static text elements behave in the same way. As you would expect, their value
* always repeats and in fact never changes until the end of the report. This is why we call
* them static texts. So, if you set isPrintRepeatedValues="false"
for one of your
* <staticText>
elements, it is displayed only once, the first time, at the beginning of the
* report, and never again.
*
* Now, what about graphic elements? An image is considered to be repeating itself if its
* bytes are exactly the same from one occurrence to the next. This happens only if you
* choose to cache your images using the isUsingCache
attribute available in the
* <image>
(see {@link net.sf.jasperreports.engine.JRImage}
* element and if the corresponding <imageExpression>
returns the same value from one
* iteration to the next (the same file name, the same URL, etc.).
*
* Lines and rectangles always repeat themselves because they are static elements, just like
* the static texts shown previously. So, when you suppress repeating values for a line or a
* rectangle, it is displayed only once, at the beginning of the report, and then ignored until
* the end of the report.
*
* Note: The isPrintRepeatedValues
attribute works only if the corresponding
* <printWhenExpression>
is missing. If it is not missing, it will always dictate
* whether the element should be printed, regardless of the repeating values.
*
* If you decide to not display the repeating values for some of your report elements, you
* can modify this behavior by indicating the exceptional occasions in which you might
* want to have a particular value redisplayed during the report-generation process.
*
* When the repeating value spans multiple pages or columns, you can redisplay this
* repeating value at least once for every page or column. If you set
* isPrintInFirstWholeBand="true"
, then the report element will reappear in the first
* band of a new page or column that is not an overflow from a previous page or column.
* Also, if the repeating value you have suppressed spans multiple groups, you can make it
* reappear at the beginning of a certain report group if you specify the name of that
* particular group in the printWhenGroupChanges
attribute.
* Removing Blank Space
* When a report element is not displayed for some reason (for example,
* <printWhenExpression>
evaluates to Boolean.FALSE
, or a repeated value is
* suppressed), the area where the report element stood at design time will be left empty.
* This blank space also appears if a text field displays only blank characters or an empty
* text value. You can eliminate this unwanted blank space on the vertical axis only if
* certain conditions are met.
*
* The blank space will be removed only if the empty text field doesn't share any vertical space with
* other report elements that are printed, even if this empty textfield does not print. If this
* condition is met, then set isRemoveLineWhenBlank= "true"
for the empty textfield.
* Stretch Behavior
* The stretchType
attribute of a report element can be used to customize the stretch
* behavior of the element when, on the same report section, there are text fields that stretch
* themselves because their text content is too large for the original text field height. When
* stretchable text fields are present on a report section, the height of the report section
* itself is affected by the stretch.
*
* A report element can respond to the modification of the report section layout in three
* ways:
*
* NoStretch
- The report element preserves its original specified height.
* RelativeToBandHeight
- The report element adapts its height
* to match the new height of the report section it is placed on, which has been
* affected by stretch.
* RelativeToTallestObject
- Report elements can be made to automatically adapt their
* height to fit the amount of stretch suffered by the tallest element in the group that
* they are part of.
*
* Custom Element Properties
* Report elements can define arbitrary properties in the form of name/value pairs.
* JasperReports itself recognizes and uses a set of such properties, and external code can
* recognize further custom element properties.
*
* In report templates, element properties can be defined either as a static name/value pair,
* or as a pair that has a static name and an expression that produces a dynamic value.
*
* Property value expressions are evaluated at the same moment at which the element itself
* gets evaluated; hence for elements that have delayed evaluation, the dynamic properties
* will be evaluated at the moment given by the delayed evaluation type. If the value
* expression evaluates to null, no name/value pair will be set for the element.
*
* Properties that have dynamic values overwrite static properties: if the report has a static
* property and a dynamic property with the same name, the dynamic property value will
* override the static value, unless the value expression evaluates to null.
*
* Some custom element properties are used by the reporting engine at fill time, and others
* are propagated to the generated elements in the filled report and used at export time.
* The first category includes properties such as the ones used to customize text truncation.
* Another example of element properties used at fill time
* are custom chart properties that are recognized by a chart customizer.
*
* The second category includes properties that are defined for report design elements,
* transferred to the print elements generated by the design elements and used when the
* filled report gets exported. An example of such properties are the properties that specify
* export filter criteria.
*
* The JasperReports exporters recognize a limited set of custom element properties, but
* one can extend the built-in exporters to recognize and use further element properties.
* This would allow users to introduce new export functionality, and to parameterize such
* functionality per report element via custom properties.
*
* To determine which element properties need to be propagated into the filled report,
* JasperReports uses a list of configurable property prefixes. Element properties that match
* one of the configured property prefixes are copied into the print elements generated by
* the element from the report template.
*
* The prefixes of properties to be propagated are configured via JasperReports global
* properties of the form
* {@link net.sf.jasperreports.engine.JasperPrint#PROPERTIES_PRINT_TRANSFER_PREFIX net.sf.jasperreports.print.transfer.<arbitrary_suffix>}. The values of
* such properties are used as prefixes for properties that are to be transferred to the filled
* report elements.
*
* The built-in JasperReports configuration defines a single such prefix:
* net.sf.jasperreports.export
. Consequently, all element properties that start with
* this prefix will be propagated to the generated report elements by default.
*
* @author Teodor Danciu ([email protected])
*/
public interface JRElement extends JRChild, JRCommonElement, JRPropertiesHolder, JRIdentifiable
{
/**
* Returns the string value that uniquely identifies the element.
*/
@Override
public String getKey();
/**
* Returns the position type for the element
* @return the position type
*/
public PositionTypeEnum getPositionTypeValue();
/**
* Sets the position type for the element.
* @param positionType the position type
*/
public void setPositionType(PositionTypeEnum positionType);
/**
* Indicates the stretch type for the element
* @return a value representing one of the stretch type constants in {@link StretchTypeEnum}
*/
public StretchTypeEnum getStretchTypeValue();
/**
* Specifies how the engine should treat a missing image.
* @param stretchTypeEnum a value representing one of the stretch type constants in {@link StretchTypeEnum}
*/
public void setStretchType(StretchTypeEnum stretchTypeEnum);
/**
* Specifies if the element value will be printed for every iteration, even if its value has not changed.
* @see JRElement#isRemoveLineWhenBlank()
* @see JRElement#isPrintInFirstWholeBand()
*/
public boolean isPrintRepeatedValues();
/**
*
*/
public void setPrintRepeatedValues(boolean isPrintRepeatedValues);
/**
* Gets the the section relative horizontal offset of the element top left corner.
*/
public int getX();
/**
* Sets the the section relative horizontal offset of the element top left corner.
*/
public void setX(int x);
/**
* Gets the the section relative vertical offset of the element top left corner.
*/
public int getY();
/**
*
*/
public void setWidth(int width);
/**
* Returns true if the remaining blank space appearing when the value is not printed will be removed. Under certain
* circumstances (the element has an empty string as its value or contains a repeated value that is supressed) the
* space reserved for the current element remains empty. If this method returns true, it means the engine will try
* to suppress the blank line, but will only succeed if no other elements occupy the same vertical space.
*/
public boolean isRemoveLineWhenBlank();
/**
* Specifies whether the remaining blank space appearing when the value is not printed will be removed. Under certain
* circumstances (the element has an empty string as its value or contains a repeated value that is supressed) the
* space reserved for the current element remains empty. If the parameter is set to true, it means the engine will try
* to suppress the blank line, but will only succeed if no other elements occupy the same vertical space.
*/
public void setRemoveLineWhenBlank(boolean isRemoveLineWhenBlank);
/**
* Returns true if an element with a printRepeatedValues attribute set to true will be redisplayed for every
* new page or column that is not an overflow from a previous page or column.
* @see JRElement#isPrintRepeatedValues()
*/
public boolean isPrintInFirstWholeBand();
/**
* Specifies whether an element with a printRepeatedValues attribute set to true should be redisplayed for every
* new page or column that is not an overflow from a previous page or column.
* @see JRElement#isPrintRepeatedValues()
*/
public void setPrintInFirstWholeBand(boolean isPrintInFirstWholeBand);
/**
* If this is set to true, the element will be reprinted on the next page if the band does not fit in the current page.
* Actually if there is at least one element with this attribute, the band is redisplayed from the beginning, except
* those elements that fitted in the current page and have isPrintWhenDetailOverflow set to false.
*/
public boolean isPrintWhenDetailOverflows();
/**
* If this is set to true, the element will be reprinted on the next page if the band does not fit in the current page.
* Actually if there is at least one element with this attribute, the band is redisplayed from the beginning, except
* those elements that fitted in the current page and have isPrintWhenDetailOverflow set to false.
*/
public void setPrintWhenDetailOverflows(boolean isPrintWhenDetailOverflows);
/**
* Gets the expression that is evaluated in order to decide if the element should be displayed. This
* expression always returns a boolean value.
*/
public JRExpression getPrintWhenExpression();
/**
* Returns the group for which an element with a printRepeatedValues attribute set to true will be redisplayed
* even if the value has not changed.
* @see JRElement#isPrintRepeatedValues()
*/
public JRGroup getPrintWhenGroupChanges();
/**
* Indicates the logical group that the element belongs to. More elements can be grouped in order to make some of them stretch
* relative to the height of their parent group.
* @see StretchTypeEnum
*/
public JRElementGroup getElementGroup();
/**
*
*/
public void collectExpressions(JRExpressionCollector collector);
/**
* Returns the list of dynamic/expression-based properties for this report element.
*
* @return an array containing the expression-based properties of this report element
*/
public JRPropertyExpression[] getPropertyExpressions();
public JRElement clone(JRElementGroup parentGroup, int y);
}