FileDocCategorySizeDatePackage
Handler.javaAPI DocAndroid 1.5 API22819Wed May 06 22:41:56 BST 2009android.os

Handler

public class Handler extends Object
A Handler allows you to send and process {@link Message} and Runnable objects associated with a thread's {@link 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 {@link #post}, {@link #postAtTime(Runnable, long)}, {@link #postDelayed}, {@link #sendEmptyMessage}, {@link #sendMessage}, {@link #sendMessageAtTime}, and {@link #sendMessageDelayed} 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 {@link Message} object containing a bundle of data that will be processed by the Handler's {@link #handleMessage} 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 than be scheduled in the Handler's message queue and processed when appropriate.

Fields Summary
private static final boolean
FIND_POTENTIAL_LEAKS
private static final String
TAG
final MessageQueue
mQueue
final Looper
mLooper
final Callback
mCallback
IMessenger
mMessenger
Constructors Summary
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.

        if (FIND_POTENTIAL_LEAKS) {
            final Class<? extends Handler> klass = getClass();
            if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
                    (klass.getModifiers() & Modifier.STATIC) == 0) {
                Log.w(TAG, "The following Handler class should be static or leaks might occur: " +
                    klass.getCanonicalName());
            }
        }

        mLooper = Looper.myLooper();
        if (mLooper == null) {
            throw new RuntimeException(
                "Can't create handler inside thread that has not called Looper.prepare()");
        }
        mQueue = mLooper.mQueue;
        mCallback = null;
public 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.

        if (FIND_POTENTIAL_LEAKS) {
            final Class<? extends Handler> klass = getClass();
            if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
                    (klass.getModifiers() & Modifier.STATIC) == 0) {
                Log.w(TAG, "The following Handler class should be static or leaks might occur: " +
                    klass.getCanonicalName());
            }
        }

        mLooper = Looper.myLooper();
        if (mLooper == null) {
            throw new RuntimeException(
                "Can't create handler inside thread that has not called Looper.prepare()");
        }
        mQueue = mLooper.mQueue;
        mCallback = callback;
public Handler(Looper looper)
Use the provided queue instead of the default one.

        mLooper = looper;
        mQueue = looper.mQueue;
        mCallback = null;
public Handler(Looper looper, Callback callback)
Use the provided queue instead of the default one and take a callback interface in which to handle messages.

        mLooper = looper;
        mQueue = looper.mQueue;
        mCallback = callback;
Methods Summary
public voiddispatchMessage(Message msg)
Handle system messages here.

        if (msg.callback != null) {
            handleCallback(msg);
        } else {
            if (mCallback != null) {
                if (mCallback.handleMessage(msg)) {
                    return;
                }
            }
            handleMessage(msg);
        }
public final voiddump(android.util.Printer pw, java.lang.String prefix)

        pw.println(prefix + this + " @ " + SystemClock.uptimeMillis());
        if (mLooper == null) {
            pw.println(prefix + "looper uninitialized");
        } else {
            mLooper.dump(pw, prefix + "  ");
        }
final IMessengergetIMessenger()

        synchronized (mQueue) {
            if (mMessenger != null) {
                return mMessenger;
            }
            mMessenger = new MessengerImpl();
            return mMessenger;
        }
public final LoopergetLooper()

        return mLooper;
private final MessagegetPostMessage(java.lang.Runnable r)

        Message m = Message.obtain();
        m.callback = r;
        return m;
private final MessagegetPostMessage(java.lang.Runnable r, java.lang.Object token)

        Message m = Message.obtain();
        m.obj = token;
        m.callback = r;
        return m;
private final voidhandleCallback(Message message)

        message.callback.run();
public voidhandleMessage(Message msg)
Subclasses must implement this to receive messages.
public final booleanhasMessages(int what)
Check if there are any pending posts of messages with code 'what' in the message queue.

        return mQueue.removeMessages(this, what, null, false);
public final booleanhasMessages(int what, java.lang.Object object)
Check if there are any pending posts of messages with code 'what' and whose obj is 'object' in the message queue.

        return mQueue.removeMessages(this, what, object, false);
