|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--net.rim.device.api.system.Application
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.
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 |
Method Detail |
protected boolean acceptsForeground()
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).
UiApplication
public void activate()
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.
public void deactivate()
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.
public final boolean isForeground()
public final void requestBackground()
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.
public final void requestForeground()
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.
public final void enableKeyUpEvents(boolean enable)
KeyListener.keyUp(int, int)
events.
By default, applications do not receive these events for performance reasons.
enable
- If true, this application will receive keyup events from
the system; otherwise, the system will continue to withold them from this
application.public final boolean acceptsKeyUpEvents()
KeyListener.keyUp(int, int)
events.
By default, applications do not receive these events for performance reasons.
public void addKeyListener(KeyListener listener)
listener
- Key event listener to register for this application.public void removeKeyListener(KeyListener listener)
listener
- Key event listener to de-register for this application.public void addTrackwheelListener(TrackwheelListener listener)
listener
- Trackwheel event listener to register for this
application.public void removeTrackwheelListener(TrackwheelListener listener)
listener
- Trackwheel event listener to de-register for this
application.public void addRealtimeClockListener(RealtimeClockListener listener)
listener
- Real-time clock event listener to register for this
application.public void removeRealtimeClockListener(RealtimeClockListener listener)
listener
- Real-time clock event listener to de-register from this
application.public void addSystemListener(SystemListener listener)
listener
- System event listener to register for this application.public void removeSystemListener(SystemListener listener)
listener
- System event listener to de-register for this
application.public void addHolsterListener(HolsterListener listener)
listener
- Holster event listener to register for this application.public void removeHolsterListener(HolsterListener listener)
listener
- Holster event listener to de-register for this
application.public void addRadioListener(RadioListener listener)
listener
- Radio event listener to register for this application.public void removeRadioListener(RadioListener listener)
listener
- Radio event listener to de-register for this application.public void addIOPortListener(IOPortListener listener)
listener
- I/O port event listener to register for this application.public void removeIOPortListener(IOPortListener listener)
listener
- I/O port event listener to de-register for this application.public void addGlobalEventListener(GlobalEventListener listener)
listener
- Global event listener to register for this application.public void removeGlobalEventListener(GlobalEventListener listener)
listener
- Global event listener to de-register for this
application.public void addPeripheralListener(PeripheralListener listener)
listener
- Peripheral event listener to register for this
application.public void removePeripheralListener(PeripheralListener listener)
listener
- Peripheral event listener to de-register for this
application.public void addAlertListener(AlertListener listener)
listener
- Alert listener to register for this application.public void removeAlertListener(AlertListener listener)
listener
- Alert listener to de-register for this application.public void enterEventDispatcher()
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.
public final void setAcceptEvents(boolean on)
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.
on
- True to accept system events; false to tell the system not to
pass them to this application.public boolean isAlive()
public static final boolean isEventDispatchThread()
Note: this method simply invokes isEventThread()
on
the current process's Application object.
public boolean isEventThread()
public boolean hasEventThread()
enterEventDispatcher()
); otherwise, false.public final boolean isHandlingEvents()
public static final Object getEventLock()
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.
IllegalStateException
- If this method is called when there is no
Application object in the process.public final Object getAppEventLock()
getEventLock()
public static final Application getApplication()
IllegalStateException
- If this function is called when there is no
Application object in the process.public final void invokeLater(Runnable runnable)
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.
runnable
- Runnable object to be placed on the dispatch thread's
queue of events to execute.public final int invokeLater(Runnable runnable, long time, boolean repeat)
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.
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.public final void cancelInvokeLater(int id)
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.
id
- Event ID of the runnable returned by
invokeLater(Runnable,long,boolean)
.public final void invokeAndWait(Runnable runnable)
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.
runnable
- Runnable object to be placed on the dispatch thread's
queue of events for synchronous execution.public final int getProcessId()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.