acm.util
Class MediaTools

java.lang.Object
  |
  +--acm.util.MediaTools

public class MediaTools extends Object

This class implements a standard mechanism for loading images and sounds.


Field Summary
String DEFAULT_AUDIO_PATH
The list of directories scanned for audio clips, separated by colons.
String DEFAULT_IMAGE_PATH
The list of directories scanned for images, separated by colons.
 
Constructor Summary
MediaTools()
           
 
Method Summary
void beep()
This method sounds the audible alert on the console, which is typically a beep sound.
AudioClip createAudioClip(InputStream in)
Generates an audio clip from an input stream containing the data bytes for the audio clip.
AudioClip createAudioClip(String[] hexData)
Generates an audio clip from a string array that provides the pixel values.
Image createImage(InputStream in)
Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.
Image createImage(int[] pixels, int width, int height)
Generates an image from an array of pixel values.
Image createImage(String[] hexData)
Generates an image from a string array that provides the pixel values.
void defineAudioClip(String name, AudioClip clip)
Inserts the given clip into the audio clip table under the specified name.
void defineImage(String name, Image image)
Inserts the given image into the image table under the specified name.
void flushAudioClip(String name)
Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.
void flushImage(String name)
Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.
InputStream getHexInputStream(String[] hexData)
Returns an input stream whose bytes come from the string array hex, in which the elements consist of continuous bytes of hex data.
Component getImageObserver()
This method returns a new lightweight component suitable as an imageObserver.
boolean isCachingEnabled()
This method returns the status of the flag that determins whether images and audio clips are cached internally by name, as described in setCachingEnabled.
AudioClip loadAudioClip(String name)
Searches the default audio clip search path for an audio clip with the specified name and then loads it to create an AudioClip.
Image loadImage(Image image)
Makes sure that the image is fully loaded before returning.
Image loadImage(String name)
Searches the default image search path for an image with the specified name and then loads it to create an Image.
void setCachingEnabled(boolean flag)
This method sets an internal flag in the MediaTools package to indicate whether images and audio clips are cached internally by name.
 

Field Detail

public static final String DEFAULT_AUDIO_PATH

The list of directories scanned for audio clips, separated by colons.

public static final String DEFAULT_IMAGE_PATH

The list of directories scanned for images, separated by colons.
Constructor Detail

public MediaTools()

Method Detail

public static void beep()

This method sounds the audible alert on the console, which is typically a beep sound.

 
Usage: MediaTools.beep(); 
 

public static AudioClip createAudioClip(InputStream in)

Generates an audio clip from an input stream containing the data bytes for the audio clip.

 
Usage: AudioClip clip = MediaTools.createAudioClip(in); 
Parameter: 
in  An input stream containing the data
Returns: An AudioClip object
 

public static AudioClip createAudioClip(String[] hexData)

Generates an audio clip from a string array that provides the pixel values.

 
Usage: AudioClip audio clip = MediaTools.createAudioClip(hexData); 
Parameter: 
hexData  A hex string array representing an audio clip
Returns: An AudioClip object
 

public static Image createImage(InputStream in)

Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.

 
Usage: Image image = MediaTools.createImage(in); 
Parameter: 
in  An input stream containing the data
Returns: An Image object
 

public static Image createImage(int[] pixels, int width, int height)

Generates an image from an array of pixel values.

 
Usage: Image image = MediaTools.createImage(pixels, width, height); 
Parameters: 
pixels  An array of int representing the pixels
width  The width of the image
height  The height of the image
Returns: An Image object
 

public static Image createImage(String[] hexData)

Generates an image from a string array that provides the pixel values.

 
Usage: Image image = MediaTools.createImage(hexData); 
Parameter: 
hexData  A hex string array representing a .gif value
Returns: An Image object
 

public static void defineAudioClip(String name, AudioClip clip)

Inserts the given clip into the audio clip table under the specified name.

 
Usage: MediaTools.defineAudioClip(clip); 
Parameters: 
name  The name for the audio clip
clip  The audio clip to be stored in the table
 

public static void defineImage(String name, Image image)

Inserts the given image into the image table under the specified name.

 
Usage: MediaTools.defineImage(name, image); 
Parameters: 
name  The name for the image
image  The image to be stored in the table
 

public static void flushAudioClip(String name)

Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.

 
Usage: MediaTools.flushAudioClip(name); 
Parameter: 
name  The name for the audio clip
 

public static void flushImage(String name)

Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.

 
Usage: MediaTools.flushImage(name); 
Parameter: 
name  The name for the image
 

public static InputStream getHexInputStream(String[] hexData)

Returns an input stream whose bytes come from the string array hex, in which the elements consist of continuous bytes of hex data.

 
Usage: InputStream = MediaTools.getHexInputStream(hexData); 
Parameter: 
hexData  An array of strings specifying a byte stream coded in hex
Returns: An input stream for reading the bytes
 

public static Component getImageObserver()

This method returns a new lightweight component suitable as an imageObserver.

 
Usage: Component imageObserver = MediaTools.getImageObserver(); 
Returns: A new lightweight component suitable as an imageObserver.
 

public static boolean isCachingEnabled()

This method returns the status of the flag that determins whether images and audio clips are cached internally by name, as described in setCachingEnabled.

 
Usage: boolean flag = MediaTools.isCachingEnabled(); 
Returns: true if caching by name is enabled, false otherwise.
 

public static AudioClip loadAudioClip(String name)

Searches the default audio clip search path for an audio clip with the specified name and then loads it to create an AudioClip. The search process consists of the following steps:

  1. Check to see if an audio clip with that name has already been defined. If so, return that audio clip.

  2. Check to see if there is a resource available with that name whose contents can be read as an AudioClip. If so, read the audio clip from the resource file.

  3. Load the audio clip from a file with the specified name, relative to the application directory or the applet code base.

The second and third steps are repeated for each element of the audio clip search path, which consists of a list of directories separated by colons.


 
Usage: AudioClip clip = MediaTools.loadAudioClip(name); 
Parameter: 
name  The name of the audio clip
Returns: A new AudioClip object
 

public static Image loadImage(Image image)

Makes sure that the image is fully loaded before returning.

 
Usage: image = MediaTools.loadImage(image); 
Parameter: 
image  The Image which may not yet be loaded
Returns: The same Image after ensuring that it is fully loaded
 

public static Image loadImage(String name)

Searches the default image search path for an image with the specified name and then loads it to create an Image. The search process consists of the following steps:

  1. Check to see if an image with that name has already been defined. If so, return that image.

  2. Check to see if there is a resource available with that name whose contents can be read as an Image. If so, read the image from the resource file.

  3. Load the image from a file with the specified name, relative to the application directory or the applet code base.

The second and third steps are repeated for each element of the image search path, which consists of a list of directories separated by colons.

Unlike the getImage method in the Applet class, loadImage waits for an image to be fully loaded before returning.


 
Usage: Image image = MediaTools.loadImage(name); 
Parameter: 
name  The name of the image
Returns: A fully loaded Image object
 

public static void setCachingEnabled(boolean flag)

This method sets an internal flag in the MediaTools package to indicate whether images and audio clips are cached internally by name. This flag is enabled by default, which gives better performance when clients load the same named image more than once. It does, however, tie up memory, making it unavailable to the garbage collector. Applications that make extensive use of memory should disable this flag by calling setCachingEnabled(false).

 
Usage: MediaTools.setCachingEnabled(flag); 
Parameter: 
flag  true to enable caching by name, false to disable it.