<html xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jr="http://jasperreports.sourceforge.net/jasperreports">
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>JasperReports 4.0.2 - Stretch Sample</title>
<style type="text/css">
.title {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 28px;
font-weight: normal;
}
.toc {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.name {
font-family: Courier New, Courier, serif;
font-size: 16px;
font-weight: bold;
}
.label {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: bold;
font-style: italic;
}
.description {
font-family: Arial, Verdana, Helvetica, sans-serif;
font-size: 12px;
font-weight: normal;
}
.value {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.element {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.attribute {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: bold;
}
.code {
font-family: Courier New, Courier, serif;
font-size: 12px;
font-weight: normal;
}
.copy {
font-decoration: none;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 8pt;
font-style: normal;
color: #000000;
}
.subtitle {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: bold;
text-decoration: none;
color: inherit;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td colspan="2" align="right"><span class="element"><a href="../../sample.reference.html">Sample Reference</a> - <a href="../../schema.reference.html">Schema Reference</a> - <a href="../../config.reference.html">Configuration Reference</a> - <a href="http://jasperreports.sourceforge.net/api/index.html">API (Javadoc)</a></span>
<br>
</td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
<tr valign="middle">
<td nowrap="true"><span class="title">JasperReports - Stretch Sample (version 4.0.2)</span></td><td align="right"><img src="../../resources/jasperreports.png" border="0"></td>
</tr>
<tr>
<td colspan="2">
<hr size="1">
</td>
</tr>
</table>
<br>
<span class="description"><span class="description">Shows how dynamic text fields can stretch to display their entire content and different ways to put a border around such text fields.</span></span>
<br>
<br>
<span class="element"><a href="http://sourceforge.net/projects/jasperreports/files/jasperreports/JasperReports%204.0.2/jasperreports-4.0.2-project.zip/download" target="_blank">Download All Sample Source Files</a></span>
<br>
<span class="element"><a href="http://jasperforge.org/scm/viewvc.php/tags/jr-4-0-2/jasperreports/demo/samples/stretch/?root=jasperreports" target="_blank">Browse Sample Source Files on SVN</a></span>
<table width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td style="width: 20px;">
<br>
</td><td>
<br>
</td>
</tr>
<tr>
<td colspan="2"><span class="label">Main Features in This Sample</span></td>
</tr>
<tr>
<td>
<br>
</td><td><span class="element"><a href="#stretch">Stretching Text Fields</a></span></td>
</tr>
</table>
<table width="100%" cellspacing="0" cellpadding="0" border="0">
<tr>
<td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td><img src="../../resources/px.gif" border="0" width="20" height="1"></td><td width="80%">
<br>
</td><td width="20%">
<br>
</td>
</tr>
<tr>
<td colspan="6" align="right"><a name="stretch"></a><a href="#top" class="toc">top</a></td>
</tr>
<tr>
<td colspan="6">
<hr size="1">
</td>
</tr>
<tr valign="top">
<td><img src="../../resources/jr-16x16.png" border="0"></td><td colspan="4"><span class="name">Stretching Text Fields</span></td><td align="right"><span class="copy">Documented by
<a href="mailto:shertage@users.sourceforge.net" class="copy">Sanda Zaharia</a></span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr valign="top">
<td>
<br>
</td><td nowrap="true"><span class="label">Description / Goal</span></td><td>
<br>
</td><td colspan="3"><span class="description">
How to make text fields resize dynamically and render all their runtime text content.
</span></td>
</tr>
<tr valign="top">
<td>
<br>
</td><td colspan="1"><span class="label">Since</span></td><td>
<br>
</td><td colspan="3"><span class="description">0.1.0</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
<tr>
<td>
<br>
</td><td colspan="5"><span class="description">
<b>Pixel-Perfect Representation and Report Element Stretch</b>
<br>
<br>
JasperReports prepares documents ready to be printed out in a pixel-perfect representation.
In order to accomplish this, each report element provides four mandatory attributes used to
determine the absolute position of the element within the document layout: two coordinates
(<span class="code"><code>x</code></span> and <span class="code"><code>y</code></span>) and two rectangular dimensions (<span class="code"><code>width</code></span> and
<span class="code"><code>height</code></span>). When all elements in the document contain static information only,
these four attributes are sufficient to completely localize an element within the page, because
the amount of space needed to represent static data can be calculated at report design time.
<br>
But dynamic elements may be involved in a report design too. These elements may acquire their data
at runtime, and one cannot calculate the most appropriate dimensions needed to display the entire
element's information. It is possible that when running the report the content of a text element do not fit
into its precalculated area. In this case the engine will either truncate the
text content or, if stretching is allowed for that element, increase the height of
the element to accommodate the content. To do so, runtime measurements and calculations are required.
<br>
Usually, the stretching process refers to the height adjustment only. When stretching report elements,
adjusting the width could affect also the page width and raise unexpected errors at runtime (for instance, truncated
information could be printed out on pages). This is why stretching an element let its width unchanged, while its height
gets definitely enlarged in order to make room for all information that have to be displayed.
<br>
<br>
<b>Report Element Size</b>
<br>
<br>
Any report element's size can be calculated using the two mandatory attributes
<span class="code"><code>width</code></span> and <span class="code"><code>height</code></span>, measured in pixels. They can be set
only at report design time and afterwards their value remains invariant.
<br>
This is a satisfactory solution for elements with static content only, because one can very
simple to determine the rectangle area needed to expose the entire element content, and the
element won't need any size adjustment at runtime.
<br>
However, for dynamic elements both content and actual size are completely determined at runtime.
Therefore some element stretching settings are necessary to instruct the reporting engine to ignore
the element's original size attributes and allow it to stretch in height. Even in this case, the
static <span class="code"><code>width</code></span> and <span class="code"><code>height</code></span> attributes still
remain mandatory, since the element may not be smaller than the originally specified dimensions.
<br>
Stretching elements in height can be managed very well, due to the section split facility: with very few exceptions (ie the
column and page footers), report sections can also stretch beyond the initial specified height, and split onto next page (see
the <span class="code"><code>spliType</code></span> attribute in the <span class="code"><code><band></code></span> element).
<br>
<br>
<b>Report Element Position</b>
<br>
<br>
The other two mandatory attributes in a report element are the <span class="code"><code>x</code></span> and <span class="code"><code>y</code></span> coordinates,
measured in pixels, that mark the absolute position of the top-left corner of the specified element within
its parent report section.
<br>
These coordinates remain invariant if all elements in the report would have only static content.
<br>
Things change when dynamic text fields are implied and some of them stretch beyond the initial dimensions to allow
the whole information to be displayed at runtime. This may affect the neighboring elements
in the same report section, especially those placed immediately below them. When a given element
stretches in height, all elements below should rearrange themselves in order to avoid their overlapping.
Usually they have to be translated with the same amount downwards along the
vertical axis. As consequence, the report section containing that element will be stretched too.
<br>
The <span class="code"><code>positionType</code></span> attribute specifies the behavior that a report element will have if
the layout of the report section in which it is been placed is stretched.
<br>
There are three possible values for the <span class="code"><code>positionType</code></span> attribute:
<ul>
<li>
<span class="code"><code>positionType="Float"</code></span> - 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.</li>
<li>
<span class="code"><code>positionType="FixRelativeToTop"</code></span> - 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. This is the default position.</li>
<li>
<span class="code"><code>positionType="FixRelativeToBottom"</code></span> - 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 section.</li>
</ul>
<br>
<br>
<b>The <span class="code"><code>stretchType</code></span> Attribute</b>
<br>
<br>
When stretchable text fields are present on a report section, the height of the report section
itself is affected by the stretch. In this case the engine should be instructed how to represent
the other report elements existing in a stretched section, in order to preserve as much as possible
the pixel-perfect representation.
<br>
The <span class="code"><code>stretchType</code></span> attribute of a report element can be used to customize the stretch
behavior of the element when the enclosing report section stretches itself according to the
text fields which stretch themselves. The element response to the modification of the report section
layout could be:
<ul>
<li>
<span class="code"><code>strechType= "NoStretch"</code></span> - The element won't stretch. It preserves its original height.</li>
<li>
<span class="code"><code>stretchType="RelativeToBandHeight"</code></span> - The element adjusts its height to fit the new height of the
report section it belongs to.</li>
<li>
<span class="code"><code>stretchType="RelativeToTallestObject"</code></span> - if the element belongs to an element group, it can
adjust its height to fit the new height of the tallest element in that group</li>
</ul>
<br>
<br>
<b>Dynamic Text Fields</b>
<br>
<br>
Text fields are elements with specific stretch behavior. When their content does not fit within
their boundaries, the engine either truncate them to fit within the initial dimensions, or recalculates their height in order to make
room for all the text content. Text fields are the elements which require dynamic text measurement
at runtime and then start the element size recalculation for all the elements in the affected section.
After text fields are measured and stretched, all other elements in
the same section are resized or repositioned, according to their own stretching attributes.
<br>
To decide whether a text field content gets truncated at runtime or no, one can use the
<span class="code"><code>isStretchWithOverflow</code></span> attribute in the <span class="code"><code><textField/></code></span> element.
If <span class="code"><code>true</code></span>, then the text field height will be automatically increased until the
whole text content can be displayed. The default value is <span class="code"><code>false</code></span>.
<br>
<br>
<b>Notes:</b>
<ol>
<li>Text fields with delayed evaluation do not stretch to acquire all the expression’s content. This is
because the text element height is calculated when the report section is generated, and even if the engine comes
back later with the text content of the text field, the element height will not adapt, because this would ruin the
already created layout.
</li>
<li>When filling report templates horizontally, dynamic text fields inside the detail section
do not stretch to their entire text content, because this might cause misalignment on the
horizontal axis of subsequent detail sections. The detail band actually behaves the same
as the page and column footers, preserving its declared height when horizontal filling is
used.</li>
</ol>
<b>Text Truncation</b>
<br>
<br>
In some situations preserving the initial layout takes precedence over any other runtime modification. If
the text content gets wider than the available area, then a truncation mechanism is applied in order to keep
only the part of text which fits within the original boundaries. If one choose the text truncation as desired
behavior for a text element, a series of custom properties can be set to indicate how to perform the truncation:
<ul>
<li>
<span class="code"><code>net.sf.jasperreports.text.truncate.at.char</code></span> - Flag that determines whether text elements are to
be truncated at the last character that fits. By default, when the entire text of a text element does not fit
the element's area, the text is truncated at the last word that fits the area.</li>
<li>
<span class="code"><code>net.sf.jasperreports.text.truncate.suffix</code></span> - Contains a suffix for the truncated text. The suffix
is appended to the text when truncation occurs. If the property is not defined, no suffix will be used when the
text is truncated.</li>
<li>
<span class="code"><code>net.sf.jasperreports.print.keep.full.text</code></span> - Flag to determine whether the fill process must preserve
the original text for text elements that are not able to fit their entire contents. When this property is set, the
engine saves the original text in the JRPrintText print text object, along with the index at which the text is to
be truncated by the print object. The original text can be then entirely exported to layout insensitive formats such as
CSV, XML, Excel.</li>
</ul>
<br>
<br>
<b>Text Truncation and Element Stretching Examples</b>
<br>
<br>
This sample provides some examples of element stretching and text truncations. One can see various combinations between
different elements stretching attributes (<span class="code"><code>positionType</code></span>, <span class="code"><code>stretchType</code></span>, <span class="code"><code>isStretchWithOverflow</code></span>):
<pre>
<elementGroup>
<line>
<reportElement positionType="Float" stretchType="RelativeToTallestObject" x="5" y="5"
width="1" height="16" isPrintWhenDetailOverflows="true"/>
<graphicElement/>
</line>
<textField isStretchWithOverflow="true">
<reportElement x="10" y="5" width="100" height="16" isRemoveLineWhenBlank="true"/>
<textElement textAlignment="Justified">
<font size="12"/>
</textElement>
<textFieldExpression class="java.lang.String">
This is a FIRST long chunk of text that will cause the text field to stretch
outside its defined height and force other elements to move downwards.
</textFieldExpression>
</textField>
<line>
<reportElement positionType="Float" stretchType="RelativeToTallestObject" x="135" y="5"
width="1" height="16" isPrintWhenDetailOverflows="true"/>
<graphicElement/>
</line>
</elementGroup></pre>
or text truncation properties:
<pre>
<staticText>
<reportElement x="145" y="205" width="130" height="100">
<property name="net.sf.jasperreports.text.truncate.at.char" value="true"/>
</reportElement>
<textElement>
<font size="10"/>
</textElement>
<text>Text elements can also be truncated at the last character that fits
the element reserved area; the behavior is triggered by setting a property.
This sentence might not fit fully in the space reserved for the element.
</text>
</staticText></pre>
<b>Running the Sample</b>
<br>
<br>
Running the sample requires the <a href="http://ant.apache.org/" target="_blank" class="element">Apache Ant</a> library. Make sure that <span class="code"><code>ant</code></span> is already installed on your system (version 1.5 or later).
<br>
In a command prompt/terminal window set the current folder to <span class="code"><code>demo/samples/stretch</code></span> within the JasperReports source project and run the <span class="code"><code>> ant test view</code></span> command.
<br>
It will generate all supported document types containing the sample report in the <span class="code"><code>demo/samples/stretch/build/reports</code></span> directory.
<br>
Then the report will open in the JasperReports internal viewer.
</span></td>
</tr>
<tr>
<td colspan="6">
<br>
</td>
</tr>
</table>
<br>
<table cellspacing="0" cellpadding="0" border="0" width="100%">
<tr>
<td>
<hr size="1">
</td>
</tr>
<tr>
<td align="center"><span class="copy">© 2001-2010 Jaspersoft Corporation <a href="http://www.jaspersoft.com" target="_blank" class="copy">www.jaspersoft.com</a></span></td>
</tr>
</table>
</body>
</html>
