WActionHandler class

Bridges JSON action definitions to Dart callback handlers in the dynamic module.

WActionHandler is the action dispatch system for Wind's dynamic widgets. It maps string action names from JSON to registered Dart functions, enabling interactive behavior in JSON-driven UIs without hardcoding widget logic.

Handler Signatures

Two callback signatures are supported:

Simple handler (no state access):

(Map<String, dynamic> args) => void

Stateful handler (with state access):

(Map<String, dynamic> args, WDynamicState state) => void

Both signatures can return void or Future<void> for async operations.

Dispatch Resolution

When dispatch() is called, the handler signature is resolved in this order:

  1. Type check for stateful signature: Function(Map<String, dynamic>, WDynamicState)
  2. Type check for simple signature: Function(Map<String, dynamic>)
  3. Fallback to Function.apply: Attempts generic invocation with [args, state]

If the action name is not registered, the call is silently ignored with a debugPrint. If an exception occurs during handler execution, it is caught and logged via debugPrint.

Action Parsing

Simple Actions (parseAction)

Used for tap/click events that don't pass values. JSON shape:

{
  "action": "actionName",
  "args": {
    "key": "value"
  }
}

Returns VoidCallback? that calls dispatch(actionName, args) when invoked.

Value Actions (parseValueAction)

Used for input changes, selections, and other value-emitting events. JSON shape:

{
  "action": "actionName",
  "args": {
    "key": "value"
  }
}

Returns ValueChanged<T>? that:

  1. Updates WDynamicState if stateId is provided: state.set(stateId, value)
  2. Injects the changed value into args as _value
  3. Calls dispatch(actionName, {...args, _value: value})

State Integration

When parseValueAction is called with a stateId:

  • The changed value is automatically written to WDynamicState before action dispatch
  • The value is injected into action args under the _value key
  • Widgets with matching id props will reactively rebuild with the new state value

This enables two-way data binding: widget → state → action handler.

Error Handling

Unknown action: If an action name is not in the registered actions map, the call is silently ignored and a debug message is printed: "Unknown action {name}, ignored."

Handler exception: If a handler throws an exception, it is caught and logged: "Action {name} error: {exception}". The error does not propagate to the widget tree.

Example Usage

final actionHandler = WActionHandler(
  actions: {
    'navigate': (args) {
      final route = args['route'] as String;
      Navigator.pushNamed(context, route);
    },
    'updateUser': (args, state) {
      final field = args['field'] as String;
      final value = args['_value']; // Injected by parseValueAction
      print('Update $field to $value');
      // Access other state values via state.get(id)
    },
    'submitForm': (args, state) async {
      final email = state.get('email');
      final password = state.get('password');
      await api.login(email, password);
    },
  },
  state: WDynamicState(),
);

// In JSON widget definition:
// {
//   "type": "WButton",
//   "props": {
//     "onTap": {"action": "navigate", "args": {"route": "/home"}}
//   }
// }
//
// {
//   "type": "WInput",
//   "props": {
//     "id": "email",
//     "onChange": {"action": "updateUser", "args": {"field": "email"}}
//   }
// }

Constructors

WActionHandler({required Map<String, Function> actions, required WDynamicState state})

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

dispatch(String actionName, Map<String, dynamic> args) → FutureOr<void>
Dispatch a registered action handler with the provided arguments.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
parseAction(dynamic actionProp) → VoidCallback?
Parse a simple action from JSON and return a VoidCallback.
parseValueAction<T>(dynamic actionProp, {String? stateId}) → ValueChanged<T>?
Parse a value action from JSON and return a typed ValueChanged callback.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited