Added in API level 1

Handler

---

Kotlin |Java

open class Handler

kotlin.Any
↳	android.os.Handler

Known Direct Subclasses AsyncQueryHandler, AsyncQueryHandler.WorkerHandler, HttpAuthHandler, SslErrorHandler AsyncQueryHandler A helper class to help make handling asynchronous ContentResolver queries easier. AsyncQueryHandler.WorkerHandler HttpAuthHandler Represents a request for HTTP authentication. SslErrorHandler Represents a request for handling an SSL error.

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 a Looper. It will deliver messages and runnables to that Looper's message queue and execute them on that Looper's thread.

There are two main uses for a Handler: (1) to schedule messages and runnables to be executed at 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, postAtTime(java.lang.Runnable,long), #postDelayed, sendEmptyMessage, sendMessage, sendMessageAtTime, and 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 Message object containing a bundle of data that will be processed by the Handler's 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 then be scheduled in the Handler's message queue and processed when appropriate.

Summary

Nested classes
abstract	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(callback: Handler.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, callback: Handler.Callback?) Use the provided Looper instead of the default one and take a callback interface in which to handle messages.

Public methods
open static Handler	createAsync(looper: Looper) Create a new Handler whose posted messages and runnables are not subject to synchronization barriers such as display vsync.
open static Handler	createAsync(looper: Looper, callback: Handler.Callback) Create a new Handler whose posted messages and runnables are not subject to synchronization barriers such as display vsync.
open Unit	dispatchMessage(msg: Message) Handle system messages here.
Unit	dump(pw: Printer, prefix: String)
Looper	getLooper()
open String	getMessageName(message: Message) Returns a string representing the name of the specified message.
open Unit	handleMessage(msg: Message) Subclasses must implement this to receive messages.
Boolean	hasCallbacks(r: Runnable) Check if there are any pending posts of messages with callback r in the message queue.
Boolean	hasMessages(what: Int) Check if there are any pending posts of messages with code 'what' in the message queue.
Boolean	hasMessages(what: Int, object: Any?) 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(what: Int) Same as obtainMessage(), except that it also sets the what member of the returned Message.
Message	obtainMessage(what: Int, arg1: Int, arg2: Int) Same as obtainMessage(), except that it also sets the what, arg1 and arg2 members of the returned Message.
Message	obtainMessage(what: Int, arg1: Int, arg2: Int, obj: Any?) Same as obtainMessage(), except that it also sets the what, obj, arg1,and arg2 values on the returned Message.
Message	obtainMessage(what: Int, obj: Any?) Same as obtainMessage(), except that it also sets the what and obj members of the returned Message.
Boolean	post(r: Runnable) Causes the Runnable r to be added to the message queue.
Boolean	postAtFrontOfQueue(r: Runnable) Posts a message to an object that implements Runnable.
Boolean	postAtTime(r: Runnable, token: Any?, uptimeMillis: Long) Causes the Runnable r to be added to the message queue, to be run at a specific time given by uptimeMillis.
Boolean	postAtTime(r: Runnable, uptimeMillis: Long) Causes the Runnable r to be added to the message queue, to be run at a specific time given by uptimeMillis.
Boolean	postDelayed(r: Runnable, token: Any?, delayMillis: Long) Causes the Runnable r to be added to the message queue, to be run after the specified amount of time elapses.
Boolean	postDelayed(r: Runnable, delayMillis: Long) Causes the Runnable r to be added to the message queue, to be run after the specified amount of time elapses.
Unit	removeCallbacks(r: Runnable) Remove any pending posts of Runnable r that are in the message queue.
Unit	removeCallbacks(r: Runnable, token: Any?) Remove any pending posts of Runnable r with Object token that are in the message queue.
Unit	removeCallbacksAndMessages(token: Any?) Remove any pending posts of callbacks and sent messages whose obj is token.
Unit	removeMessages(what: Int) Remove any pending posts of messages with code 'what' that are in the message queue.
Unit	removeMessages(what: Int, object: Any?) Remove any pending posts of messages with code 'what' and whose obj is 'object' that are in the message queue.
Boolean	sendEmptyMessage(what: Int) Sends a Message containing only the what value.
Boolean	sendEmptyMessageAtTime(what: Int, uptimeMillis: Long) Sends a Message containing only the what value, to be delivered at a specific time.
Boolean	sendEmptyMessageDelayed(what: Int, delayMillis: Long) Sends a Message containing only the what value, to be delivered after the specified amount of time elapses.
Boolean	sendMessage(msg: Message) Pushes a message onto the end of the message queue after all pending messages before the current time.
Boolean	sendMessageAtFrontOfQueue(msg: Message) Enqueue a message at the front of the message queue, to be processed on the next iteration of the message loop.
open Boolean	sendMessageAtTime(msg: Message, uptimeMillis: Long) Enqueue a message into the message queue after all pending messages before the absolute time (in milliseconds) uptimeMillis.
Boolean	sendMessageDelayed(msg: Message, delayMillis: Long) Enqueue a message into the message queue after all pending messages before (current time + delayMillis).
open String	toString()

