Find Usages Diff Raw Download HTML Widget
Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions 
1
  /*
2
   * Copyright (C) 2006 The Android Open Source Project
3
   *
4
   * Licensed under the Apache License, Version 2.0 (the "License");
5
   * you may not use this file except in compliance with the License.
6
   * You may obtain a copy of the License at
7
   *
8
   *      http://www.apache.org/licenses/LICENSE-2.0
9
   *
10
  * Unless required by applicable law or agreed to in writing, software
11
  * distributed under the License is distributed on an "AS IS" BASIS,
12
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
  * See the License for the specific language governing permissions and
14
  * limitations under the License.
15
  */
16
 
17
 package android.os;
18
 
21
 
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(java.lang.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 than be scheduled in the Handler's message queue and processed when appropriate. 

63
 
64
 public class Handler {
65
     /*
66
      * Set this flag to true to detect anonymous, local or member classes
67
      * that extend this Handler class and that are not static. These kind
68
      * of classes can potentially create leaks.
69
      */
70
     private static final boolean FIND_POTENTIAL_LEAKS = false;
71
     private static final String TAG = "Handler";

    
Callback interface you can use when instantiating a Handler to avoid having to implement your own subclass of Handler. 
76
 
77
     public interface Callback {
78
         public boolean handleMessage(Message msg);
79
     }
    
    
Subclasses must implement this to receive messages. 
83
 
84
     public void handleMessage(Message msg) {
85
     }
    
    
Handle system messages here. 
89
 
90
     public void dispatchMessage(Message msg) {
91
         if (msg.callback != null) {
92
             handleCallback(msg);
93
         } else {
94
             if ( != null) {
95
                 if (.handleMessage(msg)) {
96
                     return;
97
                 }
98
             }
99
             handleMessage(msg);
100
        }
101
    }

    
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. 
109
    public Handler() {
110
        if () {
111
            final Class<? extends Handler> klass = getClass();
112
            if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
113
                    (klass.getModifiers() & .) == 0) {
114
                Log.w(, "The following Handler class should be static or leaks might occur: " +
115
                    klass.getCanonicalName());
116
            }
117
        }
119
         = Looper.myLooper();
120
        if ( == null) {
121
            throw new RuntimeException(
122
                "Can't create handler inside thread that has not called Looper.prepare()");
123
        }
124
         = .;
125
         = null;
126
    }

    
Constructor associates this handler with the queue for the current thread and takes a callback interface in which you can handle messages. 
133
    public Handler(Callback callback) {
134
        if () {
135
            final Class<? extends Handler> klass = getClass();
136
            if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
137
                    (klass.getModifiers() & .) == 0) {
138
                Log.w(, "The following Handler class should be static or leaks might occur: " +
139
                    klass.getCanonicalName());
140
            }
141
        }
143
         = Looper.myLooper();
144
        if ( == null) {
145
            throw new RuntimeException(
146
                "Can't create handler inside thread that has not called Looper.prepare()");
147
        }
148
         = .;
149
         = callback;
150
    }

    
Use the provided queue instead of the default one. 
155
    public Handler(Looper looper) {
156
         = looper;
157
         = looper.mQueue;
158
         = null;
159
    }

    
Use the provided queue instead of the default one and take a callback interface in which to handle messages. 
165
    public Handler(Looper looper, Callback callback) {
166
         = looper;
167
         = looper.mQueue;
168
         = callback;
169
    }

    
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. 
176
    public final Message obtainMessage()
177
    {
178
        return Message.obtain(this);
179
    }

    
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.
187
    public final Message obtainMessage(int what)
188
    {
189
        return Message.obtain(this, what);
190
    }
    
    
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.
201
    public final Message obtainMessage(int what, Object obj)
202
    {
203
        return Message.obtain(this, what, obj);
204
    }

    
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.
215
    public final Message obtainMessage(int what, int arg1, int arg2)
216
    {
217
        return Message.obtain(this, what, arg1, arg2);
218
    }
    
    
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.
230
    public final Message obtainMessage(int what, int arg1, int arg2, Object obj)
231
    {
232
        return Message.obtain(this, what, arg1, arg2, obj);
233
    }

    
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.
246
    public final boolean post(Runnable r)
247
    {
248
       return  sendMessageDelayed(getPostMessage(r), 0);
249
    }
    
    
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(). 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.
268
    public final boolean postAtTime(Runnable r, long uptimeMillis)
269
    {
270
        return sendMessageAtTime(getPostMessage(r), uptimeMillis);
271
    }
    
    
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(). 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()
292
    public final boolean postAtTime(Runnable r, Object token, long uptimeMillis)
293
    {
294
        return sendMessageAtTime(getPostMessage(r, token), uptimeMillis);
295
    }
    
    
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.
314
    public final boolean postDelayed(Runnable r, long delayMillis)
315
    {
316
        return sendMessageDelayed(getPostMessage(r), delayMillis);
317
    }
    
    
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.
334
    public final boolean postAtFrontOfQueue(Runnable r)
335
    {
336
        return sendMessageAtFrontOfQueue(getPostMessage(r));
337
    }

    
Remove any pending posts of Runnable r that are in the message queue. 
342
    public final void removeCallbacks(Runnable r)
