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 }
--- EOF ---