<EventListener>

Overview

The <EventListener> component creates a stateful widget that listens for application-wide events and rebuilds its children when those events occur. It provides a publish-subscribe pattern for decoupled component communication - when an event fires anywhere in your app, all registered listeners are notified and rebuild their UI, making your code more modular and testable.

Lifecycle:

1. Register: <EventListener> registers for the specified event type on initialization
2. Render: The widget renders its children normally
3. Notify: When the event fires anywhere in the app, the listener is notified
4. Handle: If onEvent callback is specified, it's called with the event and payload
5. Rebuild: The widget rebuilds, allowing children to access updated dependencies
6. Cleanup: Listener is automatically unregistered when widget is disposed

Use Cases

• Responding to global state changes (user login/logout, theme changes)
• Updating UI based on background tasks or timers
• Handling system events (network status, notifications)
• Coordinating updates across multiple screens or widgets
• Implementing event-driven architectures
• Broadcasting data changes without tight coupling

Attributes

Name	Type	Description	Required	Default
event	Enum	The event type to listen for. Must be a registered event enum value.	Yes	-
onEvent	Function	Optional callback function executed when the event fires. Signature: (Enum event, dynamic payload) => void	No	null
key	Key	Widget key for controlling widget identity	No	null
for	String	The name of the parent's attribute that will be assigned this component	No	null
visible	bool	Controls widget visibility	No	true

Examples

XML

<EventListener event="AppEvent.dataRefreshed">
  <Column>
    <Text>Last updated: ${lastUpdateTime}</Text>
    <Text>Data count: ${dataCount}</Text>
  </Column>
</EventListener>

See Also

• <ValueListener> - For listening to value changes in a ValueNotifier
• <Controller> - For managing state and firing events
• <DynamicBuilder> - For rebuilding based on async data