net.rim.device.api.system
Class Application

java.lang.Object
  extended by net.rim.device.api.system.Application
Direct Known Subclasses:
UiApplication

public abstract class Application
extends Object

The base class for all device applications. There should only be one Application instance per process.

Applications which do not require any user interaction may be derived directly from this class. Applications which require user interaction should be derived from UiApplication.

An application can synchronize with the event lock (returned by Application.getEventLock()) to serialize operations with the event dispatcher.

See Also:
ApplicationDescriptor, ApplicationManager

Constructor Summary
protected Application()
          Constructs a new Application instance.
 
Method Summary
protected  boolean acceptsForeground()
          Determines if this application can function in the foreground.
 boolean acceptsKeyUpEvents()
          Deprecated. KEY_UP events are now always sent.
 void activate()
          Handles foregrounding event.
 void addAlertListener(AlertListener listener)
          Adds an alert listener to this application.
 void addFileSystemJournalListener(FileSystemJournalListener listener)
          Adds an file system event journal listener to this application.
 void addFileSystemListener(FileSystemListener listener)
          Adds an file system event listener to this application.
 void addGlobalEventListener(GlobalEventListener listener)
          Adds a global event listener to this application.
 void addHolsterListener(HolsterListener listener)
          Deprecated.  
 void addIOPortListener(IOPortListener listener)
          Adds an I/O port event listener to this application.
 void addKeyListener(KeyListener listener)
          Adds a key event listener to this application.
 void addKeyListener(KeyListener listener, boolean excludeFromUnhandledGlobalKeyEvents)
          Adds a key event listener to this application.
 boolean addMediaActionHandler(MediaActionHandler handler)
          Adds a MediaActionHandler to this applicaton's list of media actions handlers.
 void addPeripheralListener(PeripheralListener listener)
          Deprecated.  
 void addRadioListener(int WAFFilter, RadioListener listener)
          Adds a radio event listener to this application.
 void addRadioListener(RadioListener listener)
          Adds a radio event listener to this application.
 void addRealtimeClockListener(RealtimeClockListener listener)
          Adds a real-time clock event listener to this application.
 void addSystemListener(SystemListener listener)
          Adds a system event listener to this application.
 void addTrackwheelListener(TrackwheelListener listener)
          Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.
 void cancelInvokeLater(int id)
          Cancels a runnable timed to invoke later.
 void deactivate()
          Handles backgrounding event.
 void enableKeyUpEvents(boolean enable)
          Deprecated. KEY_UP events are now always sent.
 void enterEventDispatcher()
          Enters the event dispatcher.
 Object getAppEventLock()
          Retrieves the application event lock for this application.
static Application getApplication()
          Retrieves the current application instance.
static Object getEventLock()
          Retrieves the application user interface event lock.
 int getProcessId()
          Retrieves the process ID for this application.
 boolean hasEventThread()
          Determines if this application has entered the event dispatcher.
 void invokeAndWait(Runnable runnable)
          Puts runnable object into this application's event queue, and waits until it is processed.
 void invokeLater(Runnable runnable)
          Puts runnable object into this application's event queue.
 int invokeLater(Runnable runnable, long time, boolean repeat)
          Puts runnable object into this application's event queue for repeated execution.
 boolean isAlive()
          Determines if this application's process is still alive.
