com.github.exerrk.engine.JRCommonImage Maven / Gradle / Ivy
The newest version!
/*
* JasperReports - Free Java Reporting Library.
* Copyright (C) 2001 - 2016 TIBCO Software 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 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 {@link #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 {@link com.github.exerrk.renderers.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.
*
* @see com.github.exerrk.renderers.Renderable
* @author Teodor Danciu ([email protected])
*/
public interface JRCommonImage extends JRCommonGraphicElement, JRBoxContainer
{
/**
* Gets the image scale type.
* @return a value representing one of the scale type constants in {@link ScaleImageEnum}
*/
public ScaleImageEnum getScaleImageValue();
/**
* Gets the image own scale type.
* @return a value representing one of the scale type constants in {@link ScaleImageEnum}
*/
public ScaleImageEnum getOwnScaleImageValue();
/**
* Sets the image scale type.
* @param scaleImageEnum a value representing one of the scale type constants in {@link ScaleImageEnum}
*/
public void setScaleImage(ScaleImageEnum scaleImageEnum);
}