1 /*
2 * Copyright (c) 1995, 1999, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.awt.image;
27
28 import java.awt.Image;
29
30 import javax.tools.annotation.GenerateNativeHeader;
31
32 /**
33 * An asynchronous update interface for receiving notifications about
34 * Image information as the Image is constructed.
35 *
36 * @author Jim Graham
37 */
38 /* No native methods here, but the constants are needed in the supporting JNI code */
39 @GenerateNativeHeader
40 public interface ImageObserver {
41 /**
42 * This method is called when information about an image which was
43 * previously requested using an asynchronous interface becomes
44 * available. Asynchronous interfaces are method calls such as
45 * getWidth(ImageObserver) and drawImage(img, x, y, ImageObserver)
46 * which take an ImageObserver object as an argument. Those methods
47 * register the caller as interested either in information about
48 * the overall image itself (in the case of getWidth(ImageObserver))
49 * or about an output version of an image (in the case of the
50 * drawImage(img, x, y, [w, h,] ImageObserver) call).
51 *
52 * <p>This method
53 * should return true if further updates are needed or false if the
54 * required information has been acquired. The image which was being
55 * tracked is passed in using the img argument. Various constants
56 * are combined to form the infoflags argument which indicates what
57 * information about the image is now available. The interpretation
58 * of the x, y, width, and height arguments depends on the contents
59 * of the infoflags argument.
60 * <p>
61 * The <code>infoflags</code> argument should be the bitwise inclusive
62 * <b>OR</b> of the following flags: <code>WIDTH</code>,
63 * <code>HEIGHT</code>, <code>PROPERTIES</code>, <code>SOMEBITS</code>,
64 * <code>FRAMEBITS</code>, <code>ALLBITS</code>, <code>ERROR</code>,
65 * <code>ABORT</code>.
66 *
67 * @param img the image being observed.
68 * @param infoflags the bitwise inclusive OR of the following
69 * flags: <code>WIDTH</code>, <code>HEIGHT</code>,
70 * <code>PROPERTIES</code>, <code>SOMEBITS</code>,
71 * <code>FRAMEBITS</code>, <code>ALLBITS</code>,
72 * <code>ERROR</code>, <code>ABORT</code>.
73 * @param x the <i>x</i> coordinate.
74 * @param y the <i>y</i> coordinate.
75 * @param width the width.
76 * @param height the height.
77 * @return <code>false</code> if the infoflags indicate that the
78 * image is completely loaded; <code>true</code> otherwise.
79 *
80 * @see #WIDTH
81 * @see #HEIGHT
82 * @see #PROPERTIES
83 * @see #SOMEBITS
84 * @see #FRAMEBITS
85 * @see #ALLBITS
86 * @see #ERROR
87 * @see #ABORT
88 * @see Image#getWidth
89 * @see Image#getHeight
90 * @see java.awt.Graphics#drawImage
91 */
92 public boolean imageUpdate(Image img, int infoflags,
93 int x, int y, int width, int height);
94
95 /**
96 * This flag in the infoflags argument to imageUpdate indicates that
97 * the width of the base image is now available and can be taken
98 * from the width argument to the imageUpdate callback method.
99 * @see Image#getWidth
100 * @see #imageUpdate
101 */
102 public static final int WIDTH = 1;
103
104 /**
105 * This flag in the infoflags argument to imageUpdate indicates that
106 * the height of the base image is now available and can be taken
107 * from the height argument to the imageUpdate callback method.
108 * @see Image#getHeight
109 * @see #imageUpdate
110 */
111 public static final int HEIGHT = 2;
112
113 /**
114 * This flag in the infoflags argument to imageUpdate indicates that
115 * the properties of the image are now available.
116 * @see Image#getProperty
117 * @see #imageUpdate
118 */
119 public static final int PROPERTIES = 4;
120
121 /**
122 * This flag in the infoflags argument to imageUpdate indicates that
123 * more pixels needed for drawing a scaled variation of the image
124 * are available. The bounding box of the new pixels can be taken
125 * from the x, y, width, and height arguments to the imageUpdate
126 * callback method.
127 * @see java.awt.Graphics#drawImage
128 * @see #imageUpdate
129 */
130 public static final int SOMEBITS = 8;
131
132 /**
133 * This flag in the infoflags argument to imageUpdate indicates that
134 * another complete frame of a multi-frame image which was previously
135 * drawn is now available to be drawn again. The x, y, width, and height
136 * arguments to the imageUpdate callback method should be ignored.
137 * @see java.awt.Graphics#drawImage
138 * @see #imageUpdate
139 */
140 public static final int FRAMEBITS = 16;
141
142 /**
143 * This flag in the infoflags argument to imageUpdate indicates that
144 * a static image which was previously drawn is now complete and can
145 * be drawn again in its final form. The x, y, width, and height
146 * arguments to the imageUpdate callback method should be ignored.
147 * @see java.awt.Graphics#drawImage
148 * @see #imageUpdate
149 */
150 public static final int ALLBITS = 32;
151
152 /**
153 * This flag in the infoflags argument to imageUpdate indicates that
154 * an image which was being tracked asynchronously has encountered
155 * an error. No further information will become available and
156 * drawing the image will fail.
157 * As a convenience, the ABORT flag will be indicated at the same
158 * time to indicate that the image production was aborted.
159 * @see #imageUpdate
160 */
161 public static final int ERROR = 64;
162
163 /**
164 * This flag in the infoflags argument to imageUpdate indicates that
165 * an image which was being tracked asynchronously was aborted before
166 * production was complete. No more information will become available
167 * without further action to trigger another image production sequence.
168 * If the ERROR flag was not also set in this image update, then
169 * accessing any of the data in the image will restart the production
170 * again, probably from the beginning.
171 * @see #imageUpdate
172 */
173 public static final int ABORT = 128;
174 }