Pigeon is a code generator tool to make communication between Flutter and the host platform type-safe, easier and faster.
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.
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.
flutter pub get
then flutter pub run pigeon
with suitable arguments (see example).lib
for compilation.ios/Runner.xcworkspace
or .podspec
).flutter pub get
then flutter pub run pigeon
with suitable arguments (see example)../lib
for compilation../android/app/src/main/java
directory for compilation.Flutter also supports calling in the opposite direction. The steps are similar but reversed. For more information look at the annotation @FlutterApi()
which denotes APIs that live in Flutter but are invoked from the host platform.
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.void
.List<int?>
).Pigeon uses the StandardMessageCodec
so it supports any datatype Platform Channels supports [documentation]. Nested datatypes are supported, too.
By default Pigeon will generate synchronous handlers for messages. If you want to be able to respond to a message asynchronously you can use the @async
annotation as of version 0.1.20.
Example:
class Value { int? number; } @HostApi() abstract class Api2Host { @async Value calculate(Value value); }
Generates:
// Objc @protocol Api2Host -(void)calculate:(nullable Value *)input completion:(void(^)(Value *_Nullable, FlutterError *_Nullable))completion; @end
// Java public interface Result<T> { void success(T result); } /** Generated interface from Pigeon that represents a handler of messages from Flutter.*/ public interface Api2Host { void calculate(Value arg, Result<Value> result); }
Pigeon supports generating null-safe code, but it doesn't yet support:
It does support:
The default is to generate null-safe code but in order to generate non-null-safe code run Pigeon with the extra argument --no-dart_null_safety
. For example: flutter pub run pigeon --input ./pigeons/messages.dart --no-dart_null_safety --dart_out stdout
.
As of version 0.2.2 Pigeon supports enum generation in class fields. For example:
enum State { pending, success, error, } class StateResult { String? errorMessage; State? state; } @HostApi() abstract class Api { StateResult queryState(); }
Prior to version 1.0 all arguments to API methods had to be wrapped in a class, now they can be used directly. For example:
@HostApi() abstract class Api { Map<String?, int?> makeMap(List<String?> keys, List<String?> values); }
File an issue in flutter/flutter with the word ‘pigeon’ clearly in the title and cc @gaaclarke.