Public constructors

Handler

Added in API level 1

Handler()

Deprecated: Implicitly choosing a Looper during Handler construction can lead to bugs where operations are silently lost (if the Handler is not expecting new tasks and quits), crashes (if a handler is sometimes created on a thread without a Looper active), or race conditions, where the thread a handler is associated with is not what the author anticipated. Instead, use an java.util.concurrent.Executor or specify the Looper explicitly, using Looper.getMainLooper, android.view.View#getHandler, or similar. If the implicit thread local behavior is required for compatibility, use new Handler(Looper.myLooper()) to make it clear to readers.

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

Added in API level 3

Handler(callback: Handler.Callback?)

Deprecated: Implicitly choosing a Looper during Handler construction can lead to bugs where operations are silently lost (if the Handler is not expecting new tasks and quits), crashes (if a handler is sometimes created on a thread without a Looper active), or race conditions, where the thread a handler is associated with is not what the author anticipated. Instead, use an java.util.concurrent.Executor or specify the Looper explicitly, using Looper.getMainLooper, android.view.View#getHandler, or similar. If the implicit thread local behavior is required for compatibility, use new Handler(Looper.myLooper(), callback) to make it clear to readers.

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	Handler.Callback?: The callback interface in which to handle messages, or null.

Handler

Added in API level 1

Handler(looper: Looper)

Use the provided Looper instead of the default one.

Parameters
looper	Looper: The looper, must not be null.

Handler

Added in API level 3

Handler(
    looper: Looper, 
    callback: Handler.Callback?)

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

Parameters
looper	Looper: The looper, must not be null.
callback	Handler.Callback?: The callback interface in which to handle messages, or null.

Public methods

createAsync

Added in API level 28

open static fun createAsync(looper: Looper): Handler

Create a new Handler whose posted messages and runnables are not subject to synchronization barriers such as display vsync.

Messages sent to an async handler are guaranteed to be ordered with respect to one another, but not necessarily with respect to messages from other Handlers.

Parameters
looper	Looper: the Looper that the new Handler should be bound to This value cannot be null.

Return
Handler	a new async Handler instance This value cannot be null.

See Also

• #createAsync(Looper, Callback)

createAsync

Added in API level 28

open static fun createAsync(
    looper: Looper, 
    callback: Handler.Callback
): Handler

Create a new Handler whose posted messages and runnables are not subject to synchronization barriers such as display vsync.

Messages sent to an async handler are guaranteed to be ordered with respect to one another, but not necessarily with respect to messages from other Handlers.

Parameters
looper	Looper: the Looper that the new Handler should be bound to This value cannot be null.
callback	Handler.Callback: This value cannot be null.

Return
Handler	a new async Handler instance This value cannot be null.

See Also

• #createAsync(Looper)

dispatchMessage

Added in API level 1

open fun dispatchMessage(msg: Message): Unit

Handle system messages here.

Parameters
msg	Message: This value cannot be null.

dump

Added in API level 1

fun dump(
    pw: Printer, 
    prefix: String
): Unit

Parameters
pw	Printer: This value cannot be null.
prefix	String: This value cannot be null.

getLooper

Added in API level 1

fun getLooper(): Looper

Return
Looper	This value cannot be null.

getMessageName

Added in API level 14

open fun getMessageName(message: Message): String

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	Message: The message whose name is being queried This value cannot be null.

