acm.util

Class MediaTools

java.lang.Object

acm.util.MediaTools

public class MediaTools
extends java.lang.Object

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

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_AUDIO_PATH The list of directories scanned for audio clips, separated by colons.
static java.lang.String	DEFAULT_IMAGE_PATH The list of directories scanned for images, separated by colons.

Method Summary

Methods

Modifier and Type	Method and Description
static void	beep() This method sounds the audible alert on the console, which is typically a beep sound.
static java.applet.AudioClip	createAudioClip(java.io.InputStream in) Generates an audio clip from an input stream containing the data bytes for the audio clip.
static java.applet.AudioClip	createAudioClip(java.lang.String[] hexData) Generates an audio clip from a string array that provides the pixel values.
static java.awt.Image	createImage(java.io.InputStream in) Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.
static java.awt.Image	createImage(int[] pixels, int width, int height) Generates an image from an array of pixel values.
static java.awt.Image	createImage(java.lang.String[] hexData) Generates an image from a string array that provides the pixel values.
static void	defineAudioClip(java.lang.String name, java.applet.AudioClip clip) Inserts the given clip into the audio clip table under the specified name.
static void	defineImage(java.lang.String name, java.awt.Image image) Inserts the given image into the image table under the specified name.
static void	flushAudioClip(java.lang.String name) Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.
static void	flushImage(java.lang.String name) Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.
static java.io.InputStream	getHexInputStream(java.lang.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.
static java.awt.Component	getImageObserver() This method returns a new lightweight component suitable as an imageObserver.
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.
static java.applet.AudioClip	loadAudioClip(java.lang.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.
static java.applet.AudioClip	loadAudioClip(java.lang.String name, java.lang.String path) Searches for an audio clip with the given name and loads it to create an AudioClip.
static java.awt.Image	loadImage(java.awt.Image image) Makes sure that the image is fully loaded before returning.
static java.awt.Image	loadImage(java.lang.String name) Searches the default image search path for an image with the specified name and then loads it to create an Image.
static java.awt.Image	loadImage(java.lang.String name, java.lang.String path) Searches for an image with the given name and loads it to create an Image.
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_IMAGE_PATH

public static final java.lang.String DEFAULT_IMAGE_PATH

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

See Also:

Constant Field Values

DEFAULT_AUDIO_PATH

public static final java.lang.String DEFAULT_AUDIO_PATH

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

See Also:

Constant Field Values

Method Detail

loadImage

public static java.awt.Image loadImage(java.lang.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.

Parameters:

name - The name of the image

Returns:

A fully loaded Image object

loadImage

public static java.awt.Image loadImage(java.lang.String name,
                       java.lang.String path)

Searches for an image with the given name and loads it to create an Image. Its operation is identical to the single-argument loadImage call except in that this version allows the client to specify the search path explicitly.

Parameters:

name - The name of the image

path - A string of directories names separated by colons

Returns:

A fully loaded Image object

loadImage

public static java.awt.Image loadImage(java.awt.Image image)

Makes sure that the image is fully loaded before returning.

Parameters:

image - The Image which may not yet be loaded

Returns:

The same Image after ensuring that it is fully loaded

defineImage

public static void defineImage(java.lang.String name,
               java.awt.Image image)

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

Parameters:

name - The name for the image

image - The image to be stored in the table

flushImage

public static void flushImage(java.lang.String name)

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

Parameters:

name - The name for the image

createImage

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

Generates an image from an array of pixel values.

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

createImage

public static java.awt.Image createImage(java.io.InputStream in)

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

Parameters:

in - An input stream containing the data

Returns:

An Image object

createImage

public static java.awt.Image createImage(java.lang.String[] hexData)

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

Parameters:

hexData - A hex string array representing a .gif value

Returns:

An Image object

loadAudioClip

public static java.applet.AudioClip loadAudioClip(java.lang.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.

Parameters:

name - The name of the audio clip

Returns:

A new AudioClip object

loadAudioClip

public static java.applet.AudioClip loadAudioClip(java.lang.String name,
                                  java.lang.String path)

Searches for an audio clip with the given name and loads it to create an AudioClip. Its operation is identical to the single-argument loadAudioClip call except in that this version allows the client to specify the search path explicitly.

Parameters:

name - The name of the audio clip

path - A string of directories names separated by colons

Returns:

A fully loaded AudioClip object

defineAudioClip

public static void defineAudioClip(java.lang.String name,
                   java.applet.AudioClip clip)

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

Parameters:

name - The name for the audio clip

clip - The audio clip to be stored in the table

flushAudioClip

public static void flushAudioClip(java.lang.String name)

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

Parameters:

name - The name for the audio clip

createAudioClip

public static java.applet.AudioClip createAudioClip(java.io.InputStream in)

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

Parameters:

in - An input stream containing the data

Returns:

An AudioClip object

createAudioClip

public static java.applet.AudioClip createAudioClip(java.lang.String[] hexData)

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

Parameters:

hexData - A hex string array representing an audio clip

Returns:

An AudioClip object

getHexInputStream

public static java.io.InputStream getHexInputStream(java.lang.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.

Parameters:

hexData - An array of strings specifying a byte stream coded in hex

Returns:

An input stream for reading the bytes

setCachingEnabled

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).

Parameters:

flag - true to enable caching by name, false to disable it.

isCachingEnabled

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.

Returns:

true if caching by name is enabled, false otherwise.

getImageObserver

public static java.awt.Component getImageObserver()

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

Returns:

A new lightweight component suitable as an imageObserver.

beep

public static void beep()

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