static boolean isEventDispatchThread()
          Determines if this is the event dispatching thread.
 boolean isEventThread()
          Determines if this is the event dispatching thread.
 boolean isForeground()
          Determines if this application is in the foreground.
 boolean isHandlingEvents()
          Determines if this application has entered the event dispatch loop.
 boolean isInTouchCompatibilityMode()
          Returns whether app is running in touch compatibility mode (always show keyboard, disable rotation, 320x240 screen).
 void removeAlertListener(AlertListener listener)
          Removes an alert listener from this application.
 void removeFileSystemJournalListener(FileSystemJournalListener listener)
          Removes a file system journal listener from this application.
 void removeFileSystemListener(FileSystemListener listener)
          Removes a file system listener from this application.
 void removeGlobalEventListener(GlobalEventListener listener)
          Removes a global event listener from this application.
 void removeHolsterListener(HolsterListener listener)
          Deprecated.  
 void removeIOPortListener(IOPortListener listener)
          Removes an I/O port event listener from this application.
 void removeKeyListener(KeyListener listener)
          Removes a key event listener from this application.
 void removeMediaActionHandler(MediaActionHandler handler)
          Removes a MediaActionHandler from this applicaton's list of media actions handlers.
 void removePeripheralListener(PeripheralListener listener)
          Deprecated.  
 void removeRadioListener(RadioListener listener)
          Removes a radio event listener from this application.
 void removeRealtimeClockListener(RealtimeClockListener listener)
          Removes a real-time clock event listener from this application.
 void removeSystemListener(SystemListener listener)
          Removes a system event listener from this application.
 void removeTrackwheelListener(TrackwheelListener listener)
          Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.
 void requestBackground()
          Requests to have this application sent to the background.
 boolean requestClose()
          Individual apps can handle this new API call by cleaning up and then closing themselves, if they so desire.
 void requestForeground()
          Requests to have this application brought to the foreground.
 void setAcceptEvents(boolean on)
          Determines if this application accepts system events.
 boolean shouldAppearInApplicationSwitcher()
          Determines if this application should appear in the Application Switcher.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

Application

protected Application()
Constructs a new Application instance.

Throws:
RuntimeException - if an instance of Application already exists in the current application.


Method Detail

isInTouchCompatibilityMode

public boolean isInTouchCompatibilityMode()
Returns whether app is running in touch compatibility mode (always show keyboard, disable rotation, 320x240 screen).

Returns:
True if app is in touch compatibility mode, otherwise false
Since:
BlackBerry API 4.7.0

acceptsForeground

protected boolean acceptsForeground()
Determines if this application can function in the foreground.

Note that this method returns false by default; classes that extend Application should override this method to return true. They furnish applications that can handle foregrounding (that is, applications presenting an interface to the user).

Returns:
True if this application can be pushed into the foreground; otherwise, false.
See Also:
UiApplication

shouldAppearInApplicationSwitcher

public boolean shouldAppearInApplicationSwitcher()
Determines if this application should appear in the Application Switcher.

Note that this method returns the value of acceptsForeground() by default. This is the method the Application Switcher used to populate itself before this method was added. However, there are applications that have other criteria for deciding when they wish to appear in the Application Switcher that aren't necessarily based on the ability of the application to take the foreground. This method decouples these two concepts. Classes that extend Application can override this method to base this decision on other criteria.

Returns:
True if this application should appear in the Application Switcher, false otherwise.
Since:
BlackBerry API 6.0.0

activate

public void activate()
Handles foregrounding event.

The system invokes this method when it brings this application to the foreground. By default, this method does nothing. Override this method to perform additional processing when being brought to the foreground.


deactivate

public void deactivate()
Handles backgrounding event.

The system invokes this method when sending this application to the background. By default, this method does nothing. Override this method to perform additional processing when being sent to the background.


isForeground

public final boolean isForeground()
Determines if this application is in the foreground.

Returns:
True if this application is in the foreground; otherwise, false.

requestBackground

public final void requestBackground()
Requests to have this application sent to the background.

The Application.deactivate() method will be invoked when the switch to the background actually occurs. If the application is not in the foreground when you invoke this method, this method does nothing.


requestForeground

public final void requestForeground()
Requests to have this application brought to the foreground.

The Application.activate() method will be invoked when the switch to the foreground actually occurs. If this application is already in the foreground when the request is granted, this method does nothing.


enableKeyUpEvents

public final void enableKeyUpEvents(boolean enable)
Deprecated. KEY_UP events are now always sent.

