pigeon 0.1.0-experimental.5

  • Readme
  • Changelog
  • Example
  • Installing
  • 84

Pigeon #

Warning: Pigeon is experimental and unsupported. It can be removed or changed at any time.

Pigeon is a code generator tool to make communication between Flutter and the host platform type-safe and easier.

Supported Platforms #

Currently Pigeon only supports generating Objective-C code for usage on iOS and Java code for Android.

Runtime Requirements #

Pigeon generates all the code that is needed to communicate between Flutter and the host platform, there is no extra runtime requirement. A plugin author doesn't need to worry about conflicting versions of Pigeon.

Usage #

Flutter calling into iOS Steps #

  1. Add Pigeon as a dev_dependency.
  2. Make a ".dart" file outside of your "lib" directory for defining the communication interface.
  3. Run pigeon on your ".dart" file to generate the required Dart and Objective-C code.
  4. Add the generated Dart code to lib for compilation.
  5. Add the generated Objective-C code to your Xcode project for compilation (e.g. ios/Runner.xcworkspace).
  6. Implement the generated iOS protocol for handling the calls on iOS, set it up as the handler for the messages.
  7. Call the generated Dart methods.

Flutter calling into Android Steps #

  1. Add Pigeon as a dev_dependency.
  2. Make a ".dart" file outside of your "lib" directory for defining the communication interface.
  3. Run pigeon on your ".dart" file to generate the required Dart and Java code.
  4. Add the generated Dart code to ./lib for compilation.
  5. Add the generated Java code to your ./android/app/src/main/java directory for compilation.
  6. Implement the generated Java interface for handling the calls on Android, set it up as the handler for the messages.
  7. Call the generated Dart methods.

Rules for defining your communication interface #

  1. The file should contain no methods or function definitions.
  2. Datatypes are defined as classes with fields of the supported datatypes (see the supported Datatypes section).
  3. Api's should be defined as an abstract class with either HostApi() or FlutterApi() as metadata. The former being for procedures that are defined on the host platform and the latter for procedures that are defined in Dart.
  4. Method declarations on the Api classes should have one argument and a return value whose types are defined in the file.

Example #

See the "Example" tab.

Supported Datatypes #

Pigeon uses the StandardMessageCodec so it supports any data-type platform channels supports [documentation]. Nested data-types are supported, too.

Note: Generics for List and Map aren't supported yet.

Feedback #

File an issue in flutter/flutter with the word 'pigeon' clearly in the title and cc @gaaclarke.

0.1.0-experimental.5 #

  • Fixed runtime exception in Android with values of ints less than 2^32.
  • Incremented codegen version warning.

0.1.0-experimental.4 #

  • Fixed primitive types for Android Java.

0.1.0-experimental.3 #

  • Added support for for Android Java.

0.1.0-experimental.2 #

  • Added Host->Flutter calls for Objective-C

0.1.0-experimental.1 #

  • Fixed warning in the README.md

0.1.0-experimental.0 #

  • Initial release.

example/README.md

Pigeon iOS / Android Example #

message.dart #

import 'package:pigeon/pigeon_lib.dart';

class SearchRequest {
  String query;
}

class SearchReply {
  String result;
}

@HostApi()
abstract class Api {
  SearchReply search(SearchRequest request);
}

invocation #

flutter pub run pigeon \
  --input pigeons/message.dart \
  --dart_out lib/pigeon.dart \
  --objc_header_out ios/Runner/pigeon.h \
  --objc_source_out ios/Runner/pigeon.m \
  --java_out ./android/app/src/main/java/dev/flutter/pigeon/Pigeon.java \
  --java_package "dev.flutter.pigeon"

AppDelegate.m #

#import "AppDelegate.h"
#import <Flutter/Flutter.h>
#import "pigeon.h"

@interface MyApi : NSObject <Api>
@end

@implementation MyApi
-(SearchReply*)search:(SearchRequest*)request error:(FlutterError **)error {
  SearchReply *reply = [[SearchReply alloc] init];
  reply.result =
      [NSString stringWithFormat:@"Hi %@!", request.query];
  return reply;
}
@end

- (BOOL)application:(UIApplication *)application 
didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
  MyApi *api = [[MyApi alloc] init];
  ApiSetup(getFlutterEngine().binaryMessenger, api);
  return YES;
}

StartActivity.java #

import dev.flutter.pigeon.Pigeon;

public class StartActivity extends Activity {
  private class MyApi extends Pigeon.Api {
    Pigeon.SearchReply search(Pigeon.SearchRequest request) {
      Pigeon.SearchReply reply = new Pigeon.SearchReply();
      reply.result = String.format("Hi %s!", request.query);
      return reply;
    }
  }

  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Pigeon.SetupApi(getBinaryMessenger(), new MyApi());
  }
}

test.dart #

import 'pigeon.dart';

void main() {
  testWidgets("test pigeon", (WidgetTester tester) async {
    SearchRequest request = SearchRequest()..query = "Aaron";
    Api api = Api();
    SearchReply reply = await api.search(request);
    expect(reply.result, equals("Hi Aaron!"));
  });
}

Use this package as a library

1. Depend on it

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


dependencies:
  pigeon: ^0.1.0-experimental.5

2. Install it

You can install packages from the command line:

with pub:


$ pub get

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

3. Import it

Now in your Dart code, you can use:


import 'package:pigeon/ast.dart';
import 'package:pigeon/dart_generator.dart';
import 'package:pigeon/generator_tools.dart';
import 'package:pigeon/java_generator.dart';
import 'package:pigeon/objc_generator.dart';
import 'package:pigeon/pigeon_lib.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
69
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
95
Overall:
Weighted score of the above. [more]
84
Learn more about scoring.

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

  • Dart: 2.8.4
  • pana: 0.13.13

Analysis suggestions

Package not compatible with SDK flutter

Because it is not compatible with any of the supported runtimes: flutter-native, flutter-web

Package not compatible with runtime flutter-native on android

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on ios

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on linux

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on macos

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-native on windows

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime flutter-web on web

Because of the import of dart:io via the import chain package:pigeon/dart_generator.dartpackage:pigeon/generator_tools.dartdart:io

Package not compatible with runtime native-aot

Because of the import of dart:mirrors via the import chain package:pigeon/pigeon_lib.dartdart:mirrors

Package not compatible with runtime web

Because of the import of dart:io via the import chain package:pigeon/dart_generator.dartpackage:pigeon/generator_tools.dartdart:io

Maintenance suggestions

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.0 <3.0.0
args ^1.5.2 1.6.0
path ^1.6.4 1.7.0
Dev dependencies
test ^1.11.1