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()).

To start an audio alert, you must pass an array containing the coding for a tune, and the volume level as a percentage of the maximum.

The following code sample illustrates how to play a tune:

 // The TUNE (bar 1 and 2 of Islamey by Balakirev)
 private static final short BFlat = 466;   //466.16
 private static final short AFlat = 415;     //415.30
 private static final short A = 440; //440.00
 private static final short GFlat = 370;     //369.99
 private static final short DFlat = 554;     //554.37
 private static final short C = 523; //523.25
 private static final short F = 349; //349.32
 
 private static final short TEMPO = 125;
 
 // Duration of a 16th note, arbitrary, in ms.
 private static final short d16 = 1 * TEMPO;
 
 // Duration of an eighth note, arbitrary, in ms.
 private static final short d8 = d16 << 1;
 
 // 10 ms pause.
 private static final short dpause = 10;
 
 // Zero frequency pause.
 private static final short pause = 0;
 
 private static final short[] TUNE = new short[]
 {
     BFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     A, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     GFlat, d16, pause, dpause,
     GFlat, d16, pause, dpause,
     A, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     DFlat, d16, pause, dpause,
     C, d16, pause, dpause, //bar 1
     AFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     F, d16, pause, dpause,
     GFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     BFlat, d16, pause, dpause,
     AFlat, d16, pause, dpause,
     F, d8 + d16 //bar 2
 };
 
 // % volume
 private static final int VOLUME = 80;
 
 if ( Alert.isAudioSupported())
 {
     Alert.startAudio(TUNE, VOLUME);
 }
 

On completion, AlertListener.audioDone() is invoked on the event thread.

To start a MIDI alert, you must pass an array containing the coding for a tune, and a flag that determines whether the tune can be interrupted by keyboard or trackwheel activity. On completion, AlertListener2.midiDone() will be invoked on the event thread.

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()
          Deprecated. ADPCM is no longer supported.
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 newMuteState)
          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)
          Deprecated. ADPCM is no longer supported.
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)
          Deprecated. ADPCM is no longer supported.
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()
          Deprecated. ADPCM is no longer supported.
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_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

ALERT_ERROR_UNKNOWN

public static final int ALERT_ERROR_UNKNOWN
Unknown error
Since:
JDE 4.0.0

ALERT_OK

public static final int ALERT_OK
Playback has begun
Since:
JDE 4.0.0
Method Detail

enablePWMSync

public static void enablePWMSync(boolean enable)
Deprecated. This is no longer supported.

Enables or disables PWM sync.
Throws:
UnsupportedOperationException - if the device does not support ADPCM.
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

isADPCMSupported

public static boolean isADPCMSupported()
Deprecated. ADPCM is no longer supported.

Determines if this device provides ADPCM support.
Returns:
True if this device provides ADPCM support; false otherwise.
Since:
JDE 4.0.0

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

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

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

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

mute

public static void mute(boolean newMuteState)
Toggles the device between mute (volume 0) and loud state, and persists the current volume level. Any call to setVolume() overrides the current mute state. Any later call to mute(false) returns the volume to the cached value.

If newMuteState is equal to the current mute state, this method does nothing.

Parameters:
newMuteState - If true, mutes the device; otherwise, returns the volume to the value previous to muting.
Since:
JDE 4.0.2

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.

If the device does not support the buzzer, then invoking this method has no effect.

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 0 to 100.
Throws:
IllegalArgumentException - if the specified volume is outside the range 0 to 100.
Since:
JDE 3.7.0
See Also:
AlertListener.buzzerDone(int)

setADPCMVolume

public static void setADPCMVolume(int volume)
Deprecated. ADPCM is no longer supported.

Sets the volume for ADPCM.

Note: This value is multiplied with the master volume.

If the device does not support an ADPCM alert, invoking this method throws an UnsupportedOperationException.

Parameters:
volume - Percentage of total capable volume, from 0 to 100.
Throws:
UnsupportedOperationException - if the device does not support ADPCM.
IllegalArgumentException - if the specified volume is outside the range 0 to 100.
Since:
JDE 4.0.0

setBuzzerVolume

public static void setBuzzerVolume(int volume)

Sets the volume for the buzzer.

If the device does not support the buzzer, then invoking this method has no effect.

Note: This value is multiplied with the master volume.

Parameters:
volume - Percentage of total capable volume, from 0 to 100.
Throws:
IllegalArgumentException - if the specified volume is outside the range 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.
Throws:
IllegalArgumentException - if the specified volume is outside the range 0 to 100.
Since:
JDE 4.0.0

startADPCM

public static int startADPCM(byte[] tune,
                             boolean interruptable)
Deprecated. ADPCM is no longer supported.

Starts an ADPCM alert.

The specified tune is played using the polyphonic device. When the alert is complete, AlertListener2#adpcmDone is invoked on the event thread.

If the device does not support an ADPCM alert, invoking this method throws an UnsupportedOperationException.

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.
Throws:
UnsupportedOperationException - if the device does not support ADPCM.
Since:
JDE 4.0.0
See Also:
AlertListener2#adpcmDone

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 0 to 100.
Throws:
IllegalArgumentException - if the specified volume is outside the range 0 to 100.
Since:
JDE 3.6.0
See Also:
AlertListener.audioDone(int)

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.

If the device does not support the buzzer, then invoking this method has no effect.

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 0 to 100.
Throws:
IllegalArgumentException - if the specified volume is outside the range 0 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.

If the device does not support the buzzer, then invoking this method has no effect.

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 0 to 100.
interruptable - If true, the tune might be interrupted by keypad or trackwheel activity; otherwise, the tune will not be interrupted.
Throws:
IllegalArgumentException - if the specified volume is outside the range 0 to 100.
Since:
JDE 4.0.0
See Also:
AlertListener.buzzerDone(int)

startMIDI

public static int startMIDI(byte[] tune,
                            boolean interruptable)
Starts a MIDI alert.

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

If the device does not support a MIDI alert, invoking this method throws an UnsupportedOperationException.

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.
Throws:
UnsupportedOperationException - if the device does not support MIDI.
Since:
JDE 4.0.0
See Also:
AlertListener2.midiDone(int)

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.vibrateDone(int) is invoked on the event thread.

Parameters:
duration - Vibration time in milliseconds, from 0 to 25500.
Throws:
IllegalArgumentException - if the specified duration is outside the range 0 to 25500.
Since:
JDE 3.6.0
See Also:
AlertListener.vibrateDone(int)

stopADPCM

public static void stopADPCM()
Deprecated. ADPCM is no longer supported.

Cancels an ADPCM alert in progress.

If the device does not support an ADPCM alert, invoking this method throws an UnsupportedOperationException.

Throws:
UnsupportedOperationException - if the device does not support ADPCM.
Since:
JDE 4.0.0

stopAudio

public static void stopAudio()
Cancels an audio alert in progress.
Since:
JDE 3.6.0

stopBuzzer

public static void stopBuzzer()
Cancels a buzzer alert in progress.

If the device does not support the buzzer, then invoking this method has no effect.

Since:
JDE 3.6.0

stopMIDI

public static void stopMIDI()
Cancels a MIDI alert in progress.

If the device does not support a MIDI alert, invoking this method throws an UnsupportedOperationException.

Throws:
UnsupportedOperationException - if the device does not support MIDI.
Since:
JDE 4.0.0

stopVibrate

public static void stopVibrate()
Cancels a vibrate alert in progress.
Since:
JDE 3.6.0



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.