net.sf.jasperreports.engine

## Interface JRElement

- All Superinterfaces:
    java.lang.Cloneable, JRChild, JRCloneable, JRCommonElement, JRIdentifiable, JRPropertiesHolder, JRStyleContainer, JRVisitable
  All Known Subinterfaces:
    JRBreak, JRChart, JRComponentElement, JRCrosstab, JREllipse, JRFrame, JRGenericElement, JRGraphicElement, JRImage, JRLine, JRRectangle, JRStaticText, JRSubreport, JRTextElement, JRTextField
  All Known Implementing Classes:
    ElementDecorator, FillTableSubreport, JRBaseBreak, JRBaseChart, JRBaseComponentElement, JRBaseCrosstab, JRBaseElement, JRBaseEllipse, JRBaseFrame, JRBaseGenericElement, JRBaseGraphicElement, JRBaseImage, JRBaseLine, JRBaseRectangle, JRBaseStaticText, JRBaseSubreport, JRBaseTextElement, JRBaseTextField, JRDesignBreak, JRDesignChart, JRDesignComponentElement, JRDesignCrosstab, JRDesignElement, JRDesignEllipse, JRDesignFrame, JRDesignGenericElement, JRDesignGraphicElement, JRDesignImage, JRDesignLine, JRDesignRectangle, JRDesignStaticText, JRDesignSubreport, JRDesignTextElement, JRDesignTextField, JRFillBreak, JRFillChart, JRFillComponentElement, JRFillCrosstab, JRFillElement, JRFillEllipse, JRFillFrame, JRFillGenericElement, JRFillGraphicElement, JRFillImage, JRFillLine, JRFillRectangle, JRFillStaticText, JRFillSubreport, JRFillTextElement, JRFillTextField, TableSubreport

      public interface JRElement
      extends JRChild, JRCommonElement, JRPropertiesHolder, JRIdentifiable

  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 `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 `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 `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.
  Version:
    $Id: JRElement.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JRElement` | `clone(JRElementGroup parentGroup, int y)`
    `void` | `collectExpressions(JRExpressionCollector collector)`
    `JRElementGroup` | `getElementGroup()` Indicates the logical group that the element belongs to.
    `java.lang.String` | `getKey()` Returns the string value that uniquely identifies the element.
    `PositionTypeEnum` | `getPositionTypeValue()` Returns the position type for the element
    `JRExpression` | `getPrintWhenExpression()` Gets the expression that is evaluated in order to decide if the element should be displayed.
    `JRGroup` | `getPrintWhenGroupChanges()` Returns the group for which an element with a printRepeatedValues attribute set to true will be redisplayed even if the value has not changed.
    `JRPropertyExpression[]` | `getPropertyExpressions()` Returns the list of dynamic/expression-based properties for this report element.
    `StretchTypeEnum` | `getStretchTypeValue()` Indicates the stretch type for the element
    `int` | `getX()` Gets the the section relative horizontal offset of the element top left corner.
    `int` | `getY()` Gets the the section relative vertical offset of the element top left corner.
    `boolean` | `isPrintInFirstWholeBand()` 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.
    `boolean` | `isPrintRepeatedValues()` Specifies if the element value will be printed for every iteration, even if its value has not changed.
    `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.
    `boolean` | `isRemoveLineWhenBlank()` Returns true if the remaining blank space appearing when the value is not printed will be removed.
    `void` | `setPositionType(PositionTypeEnum positionType)` Sets the position type for the element.
    `void` | `setPrintInFirstWholeBand(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.
    `void` | `setPrintRepeatedValues(boolean isPrintRepeatedValues)`
    `void` | `setPrintWhenDetailOverflows(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.
    `void` | `setRemoveLineWhenBlank(boolean isRemoveLineWhenBlank)` Specifies whether the remaining blank space appearing when the value is not printed will be removed.
    `void` | `setStretchType(StretchTypeEnum stretchTypeEnum)` Specifies how the engine should treat a missing image.
    `void` | `setWidth(int width)`
    `void` | `setX(int x)` Sets the the section relative horizontal offset of the element top left corner.

    - ### 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.JRCommonElement

      `getBackcolor, getForecolor, getHeight, getModeValue, getOwnBackcolor, getOwnForecolor, getOwnModeValue, getWidth, setBackcolor, setForecolor, setMode`

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

      `getDefaultStyleProvider, getStyle, getStyleNameReference`

    - ### Methods inherited from interface net.sf.jasperreports.engine.JRPropertiesHolder

      `getParentProperties, getPropertiesMap, hasProperties`

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

      `getUUID`

- - ### Method Detail

    - #### getKey

          java.lang.String getKey()

      Returns the string value that uniquely identifies the element.
      Specified by:
        `getKey` in interface `JRCommonElement`

    - #### getPositionTypeValue

          PositionTypeEnum getPositionTypeValue()

      Returns the position type for the element
      Returns:
        the position type

    - #### setPositionType

          void setPositionType(PositionTypeEnum positionType)

      Sets the position type for the element.
      Parameters:
        `positionType` - the position type

    - #### getStretchTypeValue

          StretchTypeEnum getStretchTypeValue()

      Indicates the stretch type for the element
      Returns:
        a value representing one of the stretch type constants in `StretchTypeEnum`

    - #### setStretchType

          void setStretchType(StretchTypeEnum stretchTypeEnum)

      Specifies how the engine should treat a missing image.
      Parameters:
        `stretchTypeEnum` - a value representing one of the stretch type constants in `StretchTypeEnum`

    - #### isPrintRepeatedValues

          boolean isPrintRepeatedValues()

      Specifies if the element value will be printed for every iteration, even if its value has not changed.
      See Also:
        `isRemoveLineWhenBlank()`, `isPrintInFirstWholeBand()`

    - #### setPrintRepeatedValues

          void setPrintRepeatedValues(boolean isPrintRepeatedValues)

    - #### getX

          int getX()

      Gets the the section relative horizontal offset of the element top left corner.

    - #### setX

          void setX(int x)

      Sets the the section relative horizontal offset of the element top left corner.

    - #### getY

          int getY()

      Gets the the section relative vertical offset of the element top left corner.

    - #### setWidth

          void setWidth(int width)

    - #### isRemoveLineWhenBlank

          boolean isRemoveLineWhenBlank()

      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.

    - #### setRemoveLineWhenBlank

          void setRemoveLineWhenBlank(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.

    - #### isPrintInFirstWholeBand

          boolean isPrintInFirstWholeBand()

      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 Also:
        `isPrintRepeatedValues()`

    - #### setPrintInFirstWholeBand

          void setPrintInFirstWholeBand(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 Also:
        `isPrintRepeatedValues()`

    - #### isPrintWhenDetailOverflows

          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.

    - #### setPrintWhenDetailOverflows

          void setPrintWhenDetailOverflows(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.

    - #### getPrintWhenExpression

          JRExpression getPrintWhenExpression()

      Gets the expression that is evaluated in order to decide if the element should be displayed. This expression always returns a boolean value.

    - #### getPrintWhenGroupChanges

          JRGroup getPrintWhenGroupChanges()

      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 Also:
        `isPrintRepeatedValues()`

    - #### getElementGroup

          JRElementGroup getElementGroup()

      Indicates the logical group that the element belongs to. More elements can be grouped in order to get the height of the tallest one.
      See Also:
        `StretchTypeEnum.RELATIVE_TO_TALLEST_OBJECT`

    - #### collectExpressions

          void collectExpressions(JRExpressionCollector collector)

    - #### getPropertyExpressions

          JRPropertyExpression[] getPropertyExpressions()

      Returns the list of dynamic/expression-based properties for this report element.
      Returns:
        an array containing the expression-based properties of this report element

    - #### clone

          JRElement clone(JRElementGroup parentGroup,
                        int y)

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com