Allows this application to receive KeyListener.keyUp(int, int) events.

By default, applications do not receive these events for performance reasons.

Parameters:
enable - If true, this application will receive keyup events from the system; otherwise, the system will continue to withold them from this application.

acceptsKeyUpEvents

public final boolean acceptsKeyUpEvents()
Deprecated. KEY_UP events are now always sent.

Determines if this application receives KeyListener.keyUp(int, int) events.

By default, applications do not receive these events for performance reasons.

Returns:
True if this application receives keyUp events; otherwise, false.
Since:
BlackBerry API 4.0.0

addKeyListener

public void addKeyListener(KeyListener listener)
Adds a key event listener to this application. When a key listener is attached to an Application object, the listener receives all key events (both handled keys and unhandled global keys) while the application is in the foreground. In addition, the key listener receives all unhandled global key events while the application is in the background. If the latter key events are not desired, then key listeners should be attached to the individual screens in an application rather than to the Application object itself.

Parameters:
listener - Key event listener to register for this application.
Throws:
NullPointerException - if listener is null.

addKeyListener

public void addKeyListener(KeyListener listener,
                           boolean excludeFromUnhandledGlobalKeyEvents)
Adds a key event listener to this application.

Parameters:
listener - Key event listener to register for this application.
excludeFromUnhandledGlobalKeyEvents - If a foreground application does not consume a global key event, it is reposted as an unhandled global key event. Pass in true if the listener should be excluded from receiving unhandled global key events, false otherwise. This is desirable if an application is registered with KeyHandlerRegistry and does not want to receive duplicate notifications of global key events.
Throws:
NullPointerException - if listener is null.
Since:
BlackBerry API 6.0.0

removeKeyListener

public void removeKeyListener(KeyListener listener)
Removes a key event listener from this application.

Parameters:
listener - Key event listener to de-register for this application.

addMediaActionHandler

public boolean addMediaActionHandler(MediaActionHandler handler)
Adds a MediaActionHandler to this applicaton's list of media actions handlers. Examples of media actions include key presses of media keys while in the background, button presses on connected wired headsets, and button presses on paired Bluetooth headsets. See the documentation of MediaActionHandler for details.

When the mediaAction() method of the specified MediaActionHandler is invoked for media key presses from this registration it will be specified source==SOURCE_BACKGROUND_KEY, even if this application is currently in the foreground. If it is desired that mediaAction() be invoked with SOURCE_FOREGROUND_KEY when this application is in the foreground then register a MediaKeyListener using addKeyListener() to receive key presses while in the foreground and a MediaActionHandler to receive key presses while in the background. Since MediaKeyListener actually implements MediaActionHandler, the MediaKeyListener instance can be registered with both addKeyListener() and addMediaActionHandler().

The callbacks into the specified MediaActionHandler will occur on the event thread of this application.

Parameters:
handler - the MediaActionHandler to add to this application's list.
Returns:
true if the MediaActionHandler was successfully registered; false if the registration failed, possibly because net_rim_media_actions or net_rim_media_actions_daemon is missing or failed to run.
Throws:
NullPointerException - if handler is null.
ControlledAccessException - if registering the specified handler is forbidden for this application.
See Also:
Application.removeMediaActionHandler(MediaActionHandler), MediaActionHandler.SOURCE_BACKGROUND_KEY, Application.addKeyListener(KeyListener), MediaKeyListener
Since:
BlackBerry API 5.0.0

removeMediaActionHandler

public void removeMediaActionHandler(MediaActionHandler handler)
Removes a MediaActionHandler from this applicaton's list of media actions handlers.

Parameters:
handler - the MediaActionHandler to remove from this application's list; if null this method does nothing.
See Also:
Application.addMediaActionHandler(MediaActionHandler)
Since:
BlackBerry API 5.0.0

addTrackwheelListener

