net.sf.jasperreports.engine

Interface JRTextField

All Superinterfaces:

Cloneable, JRAlignment, JRAnchor, JRBoxContainer, JRChild, JRCloneable, JRCommonElement, JRCommonText, JRElement, JREvaluation, JRFont, JRHyperlink, JRIdentifiable, JRParagraphContainer, JRPropertiesHolder, JRStyleContainer, JRTextAlignment, JRTextElement, JRVisitable

All Known Implementing Classes:

JRBaseTextField, JRDesignTextField, JRFillTextField

public interface JRTextField
extends JRTextElement, JREvaluation, JRAnchor, JRHyperlink

An abstract representation of a report text. It provides functionality for dynamic texts.

Unlike static text elements, which do not change their text content, text fields have an associated expression that is evaluated with every iteration in the data source to obtain the text content to be displayed.

Variable-Height Text Fields

Because text fields have dynamic content, most of the time one can't anticipate the exact amount of space to provide for them. If the space reserved for the text fields is not sufficient, the text content is truncated so that it fits into the available area.

This scenario is not always acceptable, so one can let the reporting engine calculate the amount of space required to display the entire content of the text field at runtime, and automatically adjust the size of the report element.

To do this, set the isStretchWithOverflow flag to true for the particular text field elements you are interested in. By doing this, you'll ensure that if the specified height for the text field is not sufficient, it will automatically be increased (never decreased) in order to be able to display the entire text content. When text fields are affected by this stretch mechanism, the entire report section to which they belong is also stretched.

Text Field Expression

A text field expression is introduced in the JRXML template by the <textFieldExpression> element (see getExpression()) and can return values from various types, like the ones listed below:

• java.lang.Boolean
• java.lang.Byte
• java.util.Date
• java.sql.Timestamp
• java.sql.Time
• java.lang.Double
• java.lang.Float
• java.lang.Integer
• java.lang.Long
• java.lang.Short
• java.math.BigDecimal
• java.lang.Number
• java.lang.String

Evaluating Text Fields

JasperReports provides a feature (the evaluationTime attribute inherited from JREvaluation) that lets you decide the exact moment you want the text field expression to be evaluated, avoiding the default behavior in which the expression is evaluated immediately when the current report section is generated.

The evaluationTime attribute can have one of the following values (see JREvaluation.getEvaluationTimeValue()):

• Now - The text field expression is evaluated when the current band is filled.
• Report - The text field expression is evaluated when the end of the report is reached.
• Page - The text field expression is evaluated when the end of the current page is reached
• Column - The text field expression is evaluated when the end of the current column is reached
• Group - The text field expression is evaluated when the group specified by the evaluationGroup attribute (see JREvaluation.getEvaluationGroup()) changes
• Auto - Each variable participating in the text field expression is evaluated at a time corresponding to its reset type. Fields are evaluated Now. This evaluation type should be used for expressions that combine values evaluated at different times, like the percentage out of a total

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.

Also, avoid using evaluation type Auto when other types suffice, as it can lead to performance loss.

Suppressing the Display of the Null Values

If the text field expression returns null, your text field will display the null text in the generated document. A simple way to avoid this is to set the isBlankWhenNull attribute (see isBlankWhenNull()) to true. By doing this, the text field will cease to display null and will instead display an empty string. This way nothing will appear on your document if the text field value is null.

Formatting Output

When dealing with numeric or date/time values, you can use the Java API to format the output of the text field expressions. But there is a more convenient way to do it: by using either the pattern attribute (see getPattern()) or the <patternExpression> element (see getPatternExpression()).

The engine instantiates the java.text.DecimalFormat class if the text field expression returns subclasses of the java.lang.Number class, or instantiates the java.text.SimpleDataFormat if the text field expression returns java.util.Date, java.sql.Timestamp or java.sql.Time objects. For numeric fields, the value you should supply to this attribute is the same as if you formatted the value using java.text.DecimalFormat. For date/time fields, the value of this attribute has to be one of the following:

• A style for the date part of the value and one for the time part, separated by a comma, or one style for both the date part and the time part. A style is one of Short, Medium, Long, Full, Default (corresponding to java.text.DateFormat styles), or Hide. The formatter is constructed by calling one of the getDateTimeInstance(), getDateInstance(), or getTimeInstance() methods of java.text.DateFormat (depending on one of the date/time parts being hidden) and supplying the date/time styles and report locale.
• A pattern that can be supplied to java.text.SimpleDateFormat. Note that in this case the internationalization support is limited.

For more details about the syntax of this pattern attribute, check the Java API documentation for the java.text.DecimalFormat and java.text.SimpleDateFormat classes.

Author:

Teodor Danciu (teodord@users.sourceforge.net)

See Also:

JREvaluation

Field Summary

Fields

