1/*
2 * Copyright (c) 1995, 2013, 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
26package java.awt.image;
27
28import java.awt.Image;
29
30
31/**
32 * An asynchronous update interface for receiving notifications about
33 * Image information as the Image is constructed.
34 *
35 * @author      Jim Graham
36 */
37public interface ImageObserver {
38    /**
39     * This method is called when information about an image which was
40     * previously requested using an asynchronous interface becomes
41     * available.  Asynchronous interfaces are method calls such as
42     * getWidth(ImageObserver) and drawImage(img, x, y, ImageObserver)
43     * which take an ImageObserver object as an argument.  Those methods
44     * register the caller as interested either in information about
45     * the overall image itself (in the case of getWidth(ImageObserver))
46     * or about an output version of an image (in the case of the
47     * drawImage(img, x, y, [w, h,] ImageObserver) call).
48     *
49     * <p>This method
50     * should return true if further updates are needed or false if the
51     * required information has been acquired.  The image which was being
52     * tracked is passed in using the img argument.  Various constants
53     * are combined to form the infoflags argument which indicates what
54     * information about the image is now available.  The interpretation
55     * of the x, y, width, and height arguments depends on the contents
56     * of the infoflags argument.
57     * <p>
58     * The {@code infoflags} argument should be the bitwise inclusive
59     * <b>OR</b> of the following flags: {@code WIDTH},
60     * {@code HEIGHT}, {@code PROPERTIES}, {@code SOMEBITS},
61     * {@code FRAMEBITS}, {@code ALLBITS}, {@code ERROR},
62     * {@code ABORT}.
63     *
64     * @param     img   the image being observed.
65     * @param     infoflags   the bitwise inclusive OR of the following
66     *               flags:  {@code WIDTH}, {@code HEIGHT},
67     *               {@code PROPERTIES}, {@code SOMEBITS},
68     *               {@code FRAMEBITS}, {@code ALLBITS},
69     *               {@code ERROR}, {@code ABORT}.
70     * @param     x   the <i>x</i> coordinate.
71     * @param     y   the <i>y</i> coordinate.
72     * @param     width    the width.
73     * @param     height   the height.
74     * @return    {@code false} if the infoflags indicate that the
75     *            image is completely loaded; {@code true} otherwise.
76     *
77     * @see #WIDTH
78     * @see #HEIGHT
79     * @see #PROPERTIES
80     * @see #SOMEBITS
81     * @see #FRAMEBITS
82     * @see #ALLBITS
83     * @see #ERROR
84     * @see #ABORT
85     * @see Image#getWidth
86     * @see Image#getHeight
87     * @see java.awt.Graphics#drawImage
88     */
89    public boolean imageUpdate(Image img, int infoflags,
90                               int x, int y, int width, int height);
91
92    /**
93     * This flag in the infoflags argument to imageUpdate indicates that
94     * the width of the base image is now available and can be taken
95     * from the width argument to the imageUpdate callback method.
96     * @see Image#getWidth
97     * @see #imageUpdate
98     */
99    public static final int WIDTH = 1;
100
101    /**
102     * This flag in the infoflags argument to imageUpdate indicates that
103     * the height of the base image is now available and can be taken
104     * from the height argument to the imageUpdate callback method.
105     * @see Image#getHeight
106     * @see #imageUpdate
107     */
108    public static final int HEIGHT = 2;
109
110    /**
111     * This flag in the infoflags argument to imageUpdate indicates that
112     * the properties of the image are now available.
113     * @see Image#getProperty
114     * @see #imageUpdate
115     */
116    public static final int PROPERTIES = 4;
117
118    /**
119     * This flag in the infoflags argument to imageUpdate indicates that
120     * more pixels needed for drawing a scaled variation of the image
121     * are available.  The bounding box of the new pixels can be taken
122     * from the x, y, width, and height arguments to the imageUpdate
123     * callback method.
124     * @see java.awt.Graphics#drawImage
125     * @see #imageUpdate
126     */
127    public static final int SOMEBITS = 8;
128
129    /**
130     * This flag in the infoflags argument to imageUpdate indicates that
131     * another complete frame of a multi-frame image which was previously
132     * drawn is now available to be drawn again.  The x, y, width, and height
133     * arguments to the imageUpdate callback method should be ignored.
134     * @see java.awt.Graphics#drawImage
135     * @see #imageUpdate
136     */
137    public static final int FRAMEBITS = 16;
138
139    /**
140     * This flag in the infoflags argument to imageUpdate indicates that
141     * a static image which was previously drawn is now complete and can
142     * be drawn again in its final form.  The x, y, width, and height
143     * arguments to the imageUpdate callback method should be ignored.
144     * @see java.awt.Graphics#drawImage
145     * @see #imageUpdate
146     */
147    public static final int ALLBITS = 32;
148
149    /**
150     * This flag in the infoflags argument to imageUpdate indicates that
151     * an image which was being tracked asynchronously has encountered
152     * an error.  No further information will become available and
153     * drawing the image will fail.
154     * As a convenience, the ABORT flag will be indicated at the same
155     * time to indicate that the image production was aborted.
156     * @see #imageUpdate
157     */
158    public static final int ERROR = 64;
159
160    /**
161     * This flag in the infoflags argument to imageUpdate indicates that
162     * an image which was being tracked asynchronously was aborted before
163     * production was complete.  No more information will become available
164     * without further action to trigger another image production sequence.
165     * If the ERROR flag was not also set in this image update, then
166     * accessing any of the data in the image will restart the production
167     * again, probably from the beginning.
168     * @see #imageUpdate
169     */
170    public static final int ABORT = 128;
171}
172