[pigeon] Better documentation for @FlutterApi usage

[knaeckeKami]

Use case

The documentation and example of pigeon describe the usage of @HostApi, which is used to call into native code from flutter.
But Pigeon also supports @FlutterApi, which enables the native code to call into Flutter code, typically used for Steam-like updates that are not initiated from the Flutter side, but from the OS/native side.
This feature is not mentioned only briefly in the README and there are no examples that showcase it.

Proposal

Pigeon should have better documentation for@FlutterApi in the README and either add an example project or at least link to a third-party package that uses it.

In a quick search I only found these third-party projects using it:

• https://github.com/fluttercandies/ff_native_screenshot/ simple package for listening to native screenshots, good candidate IMO
• https://github.com/zero-li/flutter_pigeon_plugin very minimal example project using @FlutterApi, would be a good candidate but the documentation is in Chinese
• https://gitlab.com/twilio-flutter/conversations complex-ish package using @FlutterApi

[danagbemava-nc]

But Pigeon also supports @FlutterApi, which enables the native code to call into Flutter code, typically used for Steam-like updates that are not initiated from the Flutter side, but from the OS/native side.
This feature is not mentioned in the README and there are no examples that showcase it.

This isn't entirely accurate. See https://pub.dev/packages/pigeon#calling-into-flutter-from-the-host-platform

Nonetheless, more documentation is always good.

[knaeckeKami]

Sorry, yeah, I missed that. I updated the issue.

[ghost]

Yes, that Twilio example is pretty good. On my host (iOS Swift) side I was doing flutterApi = MyPluginFlutterApi(), when I should have been doing:

flutterApi = MyPluginFlutterApi(binaryMessenger: registrar.messenger())

and therefore nothing was getting called on the Flutter side! (Going over the Twilio example pointed that out to me, but a quick README example would have been much faster/easier to find.) The generated Pigeon code allows me to instantiate the FlutterApi without a binary messenger, which was why it wasn't working -- binaryMessenger should really be a required argument. (Maybe not for mocking, but then why not then just require a mocked messenger?)

And had to figure out how to extend the MyPluginFlutterApi on the Dart side as well. But there, it uses the default binary messenger in Flutter -- but it obviously can't do that on the host side and needs to be instantiated with it. In both places, it needs to be "setup", which a quick example would really help with as well:

MyPluginFlutterApi.setup(MyPluginFlutterApiImpl(instance: this));

Pigeon is amazing! Respectfully, I would not regard the small paragraph stating one can use @FlutterApi "...The steps are similar but reversed...." as, "documentation." Please provide brief, simple examples for the @FlutterApi similar to the ones for @HostApi so we know what to do -- and so all your hard work on this framework gets fulfilled when people see how much easier it really is than dealing with channels directly. Would be great (easy?) to even just add a host-to-Flutter method sending a value to the existing examples, with a comment that it is optional or something.

[daniloapr]

Pigeon is really amazing and easy to use, but its poor documentation makes it very tricky. I just created a plugin a found multiple issues that were not touched by the documentation. Even the example repository provided is not up to date, implementing the version 1.0.0 while pigeon is already in 4.2.5.

Note that lots of Flutter devs don't have experience with native code, so more complete examples would be much appreciated.

[Sri-Kumaran-DR]

checkout this blog for more info on using @FlutterApi()

[learncodingforweb]

I am also not able to do native to flutter communication on android using java.
Please provide example code, how use @FlutterApi with android java?

[andreisas06]

@learncodingforweb The webview_flutter plugin uses Pigeon. I was learning myself how to use it and found this a great example to learn from.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.