public void addTrackwheelListener(TrackwheelListener listener)
Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.

Adds a trackwheel event listener to this application.

Parameters:
listener - Trackwheel event listener to register for this application.
Throws:
NullPointerException - if listener is null.

removeTrackwheelListener

public void removeTrackwheelListener(TrackwheelListener listener)
Deprecated. Use Screen.navigationClick(int, int) or Screen.navigationMovement(int, int, int, int) instead.

Removes a trackwheel event listener from this application.

Parameters:
listener - Trackwheel event listener to de-register for this application.

addRealtimeClockListener

public void addRealtimeClockListener(RealtimeClockListener listener)
Adds a real-time clock event listener to this application.

Parameters:
listener - Real-time clock event listener to register for this application.
Throws:
NullPointerException - if listener is null.

removeRealtimeClockListener

public void removeRealtimeClockListener(RealtimeClockListener listener)
Removes a real-time clock event listener from this application.

Parameters:
listener - Real-time clock event listener to de-register from this application.

addSystemListener

public void addSystemListener(SystemListener listener)
Adds a system event listener to this application.

Parameters:
listener - System event listener to register for this application.
Throws:
NullPointerException - if listener is null.

removeSystemListener

public void removeSystemListener(SystemListener listener)
Removes a system event listener from this application.

Parameters:
listener - System event listener to de-register for this application.

addHolsterListener

public void addHolsterListener(HolsterListener listener)
Deprecated. 

Adds a holster event listener to this application. The HolsterListener is deprecated. Please use SensorListener.

Parameters:
listener - Holster event listener to register for this application.
Throws:
NullPointerException - if listener is null.

removeHolsterListener

public void removeHolsterListener(HolsterListener listener)
Deprecated. 

Removes a holster event listener from this application. The HolsterListener is deprecated. Please use SensorListener.

Parameters:
listener - Holster event listener to de-register for this application.

addRadioListener

public void addRadioListener(RadioListener listener)
Adds a radio event listener to this application.

Parameters:
listener - Radio event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
BlackBerry API 3.6.0

addRadioListener

public void addRadioListener(int WAFFilter,
                             RadioListener listener)
Adds a radio event listener to this application. The listener will only receive events generated by radios belonging to the provided Wireless Access Families.

Parameters:
WAFFilter - A bitmask of RadioInfo.WAF_* flags indicating the Wireless Access Families for this listener.
listener - Radio event listener to register for this application.
Throws:
NullPointerException - if listener is null.
See Also:
RadioInfo
Since:
BlackBerry API 4.2.1

removeRadioListener

public void removeRadioListener(RadioListener listener)
Removes a radio event listener from this application.

Parameters:
listener - Radio event listener to de-register for this application.
Since:
BlackBerry API 3.6.0

addIOPortListener

public void addIOPortListener(IOPortListener listener)
Adds an I/O port event listener to this application.

Parameters:
listener - I/O port event listener to register for this application.
Throws:
NullPointerException - if listener is null.

removeIOPortListener

public void removeIOPortListener(IOPortListener listener)
Removes an I/O port event listener from this application.

Parameters:
listener - I/O port event listener to de-register for this application.

addFileSystemListener

public void addFileSystemListener(FileSystemListener listener)
Adds an file system event listener to this application.

Parameters:
listener - File system event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
BlackBerry API 4.2.0

removeFileSystemListener

public void removeFileSystemListener(FileSystemListener listener)
Removes a file system listener from this application.

Parameters:
listener - File system event listener to de-register for this application.
Since:
BlackBerry API 4.2.0

addFileSystemJournalListener

public void addFileSystemJournalListener(FileSystemJournalListener listener)
Adds an file system event journal listener to this application.

Parameters:
listener - File system journal event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
BlackBerry API 4.2.0

removeFileSystemJournalListener

public void removeFileSystemJournalListener(FileSystemJournalListener listener)
Removes a file system journal listener from this application.

