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, new messages or phone calls).

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 the device does support a particular kind of alert, 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) Deprecated. This is no longer supported.
static int	getVolume() Retrieves the master volume.
static boolean	isADPCMSupported() Determines if this device provides ADPCM support.
static boolean	isAudioSupported() Determines if this device provides support for playing audio alerts via startAudio(short[], int).
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.
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 support for playing audio alerts via startAudio(short[], int).

Returns:

True if this device provides audio support; false otherwise.

Since:

JDE 4.0.0

startAudio

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

Starts an audio alert.

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

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

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data. The elements of the array 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 3.6.0

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; false otherwise.

Since:

JDE 4.0.0

startBuzzer

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

Starts a buzzer alert.

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

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data. The array 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 3.6.0

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 using the piezoelectric buzzer at the specified volume. When the alert is complete, AlertListener.buzzerDone(int) is invoked on the event thread. The tune is interrupted by any keypad or trackwheel activity.

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series all have a frequency range f(hz) > 200.

Parameters:

tune - Two-element array containing tune data. The array 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 might be interrupted by keypad or trackwheel activity; otherwise, the tune will not be interrupted.

Since:

JDE 4.0.0

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 using the piezoelectric buzzer at the specified volume. When the alert is complete, AlertListener.buzzerDone(int) is invoked on the event thread. The tune is not interrupted by keypad or trackwheel activity.

Notes:

Tune data arrays consist of frequency, duration pairs (both a short). Consecutive notes of the same frequency appear to bleed together. To create staccato-type effects, insert brief 0 frequency pauses into the note array. Devices vary in their frequency response. The BlackBerry 5800 Series, BlackBerry 6200 Series, and BlackBerry 6700 Series 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 3.7.0

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; false otherwise.

Since:

JDE 4.0.0

startVibrate

public static void startVibrate(int duration)

Starts a vibrate alert.

The device vibrates for the specified amount of time. When the alert is complete, AlertListener.buzzerDone(int) is invoked on the event thread.

Parameters:

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

Since:

JDE 3.6.0

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; false otherwise.

Since:

JDE 4.0.0

startMIDI

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

Starts a MIDI alert.

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

Parameters:

tune - Tune to play.

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

Returns:

One of the ALERT_ values.

Since:

JDE 4.0.0

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; false otherwise.

Since:

JDE 4.0.0

startADPCM

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

Starts an ADPCM alert.

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

Parameters:

tune - Tune to play.

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

Returns:

One of the ALERT_* values.

Since:

JDE 4.0.0

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)

Deprecated. This is no longer supported.

Enables or disables PWM sync.

Since:

JDE 4.0.0

setADPCMVolume

public static void setADPCMVolume(int volume)

Sets the volume for ADPCM.

Note: This value is multiplied with the master volume.

Parameters:

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

Since:

JDE 4.0.0

setBuzzerVolume

public static void setBuzzerVolume(int volume)

Sets the volume for the buzzer.

Note: This value is multiplied with the master volume.

Parameters:

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

Since:

JDE 4.0.0

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.0

getVolume

public static int getVolume()

Retrieves the master volume.

Returns:

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() overrides mute state.

Any later call to mute(false) returns the volume to the cached value.

Parameters:

toggle - If true, mutes the device; otherwise, returns the volume to the value previous to muting.

Since:

JDE 4.0.2