acm.util

Class MediaTools

java.lang.Object

acm.util.MediaTools

public class MediaTools
extends Object

This class implements a standard mechanism for loading images, sounds, and data files from the resources associated with a jar file.

Field Summary

Fields

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

Method Summary

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 AudioClip	createAudioClip(InputStream in) Generates an audio clip from an input stream containing the data bytes for the audio clip.
static AudioClip	createAudioClip(String[] hexData) Generates an audio clip from a string array that provides the sound values.
static BufferedImage	createBufferedImage(Image image, int type) Creates a BufferedImage from the specified image.
static Image	createImage(InputStream in) Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.
static Image	createImage(int[][] array) Generates an image from a two-dimensional array of pixel values.
static Image	createImage(int[] pixels, int width, int height) Generates an image from a single-dimensional array of pixel values.
static Image	createImage(String[] hexData) Generates an image from a string array that provides the pixel values.
static Image	createPSPreviewImage(Image image, String[] preview) Creates a new image that combines an existing image with a PostScript preview represented as a string array.
static void	defineAudioClip(String name, AudioClip clip) Inserts the given clip into the audio clip table under the specified name.
static void	defineImage(String name, Image image) Inserts the given image into the image table under the specified name.
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.
static void	flushImage(String name) Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.
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.
static Component	getImageObserver() This method returns a new lightweight component suitable as an imageObserver.
static int[][]	getPixelArray(Image image) Returns a two-dimensional array of the pixels in the image.
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 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.
static AudioClip	loadAudioClip(String name, String path) Searches for an audio clip with the given name and loads it to create an AudioClip.
static AudioClip	loadAudioClip(URL url) Loads an audio clip from the specified URL.
static AudioClip	loadAudioClip(URL url, boolean topLevel) Loads an audio clip from the specified URL.
static Image	loadImage(File file) Searches the default image search path for an image with the specified file's name and then loads it to create an Image.
static Image	loadImage(Image image) Makes sure that the image is fully loaded before returning.
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.
static Image	loadImage(String name, String path) Searches for an image with the given name and loads it to create an Image.
static Image	loadImage(URL url) Loads an image from the specified URL.
static Image	loadImage(URL url, boolean topLevel) Loads an image from the specified URL.
static InputStream	openDataFile(String name) Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream.
static InputStream	openDataFile(String name, String path) Searches for a data file with the given name and opens it to create an InputStream.
static InputStream	openDataFile(URL url) Opens the specified URL to create an InputStream.
static InputStream	openDataFile(URL url, boolean topLevel) Opens a data file using the specified URL.
static void	saveImage(Image image, File file) Saves an image to the specified file.
static void	saveImage(Image image, String filename) Saves an image to a file with the specified filename.
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

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

Field Detail

DEFAULT_IMAGE_PATH

public static final 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 String DEFAULT_AUDIO_PATH

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

See Also:

Constant Field Values

DEFAULT_DATAFILE_PATH

public static final String DEFAULT_DATAFILE_PATH

The list of directories scanned for data files, separated by colons.

See Also:

Constant Field Values

Method Detail

loadImage

public static Image loadImage(File file)

Searches the default image search path for an image with the specified file's 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:

file - The file of the image

Returns:

A fully loaded Image object

Usage:

Image image = MediaTools.loadImage(name);

loadImage

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.

Parameters:

name - The name of the image

Returns:

A fully loaded Image object

Usage:

Image image = MediaTools.loadImage(name);

loadImage

