View Javadoc
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  
26  package java.awt.image;
27  
28  import 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   */
37  public 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</code> argument should be the bitwise inclusive
59       * <b>OR</b> of the following flags: <code>WIDTH</code>,
60       * <code>HEIGHT</code>, <code>PROPERTIES</code>, <code>SOMEBITS</code>,
61       * <code>FRAMEBITS</code>, <code>ALLBITS</code>, <code>ERROR</code>,
62       * <code>ABORT</code>.
63       *
64       * @param     img   the image being observed.
65       * @param     infoflags   the bitwise inclusive OR of the following
66       *               flags:  <code>WIDTH</code>, <code>HEIGHT</code>,
67       *               <code>PROPERTIES</code>, <code>SOMEBITS</code>,
68       *               <code>FRAMEBITS</code>, <code>ALLBITS</code>,
69       *               <code>ERROR</code>, <code>ABORT</code>.
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</code> if the infoflags indicate that the
75       *            image is completely loaded; <code>true</code> 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 }