Text Elements

Two elements are specifically designed to display text in a report: static text and text field. Static text is used for creating labels or printing static text set at design time that is not meant to change when the report is generated. That said, in some cases you still use a text field to print labels too, since the nature of the static text elements prevents the ability to display text dynamically translated in different languages when the report is run with a specific locale and it is configured to use a resource bundle using the JasperReports internationalization capabilities.

A text field is similar to a static text string, but the content (the text in the field) is provided using an expression (which can be a simple static text string itself). That expression can return several kinds of value types, allowing the user to specify a pattern to format that value. Since the text specified dynamically can have an arbitrary length, a text field provides several options about how the text must be treated regarding alignment, position, line breaks and so on. Optionally, the text field is able to grow vertically to fit the content when required.

By default both text elements are transparent with no border, with a black text color. The most used text properties can be modified using the text tool bar displayed when a text element is selected. Text element properties can also be modified using the Properties view.

Text fields support hyperlinks as well. See Creating a Hyperlink for more information.

Static Text

The static text element is used to show non-dynamic text in reports. The only parameter that distinguishes this element from a generic text element is the Text property, where the text to view is specified: it is a normal text, not an expression, and so it is not necessary to enclose it in double quotes to respect the conventions of Java, Groovy, or JavaScript syntax.

Text Fields

A text field allows you to print an arbitrary section of text (or a number or a date) created using an expression. The simplest case of use of a text field is to print a constant string (java.lang.String) created using an expression like this:

"This is a text"

A text field that prints a constant value like the one returned by this expression can be easily replaced by a static field. Actually, the use of an expression to define the content of a text field provides a high level of control on the generated text (even if it is just constant text). A common case is when labels have to be internationalized and loaded from a resource bundle. In general, an expression can contain fields, variables, and parameters, so you can print in a text field the value of a field and set the format of the value to present. For this purpose, a text field expression does not have to necessarily return a string (that is a text value): the text field expression class name property specifies what type of value is returned by the expression. It can be one of the following:

Valid Expression Types

java.lang.Object

java.sql.Time

java.lang.Long

java.lang.Boolean

java.lang.Double

java.lang.Short

java.lang.Byte

java.lang.Float

java.math.BigDecimal

java.util.Date

java.lang.Integer

java.lang.String

java.sql.Timestamp

java.io.InputStream

 

An incorrect expression class is frequently the cause of compilation errors. If you use Groovy or JavaScript, you can choose String as the expression type without causing an error when the report is compiled. The side effect is that without specifying the right expression class, the pattern (if set) is not applied to the value.

Let us see what properties can be set for a text field:

Blank when null

If set to true, this option avoids printing the text field content if the expression result is a null object that produces the text “null” when converted in a string.

Evaluation time

Determines in which phase of the report creation the Text field Expression has to be elaborated.

Evaluation group

The group to which the evaluation time is referred if it is set to Group.
Stretch with overflow

Deprecated. Replaced with Text Adjust.
Text Adjust

This option allows the text field to adapt vertically to the content, if the element is not sufficient to contain all the text lines. Select the required option from the following:

• CutText: The text is cut if it does not fit the text field element size.
• StretchHeight: The text field element is stretched in height to accommodate the entire content.
• ScaleFont: The font size of the text is scaled down so that the entire content fits the text field element size.
Pattern

The pattern property allows you to set a mask to format a value. It is used only when the expression class is congruent with the pattern to apply, meaning you need a numeric value to apply a mask to format a number, or a date to use a date pattern.