[kaffe] CVS kaffe (robilad): Resynced with GNU Classpath: Added MediaTracker docs
Kaffe CVS
cvs-commits at kaffe.org
Tue Apr 19 03:47:47 PDT 2005
PatchSet 5709
Date: 2005/04/19 10:37:34
Author: robilad
Branch: HEAD
Tag: (none)
Log:
Resynced with GNU Classpath: Added MediaTracker docs
2005-04-19 Dalibor Topic <robilad at kaffe.org>
Resynced with GNU Classpath.
2005-04-11 Roman Kennke <roman at kennke.org>
* java/awt/MediaTracker.java
Added API documentation.
Members:
ChangeLog:1.3876->1.3877
libraries/javalib/java/awt/MediaTracker.java:1.15->1.16
Index: kaffe/ChangeLog
diff -u kaffe/ChangeLog:1.3876 kaffe/ChangeLog:1.3877
--- kaffe/ChangeLog:1.3876 Tue Apr 19 10:29:56 2005
+++ kaffe/ChangeLog Tue Apr 19 10:37:34 2005
@@ -2,6 +2,15 @@
Resynced with GNU Classpath.
+ 2005-04-11 Roman Kennke <roman at kennke.org>
+
+ * java/awt/MediaTracker.java
+ Added API documentation.
+
+2005-04-19 Dalibor Topic <robilad at kaffe.org>
+
+ Resynced with GNU Classpath.
+
2005-04-11 Michael Koch <konqueror at gmx.de>
* javax/imageio/ImageIO.java (ReaderFormatFilter.filter):
Index: kaffe/libraries/javalib/java/awt/MediaTracker.java
diff -u kaffe/libraries/javalib/java/awt/MediaTracker.java:1.15 kaffe/libraries/javalib/java/awt/MediaTracker.java:1.16
--- kaffe/libraries/javalib/java/awt/MediaTracker.java:1.15 Tue Apr 19 00:07:24 2005
+++ kaffe/libraries/javalib/java/awt/MediaTracker.java Tue Apr 19 10:37:36 2005
@@ -45,33 +45,86 @@
* This class is used for keeping track of the status of various media
* objects.
*
+ * Media objects are tracked by assigning them an ID. It is possible
+ * to assign the same ID to mutliple objects, effectivly grouping them
+ * together. In this case the status flags ({@link #statusID}) and error flag
+ * (@link #isErrorID} and {@link #getErrorId}) are ORed together. This
+ * means that you cannot say exactly which media object has which status,
+ * at most you can say that there <em>are</em> certain media objects with
+ * some certain status.
+ *
+ * At the moment only images are supported by this class.
+ *
* @author Aaron M. Renn (arenn at urbanophile.com)
* @author Bryce McKinlay
*/
public class MediaTracker implements java.io.Serializable
{
+ /** Indicates that the media is still loading. */
public static final int LOADING = 1 << 0;
+
+ /** Indicates that the loading operation has been aborted. */
public static final int ABORTED = 1 << 1;
+
+ /** Indicates that an error has occured during loading of the media. */
public static final int ERRORED = 1 << 2;
+
+ /** Indicates that the media has been successfully and completely loaded. */
public static final int COMPLETE = 1 << 3;
-
+
+ /** The component on which the media is eventually been drawn. */
Component target;
+
+ /** The head of the linked list of tracked media objects. */
MediaEntry head;
+ /** Our serialVersionUID for serialization. */
static final long serialVersionUID = -483174189758638095L;
+ /**
+ * This represents a media object that is tracked by a MediaTracker.
+ * It also implements a simple linked list.
+ */
// FIXME: The serialized form documentation says MediaEntry is a
// serializable field, but the serialized form of MediaEntry itself
// doesn't appear to be documented.
class MediaEntry implements ImageObserver
{
+ /** The ID of the media object. */
int id;
+
+ /** The media object. (only images are supported ATM). */
Image image;
+
+ /** The link to the next entry in the list. */
MediaEntry next;
+
+ /** The tracking status. */
int status;
+
+ /** The width of the image. */
int width;
+
+ /** The height of the image. */
int height;
+ /**
+ * Receives notification from an {@link java.awt.image.ImageProducer}
+ * that more data of the image is available.
+ *
+ * @param img the image that is updated
+ * @param flags flags from the ImageProducer that indicate the status
+ * of the loading process
+ * @param x the X coordinate of the upper left corner of the image
+ * @param y the Y coordinate of the upper left corner of the image
+ * @param width the width of the image
+ * @param height the height of the image
+ *
+ * @return <code>true</code> if more data is needed, <code>false</code>
+ * otherwise
+ *
+ * @see {@link java.awt.image.ImageObserver}
+ */
public boolean imageUpdate(Image img, int flags, int x, int y,
int width, int height)
{
@@ -96,11 +149,23 @@
}
}
+ /**
+ * Constructs a new MediaTracker for the component <code>c</code>. The
+ * component should be the component that uses the media (i.e. draws it).
+ *
+ * @param c the Component that wants to use the media
+ */
public MediaTracker(Component c)
{
target = c;
}
+ /**
+ * Adds an image to the tracker with the specified <code>ID</code>.
+ *
+ * @param image the image to be added
+ * @param id the ID of the tracker list to which the image is added
+ */
public void addImage(Image image, int id)
{
MediaEntry e = new MediaEntry();
@@ -113,6 +178,16 @@
e.imageUpdate(image, flags, -1, -1, -1, -1);
}
+ /**
+ * Adds an image to the tracker with the specified <code>ID</code>.
+ * The image is expected to be rendered with the specified width and
+ * height.
+ *
+ * @param image the image to be added
+ * @param id the ID of the tracker list to which the image is added
+ * @param width the width of the image
+ * @param height the height of the image
+ */
public void addImage(Image image, int id, int width, int height)
{
MediaEntry e = new MediaEntry();
@@ -127,11 +202,36 @@
e.imageUpdate(image, flags, -1, -1, width, height);
}
+ /**
+ * Checks if all media objects have finished loading, i.e. are
+ * {@link #COMPLETE}, {@link #ABORTED} or {@link #ERRORED}.
+ *
+ * If the media objects are not already loading, a call to this
+ * method does <em>not</em> start loading. This is equivalent to
+ * a call to <code>checkAll(false)</code>.
+ *
+ * @return if all media objects have finished loading either by beeing
+ * complete, have been aborted or errored.
+ */
public boolean checkAll()
{
return checkAll(false);
}
+ /**
+ * Checks if all media objects have finished loading, i.e. are
+ * {@link #COMPLETE}, {@link #ABORTED} or {@link #ERRORED}.
+ *
+ * If the media objects are not already loading, and <code>load</code>
+ * is <code>true</code> then a call to this
+ * method starts loading the media objects.
+ *
+ * @param load if <code>true</code> this method starts loading objects
+ * that are not already loading
+ *
+ * @return if all media objects have finished loading either by beeing
+ * complete, have been aborted or errored.
+ */
public boolean checkAll(boolean load)
{
MediaEntry e = head;
@@ -158,6 +258,14 @@
return result;
}
+ /**
+ * Checks if any of the registered media objects has encountered an error
+ * during loading.
+ *
+ * @return <code>true</code> if at least one media object has encountered
+ * an error during loading, <code>false</code> otherwise
+ *
+ */
public boolean isErrorAny()
{
MediaEntry e = head;
@@ -170,6 +278,12 @@
return false;
}
+ /**
+ * Returns all media objects that have encountered errors during loading.
+ *
+ * @return an array of all media objects that have encountered errors
+ * or <code>null</code> if there were no errors at all
+ */
public Object[] getErrorsAny()
{
MediaEntry e = head;
@@ -190,6 +304,13 @@
return result.toArray();
}
+ /**
+ * Waits for all media objects to finish loading, either by completing
+ * successfully or by aborting or encountering an error.
+ *
+ * @throws InterruptedException if another thread interrupted the
+ * current thread while waiting
+ */
public void waitForAll() throws InterruptedException
{
synchronized (this)
@@ -199,6 +320,23 @@
}
}
+ /**
+ * Waits for all media objects to finish loading, either by completing
+ * successfully or by aborting or encountering an error.
+ *
+ * This method waits at most <code>ms</code> milliseconds. If the
+ * media objects have not completed loading within this timeframe, this
+ * method returns <code>false</code>, otherwise <code>true</code>.
+ *
+ * @param ms timeframe in milliseconds to wait for the media objects to
+ * finish
+ *
+ * @return <code>true</code> if all media objects have successfully loaded
+ * within the timeframe, <code>false</code> otherwise
+ *
+ * @throws InterruptedException if another thread interrupted the
+ * current thread while waiting
+ */
public boolean waitForAll(long ms) throws InterruptedException
{
long start = System.currentTimeMillis();
@@ -217,6 +355,16 @@
return result;
}
+ /**
+ * Returns the status flags of all registered media objects ORed together.
+ * If <code>load</code> is <code>true</code> then media objects that
+ * are not already loading will be started to load.
+ *
+ * @param load if set to <code>true</code> then media objects that are
+ * not already loading are started
+ *
+ * @return the status flags of all tracked media objects ORed together
+ */
public int statusAll(boolean load)
{
int result = 0;
@@ -234,11 +382,31 @@
return result;
}
+ /**
+ * Checks if the media objects with <code>ID</code> have completed loading.
+ *
+ * @param id the ID of the media objects to check
+ *
+ * @return <code>true</code> if all media objects with <code>ID</code>
+ * have successfully finished
+ */
public boolean checkID(int id)
{
return checkID(id, false);
}
+ /**
+ * Checks if the media objects with <code>ID</code> have completed loading.
+ * If <code>load</code> is <code>true</code> then media objects that
+ * are not already loading will be started to load.
+ *
+ * @param id the ID of the media objects to check
+ * @param load if set to <code>true</code> then media objects that are
+ * not already loading are started
+ *
+ * @return <code>true</code> if all media objects with <code>ID</code>
+ * have successfully finished
+ */
public boolean checkID(int id, boolean load)
{
MediaEntry e = head;
@@ -265,6 +433,15 @@
return result;
}
+ /**
+ * Returns <code>true</code> if any of the media objects with <code>ID</code>
+ * have encountered errors during loading, false otherwise.
+ *
+ * @param id the ID of the media objects to check
+ *
+ * @return <code>true</code> if any of the media objects with <code>ID</code>
+ * have encountered errors during loading, false otherwise
+ */
public boolean isErrorID(int id)
{
MediaEntry e = head;
@@ -277,6 +454,15 @@
return false;
}
+ /**
+ * Returns all media objects with the specified ID that have encountered
+ * an error.
+ *
+ * @param id the ID of the media objects to check
+ *
+ * @return an array of all media objects with the specified ID that
+ * have encountered an error
+ */
public Object[] getErrorsID(int id)
{
MediaEntry e = head;
@@ -297,6 +483,15 @@
return result.toArray();
}
+ /**
+ * Waits for all media objects with the specified ID to finish loading,
+ * either by completing successfully or by aborting or encountering an error.
+ *
+ * @param id the ID of the media objects to wait for
+ *
+ * @throws InterruptedException if another thread interrupted the
+ * current thread while waiting
+ */
public void waitForID(int id) throws InterruptedException
{
MediaEntry e = head;
@@ -307,6 +502,24 @@
}
}
+ /**
+ * Waits for all media objects with the specified ID to finish loading,
+ * either by completing successfully or by aborting or encountering an error.
+ *
+ * This method waits at most <code>ms</code> milliseconds. If the
+ * media objects have not completed loading within this timeframe, this
+ * method returns <code>false</code>, otherwise <code>true</code>.
+ *
+ * @param id the ID of the media objects to wait for
+ * @param ms timeframe in milliseconds to wait for the media objects to
+ * finish
+ *
+ * @return <code>true</code> if all media objects have successfully loaded
+ * within the timeframe, <code>false</code> otherwise
+ *
+ * @throws InterruptedException if another thread interrupted the
+ * current thread while waiting
+ */
public boolean waitForID(int id, long ms) throws InterruptedException
{
MediaEntry e = head;
@@ -327,6 +540,18 @@
return result;
}
+ /**
+ * Returns the status flags of the media objects with the specified ID
+ * ORed together.
+ *
+ * If <code>load</code> is <code>true</code> then media objects that
+ * are not already loading will be started to load.
+ *
+ * @param load if set to <code>true</code> then media objects that are
+ * not already loading are started
+ *
+ * @return the status flags of all tracked media objects ORed together
+ */
public int statusID(int id, boolean load)
{
int result = 0;
@@ -347,6 +572,11 @@
return result;
}
+ /**
+ * Removes an image from this MediaTracker.
+ *
+ * @param image the image to be removed
+ */
public void removeImage(Image image)
{
MediaEntry e = head;
@@ -365,6 +595,11 @@
}
}
+ /**
+ * Removes an image with the specified ID from this MediaTracker.
+ *
+ * @param image the image to be removed
+ */
public void removeImage(Image image, int id)
{
MediaEntry e = head;
@@ -384,6 +619,11 @@
}
}
+ /**
+ * Removes an image with the specified ID and scale from this MediaTracker.
+ *
+ * @param image the image to be removed
+ */
public void removeImage(Image image, int id, int width, int height)
{
MediaEntry e = head;
More information about the kaffe
mailing list