[pigeon] updated the docs for 1.0 (#420)
diff --git a/packages/pigeon/CHANGELOG.md b/packages/pigeon/CHANGELOG.md
index 8466f88..2513418 100644
--- a/packages/pigeon/CHANGELOG.md
+++ b/packages/pigeon/CHANGELOG.md
@@ -1,18 +1,21 @@
## NEXT
-* [front-end] Added a more explicit error if generic fields are used.
-* [front-end] Added a more explicit error for static fields.
-* [front-end] Added more errors for incorrect usage of Pigeon (previously they were just ignored).
-* Moved Pigeon to using a custom codec which allows collection types to contain custom classes.
* Started allowing primitive data types as arguments and return types.
-* Added one_language flag for allowing Pigeon to only generate code for one platform.
-* Fixed NPE in java generated code for nested types.
-* Started supporting generics' type arguments for fields in classes.
-* Generics (class fields and primitives)
-* Added the optional sdkPath parameter for specifying Dart SDK path.
-* Arity > 1 function support.
-* BREAKING CHANGE: logic for generating Objc selectors has changed.
- `void add(Input value)` will now translate to `-(void)addValue:(Input*)value`.
+* Generics support.
+* Support for functions with more than one argument.
+* [command-line] Added `one_language` flag for allowing Pigeon to only generate
+ code for one platform.
+* [command-line] Added the optional sdkPath parameter for specifying Dart SDK
+ path.
+* [front-end] Added more errors for incorrect usage of Pigeon (previously they
+ were just ignored).
+* [generators] Moved Pigeon to using a custom codec which allows collection
+ types to contain custom classes.
+* [java] Fixed NPE in Java generated code for nested types.
+* [objc] BREAKING CHANGE: logic for generating Objective-C selectors has
+ changed. `void add(Input value)` will now translate to
+ `-(void)addValue:(Input*)value`, methods with no arguments will translate to
+ `...WithError:` or `...WithCompletion:`.
## 0.3.0
diff --git a/packages/pigeon/README.md b/packages/pigeon/README.md
index 4292c03..f9cc130 100644
--- a/packages/pigeon/README.md
+++ b/packages/pigeon/README.md
@@ -1,9 +1,7 @@
# 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.
+host platform type-safe, easier and faster.
## Supported Platforms
@@ -24,8 +22,9 @@
1) Add Pigeon as a dev_dependency.
1) Make a ".dart" file outside of your "lib" directory for defining the communication interface.
-1) Run pigeon on your ".dart" file to generate the required Dart and Objective-C code:
- `flutter pub get` then `flutter pub run pigeon` with suitable arguments.
+1) Run pigeon on your ".dart" file to generate the required Dart and Objective-C
+ code: `flutter pub get` then `flutter pub run pigeon` with suitable arguments
+ (see [example](./example)).
1) Add the generated Dart code to `lib` for compilation.
1) Add the generated Objective-C code to your Xcode project for compilation
(e.g. `ios/Runner.xcworkspace` or `.podspec`).
@@ -38,37 +37,42 @@
1) Add Pigeon as a dev_dependency.
1) Make a ".dart" file outside of your "lib" directory for defining the communication interface.
1) Run pigeon on your ".dart" file to generate the required Dart and Java code.
- `flutter pub get` then `flutter pub run pigeon` with suitable arguments.
+ `flutter pub get` then `flutter pub run pigeon` with suitable arguments
+ (see [example](./example)).
1) Add the generated Dart code to `./lib` for compilation.
1) Add the generated Java code to your `./android/app/src/main/java` directory for compilation.
1) Implement the generated Java interface for handling the calls on Android, set it up
as the handler for the messages.
1) Call the generated Dart methods.
+### Calling into Flutter from the host platform
+
+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.
+
### Rules for defining your communication interface
1) The file should contain no method or function definitions, only declarations.
-1) Datatypes are defined as classes with fields of the supported datatypes (see
- the supported Datatypes section).
-1) Api's should be defined as an `abstract class` with either `HostApi()` or
+1) Custom classes used by APIs are defined as classes with fields of the
+ supported datatypes (see the supported Datatypes section).
+1) APIs 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.
-1) 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](https://github.com/flutter/plugins/tree/master/packages/video_player).
+1) Method declarations on the API classes should have arguments and a return
+ value whose types are defined in the file, are supported datatypes, or are
+ `void`.
+1) Generics are supported, but can currently only be used with nullable types
+ (example: `List<int?>`).
+1) Fields on classes currently must be nullable, arguments and return values to
+ methods must be non-nullable.
## Supported Datatypes
-Pigeon uses the `StandardMessageCodec` so it supports any data-type platform
-channels supports
+Pigeon uses the `StandardMessageCodec` so it supports any datatype Platform
+Channels supports
[[documentation](https://flutter.dev/docs/development/platform-integration/platform-channels#codec)].
-Nested data-types are supported, too.
-
-Note: Generics for List and Map aren't supported yet.
+Nested datatypes are supported, too.
## Features
@@ -125,7 +129,8 @@
### Enums
-As of version 0.2.2 Pigeon supports enum generation. For example:
+As of version 0.2.2 Pigeon supports enum generation in class fields. For
+example:
```dart
enum State {
pending,
@@ -144,36 +149,17 @@
}
```
-Generates on Dart, Java, Objective-C:
+### Primitive Data-types
+
+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:
+
```dart
-enum State {
- pending,
- success,
- error,
+@HostApi()
+abstract class Api {
+ Map<String?, int?> makeMap(List<String?> keys, List<String?> values);
}
```
-```java
-public enum State {
- pending(0),
- success(1),
- error(2);
-
- private int index;
- private State(final int index) {
- this.index = index;
- }
-}
-```
-
-```objc
-typedef NS_ENUM(NSUInteger, State) {
- StatePending = 0,
- StateSuccess = 1,
- StateError = 2,
-};
-```
-
## Feedback
File an issue in [flutter/flutter](https://github.com/flutter/flutter) with the
diff --git a/packages/pigeon/example/README.md b/packages/pigeon/example/README.md
index a6d18e3..41bf517 100644
--- a/packages/pigeon/example/README.md
+++ b/packages/pigeon/example/README.md
@@ -13,23 +13,20 @@
```dart
import 'package:pigeon/pigeon.dart';
-class SearchRequest {
- String? query;
-}
-
-class SearchReply {
- String? result;
+class Book {
+ String? title;
+ String? author;
}
@HostApi()
-abstract class Api {
- SearchReply search(SearchRequest request);
+abstract class BookApi {
+ List<Book?> search(String keyword);
}
```
### invocation
-This is the call to Pigeon that will injest `message.dart` and generate the code
+This is the call to Pigeon that will ingest `message.dart` and generate the code
for iOS and Android.
```sh
@@ -44,7 +41,7 @@
### AppDelegate.m
-This is the code that will use the generated Objective-C code to recieve calls
+This is the code that will use the generated Objective-C code to receive calls
from Flutter.
```objc
@@ -52,24 +49,27 @@
#import <Flutter/Flutter.h>
#import "pigeon.h"
-@interface MyApi : NSObject <Api>
+@interface MyApi : NSObject <BookApi>
@end
@implementation MyApi
--(SearchReply*)search:(SearchRequest*)request error:(FlutterError **)error {
- SearchReply *reply = [[SearchReply alloc] init];
- reply.result =
- [NSString stringWithFormat:@"Hi %@!", request.query];
- return reply;
+-(NSArray<Book *> *)searchKeyword:(NSString *)keyword error:(FlutterError **)error {
+ Book *result = [[Book alloc] init];
+ result.title =
+ [NSString stringWithFormat:@"%@'s Life", request.query];
+ result.author = keyword;
+ return @[ result ];
}
@end
+@implementation AppDelegate
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey, id> *)launchOptions {
MyApi *api = [[MyApi alloc] init];
- ApiSetup(getFlutterEngine().binaryMessenger, api);
+ BookApiSetup(getFlutterEngine().binaryMessenger, api);
return YES;
}
+@end
```
### StartActivity.java
@@ -77,20 +77,22 @@
This is the code that will use the generated Java code to receive calls from Flutter.
```java
-import dev.flutter.pigeon.Pigeon;
+import dev.flutter.pigeon.Pigeon.*;
+import java.util.Collections;
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;
+ private class MyApi implements BookApi {
+ List<Book> search(String keyword) {
+ Book result = new Book();
+ result.author = keyword;
+ result.title = String.format("%s's Life", keyword);
+ return Collections.singletonList(result)
}
}
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
- Pigeon.SetupApi(getBinaryMessenger(), new MyApi());
+ BookApi.setup(getBinaryMessenger(), new MyApi());
}
}
```
@@ -105,10 +107,9 @@
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!"));
+ List<Book?> reply = await api.search("Aaron");
+ expect(reply[0].title, equals("Aaron's Life"));
});
}
@@ -124,3 +125,8 @@
A full example of using Pigeon for add-to-app with Swift on iOS can be found at
[samples/add_to_app/books](https://github.com/flutter/samples/tree/master/add_to_app/books).
+
+## Video player plugin
+
+A full real-world example can also be found in the
+[video_player plugin](https://github.com/flutter/plugins/tree/master/packages/video_player).
