Android Guides | Samples

Android.OS.Handler Class

A Handler allows you to send and process Message and Runnable objects associated with a thread's MessageQueue.

See Also: Handler

Syntax

[Android.Runtime.Register("android/os/Handler", DoNotGenerateAcw=true)]
public class Handler : Object

Remarks

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 Handler.Post(IRunnable), Handler.PostAtTime(IRunnable,Int64), Handler.PostDelayed(IRunnable,Int64), Handler.SendEmptyMessage(Int32), Handler.SendMessage(Message), Handler.SendMessageAtTime(Message,Int64), and Handler.SendMessageDelayed(Message,Int64) 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 Handler.HandleMessage(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.

[Android Documentation]

Requirements

Namespace: Android.OS
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 1

The members of Android.OS.Handler are listed below.

See Also: Object

Public Constructors

Default constructor associates this handler with the Looper for the current thread.
Constructor associates this handler with the Looper for the current thread and takes a callback interface in which you can handle messages.
Use the provided Looper instead of the default one.
Use the provided Looper instead of the default one and take a callback interface in which to handle messages.

Protected Constructors

A constructor used when creating managed representations of JNI objects; called by the runtime.

Public Properties

[read-only]
LooperLooper.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

DispatchMessage(Message)
Handle system messages here.
Dump(IPrinter, String)
DumpAsync(IPrinter, String) : Task
GetMessageName(Message) : String
Returns a string representing the name of the specified message.
HandleMessage(Message)
Subclasses must implement this to receive messages.
HasMessages(Int32) : Boolean
Check if there are any pending posts of messages with code 'what' in the message queue.
HasMessages(Int32, Object) : Boolean
Check if there are any pending posts of messages with code 'what' and whose obj is 'object' in the message queue.
ObtainMessage() : Message
Returns a new Message from the global message pool.
ObtainMessage(Int32) : Message
Same as Handler.ObtainMessage, except that it also sets the what member of the returned Message.
ObtainMessage(Int32, Object) : Message
Same as Handler.ObtainMessage, except that it also sets the what and obj members of the returned Message.
ObtainMessage(Int32, Int32, Int32) : Message
Same as Handler.ObtainMessage, except that it also sets the what, arg1 and arg2 members of the returned Message.
ObtainMessage(Int32, Int32, Int32, Object) : Message
Same as Handler.ObtainMessage, except that it also sets the what, obj, arg1,and arg2 values on the returned Message.
Post(IRunnable) : Boolean
Causes the Runnable r to be added to the message queue.
Post(Action) : Boolean
PostAtFrontOfQueue(IRunnable) : Boolean
Posts a message to an object that implements Runnable.
PostAtFrontOfQueue(Action) : Boolean
PostAtTime(IRunnable, Int64) : Boolean
Causes the Runnable r to be added to the message queue, to be run at a specific time given by uptimeMillis.
PostAtTime(Action, Int64) : Boolean
PostAtTime(IRunnable, Object, Int64) : Boolean
Causes the Runnable r to be added to the message queue, to be run at a specific time given by uptimeMillis.
PostAtTime(Action, Object, Int64) : Boolean
PostDelayed(IRunnable, Int64) : Boolean
Causes the Runnable r to be added to the message queue, to be run after the specified amount of time elapses.
PostDelayed(Action, Int64) : Boolean
RemoveCallbacks(IRunnable)
Remove any pending posts of Runnable r that are in the message queue.
RemoveCallbacks(Action)
RemoveCallbacks(IRunnable, Object)
Remove any pending posts of Runnable r with Object token that are in the message queue.
RemoveCallbacks(Action, Object)
RemoveCallbacksAndMessages(Object)
Remove any pending posts of callbacks and sent messages whose obj is token.
RemoveMessages(Int32)
Remove any pending posts of messages with code 'what' that are in the message queue.
RemoveMessages(Int32, Object)
Remove any pending posts of messages with code 'what' and whose obj is 'object' that are in the message queue.
SendEmptyMessage(Int32) : Boolean
Sends a Message containing only the what value.
SendEmptyMessageAtTime(Int32, Int64) : Boolean
Sends a Message containing only the what value, to be delivered at a specific time.
SendEmptyMessageDelayed(Int32, Int64) : Boolean
Sends a Message containing only the what value, to be delivered after the specified amount of time elapses.
SendMessage(Message) : Boolean
Pushes a message onto the end of the message queue after all pending messages before the current time.
SendMessageAtFrontOfQueue(Message) : Boolean
Enqueue a message at the front of the message queue, to be processed on the next iteration of the message loop.
SendMessageAtTime(Message, Int64) : Boolean
Enqueue a message into the message queue after all pending messages before the absolute time (in milliseconds) uptimeMillis.
SendMessageDelayed(Message, Int64) : Boolean
Enqueue a message into the message queue after all pending messages before (current time + delayMillis).