net.rim.device.api.system
Class Application

java.lang.Object
  |
  +--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 getEventLock()) to serialize operations with the event dispatcher.

See Also:
ApplicationDescriptor, ApplicationManager

Field Summary
 
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()
          Determines if this application receives KeyListener.keyUp(int, int) events.
 void activate()
          Handles foregrounding event.
 void addAlertListener(AlertListener listener)
          Adds an alert listener to this application.
 void addGlobalEventListener(GlobalEventListener listener)
          Adds a global event listener to this application.
 void addHolsterListener(HolsterListener listener)
          Adds a holster event listener to this application.
 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 addPeripheralListener(PeripheralListener listener)
          Adds a peripheral 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)
          Adds a trackwheel event listener to this application.
 void cancelInvokeLater(int id)
          Cancels a runnable timed to invoke later.
 void deactivate()
          Handles backgrounding event.
 void enableKeyUpEvents(boolean enable)
          Allows this application to receive KeyListener.keyUp(int, int) events.
 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 wait 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.
 void removeAlertListener(AlertListener listener)
          Removes an alert listener from this application.
 void removeGlobalEventListener(GlobalEventListener listener)
          Removes a global event listener from this application.
 void removeHolsterListener(HolsterListener listener)
          Removes a holster event listener from this application.
 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 removePeripheralListener(PeripheralListener listener)
          Removes a peripheral listener from this application.
 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)
          Removes a trackwheel event listener from this application.
 void requestBackground()
          Requests to have this application sent to the background.
 void requestForeground()
          Requests to have this application brought to the foreground.
 void setAcceptEvents(boolean on)
          Determines if this application accepts system events.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail
Constructor Detail

Application

protected Application()
Constructs a new Application instance.
Method Detail

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

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 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 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)
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()
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:
JDE 4.0.0

addKeyListener

public void addKeyListener(KeyListener listener)
Adds a key event listener to this application.
Parameters:
listener - Key event listener to register for this application.

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.

addTrackwheelListener

public void addTrackwheelListener(TrackwheelListener listener)
Adds a trackwheel event listener to this application.
Parameters:
listener - Trackwheel event listener to register for this application.

removeTrackwheelListener

public void removeTrackwheelListener(TrackwheelListener listener)
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.

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.

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)
Adds a holster event listener to this application.
Parameters:
listener - Holster event listener to register for this application.

removeHolsterListener

public void removeHolsterListener(HolsterListener listener)
Removes a holster event listener from this application.
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.
Since:
JDE 3.6.0

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:
JDE 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.

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.

addGlobalEventListener

public void addGlobalEventListener(GlobalEventListener listener)
Adds a global event listener to this application.
Parameters:
listener - Global event listener to register for this application.

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)
Adds a peripheral listener to this application.
Parameters:
listener - Peripheral event listener to register for this application.
Since:
JDE 3.6.0

removePeripheralListener

public void removePeripheralListener(PeripheralListener listener)
Removes a peripheral listener from this application.
Parameters:
listener - Peripheral event listener to de-register for this application.
Since:
JDE 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.
Since:
JDE 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:
JDE 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.


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 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:
JDE 4.0.0

isEventDispatchThread

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

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

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

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

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

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

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.

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.

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 invokeLater(Runnable,long,boolean).

invokeAndWait

public final void invokeAndWait(Runnable runnable)
Puts runnable object into this application's event queue, and wait 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.

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

getProcessId

public final int getProcessId()
Retrieves the process ID for this application.
Returns:
Process identifier for this application.


Copyright 1999-2004 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.