Return
String	This value cannot be null.

handleMessage

Added in API level 1

open fun handleMessage(msg: Message): Unit

Subclasses must implement this to receive messages.

Parameters
msg	Message: This value cannot be null.

hasCallbacks

Added in API level 29

fun hasCallbacks(r: Runnable): Boolean

Check if there are any pending posts of messages with callback r in the message queue.

Parameters
r	Runnable: This value cannot be null.

hasMessages

Added in API level 1

fun hasMessages(what: Int): Boolean

Check if there are any pending posts of messages with code 'what' in the message queue.

hasMessages

Added in API level 1

fun hasMessages(
    what: Int, 
    object: Any?
): Boolean

Check if there are any pending posts of messages with code 'what' and whose obj is 'object' in the message queue.

Parameters
object	Any?: This value may be null.

obtainMessage

Added in API level 1

fun obtainMessage(): Message

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.

Return
Message	This value cannot be null.

obtainMessage

Added in API level 1

fun obtainMessage(what: Int): Message

Same as obtainMessage(), except that it also sets the what member of the returned Message.

Parameters
what	Int: Value to assign to the returned Message.what field.

Return
Message	A Message from the global message pool. This value cannot be null.

obtainMessage

Added in API level 1

fun obtainMessage(
    what: Int, 
    arg1: Int, 
    arg2: Int
): Message

Same as obtainMessage(), except that it also sets the what, arg1 and arg2 members of the returned Message.

Parameters
what	Int: Value to assign to the returned Message.what field.
arg1	Int: Value to assign to the returned Message.arg1 field.
arg2	Int: Value to assign to the returned Message.arg2 field.

Return
Message	A Message from the global message pool. This value cannot be null.

obtainMessage

Added in API level 1

fun obtainMessage(
    what: Int, 
    arg1: Int, 
    arg2: Int, 
    obj: Any?
): Message

Same as obtainMessage(), except that it also sets the what, obj, arg1,and arg2 values on the returned Message.

Parameters
what	Int: Value to assign to the returned Message.what field.
arg1	Int: Value to assign to the returned Message.arg1 field.
arg2	Int: Value to assign to the returned Message.arg2 field.
obj	Any?: Value to assign to the returned Message.obj field. This value may be null.

Return
Message	A Message from the global message pool. This value cannot be null.

obtainMessage

Added in API level 1

fun obtainMessage(
    what: Int, 
    obj: Any?
): Message

Same as obtainMessage(), except that it also sets the what and obj members of the returned Message.

Parameters
what	Int: Value to assign to the returned Message.what field.
obj	Any?: Value to assign to the returned Message.obj field. This value may be null.

Return
Message	A Message from the global message pool. This value cannot be null.

post

Added in API level 1

fun post(r: Runnable): Boolean

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	Runnable: The Runnable that will be executed. This value cannot be null.

Return
Boolean	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.

postAtFrontOfQueue

Added in API level 1

fun postAtFrontOfQueue(r: Runnable): Boolean

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	Runnable: The Runnable that will be executed. This value cannot be null.

Return
Boolean	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.

postAtTime

Added in API level 1

fun postAtTime(
    r: Runnable, 
    token: Any?, 
    uptimeMillis: Long
): Boolean

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 android.os.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	Runnable: The Runnable that will be executed. This value cannot be null.
token	Any?: An instance which can be used to cancel r via removeCallbacksAndMessages. This value may be null.
uptimeMillis	Long: The absolute time at which the callback should run, using the android.os.SystemClock#uptimeMillis time-base.

Return
Boolean	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

• android.os.SystemClock#uptimeMillis

postAtTime

Added in API level 1

fun postAtTime(
    r: Runnable, 
    uptimeMillis: Long
): Boolean

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 android.os.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	Runnable: The Runnable that will be executed. This value cannot be null.
uptimeMillis	Long: The absolute time at which the callback should run, using the android.os.SystemClock#uptimeMillis time-base.

Return
Boolean	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.

postDelayed

Added in API level 28

fun postDelayed(
    r: Runnable, 
    token: Any?, 
    delayMillis: Long
): Boolean

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 android.os.SystemClock#uptimeMillis. Time spent in deep sleep will add an additional delay to execution.

