android.os.Handler
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, intent 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 than be scheduled
in the Handler's message queue and processed when appropriate.
Known Direct Subclasses
Known Indirect Subclasses
Summary
Public Constructors
Public Methods
|
|
|
|
|
void |
dispatchMessage(Message msg) |
|
|
final |
|
|
void |
dump(Printer pw, String prefix) |
|
|
final |
|
|
Looper |
getLooper() |
|
|
|
|
|
void |
handleMessage(Message msg) |
|
|
final |
|
|
boolean |
hasMessages(int what) |
|
|
final |
|
|
boolean |
hasMessages(int what, Object object) |
|
|
final |
|
|
Message |
obtainMessage(int what, Object obj) |
|
|
final |
|
|
Message |
obtainMessage(int what, int arg1, int arg2, Object obj) |
|
|
final |
|
|
Message |
obtainMessage(int what, int arg1, int arg2) |
|
|
final |
|
|
Message |
obtainMessage() |
|
|
final |
|
|
Message |
obtainMessage(int what) |
|
|
final |
|
|
boolean |
post(Runnable r) |
|
|
final |
|
|
boolean |
postAtFrontOfQueue(Runnable r) |
|
|
final |
|
|
boolean |
postAtTime(Runnable r, Object token, long uptimeMillis) |
|
|
final |
|
|
boolean |
postAtTime(Runnable r, long uptimeMillis) |
|
|
final |
|
|
boolean |
postDelayed(Runnable r, long delayMillis) |
|
|
final |
|
|
void |
removeCallbacks(Runnable r, Object token) |
|
|
final |
|
|
void |
removeCallbacks(Runnable r) |
|
|
final |
|
|
void |
removeCallbacksAndMessages(Object token) |
|
|
final |
|
|
void |
removeMessages(int what) |
|
|
final |
|
|
void |
removeMessages(int what, Object object) |
|
|
final |
|
|
boolean |
sendEmptyMessage(int what) |
|
|
final |
|
|
boolean |
sendEmptyMessageAtTime(int what, long uptimeMillis) |
|
|
final |
|
|
boolean |
sendEmptyMessageDelayed(int what, long delayMillis) |
|
|
final |
|
|
boolean |
sendMessage(Message msg) |
|
|
final |
|
|
boolean |
sendMessageAtFrontOfQueue(Message msg) |
|
|
|
|
|
boolean |
sendMessageAtTime(Message msg, long uptimeMillis) |
|
|
final |
|
|
boolean |
sendMessageDelayed(Message msg, long delayMillis) |
|
|
|
|
|
String |
toString() |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Public Constructors
public
Handler()
Default constructor associates this handler with the queue for the
current thread.
If there isn't one, this handler won't be able to receive messages.
public
Handler(Looper looper)
Use the provided queue instead of the default one.
Public Methods
public
void
dispatchMessage(Message msg)
Handle system messages here.
public
final
Looper
getLooper()
public
void
handleMessage(Message msg)
Subclasses must implement this to receive messages.
public
final
boolean
hasMessages(int what)
Check if there are any pending posts of messages with code 'what' in
the message queue.
public
final
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.
public
final
Message
obtainMessage(int what, Object obj)
Same as
obtainMessage(), except that it also sets the what and obj members
of the returned Message.
Parameters
what
| Value to assign to the returned Message.what field. |
obj
| Value to assign to the returned Message.obj field. |
Returns
- A Message from the global message pool.
public
final
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.
Parameters
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. |
Returns
- A Message from the global message pool.
public
final
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.
Parameters
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 Message from the global message pool.
public
final
Message
obtainMessage()
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.
public
final
Message
obtainMessage(int what)
Same as
obtainMessage(), except that it also sets the what member of the returned Message.
Parameters
what
| Value to assign to the returned Message.what field. |
Returns
- A Message from the global message pool.
public
final
boolean
post(Runnable r)
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.
Parameters
r
| The Runnable that will be executed. |
Returns
- Returns true if the Runnable was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
final
boolean
postAtFrontOfQueue(Runnable r)
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.
Parameters
r
| The Runnable that will be executed. |
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
final
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.
The time-base is uptimeMillis().
The runnable will be run on the thread to which this handler is attached.
Parameters
r
| The Runnable that will be executed. |
uptimeMillis
| The absolute time at which the callback should run,
using the uptimeMillis() time-base. |
Returns
- Returns true if the Runnable was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting. Note that a
result of true does not mean the Runnable will be processed -- if
the looper is quit before the delivery time of the message
occurs then the message will be dropped.
public
final
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.
The time-base is uptimeMillis().
The runnable will be run on the thread to which this handler is attached.
Parameters
r
| The Runnable that will be executed. |
uptimeMillis
| The absolute time at which the callback should run,
using the uptimeMillis() time-base. |
Returns
- Returns true if the Runnable was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting. Note that a
result of true does not mean the Runnable will be processed -- if
the looper is quit before the delivery time of the message
occurs then the message will be dropped.
public
final
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.
The runnable will be run on the thread to which this handler
is attached.
Parameters
r
| The Runnable that will be executed. |
delayMillis
| The delay (in milliseconds) until the Runnable
will be executed. |
Returns
- Returns true if the Runnable was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting. Note that a
result of true does not mean the Runnable will be processed --
if the looper is quit before the delivery time of the message
occurs then the message will be dropped.
public
final
void
removeCallbacks(Runnable r, Object token)
Remove any pending posts of Runnable r with Object
token that are in the message queue.
public
final
void
removeCallbacks(Runnable r)
Remove any pending posts of Runnable r that are in the message queue.
public
final
void
removeCallbacksAndMessages(Object token)
Remove any pending posts of callbacks and sent messages whose
obj is token.
public
final
void
removeMessages(int what)
Remove any pending posts of messages with code 'what' that are in the
message queue.
public
final
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.
public
final
boolean
sendEmptyMessage(int what)
Sends a Message containing only the what value.
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
final
boolean
sendEmptyMessageAtTime(int what, long uptimeMillis)
Sends a Message containing only the what value, to be delivered
at a specific time.
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
final
boolean
sendEmptyMessageDelayed(int what, long delayMillis)
Sends a Message containing only the what value, to be delivered
after the specified amount of time elapses.
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
final
boolean
sendMessage(Message msg)
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.
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
final
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. 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.
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting.
public
boolean
sendMessageAtTime(Message msg, long uptimeMillis)
Enqueue a message into the message queue after all pending messages
before the absolute time (in milliseconds)
uptimeMillis.
The time-base is uptimeMillis().
You will receive it in
handleMessage(Message), in the thread attached
to this handler.
Parameters
uptimeMillis
| The absolute time at which the message should be
delivered, using the
uptimeMillis() time-base. |
Returns
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting. Note that a
result of true does not mean the message will be processed -- if
the looper is quit before the delivery time of the message
occurs then the message will be dropped.
public
final
boolean
sendMessageDelayed(Message msg, long delayMillis)
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
- Returns true if the message was successfully placed in to the
message queue. Returns false on failure, usually because the
looper processing the message queue is exiting. Note that a
result of true does not mean the message will be processed -- if
the looper is quit before the delivery time of the message
occurs then the message will be dropped.
public
String
toString()
Returns a string containing a concise, human-readable description of the
receiver.
Returns
- String a printable representation for the receiver.