org.havi.ui
Class HSound

java.lang.Object
  extended by org.havi.ui.HSound

public class HSound
extends java.lang.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

ParameterDescriptionDefault value Set methodGet method
None.

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
The starting position of any audio clip to be played. At the beginning of the audio clip. --- ---


Constructor Summary
HSound()
          Creates an HSound object.
 
Method Summary
 void dispose()
          If the HSound object is playing / looping then it will be stopped.
 void load(java.lang.String location)
          Loads data synchronously into an HSound object from an audio sample in the specified file.
 void load(java.net.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(java.lang.String location)
          throws java.io.IOException,
                 java.lang.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:

Parameters:
location - the name of a file containing audio data in a recognized file format.
Throws:
java.io.IOException - if the sample cannot be loaded due to an IO problem.
java.lang.SecurityException - if the caller does not have sufficient rights to access the specified audio sample.

load

public void load(java.net.URL contents)
          throws java.io.IOException,
                 java.lang.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:

Parameters:
contents - a URL referring to the data to load.
Throws:
java.io.IOException - if the audio sample cannot be loaded due to an IO problem.
java.lang.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:

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.