Package 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:
ComponentFillSubreport
,ElementDecorator
,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
,JRFillChartForAxis
,JRFillComponentElement
,JRFillCrosstab
,JRFillElement
,JRFillEllipse
,JRFillFrame
,JRFillGenericElement
,JRFillGraphicElement
,JRFillImage
,JRFillLine
,JRFillRectangle
,JRFillStaticText
,JRFillSubreport
,JRFillTextElement
,JRFillTextField
,SubreportElementAdapter
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 theJRElementGroup.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
andy
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.
ThepositionType
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.
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 itFixRelativeToTop
- 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 sectionFixRelativeToBottom
- 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
- 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)
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, setisPrintWhenDetailOverflows="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
ThestretchType
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 formnet.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)
-
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionclone
(JRElementGroup parentGroup, int y) void
collectExpressions
(JRExpressionCollector collector) Indicates the logical group that the element belongs to.Returns the position type for the elementGets the expression that is evaluated in order to decide if the element should be displayed.Returns the group for which an element with a printRepeatedValues attribute set to true will be redisplayed even if the value has not changed.Returns the list of dynamic/expression-based properties for this report element.Indicates the stretch type for the elementGets the expression that is evaluated in order to obtain the runtime style name to be used 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
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
Specifies if the element value will be printed for every iteration, even if its value has not changed.boolean
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
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.JRCloneable
clone
Methods inherited from interface net.sf.jasperreports.engine.JRCommonElement
getBackcolor, getForecolor, getHeight, getKey, getMode, getOwnBackcolor, getOwnForecolor, getOwnMode, getWidth, setBackcolor, setForecolor, setMode
Methods inherited from interface net.sf.jasperreports.engine.JRIdentifiable
getUUID
Methods inherited from interface net.sf.jasperreports.engine.JRPropertiesHolder
getParentProperties, getPropertiesMap, hasProperties
Methods inherited from interface net.sf.jasperreports.engine.JRStyleContainer
getDefaultStyleProvider, getStyle, getStyleName, getStyleNameReference
Methods inherited from interface net.sf.jasperreports.engine.JRVisitable
visit
-
Field Details
-
PROPERTY_ELEMENT_TEMPLATE_POPULATE_STYLE
- See Also:
-
-
Method Details
-
getPositionType
PositionTypeEnum getPositionType()Returns the position type for the element- Returns:
- the position type
-
setPositionType
Sets the position type for the element.- Parameters:
positionType
- the position type
-
getStretchType
StretchTypeEnum getStretchType()Indicates the stretch type for the element- Returns:
- a value representing one of the stretch type constants in
StretchTypeEnum
-
setStretchType
Specifies how the engine should treat a missing image.- Parameters:
stretchTypeEnum
- a value representing one of the stretch type constants inStretchTypeEnum
-
isPrintRepeatedValues
boolean isPrintRepeatedValues()Specifies if the element value will be printed for every iteration, even if its value has not changed.- See Also:
-
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:
-
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:
-
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
String 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:
-
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:
-
getStyleExpression
JRExpression getStyleExpression()Gets the expression that is evaluated in order to obtain the runtime style name to be used for the element. When used, this expression takes precedence over theJRStyleContainer.getStyle()
orJRStyleContainer.getStyleNameReference()
. -
collectExpressions
-
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
-