event_cascade library

A top-down, most-recently-active-first event dispatching framework for Flutter.

This package provides a hierarchical event dispatching system that propagates events from the most recently active UI components (pages, tabs, etc.) down to older ones. It supports:

• Hierarchical dispatch: events propagate from the most recently visible page down to older ones
• Typed handlers: strongly-typed event handlers to avoid runtime type errors
• Global dispatch: call PageCascadeNotifier.dispatch(event) from anywhere
• Route & Tab support: automatically tracks route pushes/pops and tab selection
• No static keys: uses each wrapper's BuildContext as the unique identifier

Basic Usage

1. Add the navigation tracker to your MaterialApp:

MaterialApp(
  navigatorObservers: [CascadeNavigationTracker()],
  home: MyHomePage(),
)

2. Wrap your pages with PageCascadeNotifier:

PageCascadeNotifier(
  handlers: [
    CascadeEventHandler<MyEvent>((e) {
      // Handle the event
      return true; // Return true to consume the event and stop propagation
    }),
  ],
  child: Scaffold(
    // Your page content
  ),
)

3. Dispatch events from anywhere:

PageCascadeNotifier.dispatch(MyEvent(...));

Classes

CascadeEventHandler<T>

A concrete implementation of EventHandlerBase for handling typed events.

CascadeEventRegistry

Central registry for event handlers and context tracking.

CascadeNavigationTracker

A singleton RouteObserver that tracks navigation events for the event cascade system.

EventHandlerBase

Base signature for all event handlers.

PageCascadeNotifier

A widget that enables event handling for a page or tab in your application.

PageCascadeNotifierState

The state for PageCascadeNotifier.