Parameters:
listener - File system journal event listener to de-register for this application.
Since:
BlackBerry API 4.2.0

addGlobalEventListener

public void addGlobalEventListener(GlobalEventListener listener)
Adds a global event listener to this application.

Parameters:
listener - Global event listener to register for this application.
Throws:
NullPointerException - if listener is null.

removeGlobalEventListener

public void removeGlobalEventListener(GlobalEventListener listener)
Removes a global event listener from this application.

Parameters:
listener - Global event listener to de-register for this application.

addPeripheralListener

public void addPeripheralListener(PeripheralListener listener)
Deprecated. 

Adds a peripheral listener to this application.

Parameters:
listener - Peripheral event listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
BlackBerry API 3.6.0

removePeripheralListener

public void removePeripheralListener(PeripheralListener listener)
Deprecated. 

Removes a peripheral listener from this application.

Parameters:
listener - Peripheral event listener to de-register for this application.
Since:
BlackBerry API 3.6.0

addAlertListener

public void addAlertListener(AlertListener listener)
Adds an alert listener to this application.

Parameters:
listener - Alert listener to register for this application.
Throws:
NullPointerException - if listener is null.
Since:
BlackBerry API 3.6.0

removeAlertListener

public void removeAlertListener(AlertListener listener)
Removes an alert listener from this application.

Parameters:
listener - Alert listener to de-register for this application.
Since:
BlackBerry API 3.6.0

enterEventDispatcher

public void enterEventDispatcher()
Enters the event dispatcher.

The thread that calls this method (typically the main thread in the application) becomes the event-dispatching thread, which will execute all drawing and event-handling code.

Note that under normal circumstances this method does not return.

Throws:
IllegalStateException - if this method is invoked after the event thread has already been entered; that is, if Application.isHandlingEvents() returns true.

setAcceptEvents

public final void setAcceptEvents(boolean on)
Determines if this application accepts system events.

An application can use this method to turn off and on accepting of events from the system. A long running application that does not need to handle events (e.g., a non-ui background process) should invoke this method and pass it false, rather than invoking Application.enterEventDispatcher().

Invoking this method to turn off events also flushes the event queue.

Parameters:
on - True to accept system events; false to tell the system not to pass them to this application.

isAlive

public boolean isAlive()
Determines if this application's process is still alive.

Returns:
True if this application's process is still alive; otherwise, false.
Since:
BlackBerry API 4.0.0

isEventDispatchThread

public static final boolean isEventDispatchThread()
Determines if this is the event dispatching thread.

Note: this method simply invokes Application.isEventThread() on the current process's Application object.

Returns:
True if the invoking thread is the event dispatch thread; otherwise false.
Throws:
IllegalStateException - If this method is called when there is no Application object in the process.

isEventThread

public boolean isEventThread()
Determines if this is the event dispatching thread.

Returns:
True if the invoking thread is the event dispatch thread; otherwise false.

hasEventThread

public boolean hasEventThread()
Determines if this application has entered the event dispatcher.

Returns:
True if this application has entered the event dispatcher (i.e. has invoked Application.enterEventDispatcher()); otherwise, false.

isHandlingEvents

public final boolean isHandlingEvents()
Determines if this application has entered the event dispatch loop.

Returns:
True if the application has entered the event dispatch loop; otherwise, false.

getEventLock

public static final Object getEventLock()
Retrieves the application user interface event lock.

Worker threads should synchronize on this thread if they wish to execute code serialized with the event thread. Your worker thread should hold the lock only for a short period of time, as this action pauses the thread dispatcher.

Any operation involving the device's user interface must be done with the lock held. The UI system also guarantees that any methods it invokes will execute on a thread that already has the lock.

An application should never call notify or wait on this object.

Returns:
Application event lock; returns exactly Application.getApplication().getAppEventLock().
Throws:
IllegalStateException - If this method is called when there is no Application object in the process.

getAppEventLock

public final Object getAppEventLock()
Retrieves the application event lock for this application.

Returns:
Application event lock.
See Also:
Application.getEventLock()

getApplication

public static final Application getApplication()
Retrieves the current application instance.

Returns:
Current application instance.
Throws:
IllegalStateException - If this function is called when there is no Application object in the process.

invokeLater

public final void invokeLater(Runnable runnable)
Puts runnable object into this application's event queue.

Invoke this method, passing a runnable object, to have that object's run() method invoked on the dispatch thread, after all pending events are processed.

If there is no event dispatch thread (ie. Application.hasEventThread() returns false), then the last item to be queued is dropped when the queue surpasses its size limit. Note: If an application does not have an event thread, you may invoke Application.setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. All events queued to that application are then discarded.

Parameters:
runnable - Runnable object to be placed on the dispatch thread's queue of events to execute.
Throws:
NullPointerException - if runnable is null.

invokeLater

public final int invokeLater(Runnable runnable,
                             long time,
                             boolean repeat)
Puts runnable object into this application's event queue for repeated execution.

Invoke this method, passing a runnable object and schedule parameters, to have the object's run() method repeatedly invoked on the dispatch thread, after all pending events are processed.

Note that you should make sparing use of this this method, as each application has a limited number of timers. If this application currently has no timers available, this method returns -1.

If there is no event dispatch thread (ie. Application.hasEventThread() returns false), then the last item to be queued is dropped when the queue surpasses its size limit. Note: If an application does not have an event thread, you may invoke Application.setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. All events queued to that application are then discarded.

Parameters:
runnable - Runnable object to be placed on the dispatch thread's queue of events to execute.
time - Number of milliseconds to wait before adding the runnable object to the event queue. If the repeat parameter is true, then this method continually re-adds your runnable object to the queue, pausing this number of milliseconds between each insertion.
repeat - If true, the runnable object will be added to the event queue after each period of milliseconds specified by the time parameter. If false, the runnable will be added only once.
Returns:
ID of the event, or -1 if there are no timers available.
Throws:
NullPointerException - if runnable is null.
IllegalArgumentException - if time is less than or equal to zero.

cancelInvokeLater

public final void cancelInvokeLater(int id)
Cancels a runnable timed to invoke later.

Use this method to remove a runnable object inserted into the event queue (if currently in the queue), and cancel the operation to insert it into the queue in the future.

Parameters:
id - Event ID of the runnable returned by Application.invokeLater(Runnable,long,boolean). If the supplied Event ID is invalid, this method does nothing.

invokeAndWait

public final void invokeAndWait(Runnable runnable)
Puts runnable object into this application's event queue, and waits until it is processed.

Invoke this method, passing a runnable object, to have that object's run() method invoked on the dispatch thread, after all pending events are processed.

This method blocks until the insert event is processed (that is, until the runnable object's run() method returns).

It is safe to call this method on the event dispatch thread. In this case the runnable will be executed immediately.

If there is no event dispatch thread (ie. Application.hasEventThread() returns false), then the last item to be queued is dropped when the queue surpasses its size limit. Note: If an application does not have an event thread, you may invoke Application.setAcceptEvents(boolean) to inform the runtime system that the application no longer accepts events. All events queued to that application are then discarded.

Parameters:
runnable - Runnable object to be placed on the dispatch thread's queue of events for synchronous execution.
Throws:
NullPointerException - if runnable is null.

getProcessId

public final int getProcessId()
Retrieves the process ID for this application.

Returns:
Process identifier for this application.

requestClose

public boolean requestClose()
Individual apps can handle this new API call by cleaning up and then closing themselves, if they so desire. The individual app should return true if it's successful in terminating itself otherwise should return false.

Returns:
whether the application closed (true) or was sent to the background (false)
Since:
BlackBerry API 5.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.