<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>stretch</name>
  <title>Stretch Sample</title>
  <description>Shows how dynamic text fields can stretch to display their entire content and different ways to put a border around such text fields.</description>

  <mainFeature ref="stretch"/>
  
  <!-- stretch -->
  
  <feature name="stretch" title="Stretching Text Fields">
    <description>
How to make text fields resize dynamically and render all their runtime text content.
    </description>
    <since>0.1.0</since>
    <documentedBy>
      <author>
    	<name>Sanda Zaharia</name>
    	<email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<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 
(<code>x</code> and <code>y</code>) and two rectangular dimensions (<code>width</code> and 
<code>height</code>). 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  
<code>width</code> and <code>height</code>, 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 <code>width</code> and <code>height</code> 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 <code>spliType</code> attribute in the <code>&lt;band&gt;</code> element).
<br/>
<br/>
<b>Report Element Position</b>    
<br/>
<br/>
The other two mandatory attributes in a report element are the <code>x</code> and <code>y</code> 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 <code>positionType</code> 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 <code>positionType</code> attribute:
<ul>
<li><code>positionType="Float"</code> - 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><code>positionType="FixRelativeToTop"</code> - 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><code>positionType="FixRelativeToBottom"</code> - 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 <code>stretchType</code> 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 <code>stretchType</code> 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><code>strechType= "NoStretch"</code> - The element won't stretch. It preserves its original height.</li>
<li><code>stretchType="ElementGroupHeight"</code> - the element will adapt its height to match the changing 
height of the overall element group it is part of, without taking into account changes of the Y position of the 
element due to floating and/or collapsing white space above it.</li>
<li><code>stretchType="ElementGroupBottom"</code> - the element will adapt its height to match the changing 
height of the overall element group it is part of, taking into account changes of the Y position of the 
element due to floating and/or collapsing white space above it. The element's distance to the group's initial 
bottom edge will be preserved.</li>
<li><code>stretchType="ContainerHeight"</code> - the element will adapt its height to match the new 
height of the container it is placed on, without taking into account changes of the Y position of the 
element due to floating and/or collapsing white space above it.</li>
<li><code>stretchType="ContainerBottom"</code> - the element will adapt its height to match the new 
height of the container it is placed on, taking into account changes of the Y position of the 
element due to floating and/or collapsing white space above it. The element's distance to the container's initial 
bottom edge will be preserved.</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 
<code>textAdjust</code> attribute in the <code>&lt;textField/&gt;</code> element. 
If <code>StretchHeight</code> value is set, then the text field height will be automatically increased until the 
whole text content can be displayed.
The font size can be decreased so that the text fits using the <code>ScaleFont</code> value. 
The default value is <code>CutText</code>.
<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><code>net.sf.jasperreports.text.truncate.at.char</code> - 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><code>net.sf.jasperreports.text.truncate.suffix</code> - 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><code>net.sf.jasperreports.print.keep.full.text</code> - 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 (<code>positionType</code>, <code>stretchType</code>, <code>textAdjust</code>):
<pre><![CDATA[
  <elementGroup>
  <line>
    <reportElement positionType="Float" stretchType="ElementGroupHeight" x="5" y="5" 
      width="1" height="16" isPrintWhenDetailOverflows="true"/>
    <graphicElement/>
  </line>
  <textField textAdjust="StretchHeight">
    <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="ElementGroupHeight" x="135" y="5" 
      width="1" height="16" isPrintWhenDetailOverflows="true"/>
    <graphicElement/>
  </line>
  </elementGroup>]]></pre>
or text truncation properties:
<pre><![CDATA[
  <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/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/stretch</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/stretch/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.
    </content>
  </feature>

</sample>
