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.

Author:

Teodor Danciu (teodord@users.sourceforge.net)

See Also:

Renderable

Method Summary

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