eventsubscriber 1.2.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 67

EventSubscriber #

Pub Package

A Flutter widget that supports subscribing to an Event.

The EventSubscriber widget will be notified and rebuilt when the Event occurs, allowing some changing aspect of an observed object to be displayed in your Flutter user interface.


Contents #


Usage #

The Flutter EventSubscriber Widget requires that the event being subscribed to is specified, along with a handler that returns a child Widget.

// example ...
EventSubscriber(
  event: myCount.valueChangedEvent,
  handler: (context, args) => Text('${myCount.value}'),
),

See Also #

Event - broadcasts events to interested subscribers.

Dependencies #

  • Flutter - This Dart package has a dependency on the Flutter framework.
  • Event - Supports the creation of lightweight custom Dart Events, that allow interested subscribers to be notified that something has happened. Provides a notification mechanism across independent packages/layers/modules.

Examples #

Simple Example

import 'package:flutter/material.dart';
import 'package:event/event.dart';
import 'package:eventsubscriber/eventsubscriber.dart';

// An example domain model of a simple Counter
// Normally in its own module/package
// Included here inline for illustration purposes
class Count {
  int value = 0;
  var valueChangedEvent = Event(); // declare Event

  void increment() {
    value++;
    // Broadcast that the value has changed
    valueChangedEvent.broadcast();
  }
}

//////////////////////

// Create the domain model
var myCount = Count();

// Flutter application
// The Count domain value will increment when the button is pressed.
// The updated domain value will be automatically updated in the UI.
void main() => runApp(
      MaterialApp(
        home: Column(
          children: <Widget>[
            // Subscribe to the 'valueChanged' domain event
            EventSubscriber(
              event: myCount.valueChangedEvent,
              handler: (context, args) => Text(myCount.value.toString()),
            ),
            FlatButton(
              child: Text('Increment'),
              // Increment the domain value
              onPressed: () => myCount.increment(),
            )
          ],
        ),
      ),
    );

Using Arguments (EventArgs) #

One might alter the above Count domain model to include custom arguments (EventArgs). For example, we might want to provide the subscriber handler with the date and time the event occured, and also if the counter value is an even number (divisible by 2).

See the Event package for additional information about [EventArgs].


// Custom Event arguments
ValueChangedEventArgs extends EventArgs {
  DateTime whenOccured;
  bool isEven;
  // constructor
  valueChangedEvent(int value) {
    whenOccured = DateTime.now();
    isEven = (myValue % 2) == 0;  // even number?
  }
}

To use ValueChangedEventArgs, one would alter the Counter class from the previous simple example as follows:-

// Includes Event arguments
class Count {
  int value = 0;
  var valueChangedEvent = Event<ValueChangedEventArgs>(); // <<====

  void increment() {
    value++;
    // Broadcast that the value has changed
    valueChangedEvent.broadcast(ValueChangedEventArgs(value)); // <<====
  }
}

In Flutter, the arguments can be used as follows.

Note that best practice is that generally on notification one queries the domain model directly, rather than having arguments deliver data to a consumer of the domain model, i.e. this Flutter UI application. The supply of data shown here is by way of example only.

// In Flutter ...
EventSubscriber(
  event: myCount.valueChangedEvent,
  handler: (context, args) {
    // Display the counter value, as well as whether
    // the counter value is even.
    
    return Text('${myCount.value} ${args?.isEven}');

    // Note that we must check if args is null. The
    // flutter framework will also call this handler in
    // which case args will be null.
),

Requesting Features and Reporting Bugs #

Please enter feature requests and report bugs at the issue tracker.

Changelog - EventSubscriber #

Version 1.2.0 (2020-02-09) #

  • Breaking Change. Event arguments [EventArgs] are now supported.

    • The builder argument has been renamed to handler, to better reflect that you are supplying a subscriber handler that is called when the event is broadcast.
    • A handler requires now two arguments, the first representing the BuildContext, and the second the (optional) [EventArgs] associated with the Event.
      • before: builder: (context) => Text(myCount.value.toString()),
      • after: handler: (context, args) => Text(myCount.value.toString()),
    ...
    EventSubscriber(
      event: myCount.onValueChanged,
      handler: (context, args) => Text(myCount.value.toString()),
    
      // If an Event has arguments, they are now available in your handler.
      // In the example above through `args` argument.
    ),
    

    IMPORTANT: args should be checked for null before use in a handler, as the handler is called BOTH when an Event occurs, and also by the Flutter framework. In the latter case, args will always be null.

Version 1.1.2 (2020-01-31) #

  • Internal - don't repeat the event handler - refer to a single instance

Version 1.1.1 (2020-01-29) #

  • Support Event 1.1.0.
  • Modified to use new Event methods - broadcast and subscribe.

Version 1.1.0 (2020-01-23) #

Version 1.0.3 (2020-01-14) #

  • Updated to support latest EventNotifier (1.0.5), which includes support for a subscriber to optionally expect some 'argument/s' as a Map.

Version 1.0.2 (2020-01-13) #

  • Fixed LICENSE reference to package

Version 1.0.1 (2020-01-13) #

  • Fixed formatting and documentation errors.

Version 1.0.0 (2020-01-13) #

  • Initial release

example/eventsubscriber_example.dart

import 'package:flutter/material.dart';
import 'package:event/event.dart';
import 'package:eventsubscriber/eventsubscriber.dart';

// An example domain model of a simple Counter
// Normally in its own module/package
// Included here inline for illustration purposes
class Count {
  int value = 0;
  var onValueChanged = Event(); // declare Event

  void increment() {
    value++;
    // Broadcast that the value has changed
    onValueChanged.broadcast();
  }
}

//////////////////////

// Create the domain model
var myCount = Count();

// Flutter application
// The Count domain value will increment when the button is pressed.
// The updated domain value will be automatically updated in the UI.
void main() => runApp(
      MaterialApp(
        home: Column(
          children: <Widget>[
            // Subscribe to the 'valueChanged' domain event
            EventSubscriber(
              event: myCount.onValueChanged,
              handler: (context, args) => Text(myCount.value.toString()),
            ),
            FlatButton(
              child: Text('Increment'),
              onPressed: () => myCount.increment(),
            )
          ],
        ),
      ),
    );

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  eventsubscriber: ^1.2.0

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:eventsubscriber/eventsubscriber.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
35
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
67
Learn more about scoring.

We analyzed this package on Mar 27, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6
  • Flutter: 1.12.13+hotfix.8

Health suggestions

Format lib/src/eventsubscriber.dart.

Run flutter format to format lib/src/eventsubscriber.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
event ^1.1.2 1.1.3
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.8
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test
pedantic ^1.8.0
test ^1.6.0