001: /*
002: * ============================================================================
003: * GNU Lesser General Public License
004: * ============================================================================
005: *
006: * JasperReports - Free Java report-generating library.
007: * Copyright (C) 2001-2006 JasperSoft Corporation http://www.jaspersoft.com
008: *
009: * This library is free software; you can redistribute it and/or
010: * modify it under the terms of the GNU Lesser General Public
011: * License as published by the Free Software Foundation; either
012: * version 2.1 of the License, or (at your option) any later version.
013: *
014: * This library is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017: * Lesser General Public License for more details.
018: *
019: * You should have received a copy of the GNU Lesser General Public
020: * License along with this library; if not, write to the Free Software
021: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
022: *
023: * JasperSoft Corporation
024: * 303 Second Street, Suite 450 North
025: * San Francisco, CA 94107
026: * http://www.jaspersoft.com
027: */
028: package net.sf.jasperreports.engine;
029:
030: /**
031: * An abstract representation of a graphic element representing an image. Images can be aligned and scaled. They can
032: * also contain hyperlinks or be anchors for other hyperlinks.
033: *
034: * @author Teodor Danciu (teodord@users.sourceforge.net)
035: * @version $Id: JRImage.java 1229 2006-04-19 10:27:35Z teodord $
036: */
037: public interface JRImage extends JRGraphicElement, JRAnchor,
038: JRHyperlink, JRAlignment, JRBox {
039:
040: /**
041: * A constant value specifying that if the actual image is larger than the image element size, it will be cut off so
042: * that it keeps its original resolution, and only the region that fits the specified size will be displayed.
043: */
044: public static final byte SCALE_IMAGE_CLIP = 1;
045:
046: /**
047: * A constant value specifying that if the dimensions of the actual image do not fit those specified for the
048: * image element that displays it, the image can be forced to obey them and stretch itself so that it fits
049: * in the designated output area.
050: */
051: public static final byte SCALE_IMAGE_FILL_FRAME = 2;
052:
053: /**
054: * A constant value specifying that if the actual image does not fit into the image element, it can be adapted
055: * to those dimensions without needing to change its original proportions.
056: */
057: public static final byte SCALE_IMAGE_RETAIN_SHAPE = 3;
058:
059: /**
060: * A constant used for specifying that the engine should raise an exception if the image is not found.
061: */
062: public static final byte ON_ERROR_TYPE_ERROR = 1;
063:
064: /**
065: * A constant used for specifying that the engine should display blank space if the image is not found.
066: */
067: public static final byte ON_ERROR_TYPE_BLANK = 2;
068:
069: /**
070: * A constant used for specifying that the engine should display a replacement icon if the image is not found.
071: */
072: public static final byte ON_ERROR_TYPE_ICON = 3;
073:
074: /**
075: * Gets the image scale type.
076: * @return one of the scale constants in this class
077: */
078: public byte getScaleImage();
079:
080: public Byte getOwnScaleImage();
081:
082: /**
083: * Sets the image scale type.
084: * @param scaleImage one of the scale constants in this class
085: */
086: public void setScaleImage(byte scaleImage);
087:
088: public void setScaleImage(Byte scaleImage);
089:
090: /**
091: * Indicates if the engine is loading the current image from cache.
092: * Implementations of this method rely on default values that depend on the type of the image expression
093: * if a value was not explicitly set of this flag.
094: * @return true if the image should be loaded from cache, false otherwise
095: */
096: public boolean isUsingCache();
097:
098: /**
099: * Indicates if the engine is loading the current image from cache.
100: * Implementations of this method return the actual value for the internal flag that was explicitly
101: * set on this image element.
102: * @return Boolean.TRUE if the image should be loaded from cache, Boolean.FALSE otherwise
103: * or null in case the flag was never explicitly set on this image element
104: */
105: public Boolean isOwnUsingCache();
106:
107: /**
108: * Specifies if the engine should be loading the current image from cache. If set to true, the reporting engine
109: * will try to recognize previously loaded images using their specified source. For example, it will recognize
110: * an image if the image source is a file name that it has already loaded, or if it is the same URL.
111: * <p>
112: * For image elements that have expressions returning <tt>java.lang.String</tt> objects as the image source,
113: * representing file names, URLs or classpath resources, the default value for this flag is true.
114: */
115: public void setUsingCache(boolean isUsingCache);
116:
117: /**
118: * Specifies if the engine should be loading the current image from cache. If set to Boolean.TRUE, the reporting engine
119: * will try to recognize previously loaded images using their specified source. For example, it will recognize
120: * an image if the image source is a file name that it has already loaded, or if it is the same URL.
121: * <p>
122: * If set to null, the engine will rely on some default value which depends on the type of the image expression.
123: * The cache is turned on by default only for images that have <tt>java.lang.String</tt> objects in their expressions.
124: */
125: public void setUsingCache(Boolean isUsingCache);
126:
127: /**
128: * Indicates if the images will be loaded lazily or not.
129: */
130: public boolean isLazy();
131:
132: /**
133: * Gives control over when the images are retrieved from their specified location. If set to true, the image is
134: * loaded from the specified location only when the document is viewed or exported to other formats. Otherwise
135: * it is loaded during the report filling process and stored in the resulting document.
136: * @param isLazy specifies whether
137: */
138: public void setLazy(boolean isLazy);
139:
140: /**
141: * Indicates how the engine will treat a missing image.
142: * @return one of the constants for missing image error types
143: */
144: public byte getOnErrorType();
145:
146: /**
147: * Specifies how the engine should treat a missing image.
148: * @param onErrorType one of the constants for missing image error types
149: */
150: public void setOnErrorType(byte onErrorType);
151:
152: /**
153: * Indicates the evaluation time for this image.
154: * @return one of the evaluation time constants in {@link JRExpression}
155: */
156: public byte getEvaluationTime();
157:
158: /**
159: * Indicates the evaluation time for this image.
160: * @return one of the evaluation time constants in {@link JRExpression}
161: */
162: public JRGroup getEvaluationGroup();
163:
164: /**
165: * Gets the evaluation group for this text field. Used only when evaluation time is group.
166: * @see JRExpression#EVALUATION_TIME_GROUP
167: */
168: public JRExpression getExpression();
169:
170: /**
171: * Returns an object containing all border and padding properties for this text element
172: * @deprecated
173: */
174: public JRBox getBox();
175:
176: }
|