net.sf.jasperreports.engine.JRElement Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jasperreports Show documentation
Free Java Reporting Library
There is a newer version: 6.21.3
/*
 * JasperReports - Free Java Reporting Library.
 * Copyright (C) 2001 - 2023 Cloud Software Group, 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 net.sf.jasperreports.engine;

import net.sf.jasperreports.annotations.properties.Property;
import net.sf.jasperreports.annotations.properties.PropertyScope;
import net.sf.jasperreports.engine.type.PositionTypeEnum;
import net.sf.jasperreports.engine.type.StretchTypeEnum;
import net.sf.jasperreports.properties.PropertyConstants;


/**
 * An abstract representation of a report element. All report elements implement this interface. The interface contains
 * constants and methods that apply to all report elements.
 * 
 * The properties that are common to all types of report elements are grouped in the
 * <reportElement> tag, which appears in the declaration of all report elements.
 * 
Element Key
 * Unlike variables and parameters, report elements are not required to have a name,
 * because normally you do not need to obtain any individual element inside a report
 * template. However, in some cases it is useful to be able to locate an element to alter one
 * of its properties before using the report template.
 * 
 * This could be the case in an application for which the color of some elements in the
 * report template needs to change based on user input. To locate the report elements that
 * need to have their colors altered, the caller program could use the
 * {@link JRBand#getElementByKey(String)} method available at band level. A key value must be
 * associated with the report element and it must be unique within the overall band for the
 * lookup to work.
 * 
Element Position
 * 
 * Absolute position
 * The x and y attributes of any report element are mandatory and represent the x and y
 * coordinates, measured in pixels, that mark the absolute position of the top-left corner of
 * the specified element within its parent report section.
 * Relative position
 * Some report elements, such as text fields, have special properties that allow them to
 * stretch downward to acquire all the information they have to display. Their height is
 * calculated at runtime and may affect the neighboring elements in the same report section,
 * especially those placed immediately below them.
 * 

 * The positionType attribute specifies the behavior that the report element will have if
 * the layout of the report section in which it is been placed is stretched.
 * 
 * There are three possible values for the positionType attribute:
 * 
 * Float - The element floats in its parent section if it is pushed downward
 * by other elements found above it. It tries to conserve the distance between it and
 * the neighboring elements placed immediately above it
 * FixRelativeToTop - The current report element
 * simply ignores what happens to the other section elements and tries to conserve the
 * y offset measured from the top of its parent report section
 * FixRelativeToBottom - If the height of the parent
 * report section is affected by elements that stretch, the current element tries to
 * conserve the original distance between its bottom margin and the bottom of the
 * band
 * 
 * A report element called e2 will float when another report element e1 stretches only if
 * these three conditions are met:
 * 
 * e2 has positionType="Float"
 * e1.y + e1.height <= e2.y
 * e1.width + e2.width > max(e1.x + e1.width, e2.x + e2.width) - min(e1.x, e2.x)
 * 
 * The second and third conditions together imply that the element e2 must be placed
 * below the e1. By default, all elements have a fixed position relative to the top of the
 * band.
 * Skipping Element Display
 * The engine can decide at runtime if it really should display a report element when a
 * <printWhenExpression> is used, which is available for all types of report elements.
 * 
 * If present, this report expression should return a java.lang.Boolean object or null. It
 * is evaluated every time the section containing the current element is generated, in order
 * to see whether this particular element should appear in the report or not. If the expression
 * returns null, it is equivalent to returning java.lang.Boolean.FALSE. If the
 * expression is missing, then the report element will get printed every time - that is, if
 * other settings do not intervene.
 * 
Reprinting Elements on Section Overflows
 * When generating a report section, the engine might be forced to start a new page or
 * column because the remaining space at the bottom of the current page or column is not
 * sufficient for all the section elements to fit in, probably because some elements have
 * stretched. In such cases, you might want to reprint some of the already displayed
 * elements on the new page or column to recreate the context in which the page/column
 * break occurred.
 * 
 * To achieve this, set isPrintWhenDetailOverflows="true" for all report elements
 * you want to reappear on the next page or column.
 * 
Suppressing Repeated Values Display
 * First, let's see what exactly a "repeating value" is. It very much depends on the type of
 * the report element we are talking about. For textfield elements, this is very intuitive. 
 * For instance, in an ordinary phone book, one can see that
 * for some consecutive lines, the value of the Family Name column repeats itself. You might want 
 * to suppress the repeating Family Name values and print only their first occurrence. To 
 * do that, set the following for the text field that displays the family name:
 * 
 * isPrintRepeatedValues="false"
 * 

 * The static text elements behave in the same way. As you would expect, their value
 * always repeats and in fact never changes until the end of the report. This is why we call
 * them static texts. So, if you set isPrintRepeatedValues="false" for one of your
 * <staticText> elements, it is displayed only once, the first time, at the beginning of the
 * report, and never again.
 * 

 * Now, what about graphic elements? An image is considered to be repeating itself if its
 * bytes are exactly the same from one occurrence to the next. This happens only if you
 * choose to cache your images using the isUsingCache attribute available in the 
 * <image> (see {@link net.sf.jasperreports.engine.JRImage}
 * element and if the corresponding <imageExpression> returns the same value from one
 * iteration to the next (the same file name, the same URL, etc.).
 * 

 * Lines and rectangles always repeat themselves because they are static elements, just like
 * the static texts shown previously. So, when you suppress repeating values for a line or a
 * rectangle, it is displayed only once, at the beginning of the report, and then ignored until
 * the end of the report.
 * 

 * Note: The isPrintRepeatedValues attribute works only if the corresponding
 * <printWhenExpression> is missing. If it is not missing, it will always dictate 
 * whether the element should be printed, regardless of the repeating values.
 * 

 * If you decide to not display the repeating values for some of your report elements, you
 * can modify this behavior by indicating the exceptional occasions in which you might
 * want to have a particular value redisplayed during the report-generation process.
 * 

 * When the repeating value spans multiple pages or columns, you can redisplay this
 * repeating value at least once for every page or column. If you set
 * isPrintInFirstWholeBand="true", then the report element will reappear in the first
 * band of a new page or column that is not an overflow from a previous page or column.
 * Also, if the repeating value you have suppressed spans multiple groups, you can make it
 * reappear at the beginning of a certain report group if you specify the name of that
 * particular group in the printWhenGroupChanges attribute.
 * 
Removing Blank Space
 * When a report element is not displayed for some reason (for example,
 * <printWhenExpression> evaluates to Boolean.FALSE, or a repeated value is
 * suppressed), the area where the report element stood at design time will be left empty.
 * This blank space also appears if a text field displays only blank characters or an empty
 * text value. You can eliminate this unwanted blank space on the vertical axis only if
 * certain conditions are met.
 * 
 * The blank space will be removed only if the empty text field doesn't share any vertical space with
 * other report elements that are printed, even if this empty textfield does not print. If this 
 * condition is met, then set isRemoveLineWhenBlank= "true" for the empty textfield.
 * 
Stretch Behavior
 * The stretchType attribute of a report element can be used to customize the stretch
 * behavior of the element when, on the same report section, there are text fields that stretch
 * themselves because their text content is too large for the original text field height. When
 * stretchable text fields are present on a report section, the height of the report section
 * itself is affected by the stretch.
 * 
 * A report element can respond to the modification of the report section layout in three
 * ways:
 * 

 * NoStretch - The report element preserves its original specified height.
 * RelativeToBandHeight - The report element adapts its height
 * to match the new height of the report section it is placed on, which has been
 * affected by stretch.
 * RelativeToTallestObject - Report elements can be made to automatically adapt their
 * height to fit the amount of stretch suffered by the tallest element in the group that
 * they are part of.
 * 
 * Custom Element Properties
 * Report elements can define arbitrary properties in the form of name/value pairs.
 * JasperReports itself recognizes and uses a set of such properties, and external code can
 * recognize further custom element properties.
 * 
 * In report templates, element properties can be defined either as a static name/value pair,
 * or as a pair that has a static name and an expression that produces a dynamic value.
 * 

 * Property value expressions are evaluated at the same moment at which the element itself
 * gets evaluated; hence for elements that have delayed evaluation, the dynamic properties
 * will be evaluated at the moment given by the delayed evaluation type. If the value
 * expression evaluates to null, no name/value pair will be set for the element.
 * 

 * Properties that have dynamic values overwrite static properties: if the report has a static
 * property and a dynamic property with the same name, the dynamic property value will
 * override the static value, unless the value expression evaluates to null.
 * 

 * Some custom element properties are used by the reporting engine at fill time, and others
 * are propagated to the generated elements in the filled report and used at export time.
 * The first category includes properties such as the ones used to customize text truncation.
 * Another example of element properties used at fill time
 * are custom chart properties that are recognized by a chart customizer.
 * 

 * The second category includes properties that are defined for report design elements,
 * transferred to the print elements generated by the design elements and used when the
 * filled report gets exported. An example of such properties are the properties that specify
 * export filter criteria.
 * 

 * The JasperReports exporters recognize a limited set of custom element properties, but
 * one can extend the built-in exporters to recognize and use further element properties.
 * This would allow users to introduce new export functionality, and to parameterize such
 * functionality per report element via custom properties.
 * 

 * To determine which element properties need to be propagated into the filled report,
 * JasperReports uses a list of configurable property prefixes. Element properties that match
 * one of the configured property prefixes are copied into the print elements generated by
 * the element from the report template.
 * 

 * The prefixes of properties to be propagated are configured via JasperReports global
 * properties of the form
 * {@link net.sf.jasperreports.engine.JasperPrint#PROPERTIES_PRINT_TRANSFER_PREFIX net.sf.jasperreports.print.transfer.<arbitrary_suffix>}. The values of
 * such properties are used as prefixes for properties that are to be transferred to the filled
 * report elements.
 * 
 * The built-in JasperReports configuration defines a single such prefix:
 * net.sf.jasperreports.export. Consequently, all element properties that start with
 * this prefix will be propagated to the generated report elements by default.
 * 
 * @author Teodor Danciu ([email protected])
 */
