com.github.exerrk.engine.JRTextField Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of core Show documentation
The newest version!
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2016 TIBCO Software Inc. 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 com.github.exerrk.engine;

import com.github.exerrk.annotations.properties.Property;
import com.github.exerrk.annotations.properties.PropertyScope;
import com.github.exerrk.properties.PropertyConstants;

//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:
 * 
 * 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 {@link com.github.exerrk.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 com.github.exerrk.engine.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 {@link #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 {@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:
 * 

 * 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.
 * 
 * @see com.github.exerrk.engine.JREvaluation
 * @author Teodor Danciu ([email protected])
 */
public interface JRTextField extends JRTextElement, JREvaluation, JRAnchor, JRHyperlink
{

	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.ELEMENT},
			sinceVersion = PropertyConstants.VERSION_5_0_0
			)
	public static final String PROPERTY_FORMAT_TIMEZONE = JRPropertiesUtil.PROPERTY_PREFIX + "pattern.timezone";

	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.DATASET},
			sinceVersion = PropertyConstants.VERSION_6_1_1
			)
	public static final String PROPERTY_SQL_DATE_FORMAT_TIMEZONE = JRPropertiesUtil.PROPERTY_PREFIX + "sql.date.pattern.timezone";

	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.DATASET},
			sinceVersion = PropertyConstants.VERSION_6_1_1
			)
	public static final String PROPERTY_SQL_TIMESTAMP_FORMAT_TIMEZONE = JRPropertiesUtil.PROPERTY_PREFIX + "sql.timestamp.pattern.timezone";

	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.DATASET},
			sinceVersion = PropertyConstants.VERSION_6_1_1
			)
	public static final String PROPERTY_SQL_TIME_FORMAT_TIMEZONE = JRPropertiesUtil.PROPERTY_PREFIX + "sql.time.pattern.timezone";

	public static final String FORMAT_TIMEZONE_SYSTEM = "System";

	/**
	 * 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
	 */
	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.CONTEXT},
			sinceVersion = PropertyConstants.VERSION_6_0_0
			)
	public static final String PROPERTY_PATTERN_DATE = JRPropertiesUtil.PROPERTY_PREFIX + "text.pattern.date";

	/**
	 * 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
	 */
	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.CONTEXT},
			sinceVersion = PropertyConstants.VERSION_6_0_0
			)
	public static final String PROPERTY_PATTERN_TIME = JRPropertiesUtil.PROPERTY_PREFIX + "text.pattern.time";

	/**
	 * 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
	 */
	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.CONTEXT},
			sinceVersion = PropertyConstants.VERSION_6_0_0
			)
	public static final String PROPERTY_PATTERN_DATETIME = JRPropertiesUtil.PROPERTY_PREFIX + "text.pattern.datetime";

	/**
	 * 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
	 */
	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.CONTEXT},
			sinceVersion = PropertyConstants.VERSION_6_0_0
			)
	public static final String PROPERTY_PATTERN_INTEGER = JRPropertiesUtil.PROPERTY_PREFIX + "text.pattern.integer";

	/**
	 * 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
	 */
	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			scopes = {PropertyScope.CONTEXT},
			sinceVersion = PropertyConstants.VERSION_6_0_0
			)
	public static final String PROPERTY_PATTERN_NUMBER = JRPropertiesUtil.PROPERTY_PREFIX + "text.pattern.number";
	
	/**
	 * 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();

}