public final class

Message

extends Object
java.lang.Object
   ↳ mindroid.os.Message

Class Overview

Defines a message containing a description and arbitrary data object that can be sent to a Handler. This object contains two extra int fields and an extra object field that allow you to not do allocations in many cases.

While the constructor of Message is public, the best way to get one of these is to call Message.obtain() or one of the Handler.obtainMessage() methods, which will pull them from a pool of recycled objects.

Summary

Fields
public int arg1 arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.
public int arg2 arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.
public Object obj An arbitrary object to send to the recipient.
public int what User-defined message code so that the recipient can identify what this message is about.
Public Constructors
Message()
Constructor (but the preferred way to get a Message is to call Message.obtain()).
Public Methods
void copyFrom(Message otherMessage)
Make this message like o.
Runnable getCallback()
Retrieve callback object that will execute when this message is handled.
Bundle getData()
Obtains a Bundle of arbitrary data associated with this event, lazily creating it if necessary.
Handler getTarget()
Retrieve the a Handler implementation that will receive this message.
long getWhen()
Return the targeted delivery time of this message, in milliseconds.
static Message obtain(Handler handler, int what, Object obj)
Same as obtain(), but sets the values of the target, what, and obj members.
static Message obtain(Handler handler, int what)
Same as obtain(), but sets the values for both target and what members on the Message.
static Message obtain(Handler handler)
Same as obtain(), but sets the value for the target member on the Message returned.
static Message obtain(Handler handler, int what, int arg1, int arg2, Object obj)
Same as obtain(), but sets the values of the target, what, arg1, arg2, and obj members.
static Message obtain(Message origMessage)
Same as obtain(), but copies the values of an existing message (including its target) into the new one.
static Message obtain(Handler handler, Runnable callback)
Same as obtain(Handler), but assigns a callback Runnable on the Message that is returned.
static Message obtain(Handler handler, int what, int arg1, int arg2)
Same as obtain(), but sets the values of the target, what, arg1, and arg2 members.
static Message obtain()
Return a new Message instance from the global pool.
Bundle peekData()
Like getData(), but does not lazily create the Bundle.
void recycle()
Return a Message instance to the global pool.
void sendToTarget()
Sends this Message to the Handler specified by getTarget().
void setData(Bundle data)
Sets a Bundle of arbitrary data values.
void setTarget(Handler target)
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public int arg1

arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.

public int arg2

arg1 and arg2 are lower-cost alternatives to using setData() if you only need to store a few integer values.

public Object obj

An arbitrary object to send to the recipient.

public int what

User-defined message code so that the recipient can identify what this message is about. Each Handler has its own name-space for message codes, so you do not need to worry about yours conflicting with other handlers.

Public Constructors

public Message ()

Constructor (but the preferred way to get a Message is to call Message.obtain()).

Public Methods

public void copyFrom (Message otherMessage)

Make this message like o. Performs a shallow copy of the data field. Does not copy the linked list fields, nor the timestamp or target/callback of the original message.

public Runnable getCallback ()

Retrieve callback object that will execute when this message is handled. This object must implement Runnable. This is called by the target Handler that is receiving this Message to dispatch it. If not set, the message will be dispatched to the receiving Handler's handleMessage(Message).

public Bundle getData ()

Obtains a Bundle of arbitrary data associated with this event, lazily creating it if necessary. Set this value by calling setData(Bundle).

public Handler getTarget ()

Retrieve the a Handler implementation that will receive this message. The object must implement Handler.handleMessage(). Each Handler has its own name-space for message codes, so you do not need to worry about yours conflicting with other handlers.

public long getWhen ()

Return the targeted delivery time of this message, in milliseconds.

public static Message obtain (Handler handler, int what, Object obj)

Same as obtain(), but sets the values of the target, what, and obj members.

Parameters
handler The target value to set.
what The what value to set.
obj The object method to set.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler handler, int what)

Same as obtain(), but sets the values for both target and what members on the Message.

Parameters
handler Value to assign to the target member.
what Value to assign to the what member.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler handler)

Same as obtain(), but sets the value for the target member on the Message returned.

Parameters
handler Handler to assign to the returned Message object's target member.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler handler, int what, int arg1, int arg2, Object obj)

Same as obtain(), but sets the values of the target, what, arg1, arg2, and obj members.

Parameters
handler The target value to set.
what The what value to set.
arg1 The arg1 value to set.
arg2 The arg2 value to set.
obj The obj value to set.
Returns
  • A Message object from the global pool.

public static Message obtain (Message origMessage)

Same as obtain(), but copies the values of an existing message (including its target) into the new one.

Parameters
origMessage Original message to copy.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler handler, Runnable callback)

Same as obtain(Handler), but assigns a callback Runnable on the Message that is returned.

Parameters
handler Handler to assign to the returned Message object's target member.
callback Runnable that will execute when the message is handled.
Returns
  • A Message object from the global pool.

public static Message obtain (Handler handler, int what, int arg1, int arg2)

Same as obtain(), but sets the values of the target, what, arg1, and arg2 members.

Parameters
handler The target value to set.
what The what value to set.
arg1 The arg1 value to set.
arg2 The arg2 value to set.
Returns
  • A Message object from the global pool.

public static Message obtain ()

Return a new Message instance from the global pool. Allows us to avoid allocating new objects in many cases.

public Bundle peekData ()

Like getData(), but does not lazily create the Bundle. A null is returned if the Bundle does not already exist. See getData() for further information on this.

public void recycle ()

Return a Message instance to the global pool. You MUST NOT touch the Message after calling this function -- it has effectively been freed.

public void sendToTarget ()

Sends this Message to the Handler specified by getTarget(). Throws a null pointer exception if this field has not been set.

public void setData (Bundle data)

Sets a Bundle of arbitrary data values. Use arg1 and arg1 members as a lower cost way to send a few simple integer values, if you can.

public void setTarget (Handler target)