/* * JasperReports - Free Java Reporting Library. * Copyright (C) 2001 - 2013 Jaspersoft Corporation. All rights reserved. * http://www.jaspersoft.com * * Unless you have purchased a commercial license agreement from Jaspersoft, * the following license terms apply: * * This program is part of JasperReports. * * JasperReports is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * JasperReports is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with JasperReports. If not, see . */ package net.sf.jasperreports.engine; //import java.text.Format; /** * 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 {@link #getExpression()}) and can return values from various types, like the ones listed below: * *

Evaluating Text Fields

* JasperReports provides a feature (the evaluationTime attribute * inherited from {@link net.sf.jasperreports.engine.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 {@link net.sf.jasperreports.engine.JREvaluation#getEvaluationTimeValue()}): *

*

* 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 {@link #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 {@link #getPattern()}) or the * <patternExpression> element (see {@link #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: *

* 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. * * @see net.sf.jasperreports.engine.JREvaluation * @author Teodor Danciu (teodord@users.sourceforge.net) * @version $Id: JRTextField.java 7076 2014-05-06 10:10:35Z shertage $ */ public interface JRTextField extends JRTextElement, JREvaluation, JRAnchor, JRHyperlink { public static final String PROPERTY_FORMAT_TIMEZONE = JRPropertiesUtil.PROPERTY_PREFIX + "pattern.timezone"; public static final String FORMAT_TIMEZONE_SYSTEM = "System"; /** * Specifies whether the text field will stretch vertically if its text does not fit in one line. * @return true if the text field will stretch vertically, false otherwise */ public boolean isStretchWithOverflow(); /** * Set to true if the text field should stretch vertically if its text does not fit in one line. */ public void setStretchWithOverflow(boolean isStretchWithOverflow); /** * 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. * @return a string containing the pattern. */ public String getPattern(); public String getOwnPattern(); /** * 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. */ public void setPattern(String pattern); /** * Indicates whether an empty string will be displayed if the field's expression evaluates to null. * @return true if an empty string will be displayed instead of null values, false otherwise */ public boolean isBlankWhenNull(); public Boolean isOwnBlankWhenNull(); /** * Specifies whether an empty string sholuld be displayed if the field's expression evaluates to null. * @param isBlank true if an empty string will be displayed instead of null values, false otherwise */ public void setBlankWhenNull(boolean isBlank); public void setBlankWhenNull(Boolean isBlank); /** * Gets the expression for this field. The result obtained after evaluating this expression will be dispayed as * the field text. */ public JRExpression getExpression(); /** * Gets the pattern expression, in case the patter needs to be dynamic. * @see #getPattern() */ public JRExpression getPatternExpression(); }