public class Handler extends Object
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(java.lang.Runnable)
, postAtTime(Runnable, long)
,
postDelayed(java.lang.Runnable, long)
, sendEmptyMessage(int)
,
sendMessage(android.os.Message)
, sendMessageAtTime(android.os.Message, long)
, and
sendMessageDelayed(android.os.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(android.os.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.
Modifier and Type | Class and Description |
---|---|
static interface |
Handler.Callback
Callback interface you can use when instantiating a Handler to avoid
having to implement your own subclass of Handler.
|
Constructor and Description |
---|
Handler()
Default constructor associates this handler with the
Looper for the
current thread. |
Handler(boolean async)
Use the
Looper for the current thread
and set whether the handler should be asynchronous. |
Handler(Handler.Callback callback)
Constructor associates this handler with the
Looper for the
current thread and takes a callback interface in which you can handle
messages. |
Handler(Handler.Callback callback,
boolean async)
Use the
Looper for the current thread with the specified callback interface
and set whether the handler should be asynchronous. |
Handler(Looper looper)
Use the provided
Looper instead of the default one. |
Handler(Looper looper,
Handler.Callback callback)
Use the provided
Looper instead of the default one and take a callback
interface in which to handle messages. |
Handler(Looper looper,
Handler.Callback callback,
boolean async)
Use the provided
Looper instead of the default one and take a callback
interface in which to handle messages. |
Modifier and Type | Method and Description |
---|---|
void |
dispatchMessage(Message msg)
Handle system messages here.
|
void |
dump(Printer pw,
String prefix) |
Looper |
getLooper() |
String |
getMessageName(Message message)
Returns a string representing the name of the specified message.
|
void |
handleMessage(Message msg)
Subclasses must implement this to receive messages.
|
boolean |
hasCallbacks(Runnable r)
Check if there are any pending posts of messages with callback r in
the message queue.
|
boolean |
hasMessages(int what)
Check if there are any pending posts of messages with code 'what' in
the message queue.
|
boolean |
hasMessages(int what,
Object object)
Check if there are any pending posts of messages with code 'what' and
whose obj is 'object' in the message queue.
|
Message |
obtainMessage()
Returns a new
Message from the global message pool. |
Message |
obtainMessage(int what)
Same as
obtainMessage() , except that it also sets the what member of the returned Message. |
Message |
obtainMessage(int what,
int arg1,
int arg2)
Same as
obtainMessage() , except that it also sets the what, arg1 and arg2 members of the returned
Message. |
Message |
obtainMessage(int what,
int arg1,
int arg2,
Object obj)
Same as
obtainMessage() , except that it also sets the what, obj, arg1,and arg2 values on the
returned Message. |
Message |
obtainMessage(int what,
Object obj)
Same as
obtainMessage() , except that it also sets the what and obj members
of the returned Message. |
boolean |
post(Runnable r)
Causes the Runnable r to be added to the message queue.
|
boolean |
postAtFrontOfQueue(Runnable r)
Posts a message to an object that implements Runnable.
|
boolean |
postAtTime(Runnable r,
long uptimeMillis)
Causes the Runnable r to be added to the message queue, to be run
at a specific time given by uptimeMillis.
|
boolean |
postAtTime(Runnable r,
Object token,
long uptimeMillis)
Causes the Runnable r to be added to the message queue, to be run
at a specific time given by uptimeMillis.
|
boolean |
postDelayed(Runnable r,
long delayMillis)
Causes the Runnable r to be added to the message queue, to be run
after the specified amount of time elapses.
|
void |
removeCallbacks(Runnable r)
Remove any pending posts of Runnable r that are in the message queue.
|
void |
removeCallbacks(Runnable r,
Object token)
Remove any pending posts of Runnable r with Object
token that are in the message queue.
|
void |
removeCallbacksAndMessages(Object token)
Remove any pending posts of callbacks and sent messages whose
obj is token.
|
void |
removeMessages(int what)
Remove any pending posts of messages with code 'what' that are in the
message queue.
|
void |
removeMessages(int what,
Object object)
Remove any pending posts of messages with code 'what' and whose obj is
'object' that are in the message queue.
|
boolean |
runWithScissors(Runnable r,
long timeout)
Runs the specified task synchronously.
|
boolean |
sendEmptyMessage(int what)
Sends a Message containing only the what value.
|
boolean |
sendEmptyMessageAtTime(int what,
long uptimeMillis)
Sends a Message containing only the what value, to be delivered
at a specific time.
|
boolean |
sendEmptyMessageDelayed(int what,
long delayMillis)
Sends a Message containing only the what value, to be delivered
after the specified amount of time elapses.
|
boolean |
sendMessage(Message msg)
Pushes a message onto the end of the message queue after all pending messages
before the current time.
|
boolean |
sendMessageAtFrontOfQueue(Message msg)
Enqueue a message at the front of the message queue, to be processed on
the next iteration of the message loop.
|
boolean |
sendMessageAtTime(Message msg,
long uptimeMillis)
Enqueue a message into the message queue after all pending messages
before the absolute time (in milliseconds) uptimeMillis.
|
boolean |
sendMessageDelayed(Message msg,
long delayMillis)
Enqueue a message into the message queue after all pending messages
before (current time + delayMillis).
|
String |
toString()
Returns a string containing a concise, human-readable description of this
object.
|
public Handler()
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.public Handler(Handler.Callback callback)
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.public Handler(Looper looper)
Looper
instead of the default one.looper
- The looper, must not be null.public Handler(Looper looper, Handler.Callback callback)
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.public Handler(boolean async)
Looper
for the current thread
and set whether the handler should be asynchronous.
Handlers are synchronous by default unless this constructor is used to make
one that is strictly asynchronous.
Asynchronous messages represent interrupts or events that do not require global ordering
with represent to synchronous messages. Asynchronous messages are not subject to
the synchronization barriers introduced by MessageQueue.enqueueSyncBarrier(long)
.async
- If true, the handler calls Message.setAsynchronous(boolean)
for
each Message
that is sent to it or Runnable
that is posted to it.public Handler(Handler.Callback callback, boolean async)
Looper
for the current thread with the specified callback interface
and set whether the handler should be asynchronous.
Handlers are synchronous by default unless this constructor is used to make
one that is strictly asynchronous.
Asynchronous messages represent interrupts or events that do not require global ordering
with represent to synchronous messages. Asynchronous messages are not subject to
the synchronization barriers introduced by MessageQueue.enqueueSyncBarrier(long)
.callback
- The callback interface in which to handle messages, or null.async
- If true, the handler calls Message.setAsynchronous(boolean)
for
each Message
that is sent to it or Runnable
that is posted to it.public Handler(Looper looper, Handler.Callback callback, boolean async)
Looper
instead of the default one and take a callback
interface in which to handle messages. Also set whether the handler
should be asynchronous.
Handlers are synchronous by default unless this constructor is used to make
one that is strictly asynchronous.
Asynchronous messages represent interrupts or events that do not require global ordering
with represent to synchronous messages. Asynchronous messages are not subject to
the synchronization barriers introduced by MessageQueue.enqueueSyncBarrier(long)
.looper
- The looper, must not be null.callback
- The callback interface in which to handle messages, or null.async
- If true, the handler calls Message.setAsynchronous(boolean)
for
each Message
that is sent to it or Runnable
that is posted to it.public void handleMessage(Message msg)
public void dispatchMessage(Message msg)
public String getMessageName(Message message)
message
- The message whose name is being queriedpublic final Message obtainMessage()
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.public final Message obtainMessage(int what)
obtainMessage()
, except that it also sets the what member of the returned Message.what
- Value to assign to the returned Message.what field.public final Message obtainMessage(int what, Object obj)
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.public final Message obtainMessage(int what, int arg1, int arg2)
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.public final Message obtainMessage(int what, int arg1, int arg2, Object obj)
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.public final boolean post(Runnable r)
r
- The Runnable that will be executed.public final boolean postAtTime(Runnable r, long uptimeMillis)
SystemClock.uptimeMillis()
.
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 SystemClock.uptimeMillis()
time-base.public final boolean postAtTime(Runnable r, Object token, long uptimeMillis)
SystemClock.uptimeMillis()
.
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 SystemClock.uptimeMillis()
time-base.SystemClock.uptimeMillis()
public final boolean postDelayed(Runnable r, long delayMillis)
r
- The Runnable that will be executed.delayMillis
- The delay (in milliseconds) until the Runnable
will be executed.public final boolean postAtFrontOfQueue(Runnable r)
r
- The Runnable that will be executed.public final boolean runWithScissors(Runnable r, long timeout)
false
but the runnable
will remain posted on the handler and may already be in progress or
complete at a later time.r
- The Runnable that will be executed synchronously.timeout
- The timeout in milliseconds, or 0 to wait indefinitely.public final void removeCallbacks(Runnable r)
public final void removeCallbacks(Runnable r, Object token)
public final boolean sendMessage(Message msg)
handleMessage(android.os.Message)
,
in the thread attached to this handler.public final boolean sendEmptyMessage(int what)
public final boolean sendEmptyMessageDelayed(int what, long delayMillis)
sendMessageDelayed(android.os.Message, long)
public final boolean sendEmptyMessageAtTime(int what, long uptimeMillis)
sendMessageAtTime(android.os.Message, long)
public final boolean sendMessageDelayed(Message msg, long delayMillis)
handleMessage(android.os.Message)
, in the thread attached to this handler.public boolean sendMessageAtTime(Message msg, long uptimeMillis)
SystemClock.uptimeMillis()
.
You will receive it in handleMessage(android.os.Message)
, in the thread attached
to this handler.uptimeMillis
- The absolute time at which the message should be
delivered, using the
SystemClock.uptimeMillis()
time-base.public final boolean sendMessageAtFrontOfQueue(Message msg)
handleMessage(android.os.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.public final void removeMessages(int what)
public final void removeMessages(int what, Object object)
public final void removeCallbacksAndMessages(Object token)
public final boolean hasMessages(int what)
public final boolean hasMessages(int what, Object object)
public final boolean hasCallbacks(Runnable r)
public final Looper getLooper()
public String toString()
Object
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.