public interface JRElement extends JRChild, JRCommonElement, JRPropertiesHolder, JRIdentifiable
{

	@Property(
			category = PropertyConstants.CATEGORY_FILL,
			defaultValue = PropertyConstants.BOOLEAN_FALSE,
			scopes = {PropertyScope.CONTEXT, PropertyScope.REPORT, PropertyScope.ELEMENT},
			sinceVersion = PropertyConstants.VERSION_6_20_1,
			valueType = Boolean.class
			)
	public static final String PROPERTY_ELEMENT_TEMPLATE_POPULATE_STYLE = JRPropertiesUtil.PROPERTY_PREFIX + "element.template.populate.style";

	/**
	 * Returns the string value that uniquely identifies the element.
	 */
	@Override
	public String getKey();

	/**
	 * Returns the position type for the element
	 * @return the position type
	 */
	public PositionTypeEnum getPositionTypeValue();

	/**
	 * Sets the position type for the element.
	 * @param positionType the position type
	 */
	public void setPositionType(PositionTypeEnum positionType);

	/**
	 * Indicates the stretch type for the element
	 * @return a value representing one of the stretch type constants in {@link StretchTypeEnum}
	 */
	public StretchTypeEnum getStretchTypeValue();
	
	/**
	 * Specifies how the engine should treat a missing image.
	 * @param stretchTypeEnum a value representing one of the stretch type constants in {@link StretchTypeEnum}
	 */
	public void setStretchType(StretchTypeEnum stretchTypeEnum);
	