public final MessageobtainMessage(int what, int arg1, int arg2)
Same as {@link #obtainMessage()}, except that it also sets the what, arg1 and arg2 members of the returned Message.

param
what Value to assign to the returned Message.what field.
param
arg1 Value to assign to the returned Message.arg1 field.
param
arg2 Value to assign to the returned Message.arg2 field.
return
A Message from the global message pool.

        return Message.obtain(this, what, arg1, arg2);
public final MessageobtainMessage(int what, int arg1, int arg2, java.lang.Object obj)
Same as {@link #obtainMessage()}, except that it also sets the what, obj, arg1,and arg2 values on the returned Message.

param
what Value to assign to the returned Message.what field.
param
arg1 Value to assign to the returned Message.arg1 field.
param
arg2 Value to assign to the returned Message.arg2 field.
param
obj Value to assign to the returned Message.obj field.
return
A Message from the global message pool.

        return Message.obtain(this, what, arg1, arg2, obj);
public final MessageobtainMessage()
Returns a new {@link android.os.Message 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.

        return Message.obtain(this);
public final MessageobtainMessage(int what)
Same as {@link #obtainMessage()}, except that it also sets the what member of the returned Message.

param
what Value to assign to the returned Message.what field.
return
A Message from the global message pool.

        return Message.obtain(this, what);
public final MessageobtainMessage(int what, java.lang.Object obj)
Same as {@link #obtainMessage()}, except that it also sets the what and obj members of the returned Message.

param
what Value to assign to the returned Message.what field.
param
obj Value to assign to the returned Message.obj field.
return
A Message from the global message pool.

        return Message.obtain(this, what, obj);
public final booleanpost(java.lang.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.

param
r The Runnable that will be executed.
return
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.

       return  sendMessageDelayed(getPostMessage(r), 0);
public final booleanpostAtFrontOfQueue(java.lang.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.

param
r The Runnable that will be executed.
return
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.

        return sendMessageAtFrontOfQueue(getPostMessage(r));
public final booleanpostAtTime(java.lang.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 {@link android.os.SystemClock#uptimeMillis}. The runnable will be run on the thread to which this handler is attached.

param
r The Runnable that will be executed.
param
uptimeMillis The absolute time at which the callback should run, using the {@link android.os.SystemClock#uptimeMillis} time-base.
return
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.

        return sendMessageAtTime(getPostMessage(r), uptimeMillis);
public final booleanpostAtTime(java.lang.Runnable r, java.lang.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 {@link android.os.SystemClock#uptimeMillis}. The runnable will be run on the thread to which this handler is attached.

param
r The Runnable that will be executed.
param
uptimeMillis The absolute time at which the callback should run, using the {@link android.os.SystemClock#uptimeMillis} time-base.
return
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
android.os.SystemClock#uptimeMillis

        return sendMessageAtTime(getPostMessage(r, token), uptimeMillis);
public final booleanpostDelayed(java.lang.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.

param
r The Runnable that will be executed.
param
delayMillis The delay (in milliseconds) until the Runnable will be executed.
return
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.

        return sendMessageDelayed(getPostMessage(r), delayMillis);
public final voidremoveCallbacks(java.lang.Runnable r)
Remove any pending posts of Runnable r that are in the message queue.

        mQueue.removeMessages(this, r, null);
public final voidremoveCallbacks(java.lang.Runnable r, java.lang.Object token)
Remove any pending posts of Runnable r with Object token that are in the message queue.

        mQueue.removeMessages(this, r, token);
public final voidremoveCallbacksAndMessages(java.lang.Object token)
Remove any pending posts of callbacks and sent messages whose obj is token.

        mQueue.removeCallbacksAndMessages(this, token);
public final voidremoveMessages(int what)
Remove any pending posts of messages with code 'what' that are in the message queue.

        mQueue.removeMessages(this, what, null, true);
public final voidremoveMessages(int what, java.lang.Object object)
Remove any pending posts of messages with code 'what' and whose obj is 'object' that are in the message queue.

        mQueue.removeMessages(this, what, object, true);
public final booleansendEmptyMessage(int what)
Sends a Message containing only the what value.

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

        return sendEmptyMessageDelayed(what, 0);
public final booleansendEmptyMessageAtTime(int what, long uptimeMillis)
Sends a Message containing only the what value, to be delivered at a specific time.

see
#sendMessageAtTime(android.os.Message, long)
return
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.

        Message msg = Message.obtain();
        msg.what = what;
        return sendMessageAtTime(msg, uptimeMillis);
public final booleansendEmptyMessageDelayed(int what, long delayMillis)
Sends a Message containing only the what value, to be delivered after the specified amount of time elapses.

see
#sendMessageDelayed(android.os.Message, long)
return
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.

        Message msg = Message.obtain();
        msg.what = what;
        return sendMessageDelayed(msg, delayMillis);
public final booleansendMessage(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 {@link #handleMessage}, in the thread attached to this handler.

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

        return sendMessageDelayed(msg, 0);
public final booleansendMessageAtFrontOfQueue(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 {@link #handleMessage}, 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.

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

        boolean sent = false;
        MessageQueue queue = mQueue;
        if (queue != null) {
            msg.target = this;
            sent = queue.enqueueMessage(msg, 0);
        }
        else {
            RuntimeException e = new RuntimeException(
                this + " sendMessageAtTime() called with no mQueue");
            Log.w("Looper", e.getMessage(), e);
        }
        return sent;
public booleansendMessageAtTime(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 {@link android.os.SystemClock#uptimeMillis}. You will receive it in {@link #handleMessage}, in the thread attached to this handler.

param
uptimeMillis The absolute time at which the message should be delivered, using the {@link android.os.SystemClock#uptimeMillis} time-base.
return
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.

        boolean sent = false;
        MessageQueue queue = mQueue;
        if (queue != null) {
            msg.target = this;
            sent = queue.enqueueMessage(msg, uptimeMillis);
        }
        else {
            RuntimeException e = new RuntimeException(
                this + " sendMessageAtTime() called with no mQueue");
            Log.w("Looper", e.getMessage(), e);
        }
        return sent;
public final booleansendMessageDelayed(Message msg, long delayMillis)
Enqueue a message into the message queue after all pending messages before (current time + delayMillis). You will receive it in {@link #handleMessage}, in the thread attached to this handler.

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

        if (delayMillis < 0) {
            delayMillis = 0;
        }
        return sendMessageAtTime(msg, SystemClock.uptimeMillis() + delayMillis);
public java.lang.StringtoString()

        return "Handler{"
        + Integer.toHexString(System.identityHashCode(this))
        + "}";