Package net.sf.jasperreports.engine
Interface JRCommonImage
-
- All Superinterfaces:
JRBoxContainer
,JRCommonElement
,JRCommonGraphicElement
,JRImageAlignment
,JRPenContainer
,JRStyleContainer
- All Known Subinterfaces:
JRImage
,JRPrintImage
- All Known Implementing Classes:
ChartTemplateImage
,JRBaseImage
,JRBasePrintImage
,JRDesignImage
,JRFillImage
,JRRecordedValuesPrintImage
,JRTemplateImage
,JRTemplatePrintImage
public interface JRCommonImage extends JRImageAlignment, 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. ThescaleImage
attribute (seegetScaleImage()
) 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
andRealSize
. 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 thegetDimension()
method on the image renderer object, which is an instance of a class that implementsRenderable
. 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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description RotationEnum
getOwnRotation()
Gets the image own rotation.ScaleImageEnum
getOwnScaleImage()
Gets the image own scale type.RotationEnum
getRotation()
Gets the image rotation.ScaleImageEnum
getScaleImage()
Gets the image scale type.void
setRotation(RotationEnum rotationEnum)
Sets the image rotation.void
setScaleImage(ScaleImageEnum scaleImageEnum)
Sets the image scale type.-
Methods inherited from interface net.sf.jasperreports.engine.JRBoxContainer
getDefaultLineColor, getLineBox
-
Methods inherited from interface net.sf.jasperreports.engine.JRCommonElement
getBackcolor, getForecolor, getHeight, getKey, getMode, getOwnBackcolor, getOwnForecolor, getOwnMode, getWidth, setBackcolor, setForecolor, setMode
-
Methods inherited from interface net.sf.jasperreports.engine.JRCommonGraphicElement
getFill, getLinePen, getOwnFill, setFill
-
Methods inherited from interface net.sf.jasperreports.engine.JRImageAlignment
getHorizontalImageAlign, getOwnHorizontalImageAlign, getOwnVerticalImageAlign, getVerticalImageAlign, setHorizontalImageAlign, setVerticalImageAlign
-
Methods inherited from interface net.sf.jasperreports.engine.JRPenContainer
getDefaultLineColor, getDefaultLineWidth
-
Methods inherited from interface net.sf.jasperreports.engine.JRStyleContainer
getDefaultStyleProvider, getStyle, getStyleName, getStyleNameReference
-
-
-
-
Method Detail
-
getScaleImage
ScaleImageEnum getScaleImage()
Gets the image scale type.- Returns:
- a value representing one of the scale type constants in
ScaleImageEnum
-
getOwnScaleImage
ScaleImageEnum getOwnScaleImage()
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 inScaleImageEnum
-
getRotation
RotationEnum getRotation()
Gets the image rotation.- Returns:
- a value representing one of the image rotation constants in
RotationEnum
-
getOwnRotation
RotationEnum getOwnRotation()
Gets the image own rotation.- Returns:
- a value representing one of the image rotation constants in
RotationEnum
-
setRotation
void setRotation(RotationEnum rotationEnum)
Sets the image rotation.- Parameters:
rotationEnum
- a value representing one of the image rotation constants inRotationEnum
-
-