net.sf.jasperreports.engine

## Interface JRCommonImage

- All Superinterfaces:
    JRBoxContainer, JRCommonElement, JRCommonGraphicElement, JRPenContainer, JRStyleContainer
  All Known Subinterfaces:
    JRImage, JRPrintImage
  All Known Implementing Classes:
    JRBaseImage, JRBasePrintImage, JRDesignImage, JRFillImage, JRRecordedValuesPrintImage, JRTemplateImage, JRTemplatePrintImage

      public interface JRCommonImage
      extends JRCommonGraphicElement, JRBoxContainer

  An abstract representation that provides basic functionality for images.

  The most complex graphics on a report are the images. Just as for text field elements, their content is dynamically evaluated at runtime, using a report expression.

  ### Scaling Images

  Since images are loaded at runtime, there is no way to know their exact size when creating the report template. The dimensions of the image element specified at design time may differ from the actual image loaded at runtime. One must define how the image should adapt to the original image element dimensions specified in the report template. The `scaleImage` attribute (see `getScaleImageValue()`) allows users to choose one of the following values:
  `Clip`
    If the actual image is larger than the image element size, it will be cut off so that it keeps its original resolution, and only the region that fits the specified size will be displayed.
  `FillFrame`
    If the dimensions of the actual image do not fit those specified for the image element that displays it, the image is forced to obey them and stretch itself so that it fits in the designated output area. It will be deformed if necessary.
  `RetainShape`
    If the actual image does not fit into the image element, it can be adapted to those dimensions while keeping its original undeformed proportions.
  `RealHeight`
    The image can be stretched vertically to match the actual image height, while preserving the declared width of the image element.
  `RealSize`
    The image can be stretched vertically to match the actual image height, while adjusting the width of the image element to match the actual image width.

  ### Stretching Images

  The last two options allow report designers to specify a minimum height for the image element in the report template and to rely on the fact that the image element will stretch at fill time to accommodate the actual size of the rendered picture.

  Note that, as for stretchable text fields, only the image height can increase. This follows the JasperReports principle that design element widths are fixed, and that the report flows downwards while data is fed to it.

  As mentioned above, there are two scale types that allow images to stretch: `RealHeight` and `RealSize`. The difference between them is that the former always preserves the width of the image element, while the latter adjusts the width of the image when the actual image width is smaller than the design image width. Adjusting the image width is useful when a border needs to be drawn around the image; if the image width is not adjusted, then the border might get drawn according to the design image width and some empty space would be left between the image and the border.

  In order for image stretching to work, the actual image size needs to be known at report fill time. For images that use image files as sources, the image size will always be known. For images that use other type of renderers, the image size is determined by calling the `getDimension()` method on the image renderer object, which is an instance of a class that implements `Renderable`. If the method returns a null dimension, the actual image size will not be known and the image will not stretch, but will render inside the area given by the design image width and height.

  Another inherent limitation is that images that have delayed evaluation will not be able to stretch. Stretching such images is not supported because the actual image size can only be know after the image has been positioned in the generated report and other elements have been placed beneath the image, and stretching the image at this point would disturb the layout of the generated report.

  Stretching images will always preserve proportions and will never get deformed. Any scaling which performed to the image will be performed uniformly on the horizontal and vertical axes.

  If the actual image width is larger than the design width of the image element, the image will be scaled down to fit the element width set at design time. In other words, the design image width acts as an upper limit of the width of the generated image.

  When the engine stretches an image, if the actual image height is bigger than the vertical space left to the bottom of the page, the image will cause the band to overflow and the engine will render the image on the new report page or column. If the vertical space available here is still not enough to render the image at its actual size, the image will be scaled down to fit the available height.

  Note that if the actual height of the image is smaller than the declared height of the image, the height of the generated image will not be decreased. The produced image will always be at least as tall as the design image element, its height can only be increased when the report is filled.
  Version:
    $Id: JRCommonImage.java 7045 2014-04-24 14:20:46Z shertage $
  Author:
    Teodor Danciu (teodord@users.sourceforge.net)
  See Also:
    `Renderable`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ScaleImageEnum` | `getOwnScaleImageValue()` Gets the image own scale type.
    `ScaleImageEnum` | `getScaleImageValue()` Gets the image scale type.
    `void` | `setScaleImage(ScaleImageEnum scaleImageEnum)` Sets the image scale type.

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

      `getFillValue, getLinePen, getOwnFillValue, setFill`

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

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

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

      `getDefaultLineColor, getDefaultLineWidth`

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

      `getDefaultStyleProvider, getStyle, getStyleNameReference`

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

      `getDefaultLineColor, getLineBox`

- - ### Method Detail

    - #### getScaleImageValue

          ScaleImageEnum getScaleImageValue()

      Gets the image scale type.
      Returns:
        a value representing one of the scale type constants in `ScaleImageEnum`

    - #### getOwnScaleImageValue

          ScaleImageEnum getOwnScaleImageValue()

      Gets the image own scale type.
      Returns:
        a value representing one of the scale type constants in `ScaleImageEnum`

    - #### setScaleImage

          void setScaleImage(ScaleImageEnum scaleImageEnum)

      Sets the image scale type.
      Parameters:
        `scaleImageEnum` - a value representing one of the scale type constants in `ScaleImageEnum`

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com