public static Image loadImage(String name,
                              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

Usage:

Image image = MediaTools.loadImage(name, path);

Noshow:

loadImage

public static Image loadImage(URL url)

Loads an image from the specified URL.

Parameters:

url - The url containing the image

Returns:

A fully loaded Image object

Usage:

Image image = MediaTools.loadImage(url);

loadImage

public static Image loadImage(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

Usage:

image = MediaTools.loadImage(image);

defineImage

public static void defineImage(String name,
                               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

Usage:

MediaTools.defineImage(name, image);

flushImage

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.

Parameters:

name - The name for the image

Usage:

MediaTools.flushImage(name);

createImage

public static Image createImage(int[][] array)

Generates an image from a two-dimensional array of pixel values. As in standard image processing applications, the array is indexed so that the first subscript determines the row and the second determines the column.

Parameters:

array - A two-dimensional array of ints representing the pixels

Returns:

An Image object

Usage:

Image image = MediaTools.createImage(array);

createImage

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

Generates an image from a single-dimensional array of pixel values. The pixel array is stored in row-major order, which means that the pixels for the entire first row come before the pixels in the second row, and so on.

Parameters:

pixels - An array of ints representing the pixels

width - The width of the image

height - The height of the image

Returns:

An Image object

Usage:

Image image = MediaTools.createImage(pixels, width, height);

createImage

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.

Parameters:

in - An input stream containing the data

Returns:

An Image object

Usage:

Image image = MediaTools.createImage(in);

createImage

public static Image createImage(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

Usage:

Image image = MediaTools.createImage(hexData);

getPixelArray

public static int[][] getPixelArray(Image image)

Returns a two-dimensional array of the pixels in the image. As in standard image processing applications, the array is indexed so that the first subscript determines the row and the second determines the column.

Parameters:

image - The image

Returns:

A two-dimensional array of pixels

saveImage

public static void saveImage(Image image,
                             String filename)

Saves an image to a file with the specified filename. The data format for the image file is determined by the suffix of the filename. If the suffix of the file is not recognized as a supported image type, calling this method generates an error.

Parameters:

image - The image

filename - The name of the file to which the image is saved

Usage:

MediaTools.saveImage(image, filename);

saveImage

public static void saveImage(Image image,
                             File file)

Saves an image to the specified file. The data format for the image file is determined by the suffix of the filename. If the suffix of the file is not recognized as a supported image type, calling this method generates an error.

Parameters:

image - The image

file - The File to which the image is saved

Usage:

MediaTools.saveImage(image, file);

createPSPreviewImage

public static Image createPSPreviewImage(Image image,
                                         String[] preview)

Creates a new image that combines an existing image with a PostScript preview represented as a string array. Clients can retrieve the PostScript preview by asking for the "PSPreview" property.

Parameters:

image - The original image

preview - The corresponding PostScript preview

Returns:

A new image that includes the preview

Usage:

MediaTools.createPSPreviewImage(image, preview);

Noshow:

loadAudioClip

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.

Parameters:

name - The name of the audio clip

Returns:

A new AudioClip object

Usage:

AudioClip clip = MediaTools.loadAudioClip(name);

loadAudioClip

public static AudioClip loadAudioClip(String name,
                                      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 new AudioClip object

Usage:

AudioClip clip = MediaTools.loadAudioClip(name, path);

Noshow:

loadAudioClip

public static AudioClip loadAudioClip(URL url)

Loads an audio clip from the specified URL.

Parameters:

url - The url containing the audio clip

Returns:

A new AudioClip object

Usage:

AudioClip clip = MediaTools.loadAudioClip(url);

defineAudioClip

public static void defineAudioClip(String name,
                                   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

Usage:

MediaTools.defineAudioClip(name, clip);

flushAudioClip

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.

Parameters:

name - The name for the audio clip

Usage:

MediaTools.flushAudioClip(name);

createAudioClip

public static AudioClip createAudioClip(InputStream in)

Generates an audio clip from an input stream containing the data bytes for the audio clip. The implementation first tries to create a SoundClip object from the data. If that fails, it then backs up to the older strategy of using the SunAudioClip class.

Parameters:

in - An input stream containing the data

Returns:

An AudioClip object

Usage:

AudioClip clip = MediaTools.createAudioClip(in);

createAudioClip

public static AudioClip createAudioClip(String[] hexData)

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

Parameters:

hexData - A hex string array representing an audio clip

Returns:

An AudioClip object

Usage:

AudioClip audio clip = MediaTools.createAudioClip(hexData);

openDataFile

public static InputStream openDataFile(String name)

Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream. The search process consists of the following steps:

1. Check to see if there is a resource available with that name. If so, return an InputStream open on that resource.

2. Open the file with the specified name, relative to the application directory or the applet code base.

These steps are repeated for each element of the datafile search path, which consists of a list of directories separated by colons.

Parameters:

name - The name of the input file

Returns:

A new InputStream open on the specified file

Usage:

InputStream in = MediaTools.openDataFile(name);

openDataFile

public static InputStream openDataFile(String name,
                                       String path)

Searches for a data file with the given name and opens it to create an InputStream. Its operation is identical to the single-argument openDataFile 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 new InputStream open on the specified file

Usage:

InputStream in = MediaTools.openDataFile(name, path);

openDataFile

public static InputStream openDataFile(URL url)

Opens the specified URL to create an InputStream.

Parameters:

url - The URL of the data file

Returns:

A new InputStream open on the specified URL

Usage:

InputStream in = MediaTools.openDataFile(url);

createBufferedImage

public static BufferedImage createBufferedImage(Image image,
                                                int type)

Creates a BufferedImage from the specified image. The type parameter is used to specify the image type, as described in the BufferedImage documentation.

Parameters:

image - The original image

type - The type code used to describe the image model

A - BufferedImage containing the image data

Usage:

BufferedImage image = MediaTools.createBufferedImage(image, type);

getHexInputStream

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.

Parameters:

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

Returns:

An input stream for reading the bytes

Usage:

InputStream in = MediaTools.getHexInputStream(hexData);

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 disabled by default.

Parameters:

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

Usage:

MediaTools.setCachingEnabled(flag);

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.

Usage:

boolean flag = MediaTools.isCachingEnabled();

getImageObserver

public static Component getImageObserver()

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

Returns:

A new lightweight component suitable as an imageObserver.

Usage:

Component imageObserver = MediaTools.getImageObserver();

beep

public static void beep()

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

Usage:

MediaTools.beep();

loadImage

public static Image loadImage(URL url,
                              boolean topLevel)

Loads an image from the specified URL. The topLevel flag is false if this is invoked internally.

loadAudioClip

public static AudioClip loadAudioClip(URL url,
                                      boolean topLevel)

Loads an audio clip from the specified URL. The topLevel flag is false if this is invoked internally.

openDataFile

public static InputStream openDataFile(URL url,
                                       boolean topLevel)

Opens a data file using the specified URL. The topLevel flag is false if this is invoked internally.