Pigeon is a code generator tool to make communication between Flutter and the host platform type-safe, easier, and faster.
Pigeon removes the necessity to manage strings across multiple platforms and languages. It also improves efficiency over common method channel patterns. Most importantly though, it removes the need to write custom platform channel code, since pigeon generates it for you.
For usage examples, see the Example README.
Currently pigeon supports generating:
Pigeon uses the StandardMessageCodec
so it supports any datatype platform channels support.
Custom classes, nested datatypes, and enums are also supported.
Basic inheritance with empty sealed
parent classes is allowed only in the Swift, Kotlin, and Dart generators.
Nullable enums in Objective-C generated code will be wrapped in a class to allow for nullability.
By default, custom classes in Swift are defined as structs. Structs don't support some features - recursive data, or Objective-C interop. Use the @SwiftClass annotation when defining the class to generate the data as a Swift class instead.
While all calls across platform channel APIs (such as pigeon methods) are asynchronous, pigeon methods can be written on the native side as synchronous methods, to make it simpler to always reply exactly once.
If asynchronous methods are needed, the @async
annotation can be used. This will require results or errors to be returned via a provided callback. Example.
All Host API exceptions are translated into Flutter PlatformException
.
To pass custom details into PlatformException
for error handling, use FlutterError
in your Host API. Example.
For swift, use PigeonError
instead of FlutterError
when throwing an error. See Example#Swift for more details.
Host API errors can be sent using the provided FlutterError
class (translated into PlatformException
).
For synchronous methods:
error
argument to a FlutterError
reference.FlutterError
.For async methods:
FlutterError
through the provided callback.When targeting a Flutter version that supports the TaskQueue API the threading model for handling HostApi methods can be selected with the TaskQueue
annotation.
Host and Flutter APIs now support the ability to provide a unique message channel suffix string to the api to allow for multiple instances to be created and operate in parallel.
dev_dependency
.flutter pub get
then dart run pigeon
with suitable arguments. Example../lib
for compilation.abstract class
with either @HostApi()
or @FlutterApi()
as metadata. @HostApi()
being for procedures that are defined on the host platform and the @FlutterApi()
for procedures that are defined in Dart.void
.abstract class
with the metadata @EventChannelApi
.Stream
return type, just the type that is being streamed.@ObjCSelector
and @SwiftFunction
respectively.ios/Runner.xcworkspace
or .podspec
)../android/app/src/main/java
directory for compilation../windows
directory for compilation, and to your windows/CMakeLists.txt
file.macos/Runner.xcworkspace
or .podspec
)../linux
directory for compilation, and to your linux/CMakeLists.txt
file.Pigeon 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. Example.
Pigeon is intended to replace direct use of method channels in the internal implementation of plugins and applications. Because the expected use of Pigeon is as an internal implementation detail, its development strongly favors improvements to generated code over consistency with previous generated code, so breaking changes in generated code are common.
As a result, using Pigeon-generated code in public APIs is strongy discouraged, as doing so will likely create situations where you are unable to update to a new version of Pigeon without causing breaking changes for your clients.
The generated message channel code used for Pigeon communication is an internal implementation detail of Pigeon that is subject to change without warning, and changes to the communication are not considered breaking changes. Both sides of the communication (the Dart code and the host-language code) must be generated with the same version of Pigeon. Using code generated with different versions has undefined behavior, including potentially crashing the application.
This means that Pigeon-generated code should not be split across packages. For example, putting the generated Dart code in a platform interface package and the generated host-language code in a platform implementation package is very likely to cause crashes for some plugin clients after updates.
File an issue in flutter/flutter with “[pigeon]” at the start of the title.