class sap.ui.core.EventBus

Control sample: sap.ui.core.EventBus
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/core/EventBus
Application Component: CA-UI5-COR

Provides eventing capabilities for applications like firing events and attaching or detaching event handlers for events which are notified when events are fired.

It is recommended to use the EventBus only when there is no other option to communicate between different instances, e.g. native UI5 events. Custom events can be fired by classes that extend sap.ui.base.EventProvider, such as sap.ui.core.Control, sap.ui.core.mvc.View or sap.ui.core.Component, and the events can be consumed by other classes to achieve communication between different instances.

Heavily using the EventBus can easily result in code which is hard to read and maintain because it's difficult to keep an overview of all event publishers and subscribers.


Constructor

Creates an instance of EventBus.

new sap.ui.core.EventBus()

Methods Overview

Method Description
destroy

Cleans up the internal structures and removes all event handlers.

The object must not be used anymore after destroy was called.

References:

  • sap.ui.base.Object#destroy

sap.ui.core.EventBus.extend

Creates a new subclass of class sap.ui.core.EventBus with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.Object.extend.

sap.ui.core.EventBus.getMetadata

Returns a metadata object for class sap.ui.core.EventBus.

publish

Fires an event using the specified settings and notifies all attached event handlers.

resume

Resumes the EventBus, so future events will be published

subscribe

Attaches an event handler to the event with the given identifier on the given event channel.

subscribeOnce

Attaches an event handler, called one time only, to the event with the given identifier on the given event channel.

When the event occurs, the handler function is called and the handler registration is automatically removed afterwards.

suspend

Suspends the EventBus, so no further events will be published

unsubscribe

Removes a previously subscribed event handler from the event with the given identifier on the given event channel.

The passed parameters must match those used for registration with #subscribe beforehand!

destroy

Cleans up the internal structures and removes all event handlers.

The object must not be used anymore after destroy was called.

References:

sap.ui.core.EventBus.extend

Creates a new subclass of class sap.ui.core.EventBus with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.base.Object.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

sap.ui.core.EventBus.getMetadata

Returns a metadata object for class sap.ui.core.EventBus.

publish

Fires an event using the specified settings and notifies all attached event handlers.

Param Type DefaultValue Description
sChannelId string

The channel of the event to fire. If not given, the default channel is used. The channel "sap.ui" is reserved by the UI5 framework. An application might listen to events on this channel but is not allowed to publish its own events there.

sEventId string

The identifier of the event to fire

oData object

The parameters which should be carried by the event

resume

Resumes the EventBus, so future events will be published

subscribe

Attaches an event handler to the event with the given identifier on the given event channel.

Param Type DefaultValue Description
sChannelId string

The channel of the event to subscribe to. If not given, the default channel is used. The channel "sap.ui" is reserved by the UI5 framework. An application might listen to events on this channel but is not allowed to publish its own events there.

sEventId string

The identifier of the event to listen for

fnFunction function

The handler function to call when the event occurs. This function will be called in the context of the oListener instance (if present) or on the event bus instance. The channel is provided as first argument of the handler, and the event identifier is provided as the second argument. The parameter map carried by the event is provided as the third argument (if present). Handlers must not change the content of this map.

oListener object

The object that wants to be notified when the event occurs (this context within the handler function). If it is not specified, the handler function is called in the context of the event bus.

subscribeOnce

Attaches an event handler, called one time only, to the event with the given identifier on the given event channel.

When the event occurs, the handler function is called and the handler registration is automatically removed afterwards.

Param Type DefaultValue Description
sChannelId string

The channel of the event to subscribe to. If not given, the default channel is used. The channel "sap.ui" is reserved by the UI5 framework. An application might listen to events on this channel but is not allowed to publish its own events there.

sEventId string

The identifier of the event to listen for

fnFunction function

The handler function to call when the event occurs. This function will be called in the context of the oListener instance (if present) or on the event bus instance. The channel is provided as first argument of the handler, and the event identifier is provided as the second argument. The parameter map carried by the event is provided as the third argument (if present). Handlers must not change the content of this map.

oListener object

The object that wants to be notified when the event occurs (this context within the handler function). If it is not specified, the handler function is called in the context of the event bus.

suspend

Suspends the EventBus, so no further events will be published

unsubscribe

Removes a previously subscribed event handler from the event with the given identifier on the given event channel.

The passed parameters must match those used for registration with #subscribe beforehand!

Param Type DefaultValue Description
sChannelId string

The channel of the event to unsubscribe from. If not given, the default channel is used.

sEventId string

The identifier of the event to unsubscribe from

fnFunction function

The handler function to unsubscribe from the event

oListener object

The object that wanted to be notified when the event occurred