	/**
	 * Specifies if the element value will be printed for every iteration, even if its value has not changed.
	 * @see JRElement#isRemoveLineWhenBlank()
	 * @see JRElement#isPrintInFirstWholeBand()
	 */
	public boolean isPrintRepeatedValues();
	
	/**
	 *
	 */
	public void setPrintRepeatedValues(boolean isPrintRepeatedValues);


	/**
	 * Gets the the section relative horizontal offset of the element top left corner.
	 */
	public int getX();
	
	/**
	 * Sets the the section relative horizontal offset of the element top left corner.
	 */
	public void setX(int x);
	
	/**
	 * Gets the the section relative vertical offset of the element top left corner.
	 */
	public int getY();
	
	/**
	 *
	 */
	public void setWidth(int width);
	
	/**
	 * Returns true if the remaining blank space appearing when the value is not printed will be removed. Under certain
	 * circumstances (the element has an empty string as its value or contains a repeated value that is supressed) the
	 * space reserved for the current element remains empty. If this method returns true, it means the engine will try
	 * to suppress the blank line, but will only succeed if no other elements occupy the same vertical space.
	 */
	public boolean isRemoveLineWhenBlank();
	
	/**
	 * Specifies whether the remaining blank space appearing when the value is not printed will be removed. Under certain
	 * circumstances (the element has an empty string as its value or contains a repeated value that is supressed) the
	 * space reserved for the current element remains empty. If the parameter is set to true, it means the engine will try
	 * to suppress the blank line, but will only succeed if no other elements occupy the same vertical space.
	 */
	public void setRemoveLineWhenBlank(boolean isRemoveLineWhenBlank);
	
