Package android.os

Class Handler

  • public class Handler
extends Object
    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(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.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class 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 Summary

      Constructors 
      Constructor 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.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.

    • Constructor Detail

      • Handler

        public Handler()
        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.

      • Handler

        public 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. 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.

      • Handler

        public Handler​(Looper looper)
        Use the provided Looper instead of the default one.
        Parameters:
        looper - The looper, must not be null.

      • Handler

        public 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.
        Parameters:
        looper - The looper, must not be null.
        callback - The callback interface in which to handle messages, or null.

      • Handler

        public Handler​(boolean async)
        Use the 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 respect to synchronous messages. Asynchronous messages are not subject to the synchronization barriers introduced by MessageQueue#enqueueSyncBarrier(long).
        Parameters:
        async - If true, the handler calls Message.setAsynchronous(boolean) for each Message that is sent to it or Runnable that is posted to it.

      • Handler

        public 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. 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 respect to synchronous messages. Asynchronous messages are not subject to the synchronization barriers introduced by MessageQueue#enqueueSyncBarrier(long).
        Parameters:
        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.

      • Handler

        public 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. 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 respect to synchronous messages. Asynchronous messages are not subject to the synchronization barriers introduced by MessageQueue#enqueueSyncBarrier(long).
        Parameters:
        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.

    • Method Detail

      • handleMessage

        public void handleMessage​(Message msg)
        Subclasses must implement this to receive messages.

      • dispatchMessage

        public void dispatchMessage​(Message msg)
        Handle system messages here.

      • getMessageName

        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

      • obtainMessage

        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.

      • obtainMessage

        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.

      • obtainMessage

        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.

      • obtainMessage

        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.

      • obtainMessage

        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.

      • post

        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.

      • postAtTime

        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 SystemClock.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.
        Parameters:
        r - The Runnable that will be executed.
        uptimeMillis - The absolute time at which the callback should run, using the SystemClock.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.

      • postAtTime

        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 SystemClock.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.
        Parameters:
        r - The Runnable that will be executed.
        uptimeMillis - The absolute time at which the callback should run, using the SystemClock.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:
        SystemClock.uptimeMillis()

      • postDelayed

        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. The time-base is SystemClock.uptimeMillis(). Time spent in deep sleep will add an additional delay to execution.
        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.

      • postAtFrontOfQueue

        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.

      • runWithScissors

        public final boolean runWithScissors​(Runnable r,
                                     long timeout)
        Runs the specified task synchronously.

        If the current thread is the same as the handler thread, then the runnable runs immediately without being enqueued. Otherwise, posts the runnable to the handler and waits for it to complete before returning.

        This method is dangerous! Improper use can result in deadlocks. Never call this method while any locks are held or use it in a possibly re-entrant manner.

        This method is occasionally useful in situations where a background thread must synchronously await completion of a task that must run on the handler's thread. However, this problem is often a symptom of bad design. Consider improving the design (if possible) before resorting to this method.

        One example of where you might want to use this method is when you just set up a Handler thread and need to perform some initialization steps on it before continuing execution.

        If timeout occurs then this method returns false but the runnable will remain posted on the handler and may already be in progress or complete at a later time.

        When using this method, be sure to use Looper.quitSafely() when quitting the looper. Otherwise runWithScissors(java.lang.Runnable, long) may hang indefinitely. (TODO: We should fix this by making MessageQueue aware of blocking runnables.)

        Parameters:
        r - The Runnable that will be executed synchronously.
        timeout - The timeout in milliseconds, or 0 to wait indefinitely.
        Returns:
        Returns true if the Runnable was successfully executed. Returns false on failure, usually because the looper processing the message queue is exiting.

      • removeCallbacks

        public final void removeCallbacks​(Runnable r)
        Remove any pending posts of Runnable r that are in the message queue.

      • removeCallbacks

        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.

      • sendMessage

        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(android.os.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.

      • sendEmptyMessage

        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.

      • sendEmptyMessageDelayed

        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.
        See Also:
        sendMessageDelayed(android.os.Message, long)

      • sendEmptyMessageAtTime

        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.
        See Also:
        sendMessageAtTime(android.os.Message, long)

      • sendMessageDelayed

        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(android.os.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.

      • sendMessageAtTime

        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 SystemClock.uptimeMillis(). Time spent in deep sleep will add an additional delay to execution. You will receive it in handleMessage(android.os.Message), in the thread attached to this handler.
        Parameters:
        uptimeMillis - The absolute time at which the message should be delivered, using the SystemClock.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.

      • sendMessageAtFrontOfQueue

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

      • removeMessages

        public final void removeMessages​(int what)
        Remove any pending posts of messages with code 'what' that are in the message queue.

      • removeMessages

        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 object is null, all messages will be removed.

      • removeCallbacksAndMessages

        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.

      • hasMessages

        public final boolean hasMessages​(int what)
        Check if there are any pending posts of messages with code 'what' in the message queue.

      • hasMessages

        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.

      • hasCallbacks

        public final boolean hasCallbacks​(Runnable r)
        Check if there are any pending posts of messages with callback r in the message queue.

      • getLooper

        public final Looper getLooper()

      • toString

        public String toString()
        Description copied from class: Object
        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.

        Overrides:
        toString in class Object
        Returns:
        a printable representation of this object.