de.greenrobot.event

Class EventBus

java.lang.Object

de.greenrobot.event.EventBus

public class EventBus
extends java.lang.Object

EventBus is a central publish/subscribe event system for Android. Events are posted (post(Object)) to the bus, which delivers it to subscribers that have a matching handler method for the event type. To receive events, subscribers must register themselves to the bus using register(Object). Once registered, subscribers receive events until unregister(Object) is called. By convention, event handling methods must be named "onEvent", be public, return nothing (void), and have exactly one parameter (the event).

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	TAG Log tag, apps may override it.

Constructor Summary

Constructors

Constructor and Description
EventBus() Creates a new EventBus instance; each instance is a separate scope in which events are delivered.

Method Summary

Modifier and Type	Method and Description
static EventBusBuilder	builder()
void	cancelEventDelivery(java.lang.Object event) Called from a subscriber's event handling method, further event delivery will be canceled.
static void	clearCaches() For unit test primarily.
static EventBus	getDefault() Convenience singleton for apps using a process-wide EventBus instance.
<T> T	getStickyEvent(java.lang.Class<T> eventType) Gets the most recent sticky event for the given type.
boolean	hasSubscriberForEvent(java.lang.Class<?> eventClass)
boolean	isRegistered(java.lang.Object subscriber)
void	post(java.lang.Object event) Posts the given event to the event bus.
void	postSticky(java.lang.Object event) Posts the given event to the event bus and holds on to the event (because it is sticky).
void	register(java.lang.Object subscriber) Registers the given subscriber to receive events.
void	register(java.lang.Object subscriber, int priority) Like register(Object) with an additional subscriber priority to influence the order of event delivery.
void	registerSticky(java.lang.Object subscriber) Like register(Object), but also triggers delivery of the most recent sticky event (posted with postSticky(Object)) to the given subscriber.
void	registerSticky(java.lang.Object subscriber, int priority) Like register(Object, int), but also triggers delivery of the most recent sticky event (posted with postSticky(Object)) to the given subscriber.
void	removeAllStickyEvents() Removes all sticky events.
<T> T	removeStickyEvent(java.lang.Class<T> eventType) Remove and gets the recent sticky event for the given event type.
boolean	removeStickyEvent(java.lang.Object event) Removes the sticky event if it equals to the given event.
void	unregister(java.lang.Object subscriber) Unregisters the given subscriber from all event classes.

Methods inherited from class java.lang.Object

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

Field Detail

TAG

public static java.lang.String TAG

Log tag, apps may override it.

Constructor Detail

EventBus

public EventBus()

Creates a new EventBus instance; each instance is a separate scope in which events are delivered. To use a central bus, consider getDefault().

Method Detail

getDefault

public static EventBus getDefault()

Convenience singleton for apps using a process-wide EventBus instance.

builder

public static EventBusBuilder builder()

clearCaches

public static void clearCaches()

For unit test primarily.

register

public void register(java.lang.Object subscriber)

Registers the given subscriber to receive events. Subscribers must call unregister(Object) once they are no longer interested in receiving events.

Subscribers have event handling methods that are identified by their name, typically called "onEvent". Event handling methods must have exactly one parameter, the event. If the event handling method is to be called in a specific thread, a modifier is appended to the method name. Valid modifiers match one of the ThreadMode enums. For example, if a method is to be called in the UI/main thread by EventBus, it would be called "onEventMainThread".

register

public void register(java.lang.Object subscriber,
                     int priority)

Like register(Object) with an additional subscriber priority to influence the order of event delivery. Within the same delivery thread (ThreadMode), higher priority subscribers will receive events before others with a lower priority. The default priority is 0. Note: the priority does *NOT* affect the order of delivery among subscribers with different ThreadModes!

registerSticky

public void registerSticky(java.lang.Object subscriber)

Like register(Object), but also triggers delivery of the most recent sticky event (posted with postSticky(Object)) to the given subscriber.

registerSticky

public void registerSticky(java.lang.Object subscriber,
                           int priority)

Like register(Object, int), but also triggers delivery of the most recent sticky event (posted with postSticky(Object)) to the given subscriber.

isRegistered

public boolean isRegistered(java.lang.Object subscriber)

unregister

public void unregister(java.lang.Object subscriber)

Unregisters the given subscriber from all event classes.

post

public void post(java.lang.Object event)

Posts the given event to the event bus.

cancelEventDelivery

public void cancelEventDelivery(java.lang.Object event)

Called from a subscriber's event handling method, further event delivery will be canceled. Subsequent subscribers won't receive the event. Events are usually canceled by higher priority subscribers (see register(Object, int)). Canceling is restricted to event handling methods running in posting thread ThreadMode.PostThread.

postSticky

public void postSticky(java.lang.Object event)

Posts the given event to the event bus and holds on to the event (because it is sticky). The most recent sticky event of an event's type is kept in memory for future access. This can be registerSticky(Object) or getStickyEvent(Class).

getStickyEvent

public <T> T getStickyEvent(java.lang.Class<T> eventType)

Gets the most recent sticky event for the given type.

See Also:

postSticky(Object)

removeStickyEvent

public <T> T removeStickyEvent(java.lang.Class<T> eventType)

Remove and gets the recent sticky event for the given event type.

See Also:

postSticky(Object)

removeStickyEvent

public boolean removeStickyEvent(java.lang.Object event)

Removes the sticky event if it equals to the given event.

Returns:

true if the events matched and the sticky event was removed.

removeAllStickyEvents

public void removeAllStickyEvents()

Removes all sticky events.

hasSubscriberForEvent

public boolean hasSubscriberForEvent(java.lang.Class<?> eventClass)