Package icyllis.modernui.core

# Class Message

java.lang.Object
icyllis.modernui.core.Message

public final class Message extends Object
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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `int`
  `arg1`
  `int`
  `arg2`
  `Object`
  `obj`
  `int`
  `what`
  User-defined message code so that the recipient can identify what this message is about.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Message()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Runnable`
  `getCallback()`
  Retrieve callback object that will execute when this message is handled.
  `Handler`
  `getTarget()`
  Retrieve the `Handler` implementation that will receive this message.
  `long`
  `getWhen()`
  Return the targeted delivery time of this message, in milliseconds.
  `boolean`
  `isAsynchronous()`
  Returns true if the message is asynchronous, meaning that it is not subject to `Looper` synchronization barriers.
  `static Message`
  `obtain()`
  Return a new Message instance from the global pool.
  `static Message`
  `obtain(Handler h)`
  Same as `obtain()`, but sets the value for the target member on the Message returned.
  `static Message`
  `obtain(Handler h, int what)`
  Same as `obtain()`, but sets the values for both target and what members on the Message.
  `static Message`
  `obtain(Handler h, int what, int arg1, int arg2)`
  Same as `obtain()`, but sets the values of the target, what, arg1, and arg2 members.
  `static Message`
  `obtain(Handler h, 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(Handler h, int what, Object obj)`
  Same as `obtain()`, but sets the values of the target, what, and obj members.
  `static Message`
  `obtain(Handler h, Runnable callback)`
  Same as `obtain(Handler)`, but assigns a callback Runnable on the Message that is returned.
  `static Message`
  `obtain(Message o)`
  Same as `obtain()`, but copies the values of an existing message (including its target) into the new one.
  `void`
  `recycle()`
  Return a Message instance to the global pool.
  `void`
  `sendToTarget()`
  Sends this Message to the Handler specified by `getTarget()`.
  `void`
  `setAsynchronous(boolean async)`
  Sets whether the message is asynchronous, meaning that it is not subject to `Looper` synchronization barriers.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### what

    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.

  - ### arg1

    public int arg1

  - ### arg2

    public int arg2

  - ### obj

    public Object obj

- ## Constructor Details

  - ### Message

    public Message()
    See Also:
      - `obtain()`

- ## Method Details

  - ### obtain

    @NonNull public static Message obtain()
    Return a new Message instance from the global pool. Allows us to avoid allocating new objects in many cases.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Message o)
    Same as `obtain()`, but copies the values of an existing message (including its target) into the new one.
    Parameters:
      `o` - Original message to copy.
    Returns:
      A Message object from the global pool.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Handler h)
    Same as `obtain()`, but sets the value for the target member on the Message returned.
    Parameters:
      `h` - Handler to assign to the returned Message object's target member.
    Returns:
      A Message object from the global pool.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Handler h, @NonNull Runnable callback)
    Same as `obtain(Handler)`, but assigns a callback Runnable on the Message that is returned.
    Parameters:
      `h` - 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.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Handler h, int what)
    Same as `obtain()`, but sets the values for both target and what members on the Message.
    Parameters:
      `h` - Value to assign to the target member.
      `what` - Value to assign to the what member.
    Returns:
      A Message object from the global pool.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Handler h, int what, Object obj)
    Same as `obtain()`, but sets the values of the target, what, and obj members.
    Parameters:
      `h` - 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.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Handler h, int what, int arg1, int arg2)
    Same as `obtain()`, but sets the values of the target, what, arg1, and arg2 members.
    Parameters:
      `h` - 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.

  - ### obtain

    @NonNull public static Message obtain(@NonNull Handler h, 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:
      `h` - 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.

  - ### recycle

    public void recycle()
    Return a Message instance to the global pool.

    You MUST NOT touch the Message after calling this function because it has effectively been freed. It is an error to recycle a message that is currently enqueued or that is in the process of being delivered to a Handler.

  - ### getWhen

    public long getWhen()
    Return the targeted delivery time of this message, in milliseconds.

  - ### getTarget

    public Handler getTarget()
    Retrieve the `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.

  - ### getCallback

    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 `Handler.handleMessage(Message)`.

  - ### sendToTarget

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

  - ### isAsynchronous

    public boolean isAsynchronous()
    Returns true if the message is asynchronous, meaning that it is not subject to `Looper` synchronization barriers.
    Returns:
      True if the message is asynchronous.
    See Also:
      - `setAsynchronous(boolean)`

  - ### setAsynchronous

    public void setAsynchronous(boolean async)
    Sets whether the message is asynchronous, meaning that it is not subject to `Looper` synchronization barriers.

    Certain operations, such as view invalidation, may introduce synchronization barriers into the `Looper`'s message queue to prevent subsequent messages from being delivered until some condition is met. In the case of view invalidation, messages which are posted after a call to `View.invalidate()` are suspended by means of a synchronization barrier until the next frame is ready to be drawn. The synchronization barrier ensures that the invalidation request is completely handled before resuming.

    Asynchronous messages are exempt from synchronization barriers. They typically represent interrupts, input events, and other signals that must be handled independently even while other work has been suspended.

    Note that asynchronous messages may be delivered out of order with respect to synchronous messages although they are always delivered in order among themselves. If the relative order of these messages matters then they probably should not be asynchronous in the first place. Use with caution.

    Parameters:
      `async` - True if the message is asynchronous.
    See Also:
      - `isAsynchronous()`

  - ### toString

    @NonNull public String toString()
    Overrides:
      `toString` in class `Object`