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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

addTrackwheelListener

public void addTrackwheelListener(TrackwheelListener listener)

Adds a trackwheel event listener to this application.

Parameters:

listener - Trackwheel event listener to register for this application.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

addSystemListener

public void addSystemListener(SystemListener listener)

Adds a system event listener to this application.

Parameters:

listener - System event listener to register for this application.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

addHolsterListener

public void addHolsterListener(HolsterListener listener)

Adds a holster event listener to this application.

Parameters:

listener - Holster event listener to register for this application.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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 4.0.2

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 4.0.2

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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

addGlobalEventListener

public void addGlobalEventListener(GlobalEventListener listener)

Adds a global event listener to this application.

Parameters:

listener - Global event listener to register for this application.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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 4.0.2

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 4.0.2

addAlertListener

public void addAlertListener(AlertListener listener)

Adds an alert listener to this application.

Parameters:

listener - Alert listener to register for this application.

Since:

JDE 4.0.2

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 4.0.2

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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

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

Since:

JDE 4.0.2

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.

Since:

JDE 4.0.2

getProcessId

public final int getProcessId()

Retrieves the process ID for this application.

Returns:

Process identifier for this application.