ListenerSet

Kotlin |Java

@UnstableApi
public final class ListenerSet<T extends Object>

A set of listeners.

Events are guaranteed to arrive in the order in which they happened even if a new event is triggered recursively from another listener.

Events are also guaranteed to be only sent to the listeners registered at the time the event was enqueued and haven't been removed since.

All methods must be called on the thread passed to the constructor unless indicated otherwise.

Parameters
`<T extends Object>`	The listener type.

Summary

Nested types
`public interface ListenerSet.Event<T>` An event sent to a listener.
`public interface ListenerSet.IterationFinishedEvent<T>` An event sent to a listener when all other events sent during one `Looper` message queue iteration were handled by the listener.

Public constructors
`ListenerSet(Looper looper)` Creates a new listener set.
`ListenerSet(Thread thread)` Creates a new listener set.
`ListenerSet( Looper looper, Clock clock, @Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent )` Creates a new listener set.

Public methods
`void`	`add(T listener)` Adds a listener to the set.
`void`	`clear()` Removes all listeners from the set.
`ListenerSet<T>`	`copy(Clock clock)` Copies the listener set.
`ListenerSet<T>`	`copy(Looper looper)` Copies the listener set.
`ListenerSet<T>`	`copy( Looper looper, @Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent )` Copies the listener set.
`ListenerSet<T>`	`copy( Looper looper, @Nullable Clock clock, @Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent )` Copies the listener set.
`void`	`flushEvents()` Notifies listeners of events previously enqueued with `queueEvent`.
`void`	`queueEvent(ListenerSet.Event<T> event)` Adds an event that is sent to the listeners when `flushEvents` is called.
`void`	`queueEvent(int eventFlag, ListenerSet.Event<T> event)` Adds an event that is sent to the listeners when `flushEvents` is called.
`void`	`release()` Releases the set of listeners immediately.
`void`	`remove(T listener)` Removes a listener from the set.
`void`	`sendEvent(ListenerSet.Event<T> event)` `Queues` a single event and immediately `flushes` the event queue to notify all listeners.
`void`	`sendEvent(int eventFlag, ListenerSet.Event<T> event)` `Queues` a single event and immediately `flushes` the event queue to notify all listeners.
`void`	`setThrowsWhenUsingWrongThread(boolean throwsWhenUsingWrongThread)` This method is deprecated. Do not use this method and ensure all calls are made from the correct thread.
`int`	`size()` Returns the number of added listeners.

Public constructors

ListenerSet

public ListenerSet(Looper looper)

Creates a new listener set.

This listener set will not send an IterationFinishedEvent when all other events sent during one Looper message queue iteration were handled by the listeners.

Parameters
`Looper looper`	A `Looper` used to call listeners on. The same `Looper` must be used to call all other methods of this class unless indicated otherwise.

ListenerSet

public ListenerSet(Thread thread)

Creates a new listener set.

This listener set will not send an IterationFinishedEvent.

Parameters
`Thread thread`	A `Thread` used to call listeners on. The same `Thread` must be used to call all other methods of this class unless indicated otherwise.

ListenerSet

public ListenerSet(
    Looper looper,
    Clock clock,
    @Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent
)

Creates a new listener set.

Parameters
`Looper looper`	A `Looper` used to call listeners on. The same `Looper` must be used to call all other methods of this class unless indicated otherwise.
`Clock clock`	A `Clock`.
`@Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent`	An `IterationFinishedEvent` sent when all other events sent during one `Looper` message queue iteration were handled by the listeners, or null if no such event is needed.

Public methods

add

public void add(T listener)

Adds a listener to the set.

If a listener is already present, it will not be added again.

This method can be called from any thread.

Parameters
`T listener`	The listener to be added.

clear

public void clear()

Removes all listeners from the set.

copy

public ListenerSet<T> copy(Clock clock)

Copies the listener set.

This method can be called from any thread.

