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, sounds, and data files from the resources associated with a jar file.

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_DATAFILE_PATH The list of directories scanned for data files, separated by colons.
static java.lang.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 java.awt.image.BufferedImage	createBufferedImage(java.awt.Image image, int type) Creates a BufferedImage from the specified image.
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[][] array) Generates an image from a two-dimensional array of pixel values.
static java.awt.Image	createImage(int[] pixels, int width, int height) Generates an image from a single-dimensional 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 java.awt.Image	createPSPreviewImage(java.awt.Image image, java.lang.String[] preview) Creates a new image that combines an existing image with a PostScript preview represented as a string array.
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	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 int[][]	getPixelArray(java.awt.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 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 java.awt.Image	loadImage(java.net.URL url) Loads an image from the specified URL.
static java.awt.Image	loadImage(java.net.URL url, boolean topLevel) Loads an image from the specified URL.
static java.io.InputStream	openDataFile(java.lang.String name) Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream.
static java.io.InputStream	openDataFile(java.lang.String name, java.lang.String path) Searches for a data file with the given name and opens it to create an InputStream.
static java.io.InputStream	openDataFile(java.net.URL url) Opens the specified URL to create an InputStream.
static java.io.InputStream	openDataFile(java.net.URL url, boolean topLevel) Opens a data file using the specified URL.
static void	saveImage(java.awt.Image image, java.io.File file) Saves an image to the specified file.
static void	saveImage(java.awt.Image image, java.lang.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 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

DEFAULT_DATAFILE_PATH

public static final java.lang.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 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.net.URL url)

Loads an image from the specified URL.

Parameters:

url - The url containing the image

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[][] 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

createImage

public static java.awt.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

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

getPixelArray

public static int[][] getPixelArray(java.awt.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(java.awt.Image image,
                             java.lang.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

saveImage

public static void saveImage(java.awt.Image image,
                             java.io.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

createPSPreviewImage

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

openDataFile

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

openDataFile

public static java.io.InputStream openDataFile(java.lang.String name,
                                               java.lang.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

openDataFile

public static java.io.InputStream openDataFile(java.net.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

createBufferedImage

public static java.awt.image.BufferedImage createBufferedImage(java.awt.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

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

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.

loadImage

public static java.awt.Image loadImage(java.net.URL url,
                                       boolean topLevel)

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

openDataFile

public static java.io.InputStream openDataFile(java.net.URL url,
                                               boolean topLevel)

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