343
    {
344
        .removeMessages(this, r, null);
345
    }

    
Remove any pending posts of Runnable r with Object token that are in the message queue. 
351
    public final void removeCallbacks(Runnable r, Object token)
352
    {
353
        .removeMessages(this, r, token);
354
    }

    
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.
365
    public final boolean sendMessage(Message msg)
366
    {
367
        return sendMessageDelayed(msg, 0);
368
    }

    
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.
377
    public final boolean sendEmptyMessage(int what)
378
    {
379
        return sendEmptyMessageDelayed(what, 0);
380
    }

    
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)
391
    public final boolean sendEmptyMessageDelayed(int what, long delayMillis) {
392
        Message msg = Message.obtain();
393
        msg.what = what;
394
        return sendMessageDelayed(msg, delayMillis);
395
    }

    
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)
407
    public final boolean sendEmptyMessageAtTime(int what, long uptimeMillis) {
408
        Message msg = Message.obtain();
409
        msg.what = what;
410
        return sendMessageAtTime(msg, uptimeMillis);
411
    }

    
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.
425
    public final boolean sendMessageDelayed(Message msg, long delayMillis)
426
    {
427
        if (delayMillis < 0) {
428
            delayMillis = 0;
429
        }
430
        return sendMessageAtTime(msg, SystemClock.uptimeMillis() + delayMillis);
431
    }

    
Enqueue a message into the message queue after all pending messages before the absolute time (in milliseconds) uptimeMillis. The time-base is SystemClock.uptimeMillis(). 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.
451
    public boolean sendMessageAtTime(Message msg, long uptimeMillis)
452
    {
453
        boolean sent = false;
454
        MessageQueue queue = ;
455
        if (queue != null) {
456
            msg.target = this;
457
            sent = queue.enqueueMessage(msg, uptimeMillis);
458
        }
459
        else {
460
            RuntimeException e = new RuntimeException(
461
                this + " sendMessageAtTime() called with no mQueue");
462
            Log.w("Looper", e.getMessage(), e);
463
        }
464
        return sent;
465
    }

    
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.
479
    public final boolean sendMessageAtFrontOfQueue(Message msg)
480
    {
481
        boolean sent = false;
482
        MessageQueue queue = ;
483
        if (queue != null) {
484
            msg.target = this;
485
            sent = queue.enqueueMessage(msg, 0);
486
        }
487
        else {
488
            RuntimeException e = new RuntimeException(
489
                this + " sendMessageAtTime() called with no mQueue");
490
            Log.w("Looper", e.getMessage(), e);
491
        }
492
        return sent;
493
    }

    
Remove any pending posts of messages with code 'what' that are in the message queue. 
499
    public final void removeMessages(int what) {
500
        .removeMessages(this, what, null, true);
501
    }

    
Remove any pending posts of messages with code 'what' and whose obj is 'object' that are in the message queue. 
507
    public final void removeMessages(int what, Object object) {
508
        .removeMessages(this, what, object, true);
509
    }

    
Remove any pending posts of callbacks and sent messages whose obj is token. 
515
    public final void removeCallbacksAndMessages(Object token) {
516
        .removeCallbacksAndMessages(this, token);
517
    }

    
Check if there are any pending posts of messages with code 'what' in the message queue. 
523
    public final boolean hasMessages(int what) {
524
        return .removeMessages(this, what, null, false);
525
    }

    
Check if there are any pending posts of messages with code 'what' and whose obj is 'object' in the message queue. 
531
    public final boolean hasMessages(int what, Object object) {
532
        return .removeMessages(this, what, object, false);
533
    }
535
    // if we can get rid of this method, the handler need not remember its loop
536
    // we could instead export a getMessageQueue() method... 
537
    public final Looper getLooper() {
538
        return ;
539
    }
541
    public final void dump(Printer pw, String prefix) {
542
        pw.println(prefix + this + " @ " + SystemClock.uptimeMillis());
543
        if ( == null) {
544
            pw.println(prefix + "looper uninitialized");
545
        } else {
546
            .dump(pw, prefix + "  ");
547
        }
548
    }
550
    @Override
551
    public String toString() {
552
        return "Handler{"
553
        + Integer.toHexString(System.identityHashCode(this))
554
        + "}";
555
    }
557
    final IMessenger getIMessenger() {
558
        synchronized () {
559
            if ( != null) {
560
                return ;
561
            }
562
             = new MessengerImpl();
563
            return ;
564
        }
565
    }
566
    
567
    private final class MessengerImpl extends IMessenger.Stub {
568
        public void send(Message msg) {
569
            Handler.this.sendMessage(msg);
570
        }
571
    }
572
    
573
    private final Message getPostMessage(Runnable r) {
574
        Message m = Message.obtain();
575
        m.callback = r;
576
        return m;
577
    }
579
    private final Message getPostMessage(Runnable r, Object token) {
580
        Message m = Message.obtain();
581
        m.obj = token;
582
        m.callback = r;
583
        return m;
584
    }
586
    private final void handleCallback(Message message) {
587
        message.callback.run();
588
    }
590
    final MessageQueue mQueue;
591
    final Looper mLooper;
592
    final Callback mCallback;
New to GrepCode? Check out our FAQ X