java.lang.Object
↳
android.os.Handler
![]()
Known
Direct Subclasses
| java.lang.Object | |
| ↳ | android.os.Handler |
 Known
Direct Subclasses
|
Class Overview
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.
Handler允許你在一個線程的MessageQueue中處理massage和Runnable對象。每一個Handler實例和一個線程和線程隊列相關聯。創建一個新的Handler時，它關聯到創建它的線程和消息隊列。Handler發送消息和可執行對象給消息隊列，並從隊列中取出執行。
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.
Handler有2個主要的用途：(1)安排消息和runnables在將來執行；(2)使在不同線程中執行的操作排隊
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).
post***的方法，排隊Runnable對象；sendMessage***方法，排隊Message對象（Message由Handler的handleMessage()方法處理）。
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.
當post或sendMessage給Hanlder，你可以允許立即被處理或指定一個延時或指定具體時間。
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 sendMessagemethods 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.
當你的應用進程創建時，主線程是一個專用的線程，用於管理頂級的應用對象(activities,broadcast receiver等)和任何創建的新窗口。你可以創建你自己的線程，通過Handler和主應用的線程通訊。可以通過在你的新線程中調用post或sendMessage方法來實現。
Summary
| 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 queue for the current thread.
|
||||||||||
|
|
Constructor associates this handler with the queue for the current thread and takes a callback interface in which you can handle messages.
|
||||||||||
|
|
Use the provided queue instead of the default one.
|
||||||||||
|
|
Use the provided queue 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
|
|||||||||||
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 (Handler.Callback callback)
Constructor associates this handler with the queue for the current thread and takes a callback interface in which you can handle messages.
public Handler (Looper looper)
Use the provided queue instead of the default one.
public Handler (Looper looper, Handler.Callback callback)
Use the provided queue instead of the default one and take a callback interface in which to handle messages.
Public Methods
public String getMessageName (Message message)
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.
Parameters
| message | The message whose name is being queried |
|---|
public void handleMessage (Message msg)
Subclasses must implement this to receive messages.
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 boolean hasMessages (int what)
Check if there are any pending posts of messages with code 'what' in the message queue.
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, 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)
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 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 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.
See Also
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)
Remove any pending posts of Runnable r that are in the message queue.
public final void removeCallbacks (Runnable r, Object token)
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.
public final void removeCallbacksAndMessages (Object token)
Remove any pending posts of callbacks and sent messages whose obj is token. If token is null, all callbacks and messages will be removed.
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. If token is null, all messages will be removed.
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 inhandleMessage(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 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.
Returns
- a printable representation of this object.