org.havi.ui

Class HSound

java.lang.Object

org.havi.ui.HSound

Direct Known Subclasses:

OCSound

public class HSound
extends Object

The HSound class is used to represent an audio clip. The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
The starting position of any audio clip to be played.	At the beginning of the audio clip.	---	---

Constructor Summary

Constructors

Constructor and Description
HSound() Creates an HSound object.

Method Summary

Methods

Modifier and Type	Method and Description
void	dispose() If the HSound object is playing / looping then it will be stopped.
void	load(String location) Loads data synchronously into an HSound object from an audio sample in the specified file.
void	load(URL contents) Loads data synchronously into an HSound object from an audio sample indicated by a URL.
void	loop() Starts the HSound class looping from the beginning of its associated audio data.
void	play() Starts the HSound class playing from the beginning of its associated audio data.
void	set(byte[] data) Constructs an HSound object from an array of bytes encoded in the same encoding format as when reading this type of audio sample data from a file.
void	stop() Stops the HSound class playing its associated audio data.

Methods inherited from class java.lang.Object

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

Constructor Detail

HSound

public HSound()

Creates an HSound object. See the class description for details of constructor parameters and default values.

Method Detail

load

public void load(String location)
          throws IOException,
                 SecurityException

Loads data synchronously into an HSound object from an audio sample in the specified file. If the object already contains data, this method shall perform the following sequence:

• stop the sample if it is playing or looping.
• dispose of the old data and any associated resources, as if the dispose method had been called.
• load the new data synchronously.

Parameters:

location - the name of a file containing audio data in a recognized file format.

Throws:

IOException - if the sample cannot be loaded due to an IO problem.

SecurityException - if the caller does not have sufficient rights to access the specified audio sample.

load

public void load(URL contents)
          throws IOException,
                 SecurityException

Loads data synchronously into an HSound object from an audio sample indicated by a URL. If the object already contains data, this method shall perform the following sequence:

• stop the sample if it is playing or looping.
• dispose of the old data and any associated resources, as if the dispose method had been called.
• load the new data synchronously.

Parameters:

contents - a URL referring to the data to load.

Throws:

IOException - if the audio sample cannot be loaded due to an IO problem.

SecurityException - if the caller does not have sufficient rights to access the specified audio sample.

set

public void set(byte[] data)

Constructs an HSound object from an array of bytes encoded in the same encoding format as when reading this type of audio sample data from a file. If the object already contains data, this method shall perform the following sequence:

• stop the sample if it is playing or looping.
• dispose of the old data and any associated resources, as if the dispose method had been called.
• load the new data synchronously.

If the byte array does not contain a valid audio sample then this method shall throw a java.lang.IllegalArgumentException.

Parameters:

data - the data for the HSound object encoded in the specified format for audio sample files of this type.

play

public void play()

Starts the HSound class playing from the beginning of its associated audio data. If the sample data has not been completely loaded, this method has no effect.

When the audio data has been played in its entirety then no further audible output should be made until the next play or loop method is invoked. Note that the audio data is played back asynchronously. There is no mechanism for synchronization with other classes presenting sounds, images, or video.

This method may fail "silently" if (local) audio facilities are unavailable on the platform.

stop

public void stop()

Stops the HSound class playing its associated audio data.

Note that, if a play or loop method is invoked, after a stop, then presentation of the audio data will restart from the beginning of the audio data, rather than from the position where the audio data was stopped.

loop

public void loop()

Starts the HSound class looping from the beginning of its associated audio data. If the sample data has not been completely loaded, this method has no effect.

When the audio data has been played in its entirety, then it should be played again from the beginning of its associated data, so as to cause a "seamless" continuous (infinite) audio playback - until the next stop, or play method is invoked. Note that the audio data is played back asynchronously, there is no mechanism for synchronization with other classes presenting sounds, images, or video.

This method may fail "silently" if (local) audio facilities are unavailable on the platform.

dispose

public void dispose()

If the HSound object is playing / looping then it will be stopped. The dispose method then discards all sample resources used by the HSound object. This mechanism resets the HSound object to the state before a load() method was invoked.