	/**
	 * Returns true if an element with a printRepeatedValues attribute set to true will be redisplayed for every
	 * new page or column that is not an overflow from a previous page or column.
	 * @see JRElement#isPrintRepeatedValues()
	 */
	public boolean isPrintInFirstWholeBand();
	
	/**
	 * Specifies whether an element with a printRepeatedValues attribute set to true should be redisplayed for every
	 * new page or column that is not an overflow from a previous page or column.
	 * @see JRElement#isPrintRepeatedValues()
	 */
	public void setPrintInFirstWholeBand(boolean isPrintInFirstWholeBand);
	
	/**
	 * If this is set to true, the element will be reprinted on the next page if the band does not fit in the current page.
	 * Actually if there is at least one element with this attribute, the band is redisplayed from the beginning, except
	 * those elements that fitted in the current page and have isPrintWhenDetailOverflow set to false.
	 */
	public boolean isPrintWhenDetailOverflows();
	
	/**
	 * If this is set to true, the element will be reprinted on the next page if the band does not fit in the current page.
	 * Actually if there is at least one element with this attribute, the band is redisplayed from the beginning, except
	 * those elements that fitted in the current page and have isPrintWhenDetailOverflow set to false.
	 */
	public void setPrintWhenDetailOverflows(boolean isPrintWhenDetailOverflows);
	
	/**
	 * Gets the expression that is evaluated in order to decide if the element should be displayed. This
	 * expression always returns a boolean value.
	 */
	public JRExpression getPrintWhenExpression();
	
	/**
	 * Returns the group for which an element with a printRepeatedValues attribute set to true will be redisplayed
	 * even if the value has not changed.
	 * @see JRElement#isPrintRepeatedValues()
	 */
	public JRGroup getPrintWhenGroupChanges();
	
	/**
	 * Indicates the logical group that the element belongs to. More elements can be grouped in order to make some of them stretch
	 * relative to the height of their parent group.
	 * @see StretchTypeEnum
	 */
	public JRElementGroup getElementGroup();

	/**
	 *
	 */
	public void collectExpressions(JRExpressionCollector collector);


	/**
	 * Returns the list of dynamic/expression-based properties for this report element.
	 * 
	 * @return an array containing the expression-based properties of this report element
	 */
	public JRPropertyExpression[] getPropertyExpressions();
	
	public JRElement clone(JRElementGroup parentGroup, int y);
}