net.rim.device.api.system
Class Alert

java.lang.Object
  |
  +--net.rim.device.api.system.Alert

public final class Alert

extends Object

Provides access to the device's audio system.

Applications can use the device's audio system to notify the device's operator of interesting events (for example, arrived messages, phone calls, and so forth).

This class provides a number of alert type query methods you can use to determine whether the host device supports a particular kind of alert (for example isAudioSupported(). If it does, then you can use the associated "start" and "stop" control methods to use that type of alert (for example, startAudio(short[], int) and stopAudio().

If the device does not support a particular kind of alert, then invoking the control methods has no effect.

Since:

JDE 3.6.0

See Also:

AlertListener

Field Summary

static int	ALERT_ERROR_BAD_DATA Invalid data was provided
static int	ALERT_ERROR_BAD_STATE Playback is already in progress
static int	ALERT_ERROR_FILESYSTEM_FULL Filesystem is full
static int	ALERT_ERROR_UNKNOWN Unknown error
static int	ALERT_OK Playback has begun

Method Summary

static void	enablePWMSync(boolean enable) Enabled or disables PWM sync.
static int	getVolume() gets the master volume.
static boolean	isADPCMSupported() Determines if this device provides ADPCM support.
static boolean	isAudioSupported() Determines if this device provides audio support.
static boolean	isBuzzerSupported() Determines if this device provides buzzer support.
static boolean	isMIDISupported() Determines if this device provides MIDI support.
static boolean	isVibrateSupported() Determines if this device provides vibration support.
static void	mute(boolean toggle) toggles the device between mute (volume 0) and loud state and persists the current volume level any call to setVolume will override mute state any later call to mute(false) will return the volume to the cached value
static void	playBuzzer(short[] tune, int volume) Deprecated. Replaced by startBuzzer(short[],int,boolean)
static void	setADPCMVolume(int volume) Sets the volume for ADPCM.
static void	setBuzzerVolume(int volume) Sets the volume for the buzzer.
static void	setVolume(int volume) Sets the master volume.
static int	startADPCM(byte[] tune, boolean interruptable) Starts an ADPCM alert.
static void	startAudio(short[] tune, int volume) Starts an audio alert.
static void	startBuzzer(short[] tune, int volume) Starts a buzzer alert.
static void	startBuzzer(short[] tune, int volume, boolean interruptable) Starts a buzzer alert.
static int	startMIDI(byte[] tune, boolean interruptable) Starts a MIDI alert.
static void	startVibrate(int duration) Starts a vibrate alert.
static void	stopADPCM() Cancels an ADPCM alert in progress.
static void	stopAudio() Cancels an audio alert in progress.
static void	stopBuzzer() Cancels a buzzer alert in progress.
static void	stopMIDI() Cancels a MIDI alert in progress.
static void	stopVibrate() Cancels a vibrate alert in progress.

Methods inherited from class java.lang.Object

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

Field Detail

ALERT_OK

public static final int ALERT_OK

Playback has begun

Since:

JDE 4.0.0

ALERT_ERROR_UNKNOWN

public static final int ALERT_ERROR_UNKNOWN

Unknown error

Since:

JDE 4.0.0

ALERT_ERROR_BAD_DATA

public static final int ALERT_ERROR_BAD_DATA

Invalid data was provided

Since:

JDE 4.0.0

ALERT_ERROR_BAD_STATE

public static final int ALERT_ERROR_BAD_STATE

Playback is already in progress

Since:

JDE 4.0.2

ALERT_ERROR_FILESYSTEM_FULL

public static final int ALERT_ERROR_FILESYSTEM_FULL

Filesystem is full

Since:

JDE 4.0.2

Method Detail

isAudioSupported

public static boolean isAudioSupported()

Determines if this device provides audio support.

Returns:

True if this device provides audio support; otherwise, false.

Since:

JDE 4.0.0

startAudio

public static void startAudio(short[] tune,
                              int volume)

Starts an audio alert.

The specified tune is played via the currently selected audio channel at the specified volume. (Typically via the headset if the device is so equipped)

When the alert is completed, the AlertListener.audioDone(int) method is invoked on the event thread.

Note:

• Tune data arrays consist of frequency, duration pairs (both a short).
• Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
• Devices vary in their frequency response. The 5800, 6200 and 6700 series devices all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data (elements are the note frequency in hertz, and the duration of the note in milliseconds).

volume - Percentage of capable volume level, from 1 to 100.

Since:

JDE 4.0.2

See Also:

AlertListener.audioDone(int)

stopAudio

public static void stopAudio()

Cancels an audio alert in progress.

Since:

JDE 3.6.0

isBuzzerSupported

public static boolean isBuzzerSupported()

Determines if this device provides buzzer support.

Returns:

True if this device provides buzzer support; otherwise, false.

Since:

JDE 4.0.0

startBuzzer

public static void startBuzzer(short[] tune,
                               int volume)

Starts a buzzer alert.

The specified tune is played via the piezoelectric buzzer at the specified volume. When the alert is completed, the AlertListener.buzzerDone(int) method is invoked on the event thread. The tune will be interrupted by any keypad or trackwheel activity.

Note:

• Tune data arrays consist of frequency, duration pairs (both a short).
• Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
• Devices vary in their frequency response. The 5800, 6200 and 6700 series devices all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data (elements are the note frequency in hertz, and the duration of the note in milliseconds).

volume - Percentage of capable volume level, from 1 to 100.

Since:

JDE 4.0.2

See Also:

AlertListener.buzzerDone(int)

startBuzzer

public static void startBuzzer(short[] tune,
                               int volume,
                               boolean interruptable)

Starts a buzzer alert.

The specified tune is played via the piezoelectric buzzer at the specified volume. When the alert is completed, the AlertListener.buzzerDone(int) method is invoked on the event thread. The tune will be interrupted by any keypad or trackwheel activity.

Note:

• Tune data arrays consist of frequency, duration pairs (both a short).
• Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
• Devices vary in their frequency response. The 5800, 6200 and 6700 series devices all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data (elements are the note frequency in hertz, and the duration of the note in milliseconds).

volume - Percentage of capable volume level, from 1 to 100.

interruptable - If true, the tune may be interrupted by keypad or trackwheel activity; otherwise, the tune may not be interrupted.

Since:

JDE 4.0.2

See Also:

AlertListener.buzzerDone(int)

playBuzzer

public static void playBuzzer(short[] tune,
                              int volume)

Deprecated. Replaced by startBuzzer(short[],int,boolean)

Plays a buzzer alert.

The specified tune is played via the piezoelectric buzzer at the specified volume. When the alert is completed, the AlertListener.buzzerDone(int) method is invoked on the event thread. The tune will not be interrupted by keypad or trackwheel activity.

Note:

• Tune data arrays consist of frequency, duration pairs (both a short).
• Consecutive notes of the same frequency will appear to bleed together. Therefore, if staccato type effects are required, insert brief 0 frequency pauses into the note array.
• Devices vary in their frequency response. The 5800, 6200 and 6700 series devices all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data (elements are the note frequency in hertz, and the duration of the note in milliseconds).

volume - Percentage of capable volume level, from 1 to 100.

Since:

JDE 4.0.2

See Also:

AlertListener.buzzerDone(int)

stopBuzzer

public static void stopBuzzer()

Cancels a buzzer alert in progress.

Since:

JDE 3.6.0

isVibrateSupported

public static boolean isVibrateSupported()

Determines if this device provides vibration support.

Returns:

True if this device provides vibration support; otherwise, false.

Since:

JDE 4.0.0

startVibrate

public static void startVibrate(int duration)

Starts a vibrate alert.

The device will vibrate for the specified amount of time. When the alert is completed, the AlertListener.buzzerDone(int) method is invoked on the event thread.

Parameters:

duration - Vibration time in milliseconds, from 0 to 25500.

Since:

JDE 4.0.2

See Also:

AlertListener.vibrateDone(int)

stopVibrate

public static void stopVibrate()

Cancels a vibrate alert in progress.

Since:

JDE 3.6.0

isMIDISupported

public static boolean isMIDISupported()

Determines if this device provides MIDI support.

Returns:

True if this device provides MIDI support; otherwise, false.

Since:

JDE 4.0.0

startMIDI

public static int startMIDI(byte[] tune,
                            boolean interruptable)

Starts a MIDI alert.

The specified tune is played via the polyphonic device at the specified volume. When the alert is completed, the AlertListener2.midiDone(int) method is invoked on the event thread.

Parameters:

tune - Tune to play.

interruptable - If true, the tune may be interrupted by keypad or trackwheel activity; otherwise, the tune may note be interrupted.

Returns:

One of the ALERT_ values.

Since:

JDE 4.0.2

See Also:

AlertListener2.midiDone(int)

stopMIDI

public static void stopMIDI()

Cancels a MIDI alert in progress.

Since:

JDE 4.0.0

isADPCMSupported

public static boolean isADPCMSupported()

Determines if this device provides ADPCM support.

Returns:

True if this device provides ADPCM support; otherwise, false.

Since:

JDE 4.0.0

startADPCM

public static int startADPCM(byte[] tune,
                             boolean interruptable)

Starts an ADPCM alert.

The specified tune is played via the polyphonic device at the specified volume. When the alert is completed, the AlertListener2.adpcmDone(int) method is invoked on the event thread.

Parameters:

tune - Tune to play.

interruptable - If true, the tune may be interrupted by keypad or trackwheel activity; otherwise, the tune may note be interrupted.

Returns:

One of the ALERT_* values.

Since:

JDE 4.0.2

See Also:

AlertListener2.adpcmDone(int)

stopADPCM

public static void stopADPCM()

Cancels an ADPCM alert in progress.

Since:

JDE 4.0.0

enablePWMSync

public static void enablePWMSync(boolean enable)

Enabled or disables PWM sync.

Since:

JDE 4.0.2

setADPCMVolume

public static void setADPCMVolume(int volume)

Sets the volume for ADPCM.

This is multiplied with the master volume.

Parameters:

volume - Percentage of total capable volume, from 0 to 100.

Since:

JDE 4.0.2

setBuzzerVolume

public static void setBuzzerVolume(int volume)

Sets the volume for the buzzer.

This is multiplied with the master volume.

Parameters:

volume - Percentage of total capable volume, from 0 to 100.

Since:

JDE 4.0.2

setVolume

public static void setVolume(int volume)

Sets the master volume.

Parameters:

volume - Percentage of total capable volume, from 0 to 100.

Since:

JDE 4.0.2

getVolume

public static int getVolume()

gets the master volume.

Returns:

volume Percentage of total capable volume, from 0 to 100.

Since:

JDE 4.0.2

mute

public static void mute(boolean toggle)

toggles the device between mute (volume 0) and loud state and persists the current volume level

any call to setVolume will override mute state

any later call to mute(false) will return the volume to the cached value

Parameters:

toggle - sets the mute if true, returns the volume to the previous value if false

Since:

JDE 4.0.2