java.lang.Object | |
↳ | android.os.Handler |
Known Direct Subclasses |
A Handler allows you to send and process Message
and Runnable
objects associated with a thread's MessageQueue
. Each Handler
instance is associated with a single thread and that thread's message
queue. When you create a new Handler, it is bound to the thread /
message queue of the thread that is creating it -- from that point on,
it will deliver messages and runnables to that message queue and execute
them as they come out of the message queue.
There are two main uses for a Handler: (1) to schedule messages and runnables to be executed as some point in the future; and (2) to enqueue an action to be performed on a different thread than your own.
Scheduling messages is accomplished with the
post(Runnable)
, postAtTime(Runnable, long)
,
postDelayed(Runnable, long)
, sendEmptyMessage(int)
,
sendMessage(Message)
, sendMessageAtTime(Message, long)
, and
sendMessageDelayed(Message, long)
methods. The post versions allow
you to enqueue Runnable objects to be called by the message queue when
they are received; the sendMessage versions allow you to enqueue
a Message
object containing a bundle of data that will be
processed by the Handler's handleMessage(Message)
method (requiring that
you implement a subclass of Handler).
When posting or sending to a Handler, you can either allow the item to be processed as soon as the message queue is ready to do so, or specify a delay before it gets processed or absolute time for it to be processed. The latter two allow you to implement timeouts, ticks, and other timing-based behavior.
When a process is created for your application, its main thread is dedicated to running a message queue that takes care of managing the top-level application objects (activities, broadcast receivers, etc) and any windows they create. You can create your own threads, and communicate back with the main application thread through a Handler. This is done by calling the same post or sendMessage methods as before, but from your new thread. The given Runnable or Message will then be scheduled in the Handler's message queue and processed when appropriate.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Handler.Callback | Callback interface you can use when instantiating a Handler to avoid having to implement your own subclass of Handler. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Default constructor associates this handler with the
Looper for the
current thread. | |||||||||||
Constructor associates this handler with the
Looper for the
current thread and takes a callback interface in which you can handle
messages. | |||||||||||
Use the provided
Looper instead of the default one. | |||||||||||
Use the provided
Looper instead of the default one and take a callback
interface in which to handle messages. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Handle system messages here.
| |||||||||||
Returns a string representing the name of the specified message.
| |||||||||||
Subclasses must implement this to receive messages.
| |||||||||||
Check if there are any pending posts of messages with code 'what' and
whose obj is 'object' in the message queue.
| |||||||||||
Check if there are any pending posts of messages with code 'what' in
the message queue.
| |||||||||||
Same as
obtainMessage() , except that it also sets the what, arg1 and arg2 members of the returned
Message. | |||||||||||
Returns a new
Message from the global message pool. | |||||||||||
Same as
obtainMessage() , except that it also sets the what, obj, arg1,and arg2 values on the
returned Message. | |||||||||||
Same as
obtainMessage() , except that it also sets the what member of the returned Message. | |||||||||||
Same as
obtainMessage() , except that it also sets the what and obj members
of the returned Message. | |||||||||||
Causes the Runnable r to be added to the message queue.
| |||||||||||
Posts a message to an object that implements Runnable.
| |||||||||||
Causes the Runnable r to be added to the message queue, to be run
at a specific time given by uptimeMillis.
| |||||||||||
Causes the Runnable r to be added to the message queue, to be run
at a specific time given by uptimeMillis.
| |||||||||||
Causes the Runnable r to be added to the message queue, to be run
after the specified amount of time elapses.
| |||||||||||
Remove any pending posts of Runnable r that are in the message queue.
| |||||||||||
Remove any pending posts of Runnable r with Object
token that are in the message queue.
| |||||||||||
Remove any pending posts of callbacks and sent messages whose
obj is token.
| |||||||||||
Remove any pending posts of messages with code 'what' that are in the
message queue.
| |||||||||||
Remove any pending posts of messages with code 'what' and whose obj is
'object' that are in the message queue.
| |||||||||||
Sends a Message containing only the what value.
| |||||||||||
Sends a Message containing only the what value, to be delivered
at a specific time.
| |||||||||||
Sends a Message containing only the what value, to be delivered
after the specified amount of time elapses.
| |||||||||||
Pushes a message onto the end of the message queue after all pending messages
before the current time.
| |||||||||||
Enqueue a message at the front of the message queue, to be processed on
the next iteration of the message loop.
| |||||||||||
Enqueue a message into the message queue after all pending messages
before the absolute time (in milliseconds) uptimeMillis.
| |||||||||||
Enqueue a message into the message queue after all pending messages
before (current time + delayMillis).
| |||||||||||
Returns a string containing a concise, human-readable description of this
object.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Default constructor associates this handler with the Looper
for the
current thread.
If this thread does not have a looper, this handler won't be able to receive messages
so an exception is thrown.
Constructor associates this handler with the Looper
for the
current thread and takes a callback interface in which you can handle
messages.
If this thread does not have a looper, this handler won't be able to receive messages
so an exception is thrown.
callback | The callback interface in which to handle messages, or null. |
---|
Use the provided Looper
instead of the default one.
looper | The looper, must not be null. |
---|
Use the provided Looper
instead of the default one and take a callback
interface in which to handle messages.
looper | The looper, must not be null. |
---|---|
callback | The callback interface in which to handle messages, or null. |
Returns a string representing the name of the specified message. The default implementation will either return the class name of the message callback if any, or the hexadecimal representation of the message "what" field.
message | The message whose name is being queried |
---|
Subclasses must implement this to receive messages.
Check if there are any pending posts of messages with code 'what' and whose obj is 'object' in the message queue.
Check if there are any pending posts of messages with code 'what' in the message queue.
Same as obtainMessage()
, except that it also sets the what, arg1 and arg2 members of the returned
Message.
what | Value to assign to the returned Message.what field. |
---|---|
arg1 | Value to assign to the returned Message.arg1 field. |
arg2 | Value to assign to the returned Message.arg2 field. |
Returns a new Message
from the global message pool. More efficient than
creating and allocating new instances. The retrieved message has its handler set to this instance (Message.target == this).
If you don't want that facility, just call Message.obtain() instead.
Same as obtainMessage()
, except that it also sets the what, obj, arg1,and arg2 values on the
returned Message.
what | Value to assign to the returned Message.what field. |
---|---|
arg1 | Value to assign to the returned Message.arg1 field. |
arg2 | Value to assign to the returned Message.arg2 field. |
obj | Value to assign to the returned Message.obj field. |
Same as obtainMessage()
, except that it also sets the what member of the returned Message.
what | Value to assign to the returned Message.what field. |
---|
Same as obtainMessage()
, except that it also sets the what and obj members
of the returned Message.
what | Value to assign to the returned Message.what field. |
---|---|
obj | Value to assign to the returned Message.obj field. |
Causes the Runnable r to be added to the message queue. The runnable will be run on the thread to which this handler is attached.
r | The Runnable that will be executed. |
---|
Posts a message to an object that implements Runnable. Causes the Runnable r to executed on the next iteration through the message queue. The runnable will be run on the thread to which this handler is attached. This method is only for use in very special circumstances -- it can easily starve the message queue, cause ordering problems, or have other unexpected side-effects.
r | The Runnable that will be executed. |
---|
Causes the Runnable r to be added to the message queue, to be run
at a specific time given by uptimeMillis.
The time-base is uptimeMillis()
.
Time spent in deep sleep will add an additional delay to execution.
The runnable will be run on the thread to which this handler is attached.
r | The Runnable that will be executed. |
---|---|
uptimeMillis | The absolute time at which the callback should run,
using the uptimeMillis() time-base. |
Causes the Runnable r to be added to the message queue, to be run
at a specific time given by uptimeMillis.
The time-base is uptimeMillis()
.
Time spent in deep sleep will add an additional delay to execution.
The runnable will be run on the thread to which this handler is attached.
r | The Runnable that will be executed. |
---|---|
uptimeMillis | The absolute time at which the callback should run,
using the uptimeMillis() time-base. |
Causes the Runnable r to be added to the message queue, to be run
after the specified amount of time elapses.
The runnable will be run on the thread to which this handler
is attached.
The time-base is uptimeMillis()
.
Time spent in deep sleep will add an additional delay to execution.
r | The Runnable that will be executed. |
---|---|
delayMillis | The delay (in milliseconds) until the Runnable will be executed. |
Remove any pending posts of Runnable r that are in the message queue.
Remove any pending posts of Runnable r with Object token that are in the message queue. If token is null, all callbacks will be removed.
Remove any pending posts of callbacks and sent messages whose obj is token. If token is null, all callbacks and messages will be removed.
Remove any pending posts of messages with code 'what' that are in the message queue.
Remove any pending posts of messages with code 'what' and whose obj is 'object' that are in the message queue. If object is null, all messages will be removed.
Sends a Message containing only the what value.
Sends a Message containing only the what value, to be delivered at a specific time.
Sends a Message containing only the what value, to be delivered after the specified amount of time elapses.
Pushes a message onto the end of the message queue after all pending messages
before the current time. It will be received in handleMessage(Message)
,
in the thread attached to this handler.
Enqueue a message at the front of the message queue, to be processed on
the next iteration of the message loop. You will receive it in
handleMessage(Message)
, in the thread attached to this handler.
This method is only for use in very special circumstances -- it
can easily starve the message queue, cause ordering problems, or have
other unexpected side-effects.
Enqueue a message into the message queue after all pending messages
before the absolute time (in milliseconds) uptimeMillis.
The time-base is uptimeMillis()
.
Time spent in deep sleep will add an additional delay to execution.
You will receive it in handleMessage(Message)
, in the thread attached
to this handler.
uptimeMillis | The absolute time at which the message should be
delivered, using the
uptimeMillis() time-base. |
---|
Enqueue a message into the message queue after all pending messages
before (current time + delayMillis). You will receive it in
handleMessage(Message)
, in the thread attached to this handler.
Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.