net.sf.jasperreports.engine

Interface JRElement

All Superinterfaces:

Cloneable, JRChild, JRCloneable, JRCommonElement, JRIdentifiable, JRPropertiesHolder, JRStyleContainer, JRVisitable

All Known Subinterfaces:

JRBreak, JRChart, JRComponentElement, JRCrosstab, JREllipse, JRFrame, JRGenericElement, JRGraphicElement, JRImage, JRLine, JRRectangle, JRStaticText, JRSubreport, JRTextElement, JRTextField

All Known Implementing Classes:

ElementDecorator, FillTableSubreport, JRBaseBreak, JRBaseChart, JRBaseComponentElement, JRBaseCrosstab, JRBaseElement, JRBaseEllipse, JRBaseFrame, JRBaseGenericElement, JRBaseGraphicElement, JRBaseImage, JRBaseLine, JRBaseRectangle, JRBaseStaticText, JRBaseSubreport, JRBaseTextElement, JRBaseTextField, JRDesignBreak, JRDesignChart, JRDesignComponentElement, JRDesignCrosstab, JRDesignElement, JRDesignEllipse, JRDesignFrame, JRDesignGenericElement, JRDesignGraphicElement, JRDesignImage, JRDesignLine, JRDesignRectangle, JRDesignStaticText, JRDesignSubreport, JRDesignTextElement, JRDesignTextField, JRFillBreak, JRFillChart, JRFillComponentElement, JRFillCrosstab, JRFillElement, JRFillEllipse, JRFillFrame, JRFillGenericElement, JRFillGraphicElement, JRFillImage, JRFillLine, JRFillRectangle, JRFillStaticText, JRFillSubreport, JRFillTextElement, JRFillTextField, TableSubreport

public interface JRElement
extends JRChild, JRCommonElement, JRPropertiesHolder, JRIdentifiable

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 JRElementGroup.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 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 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 (teodord@users.sourceforge.net)

Method Summary

Methods

Modifier and Type	Method and Description
JRElement	clone(JRElementGroup parentGroup, int y)
void	collectExpressions(JRExpressionCollector collector)
JRElementGroup	getElementGroup() Indicates the logical group that the element belongs to.
String	getKey() Returns the string value that uniquely identifies the element.
PositionTypeEnum	getPositionTypeValue() Returns the position type for the element
JRExpression	getPrintWhenExpression() Gets the expression that is evaluated in order to decide if the element should be displayed.
JRGroup	getPrintWhenGroupChanges() Returns the group for which an element with a printRepeatedValues attribute set to true will be redisplayed even if the value has not changed.
JRPropertyExpression[]	getPropertyExpressions() Returns the list of dynamic/expression-based properties for this report element.
StretchTypeEnum	getStretchTypeValue() Indicates the stretch type for the element
int	getX() Gets the the section relative horizontal offset of the element top left corner.
int	getY() Gets the the section relative vertical offset of the element top left corner.
boolean	isPrintInFirstWholeBand() 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.
boolean	isPrintRepeatedValues() Specifies if the element value will be printed for every iteration, even if its value has not changed.
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.
boolean	isRemoveLineWhenBlank() Returns true if the remaining blank space appearing when the value is not printed will be removed.
void	setPositionType(PositionTypeEnum positionType) Sets the position type for the element.
void	setPrintInFirstWholeBand(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.
void	setPrintRepeatedValues(boolean isPrintRepeatedValues)
void	setPrintWhenDetailOverflows(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.
void	setRemoveLineWhenBlank(boolean isRemoveLineWhenBlank) Specifies whether the remaining blank space appearing when the value is not printed will be removed.
void	setStretchType(StretchTypeEnum stretchTypeEnum) Specifies how the engine should treat a missing image.
void	setWidth(int width)
void	setX(int x) Sets the the section relative horizontal offset of the element top left corner.

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.JRCommonElement

getBackcolor, getForecolor, getHeight, getModeValue, getOwnBackcolor, getOwnForecolor, getOwnModeValue, getWidth, setBackcolor, setForecolor, setMode

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

getDefaultStyleProvider, getStyle, getStyleNameReference

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

getParentProperties, getPropertiesMap, hasProperties

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

getUUID

Method Detail

getKey

String getKey()

Returns the string value that uniquely identifies the element.

Specified by:

getKey in interface JRCommonElement

getPositionTypeValue

PositionTypeEnum getPositionTypeValue()

Returns the position type for the element

Returns:

the position type

setPositionType

void setPositionType(PositionTypeEnum positionType)

Sets the position type for the element.

Parameters:

positionType - the position type

getStretchTypeValue

StretchTypeEnum getStretchTypeValue()

Indicates the stretch type for the element

Returns:

a value representing one of the stretch type constants in StretchTypeEnum

setStretchType

void setStretchType(StretchTypeEnum stretchTypeEnum)

Specifies how the engine should treat a missing image.

Parameters:

stretchTypeEnum - a value representing one of the stretch type constants in StretchTypeEnum

isPrintRepeatedValues

boolean isPrintRepeatedValues()

Specifies if the element value will be printed for every iteration, even if its value has not changed.

See Also:

isRemoveLineWhenBlank(), isPrintInFirstWholeBand()

setPrintRepeatedValues

void setPrintRepeatedValues(boolean isPrintRepeatedValues)

getX

int getX()

Gets the the section relative horizontal offset of the element top left corner.

setX

void setX(int x)

Sets the the section relative horizontal offset of the element top left corner.

getY

int getY()

Gets the the section relative vertical offset of the element top left corner.

setWidth

void setWidth(int width)

isRemoveLineWhenBlank

boolean isRemoveLineWhenBlank()

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.

setRemoveLineWhenBlank

void setRemoveLineWhenBlank(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.

isPrintInFirstWholeBand

boolean isPrintInFirstWholeBand()

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

isPrintRepeatedValues()

setPrintInFirstWholeBand

void setPrintInFirstWholeBand(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 Also:

isPrintRepeatedValues()

isPrintWhenDetailOverflows

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.

setPrintWhenDetailOverflows

void setPrintWhenDetailOverflows(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.

getPrintWhenExpression

JRExpression getPrintWhenExpression()

Gets the expression that is evaluated in order to decide if the element should be displayed. This expression always returns a boolean value.

getPrintWhenGroupChanges

JRGroup getPrintWhenGroupChanges()

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

isPrintRepeatedValues()

getElementGroup

JRElementGroup getElementGroup()

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

StretchTypeEnum

collectExpressions

void collectExpressions(JRExpressionCollector collector)

getPropertyExpressions

JRPropertyExpression[] getPropertyExpressions()

Returns the list of dynamic/expression-based properties for this report element.

Returns:

an array containing the expression-based properties of this report element

clone

JRElement clone(JRElementGroup parentGroup,
              int y)