Events Module

The Events Module provides a powerful and flexible way to manage and listen to events both inside the system and from external sources. It supports system events as well as custom events, allowing developers to build reactive and interactive applications by subscribing to, emitting, and handling various event types.

Overview

The Events Module exposes several methods to emit and listen for events:

• emit(eventName, payload): Emits an event locally within the current context.
• emitTo(targetId, eventName, payload): Emits an event to a specific target identified by targetId.
• emitToAll(eventName, payload): Emits an event to all connected targets.
• on(eventName, handler): Registers an event handler that is called every time the event is emitted.
• once(eventName, handler): Registers a handler that is called only once for the first occurrence of the event.
• onMany(eventNames, handler): Registers a single handler for multiple event names.
• Specialized handlers such as onNetworkStatus, onDeeplink, onShortcut, onDragDrop, onMenuEvent, and onTrayIconEvent listen to specific system or bridge-related events.

These methods allow fine-grained control over event flow, helping to build modular and maintainable event-driven applications.

Methods

Method	Description	Return Type
emit(eventName, payload)	Emits an event locally with the specified payload.	void
emitTo(targetId, eventName, payload)	Emits an event to a specific target identified by targetId.	void
emitToAll(eventName, payload)	Emits an event to all connected targets.	void
on(eventName, handler)	Registers an event handler for the specified event. Returns a function to deregister the handler.	() => void
once(eventName, handler)	Registers a one-time event handler for the specified event.	void
onMany(eventNames, handler)	Registers a handler for multiple event names.	() => void
onNetworkStatus(handler)	Listens for network status changes (online/offline).	() => void
onDeeplink(handler)	Listens for deeplink events triggered in the system.	() => void
onShortcut(handler)	Listens for keyboard shortcut events.	() => void
onDragDrop(handler)	Listens for drag and drop events.	() => void
onMenuEvent(handler)	Listens for menu-related events from the bridge.	() => void
onTrayIconEvent(handler)	Listens for tray icon events such as clicks or interactions.	() => void

Example Usage

// Listen to an event (is important to use the await, otherwise 'unsubscribe' will be only an instance of a Promise)
const unsubscribe = await Bubbledesk.events.on('<your_event_id>', (payload) => {
  console.log(payload);
});
// Deregister your event listener when no longer needed like this:
unsubscribe();
// Note: 'unsubscribe' is a common name for this usecase, but you can use whatever name you want.

// Emit an event
Bubbledesk.events.emit('refresh:data', { userId: 123 });

// Emit an event to a specific target window
Bubbledesk.events.emitTo('window-456', 'refresh:data', { force: true });

Notes

TIP

To deregister an event handler registered via on or onMany, call the function returned by the method. This ensures that your application does not leak event listeners and helps maintain optimal performance.

WARNING

Registering too many event listeners simultaneously can degrade performance and may cause events to be handled multiple times unexpectedly. Always deregister handlers when they are no longer needed.