pigeon 0.1.2+1

  • Readme
  • Changelog
  • Example
  • Installing
  • 86

Pigeon #

Warning: Pigeon is prerelease, breaking changes may occur.

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. The Objective-C code is accessible to Swift and the Java code is accessible to Kotlin.

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 or .podspec).
  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 method or function definitions, only declarations.
  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 or be void.

Example #

See the "Example" tab. A full working example can also be found in the video_player plugin.

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.2+1 #

  • Updated the Readme.md.

0.1.2 #

  • Removed static analysis warnings from generated Java code.

0.1.1 #

  • Fixed issue where nested types didn't work if they weren't present in the Api.

0.1.0 #

  • Added pigeon.dart.
  • Fixed some Obj-C linter problems.
  • Added the ability to generate a mock handler in Dart.

0.1.0-experimental.11 #

  • Fixed setting an api to null in Java.

0.1.0-experimental.10 #

  • Added support for void argument functions.
  • Added nullability annotations to generated objc code.

0.1.0-experimental.9 #

  • Added e2e tests for iOS.

0.1.0-experimental.8 #

  • Renamed setupPigeon to configurePigeon.

0.1.0-experimental.7 #

  • Suppressed or got rid of warnings in generated Dart code.

0.1.0-experimental.6 #

  • Added support for void return types.

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.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.2+1

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/pigeon.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
71
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]
86
Learn more about scoring.

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

  • Dart: 2.8.4
  • pana: 0.13.14

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:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime flutter-native on ios

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime flutter-native on linux

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime flutter-native on macos

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime flutter-native on windows

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime flutter-web on web

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime js

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

Package not compatible with runtime native-aot

Because:

  • package:pigeon/pigeon.dart that imports:
  • package:pigeon/pigeon_lib.dart that imports:
  • package:pigeon/objc_generator.dart that imports:
  • package:pigeon/generator_tools.dart that imports:
  • dart:mirrors

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