Andriod API之Handler

public class

Handler

扩展了  Object

java.lang.Object
↳	android.os.Handler

直接子类 AsyncQueryHandler,  AsyncQueryHandler.WorkerHandler,  HttpAuthHandler,  SslErrorHandler

Class Overview

Handler允许你通过一个线程的消息队列来发送、处理消息和可运行的对象。每个Handler实例与一个线程和线程的消息队列关联。当创建一个新的Handler，它属于创建它的那个线程，从此刻起，它将会传递消息并传送到消息队列，并当消息出列时执行他们。

Handler的两个主要用途：1.在当前线程存入消息；2.在其他线程出列处理消息

存储消息用post(Runnable), postAtTime(Runnable, long), postDelayed(Runnable, long), sendEmptyMessage(int),sendMessage(Message), sendMessageAtTime(Message, long), and sendMessageDelayed(Message, long)方法。

post版本允许你入队消息，当他们被接收到时被消息队列调用；sendMsg版本允许出列消息包含被handleMessage(Message)处理的数据（这将要求你实现Handler的子类）。

当post或send消息给Handler，你可以允许出列就被处理，或者当处理的时候有一个延迟。

当一个app创建一个进程，它的主线程运行一个处理管理高层应用对象（activities, broadcast receivers等）的消息队列。你可以创建自己的线程，通过Handler与主线程进行交互。

Summary

---

Nested Classes
interface	Handler.Callback	Callback interface you can use when instantiating a Handler to avoid having to implement your own subclass of Handler.

Public Constructors
	Handler() Default constructor associates this handler with the  Looper for the current thread.
	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( 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.

Public Methods
void	dispatchMessage( Message msg) Handle system messages here.
final void	dump( Printer pw,  String prefix)
final  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.
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.
final boolean	hasMessages(int what) Check if there are any pending posts of messages with code 'what' in the message queue.
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.
final  Message	obtainMessage() Returns a new  Message from the global message pool.
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.
final  Message	obtainMessage(int what) Same as  obtainMessage(), except that it also sets the what member of the returned Message.
final  Message	obtainMessage(int what,  Object obj) Same as  obtainMessage(), except that it also sets the what and obj members of the returned Message.
final boolean	post( Runnable r) Causes the Runnable r to be added to the message queue.
final boolean	postAtFrontOfQueue( Runnable r) Posts a message to an object that implements Runnable.
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.
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.
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.
final void	removeCallbacks( Runnable r) Remove any pending posts of Runnable r that are in the message queue.
final void	removeCallbacks( Runnable r,  Object token) Remove any pending posts of Runnable  r with Object  token that are in the message queue.
final void	removeCallbacksAndMessages( Object token) Remove any pending posts of callbacks and sent messages whose  obj is  token.
final void	removeMessages(int what) Remove any pending posts of messages with code 'what' that are in the message queue.
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.
final boolean	sendEmptyMessage(int what) Sends a Message containing only the what value.
final boolean	sendEmptyMessageAtTime(int what, long uptimeMillis) Sends a Message containing only the what value, to be delivered at a specific time.
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.
final boolean	sendMessage( Message msg) Pushes a message onto the end of the message queue after all pending messages before the current time.
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.
boolean	sendMessageAtTime( Message msg, long uptimeMillis) Enqueue a message into the message queue after all pending messages before the absolute time (in milliseconds)  uptimeMillis.
final 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.

[Expand] Inherited Methods
From class java.lang.Object

Public Constructors

---

public Handler ()

Added in  API level 1

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.

public Handler (Handler.Callback callback)

Added in  API level 3

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.

Parameters

callback	The callback interface in which to handle messages, or null.

public Handler (Looper looper)

Added in  API level 1

Use the provided Looper instead of the default one.

Parameters

looper	The looper, must not be null.

public Handler (Looper looper, Handler.Callback callback)

Added in  API level 3

Use the provided Looper instead of the default one and take a callback interface in which to handle messages.

Parameters

looper	The looper, must not be null.
callback	The callback interface in which to handle messages, or null.

Public Methods

---

public void dispatchMessage (Message msg)

Added in  API level 1

Handle system messages here.

public final void dump (Printer pw, String prefix)

Added in  API level 1

public final Looper getLooper ()

Added in  API level 1

public String getMessageName (Message message)

Added in  API level 14

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)

Added in  API level 1

Subclasses must implement this to receive messages.

public final boolean hasMessages (int what, Object object)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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 ()

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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

• uptimeMillis()

public final boolean postAtTime (Runnable r, long uptimeMillis)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

Remove any pending posts of Runnable r that are in the message queue.

public final void removeCallbacks (Runnable r, Object token)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

Remove any pending posts of messages with code 'what' that are in the message queue.

public final void removeMessages (int what, Object object)

Added in  API level 1

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.

public final boolean sendEmptyMessage (int what)

Added in  API level 1

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)

Added in  API level 1

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.

See Also

• sendMessageAtTime(android.os.Message, long)

public final boolean sendEmptyMessageDelayed (int what, long delayMillis)

Added in  API level 1

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.

See Also

• sendMessageDelayed(android.os.Message, long)

public final boolean sendMessage (Message msg)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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)

Added in  API level 1

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 ()

Added in  API level 1

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.