Modifier and Type	Field and Description
static String	FORMAT_TIMEZONE_SYSTEM
static String	PROPERTY_FORMAT_TIMEZONE
static String	PROPERTY_PATTERN_DATE Provides a default pattern to be used for java.sql.Date values.
static String	PROPERTY_PATTERN_DATETIME Provides a default pattern to be used for java.util.Date values other than java.sql.Date and java.sql.Time.
static String	PROPERTY_PATTERN_INTEGER Provides a default pattern to be used for numerical values that are known to be integer, i.e. integer primitive wrapper types and java.math.BigInteger.
static String	PROPERTY_PATTERN_NUMBER Provides a default pattern to be used for numerical values other than the integer types.
static String	PROPERTY_PATTERN_TIME Provides a default pattern to be used for java.sql.Time values.
static String	PROPERTY_SQL_DATE_FORMAT_TIMEZONE
static String	PROPERTY_SQL_TIME_FORMAT_TIMEZONE
static String	PROPERTY_SQL_TIMESTAMP_FORMAT_TIMEZONE

Fields inherited from interface net.sf.jasperreports.engine.JRTextElement

PROPERTY_PRINT_KEEP_FULL_TEXT, PROPERTY_SAVE_LINE_BREAKS, PROPERTY_TRUNCATE_AT_CHAR, PROPERTY_TRUNCATE_SUFFIX

Fields inherited from interface net.sf.jasperreports.engine.JRFont

DEFAULT_FONT_NAME, DEFAULT_FONT_SIZE, DEFAULT_PDF_EMBEDDED, DEFAULT_PDF_ENCODING, DEFAULT_PDF_FONT_NAME

Fields inherited from interface net.sf.jasperreports.engine.JRCommonText

MARKUP_HTML, MARKUP_NONE, MARKUP_RTF, MARKUP_STYLED_TEXT

Fields inherited from interface net.sf.jasperreports.engine.JRAnchor

NO_BOOKMARK

Method Summary

Methods

Modifier and Type	Method and Description
JRExpression	getExpression() Gets the expression for this field.
String	getOwnPattern()
String	getPattern() Gets the pattern used for this text field.
JRExpression	getPatternExpression() Gets the pattern expression, in case the patter needs to be dynamic.
boolean	isBlankWhenNull() Indicates whether an empty string will be displayed if the field's expression evaluates to null.
Boolean	isOwnBlankWhenNull()
boolean	isStretchWithOverflow() Specifies whether the text field will stretch vertically if its text does not fit in one line.
void	setBlankWhenNull(boolean isBlank) Specifies whether an empty string sholuld be displayed if the field's expression evaluates to null.
void	setBlankWhenNull(Boolean isBlank)
void	setPattern(String pattern) Sets the pattern used for this text field.
void	setStretchWithOverflow(boolean isStretchWithOverflow) Set to true if the text field should stretch vertically if its text does not fit in one line.

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

clone, collectExpressions, getElementGroup, getKey, getPositionTypeValue, getPrintWhenExpression, getPrintWhenGroupChanges, getPropertyExpressions, getStretchTypeValue, getX, getY, isPrintInFirstWholeBand, isPrintRepeatedValues, isPrintWhenDetailOverflows, isRemoveLineWhenBlank, setPositionType, setPrintInFirstWholeBand, setPrintRepeatedValues, setPrintWhenDetailOverflows, setRemoveLineWhenBlank, setStretchType, setWidth, setX

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

getParentProperties, getPropertiesMap, hasProperties

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

getUUID

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

getHorizontalAlignmentValue, getOwnHorizontalAlignmentValue, getOwnVerticalAlignmentValue, getVerticalAlignmentValue, setHorizontalAlignment, setVerticalAlignment

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

getHorizontalTextAlign, getOwnHorizontalTextAlign, getOwnVerticalTextAlign, getVerticalTextAlign, setHorizontalTextAlign, setVerticalTextAlign

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

getFontName, getFontsize, getFontSize, getOwnFontName, getOwnFontsize, getOwnFontSize, getOwnPdfEncoding, getOwnPdfFontName, getPdfEncoding, getPdfFontName, isBold, isItalic, isOwnBold, isOwnItalic, isOwnPdfEmbedded, isOwnStrikeThrough, isOwnUnderline, isPdfEmbedded, isStrikeThrough, isUnderline, setBold, setBold, setFontName, setFontSize, setFontSize, setFontSize, setItalic, setItalic, setPdfEmbedded, setPdfEmbedded, setPdfEncoding, setPdfFontName, setStrikeThrough, setStrikeThrough, setUnderline, setUnderline

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

getFontsize, getFontSize, getLineSpacingValue, getMarkup, getOwnLineSpacingValue, getOwnMarkup, getOwnRotationValue, getRotationValue, setLineSpacing, setMarkup, setRotation

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

getDefaultLineColor, getLineBox

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

getParagraph

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

getDefaultStyleProvider, getStyle, getStyleNameReference

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

getEvaluationGroup, getEvaluationTimeValue

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