Parameters
`Clock clock`	The new `Clock` for the copied listener set.

Returns
`ListenerSet<T>`	The copied listener set.

copy

public ListenerSet<T> copy(Looper looper)

Copies the listener set.

This method can be called from any thread.

Parameters
`Looper looper`	The new `Looper` for the copied listener set.

Returns
`ListenerSet<T>`	The copied listener set.

copy

public ListenerSet<T> copy(
    Looper looper,
    @Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent
)

Copies the listener set.

This method can be called from any thread.

Parameters
`Looper looper`	The new `Looper` for the copied listener set.
`@Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent`	The new `IterationFinishedEvent` sent when all other events sent during one `Looper` message queue iteration were handled by the listeners, or null if no such event is needed. Can only be non-null if the listener set was created with a `Clock`.

Returns
`ListenerSet<T>`	The copied listener set.

copy

public ListenerSet<T> copy(
    Looper looper,
    @Nullable Clock clock,
    @Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent
)

Copies the listener set.

This method can be called from any thread.

Parameters
`Looper looper`	The new `Looper` for the copied listener set.
`@Nullable Clock clock`	The new `Clock` for the copied listener set.
`@Nullable ListenerSet.IterationFinishedEvent<T> iterationFinishedEvent`	The new `IterationFinishedEvent` sent when all other events sent during one `Looper` message queue iteration were handled by the listeners, or null if no such event is needed. Can only be non-null if the `clock` is non-null.

Returns
`ListenerSet<T>`	The copied listener set.

flushEvents

public void flushEvents()

Notifies listeners of events previously enqueued with queueEvent.

queueEvent

public void queueEvent(ListenerSet.Event<T> event)

Adds an event that is sent to the listeners when flushEvents is called.

This call does not set an integer flag for this event to be reported in the IterationFinishedEvent. Use queueEvent instead if this is required.

Parameters
`ListenerSet.Event<T> event`	The event.

queueEvent

public void queueEvent(int eventFlag, ListenerSet.Event<T> event)

Adds an event that is sent to the listeners when flushEvents is called.

Parameters
`int eventFlag`	An integer indicating the type of the event to be reported in the `IterationFinishedEvent`, or `INDEX_UNSET` to report this event without flag.
`ListenerSet.Event<T> event`	The event.

release

public void release()

Releases the set of listeners immediately.

This will ensure no events are sent to any listener after this method has been called.

remove

public void remove(T listener)

Removes a listener from the set.

If the listener is not present, nothing happens.

Parameters
`T listener`	The listener to be removed.

sendEvent

public void sendEvent(ListenerSet.Event<T> event)

Queues a single event and immediately flushes the event queue to notify all listeners.

This call does not set an integer flag for this event to be reported in the IterationFinishedEvent. Use sendEvent instead if this is required.

Parameters
`ListenerSet.Event<T> event`	The event.

sendEvent

public void sendEvent(int eventFlag, ListenerSet.Event<T> event)

Queues a single event and immediately flushes the event queue to notify all listeners.

Parameters
`int eventFlag`	An integer flag indicating the type of the event to be reported in the `IterationFinishedEvent`, or `INDEX_UNSET` to report this event without flag.
`ListenerSet.Event<T> event`	The event.

setThrowsWhenUsingWrongThread

public void setThrowsWhenUsingWrongThread(boolean throwsWhenUsingWrongThread)

Sets whether methods throw when using the wrong thread.

Do not use this method unless to support legacy use cases.

Parameters
`boolean throwsWhenUsingWrongThread`	Whether to throw when using the wrong thread.

size

public int size()

Returns the number of added listeners.

ListenerSet

Summary

Nested types

Public constructors

Public methods

Public constructors

ListenerSet

ListenerSet

ListenerSet

Public methods

add

clear

copy

copy

copy

copy

flushEvents

queueEvent

queueEvent

release

remove

sendEvent

sendEvent

setThrowsWhenUsingWrongThread

size