Interface JRTextField
- All Superinterfaces:
Cloneable
,JRAnchor
,JRBoxContainer
,JRChild
,JRCloneable
,JRCommonElement
,JRCommonText
,JRElement
,JREvaluation
,JRFont
,JRHyperlink
,JRIdentifiable
,JRParagraphContainer
,JRPropertiesHolder
,JRStyleContainer
,JRTextAlignment
,JRTextElement
,JRVisitable
- All Known Implementing Classes:
JRBaseTextField
,JRDesignTextField
,JRFillTextField
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 theisStretchWithOverflow
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 (theevaluationTime
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.getEvaluationTime()
):
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 reachedColumn
- The text field expression is evaluated when the end of the current column is reachedGroup
- The text field expression is evaluated when the group specified by theevaluationGroup
attribute (seeJREvaluation.getEvaluationGroup()
) changesAuto
- Each variable participating in the text field expression is evaluated at a time corresponding to its reset type. Fields are evaluatedNow
. This evaluation type should be used for expressions that combine values evaluated at different times, like the percentage out of a total
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 theisBlankWhenNull
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 thepattern
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 tojava.text.DateFormat
styles), orHide
. The formatter is constructed by calling one of thegetDateTimeInstance()
,getDateInstance()
, orgetTimeInstance()
methods ofjava.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.
java.text.DecimalFormat
and
java.text.SimpleDateFormat
classes.- Author:
- Teodor Danciu (teodord@users.sourceforge.net)
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
static final String
static final String
Provides a default pattern to be used forjava.sql.Date
values.static final String
Provides a default pattern to be used forjava.util.Date
values other thanjava.sql.Date
andjava.sql.Time
.static final String
Provides a default pattern to be used for numerical values that are known to be integer, i.e.static final String
Provides a default pattern to be used for numerical values other than the integer types.static final String
Provides a default pattern to be used forjava.sql.Time
values.static final String
static final String
static final String
Fields inherited from interface net.sf.jasperreports.engine.JRAnchor
NO_BOOKMARK
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.JRElement
PROPERTY_ELEMENT_TEMPLATE_POPULATE_STYLE
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.JRTextElement
PROPERTY_PRINT_KEEP_FULL_TEXT, PROPERTY_SAVE_LINE_BREAKS, PROPERTY_TRUNCATE_AT_CHAR, PROPERTY_TRUNCATE_SUFFIX
-
Method Summary
Modifier and TypeMethodDescriptionGets the expression for this field.Gets the pattern used for this text field.Gets the pattern expression, in case the patter needs to be dynamic.Gets the text adjust type.boolean
Indicates whether an empty string will be displayed if the field's expression evaluates tonull
.void
setBlankWhenNull
(Boolean isBlank) Specifies whether an empty string should be displayed if the field's expression evaluates tonull
.void
setPattern
(String pattern) Sets the pattern used for this text field.void
setTextAdjust
(TextAdjustEnum textAdjust) Sets the text adjust type.Methods inherited from interface net.sf.jasperreports.engine.JRAnchor
getAnchorNameExpression, getBookmarkLevel, getBookmarkLevelExpression
Methods inherited from interface net.sf.jasperreports.engine.JRBoxContainer
getDefaultLineColor, getLineBox
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.JRCommonText
getFontSize, getMarkup, getOwnMarkup, getOwnRotation, getRotation, setMarkup, setRotation
Methods inherited from interface net.sf.jasperreports.engine.JRElement
clone, collectExpressions, getElementGroup, getPositionType, getPrintWhenExpression, getPrintWhenGroupChanges, getPropertyExpressions, getStretchType, getStyleExpression, getX, getY, isPrintInFirstWholeBand, isPrintRepeatedValues, isPrintWhenDetailOverflows, isRemoveLineWhenBlank, setPositionType, setPrintInFirstWholeBand, setPrintRepeatedValues, setPrintWhenDetailOverflows, setRemoveLineWhenBlank, setStretchType, setWidth, setX
Methods inherited from interface net.sf.jasperreports.engine.JREvaluation
getEvaluationGroup, getEvaluationTime
Methods inherited from interface net.sf.jasperreports.engine.JRFont
getFontName, getFontSize, getOwnFontName, getOwnFontSize, getOwnPdfEncoding, getOwnPdfFontName, getPdfEncoding, getPdfFontName, isBold, isItalic, isOwnBold, isOwnItalic, isOwnPdfEmbedded, isOwnStrikeThrough, isOwnUnderline, isPdfEmbedded, isStrikeThrough, isUnderline, setBold, setFontName, setFontSize, setItalic, setPdfEmbedded, setPdfEncoding, setPdfFontName, setStrikeThrough, setUnderline
Methods inherited from interface net.sf.jasperreports.engine.JRHyperlink
getHyperlinkAnchorExpression, getHyperlinkPageExpression, getHyperlinkParameters, getHyperlinkReferenceExpression, getHyperlinkTarget, getHyperlinkTooltipExpression, getHyperlinkType, getHyperlinkWhenExpression, getLinkTarget, getLinkType
Methods inherited from interface net.sf.jasperreports.engine.JRIdentifiable
getUUID
Methods inherited from interface net.sf.jasperreports.engine.JRParagraphContainer
getParagraph
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.JRTextAlignment
getHorizontalTextAlign, getOwnHorizontalTextAlign, getOwnVerticalTextAlign, getVerticalTextAlign, setHorizontalTextAlign, setVerticalTextAlign
Methods inherited from interface net.sf.jasperreports.engine.JRVisitable
visit
-
Field Details
-
PROPERTY_FORMAT_TIMEZONE
- See Also:
-
PROPERTY_SQL_DATE_FORMAT_TIMEZONE
- See Also:
-
PROPERTY_SQL_TIMESTAMP_FORMAT_TIMEZONE
- See Also:
-
PROPERTY_SQL_TIME_FORMAT_TIMEZONE
- See Also:
-
FORMAT_TIMEZONE_SYSTEM
- See Also:
-
PROPERTY_PATTERN_DATE
Provides a default pattern to be used forjava.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:
-
PROPERTY_PATTERN_TIME
Provides a default pattern to be used forjava.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:
-
PROPERTY_PATTERN_DATETIME
Provides a default pattern to be used forjava.util.Date
values other thanjava.sql.Date
andjava.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:
-
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 andjava.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:
-
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:
-
-
Method Details
-
getTextAdjust
TextAdjustEnum getTextAdjust()Gets the text adjust type.- Returns:
- a value representing one of the text adjust constants in
TextAdjustEnum
-
setTextAdjust
Sets the text adjust type.- Parameters:
textAdjust
- a value representing one of the text adjust type constants inTextAdjustEnum
-
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
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 tonull
.- Returns:
- true if an empty string will be displayed instead of null values, false otherwise
-
isOwnBlankWhenNull
Boolean isOwnBlankWhenNull() -
setBlankWhenNull
Specifies whether an empty string should be displayed if the field's expression evaluates tonull
.- Parameters:
isBlank
- true if an empty string will be displayed instead of null values, false otherwise
-
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:
-