getAnchorNameExpression, getBookmarkLevel

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

getHyperlinkAnchorExpression, getHyperlinkPageExpression, getHyperlinkParameters, getHyperlinkReferenceExpression, getHyperlinkTarget, getHyperlinkTooltipExpression, getHyperlinkTypeValue, getHyperlinkWhenExpression, getLinkTarget, getLinkType

Field Detail

PROPERTY_FORMAT_TIMEZONE

static final String PROPERTY_FORMAT_TIMEZONE

See Also:

Constant Field Values

PROPERTY_SQL_DATE_FORMAT_TIMEZONE

static final String PROPERTY_SQL_DATE_FORMAT_TIMEZONE

See Also:

Constant Field Values

PROPERTY_SQL_TIMESTAMP_FORMAT_TIMEZONE

static final String PROPERTY_SQL_TIMESTAMP_FORMAT_TIMEZONE

See Also:

Constant Field Values

PROPERTY_SQL_TIME_FORMAT_TIMEZONE

static final String PROPERTY_SQL_TIME_FORMAT_TIMEZONE

See Also:

Constant Field Values

FORMAT_TIMEZONE_SYSTEM

static final String FORMAT_TIMEZONE_SYSTEM

See Also:

Constant Field Values

PROPERTY_PATTERN_DATE

static final String PROPERTY_PATTERN_DATE

Provides a default pattern to be used for java.sql.Date values.

Locale specific values can be configured by appending _<locale code> to the property name.

The property can be set at global/JasperReports context level.

Since:

6.0.0

See Also:

Constant Field Values

PROPERTY_PATTERN_TIME

static final String PROPERTY_PATTERN_TIME

Provides a default pattern to be used for java.sql.Time values.

Locale specific values can be configured by appending _<locale code> to the property name.

The property can be set at global/JasperReports context level.

Since:

6.0.0

See Also:

Constant Field Values

PROPERTY_PATTERN_DATETIME

static final String PROPERTY_PATTERN_DATETIME

Provides a default pattern to be used for java.util.Date values other than java.sql.Date and java.sql.Time.

Locale specific values can be configured by appending _<locale code> to the property name.

The property can be set at global/JasperReports context level.

Since:

6.0.0

See Also:

Constant Field Values

PROPERTY_PATTERN_INTEGER

static final String PROPERTY_PATTERN_INTEGER

Provides a default pattern to be used for numerical values that are known to be integer, i.e. integer primitive wrapper types and java.math.BigInteger.

Locale specific values can be configured by appending _<locale code> to the property name.

The property can be set at global/JasperReports context level.

Since:

6.0.0

See Also:

Constant Field Values

PROPERTY_PATTERN_NUMBER

static final String PROPERTY_PATTERN_NUMBER

Provides a default pattern to be used for numerical values other than the integer types.

Locale specific values can be configured by appending _<locale code> to the property name.

The property can be set at global/JasperReports context level.

Since:

6.0.0

See Also:

Constant Field Values

Method Detail

isStretchWithOverflow

boolean isStretchWithOverflow()

Specifies whether the text field will stretch vertically if its text does not fit in one line.

Returns:

true if the text field will stretch vertically, false otherwise

setStretchWithOverflow

void setStretchWithOverflow(boolean isStretchWithOverflow)

Set to true if the text field should stretch vertically if its text does not fit in one line.

getPattern

String getPattern()

Gets the pattern used for this text field. The pattern will be used in a SimpleDateFormat for dates and a DecimalFormat for numeric text fields. The pattern format must follow one of these two classes formatting rules, as specified in the JDK API docs.

Returns:

a string containing the pattern.

getOwnPattern

String getOwnPattern()

setPattern

void setPattern(String pattern)

Sets the pattern used for this text field. The pattern will be used in a SimpleDateFormat for dates and a DecimalFormat for numeric text fields. The pattern format must follow one of these two classes formatting rules, as specified in the JDK API docs. If the pattern is incorrect, the exception thrown by formatter classes will be rethrown by the JasperReports fill engine.

isBlankWhenNull

boolean isBlankWhenNull()

Indicates whether an empty string will be displayed if the field's expression evaluates to null.

Returns:

true if an empty string will be displayed instead of null values, false otherwise

isOwnBlankWhenNull

Boolean isOwnBlankWhenNull()

setBlankWhenNull

void setBlankWhenNull(boolean isBlank)

Specifies whether an empty string sholuld be displayed if the field's expression evaluates to null.

Parameters:

isBlank - true if an empty string will be displayed instead of null values, false otherwise

setBlankWhenNull

void setBlankWhenNull(Boolean isBlank)

getExpression

JRExpression getExpression()

Gets the expression for this field. The result obtained after evaluating this expression will be dispayed as the field text.

getPatternExpression

JRExpression getPatternExpression()

Gets the pattern expression, in case the patter needs to be dynamic.

See Also:

getPattern()