Parameters
r	Runnable: The Runnable that will be executed. This value cannot be null.
token	Any?: An instance which can be used to cancel r via removeCallbacksAndMessages. This value may be null.
delayMillis	Long: The delay (in milliseconds) until the Runnable will be executed.

Return
Boolean	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.

postDelayed

Added in API level 1

fun postDelayed(
    r: Runnable, 
    delayMillis: Long
): Boolean

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 android.os.SystemClock#uptimeMillis. Time spent in deep sleep will add an additional delay to execution.

Parameters
r	Runnable: The Runnable that will be executed. This value cannot be null.
delayMillis	Long: The delay (in milliseconds) until the Runnable will be executed.

Return
Boolean	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.

removeCallbacks

Added in API level 1

fun removeCallbacks(r: Runnable): Unit

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

Parameters
r	Runnable: This value cannot be null.

removeCallbacks

Added in API level 1

fun removeCallbacks(
    r: Runnable, 
    token: Any?
): Unit

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.

Parameters
r	Runnable: This value cannot be null.
token	Any?: This value may be null.

removeCallbacksAndMessages

Added in API level 1

fun removeCallbacksAndMessages(token: Any?): Unit

Remove any pending posts of callbacks and sent messages whose obj is token. If token is null, all callbacks and messages will be removed.

Parameters
token	Any?: This value may be null.

removeMessages

Added in API level 1

fun removeMessages(what: Int): Unit

Remove any pending posts of messages with code 'what' that are in the message queue. Note that `Message#what` is 0 unless otherwise set. When calling `postMessage(Runnable)` or `postAtTime(Runnable, long)`, the `Runnable` is internally wrapped with a `Message` whose `what` is 0. Calling `removeMessages(0)` will remove all messages without a `what`, including posted `Runnable`s.

removeMessages

Added in API level 1

fun removeMessages(
    what: Int, 
    object: Any?
): Unit

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.

Parameters
object	Any?: This value may be null.

sendEmptyMessage

Added in API level 1

fun sendEmptyMessage(what: Int): Boolean

Sends a Message containing only the what value.

Return
Boolean	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.

sendEmptyMessageAtTime

Added in API level 1

fun sendEmptyMessageAtTime(
    what: Int, 
    uptimeMillis: Long
): Boolean

Sends a Message containing only the what value, to be delivered at a specific time.

Return
Boolean	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)

sendEmptyMessageDelayed

Added in API level 1

fun sendEmptyMessageDelayed(
    what: Int, 
    delayMillis: Long
): Boolean

Sends a Message containing only the what value, to be delivered after the specified amount of time elapses.

Return
Boolean	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)

sendMessage

Added in API level 1

fun sendMessage(msg: Message): Boolean

Pushes a message onto the end of the message queue after all pending messages before the current time. It will be received in handleMessage, in the thread attached to this handler.

Parameters
msg	Message: This value cannot be null.

Return
Boolean	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.

sendMessageAtFrontOfQueue

Added in API level 1

fun sendMessageAtFrontOfQueue(msg: Message): Boolean

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

Parameters
msg	Message: This value cannot be null.

Return
Boolean	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.

sendMessageAtTime

Added in API level 1

open fun sendMessageAtTime(
    msg: Message, 
    uptimeMillis: Long
): Boolean

Enqueue a message into the message queue after all pending messages before the absolute time (in milliseconds) uptimeMillis. The time-base is android.os.SystemClock#uptimeMillis. Time spent in deep sleep will add an additional delay to execution. You will receive it in handleMessage, in the thread attached to this handler.

Parameters
uptimeMillis	Long: The absolute time at which the message should be delivered, using the android.os.SystemClock#uptimeMillis time-base.
msg	Message: This value cannot be null.

Return
Boolean	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.

sendMessageDelayed

Added in API level 1

fun sendMessageDelayed(
    msg: Message, 
    delayMillis: Long
): Boolean

Enqueue a message into the message queue after all pending messages before (current time + delayMillis). You will receive it in handleMessage, in the thread attached to this handler.

Parameters
msg	Message: This value cannot be null.

Return
Boolean	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.

toString

Added in API level 1

open fun toString(): String

Return
String	a string representation of the object.