home *** CD-ROM | disk | FTP | other *** search
/ Java 1.2 How-To / JavaHowTo.iso / 3rdParty / jbuilder / unsupported / JDK1.2beta3 / SOURCE / SRC.ZIP / java / awt / image / WritableRenderedImage.java < prev   
Encoding:
Java Source  |  1998-03-20  |  5.6 KB  |  147 lines
  1. /*
  2.  * @(#)WritableRenderedImage.java    1.7 98/03/18
  3.  *
  4.  * Copyright 1997 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. /* ****************************************************************
  16.  ******************************************************************
  17.  ******************************************************************
  18.  *** COPYRIGHT (c) Eastman Kodak Company, 1997
  19.  *** As  an unpublished  work pursuant to Title 17 of the United
  20.  *** States Code.  All rights reserved.
  21.  ******************************************************************
  22.  ******************************************************************
  23.  ******************************************************************/
  24.  
  25. package java.awt.image;
  26. import java.awt.Point;
  27.  
  28. /**
  29.  *  WriteableRenderedImage is a common interface for objects which 
  30.  *  contain or can produce image data which can be modified and/or
  31.  *  written over. 
  32.  *
  33.  * WritableRenderedImage provides notification to other interested
  34.  * objects when a tile is checked out for writing (via the
  35.  * getWritableTile method) and when the last writer of a particular
  36.  * tile relinquishes its access (via a call to releaseWritableTile).
  37.  * Additionally, it allows any caller to determine whether any tiles
  38.  * are currently checked out (via hasTileWriters), and to obtain a
  39.  * list of such tiles (from getWritableTiles, in the form of a Vector
  40.  * of Point objects).
  41.  *
  42.  * Object wishing to be notified of changes in tile writability must
  43.  * implement the TileChangeListener interface, and are added by a
  44.  * call to addTileChangeListener.  Multiple calls to
  45.  * addTileChangeListener for the same object will result in multiple
  46.  * notifications.  An existing listener may reduce its notifications
  47.  * by calling removeTileChangeListener; if the listener had no
  48.  * notifications the operation is a no-op.  A Vector of the current
  49.  * TileChangeListeners is obtained by calling getTileChangeListeners.
  50.  *
  51.  * It is necessary for a WritableRenderedImage to ensure that
  52.  * notifications occur only when the first writer acquires a tile and
  53.  * the last writer deacquires it.  To simplify the necessary
  54.  * bookkeeping, the TileChangeMulticaster class is available.  Calls to
  55.  * getWritableTile are forwarded to calls to addTileWriter and calls
  56.  * to releaseWritableTile are forwared to calls to removeTileWriter;
  57.  * other listener-related calls are trivially forwarded (see
  58.  * BufferedImage for an example of this style of implementation).
  59.  * A TileChangeMulticaster may be used to inform a number of objects
  60.  * of a tile change event from a single notification. 
  61.  *
  62.  */
  63.  
  64. public interface WritableRenderedImage extends RenderedImage
  65. {
  66.  
  67.   /**
  68.    * Add a listener.  If the listener is already present,
  69.    * it will receive multiple notifications.
  70.    */
  71.   public void addTileChangeListener(TileChangeListener tcl);
  72.  
  73.   /**
  74.    * Remove a listener.  If the listener was not registered,
  75.    * nothing happens.  If the listener was registered for multiple
  76.    * notifications, it will now be registered for one fewer.
  77.    */
  78.   public void removeTileChangeListener(TileChangeListener tcl);
  79.  
  80.   /**
  81.    * Return a Vector of TileChangeListener objects.
  82.    * Listeners registered multiple times will appear
  83.    * a corresponding number of times in the list.
  84.    */
  85.   public TileChangeListener[] getTileChangeListeners();
  86.  
  87.   /**
  88.    * Check out a tile for writing.  This method is already part of
  89.    * the WritableRenderedImage interface.
  90.    * 
  91.    * The WritableRenderedImage is responsible for notifying all
  92.    * of its TileChangeListeners when a tile goes from having
  93.    * no writers to having one writer.  A simple way to fulfill this
  94.    * contract is to instantiate a TileChangeFilter and to call
  95.    * its addTileWriter method every time this method is called.
  96.    *
  97.    * @param tileX the X index of the tile.
  98.    * @param tileY the Y index of the tile.
  99.    */
  100.   public WritableRaster getWritableTile(int tileX, int tileY);
  101.  
  102.   /**
  103.    * Relinquish the right to write to a tile.  If the caller 
  104.    * continues to write to the tile, the results are undefined.
  105.    * Calls to his method should only appear in matching pairs
  106.    * with calls to getWritableTile; any other use will lead
  107.    * to undefined results.
  108.    *
  109.    * The WritableRenderedImage is responsible for notifying all of
  110.    * its TileChangeListeners when a tile goes from having one writer
  111.    * to having no writers.  A simple way to fulfill this contract is
  112.    * to instantiate a TileChangeFilter and to call its removeTileWriter
  113.    * method every time this method is called.
  114.    *
  115.    * @param tileX the X index of the tile.
  116.    * @param tileY the Y index of the tile.
  117.    */
  118.   public void releaseWritableTile(int tileX, int tileY);
  119.  
  120.   /**
  121.    * Return whether a tile is currently checked out for writing.
  122.    * This may be implemented by delegation to a TileChangeFilter.
  123.    *
  124.    * @param tileX the X index of the tile.
  125.    * @param tileY the Y index of the tile.
  126.    */
  127.   public boolean isTileWritable(int tileX, int tileY);
  128.  
  129.   /**
  130.    * Return a array of Point objects indicating which tiles
  131.    * are checked out for writing.
  132.    */
  133.   public Point[] getWritableTiles();
  134.  
  135.   /**
  136.    * Return whether any tile is checked out for writing.
  137.    * Equivalent to (getWritableTiles().size() != 0).
  138.    */
  139.   public boolean hasTileWriters();
  140.  
  141.   /**
  142.    * Set a rect of the image to the contents of rb.
  143.    */
  144.   public void setRect(Raster rb);
  145.  
  146. }
  147.