Overhaul example plugin, and rename it 'sample' (#654)

Renames the plugin from 'example_plugin' to 'sample' so that the naming is consistent with all the actual plugins (which have 'plugin' in the class name, but not the actual plugin name). Also makes various improvements to the sample code and documentation, as described in the associated bug. Fixes #648
google · Jan 29, 2020 · 1eac306 · 1eac306
1 parent 7a6897c
commit 1eac306
Show file tree

Hide file tree

Showing 29 changed files with 287 additions and 298 deletions.
diff --git a/plugins/README.md b/plugins/README.md
@@ -5,7 +5,7 @@ page](https://github.com/flutter/flutter/wiki/Desktop-shells#plugins)
 for an overview of the current state of plugin development on desktop.
 
 This directory contains three types of plugins:
-* `example_plugin`, which like `example/` will eventually be replaced by
+* `sample`, which like `example/` will eventually be replaced by
   `flutter create -t plugin` support for desktop.
 * `flutter_plugins`, which contain Windows and Linux implementations of plugins
   from [the flutter/plugins repository](https://github.com/flutter/plugins)
@@ -33,8 +33,8 @@ pubspec.yaml. For example:
 ```
 dependencies:
   ...
-  example_plugin:
-    path: relative/path/to/plugins/example_plugin
+  sample:
+    path: relative/path/to/plugins/sample
 ```
 
 (On macOS, you can use a [git
@@ -43,7 +43,7 @@ instead of referencing a local copy.)
 
 Then import it in your dart code as you would any other package:
 ```dart
-import 'package:example_plugin/example_plugin.dart';
+import 'package:sample/sample.dart';
 ```
 
 This step does not apply to `flutter_plugins` plugins, as the
@@ -132,9 +132,9 @@ headers.
 ## Writing Your Own Plugins
 
 You can create plugin packages following the model of the Windows and Linux
-plugins here to use in your own projects. In particular, `example_plugin`
+plugins here to use in your own projects. In particular, `sample`
 is intended to serve as a starting point for new plugins; see
-[its README](example_plugin/README.md) for details. For macOS,
+[its README](sample/README.md) for details. For macOS,
 you should use `flutter create` as usual.
 
 Keep in mind the notes about API stability on the Flutter desktop page

diff --git a/plugins/example_plugin/.gitignore b/plugins/example_plugin/.gitignore
diff --git a/plugins/example_plugin/README.md b/plugins/example_plugin/README.md
diff --git a/plugins/example_plugin/pubspec.yaml b/plugins/example_plugin/pubspec.yaml
diff --git a/plugins/sample/.gitignore b/plugins/sample/.gitignore
@@ -0,0 +1,5 @@
+.dart_tool
+.packages
+.flutter-plugins
+.flutter-plugins-dependencies
+pubspec.lock
diff --git a/plugins/example_plugin/LICENSE → plugins/sample/LICENSE b/plugins/example_plugin/LICENSE → plugins/sample/LICENSE
diff --git a/plugins/sample/README.md b/plugins/sample/README.md
@@ -0,0 +1,41 @@
+# sample_plugin
+
+This is intended to serve as a starting point for writing your own Windows
+and/or Linux plugin, since `flutter create` does not yet support Windows
+or Linux.
+
+Before continuing, read [the main plugins README](../README.md) if you haven't already.
+
+## Use
+
+- To create an entirely new plugin, or a federated Windows/Linux implementation
+  of an existing plugin, copy the entire `sample` directory.
+  - Update the `pubspec.yaml` as normal for a plugin. Look for comments
+    containing `***` and update those entries as described in the comment.
+  - Delete the directories for any platforms you aren't supporting.
+- To add desktop support directly to an existing plugin, copy the `windows`
+  and/or `linux` directories into that plugin.
+  - Update the plugin's `pubspec.yaml` to include the new platforms.
+    If you haven't already, you'll need to switch to the new `plugins:`
+    format, as the legacy declaration doesn't support desktop.
+
+**WARNING**: The plugin APIs, plugin tooling, and plugin structure for
+Windows and Linux **are not at all stable**. Plugins created using this
+sample are subject to breakage at any time, and will need to be updated
+any time any of those things change. This means you **should not publish
+Windows or Linux plugins to pub.dev** as anything published now will
+almost certainly not work with the final Flutter Windows and Linux support.
+
+### Windows
+
+- Change `sample` in all the filenames to your plugin's name.
+- Change the `FlutterPluginName` in `PluginInfo.props` to your plugin's name.
+- Look for comments containing `***` in the `.h` and `.cpp` file, and update
+  the code as described in the comment.
+
+### Linux
+
+- Rename `sample` in all the file names with your plugin's name.
+- Change the `PLUGIN_NAME` in the `Makefile` to your plugin's name.
+- Look for comments containing `***` in the `.h` and `.cc` file, and update
+  the code as described in the comment.
diff --git a/...ns/example_plugin/lib/example_plugin.dart → plugins/sample/lib/sample.dart b/...ns/example_plugin/lib/example_plugin.dart → plugins/sample/lib/sample.dart
@@ -2,9 +2,9 @@ import 'dart:async';
 
 import 'package:flutter/services.dart';
 
-class ExamplePlugin {
+class Sample {
   static const MethodChannel _channel =
-      const MethodChannel('example_plugin');
+      const MethodChannel('sample_plugin');
 
   static Future<String> get platformVersion async {
     final String version = await _channel.invokeMethod('getPlatformVersion');

diff --git a/plugins/example_plugin/linux/Makefile → plugins/sample/linux/Makefile b/plugins/example_plugin/linux/Makefile → plugins/sample/linux/Makefile
@@ -17,9 +17,10 @@
 # the values that are mostly likely to need to be changed.
 
 # The name of the plugin.
-# The primary source file is assumed to be $(PLUGIN_NAME).cc, with
-# $(PLUGIN_NAME).h as the public header meant for inclusion by the application.
-PLUGIN_NAME=example_plugin
+# The primary source file is assumed to be $(PLUGIN_NAME)_plugin.cc, with
+# $(PLUGIN_NAME)_plugin.h as the public header meant for inclusion by the
+# application.
+PLUGIN_NAME=sample
 # Any files other than the plugin class files that need to be compiled.
 EXTRA_SOURCES=
 # Extra flags (e.g., for library dependencies).
@@ -66,8 +67,8 @@ WRAPPER_SOURCES= \
 
 # Use abspath for extra sources, which may also contain relative paths (see
 # note above about WRAPPER_ROOT).
-SOURCES=$(PLUGIN_NAME).cc $(WRAPPER_SOURCES) $(abspath $(EXTRA_SOURCES))
-PUBLIC_HEADER=$(PLUGIN_NAME).h
+SOURCES=$(PLUGIN_NAME)_plugin.cc $(WRAPPER_SOURCES) $(abspath $(EXTRA_SOURCES))
+PUBLIC_HEADER=$(PLUGIN_NAME)_plugin.h
 
 WRAPPER_INCLUDE_DIR=$(WRAPPER_ROOT)/include
 INCLUDE_DIRS=$(FLUTTER_EPHEMERAL_DIR) $(WRAPPER_INCLUDE_DIR)
@@ -81,7 +82,7 @@ CPPFLAGS=$(patsubst %,-I%,$(INCLUDE_DIRS)) $(EXTRA_CPPFLAGS)
 LDFLAGS=-shared -L$(FLUTTER_EPHEMERAL_DIR) -l$(FLUTTER_LIB_NAME) $(EXTRA_LDFLAGS)
 
 # Final output files that will be used by applications.
-LIBRARY_OUT=$(OUT_DIR)/lib$(PLUGIN_NAME).so
+LIBRARY_OUT=$(OUT_DIR)/lib$(PLUGIN_NAME)_plugin.so
 HEADER_OUT=$(OUT_DIR)/include/$(PUBLIC_HEADER)
 
 # Intermediate files.

diff --git a/...ns/example_plugin/linux/example_plugin.cc → plugins/sample/linux/sample_plugin.cc b/...ns/example_plugin/linux/example_plugin.cc → plugins/sample/linux/sample_plugin.cc
@@ -11,64 +11,66 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-#include "example_plugin.h"
+#include "sample_plugin.h"
 
 #include <flutter/method_channel.h>
-#include <flutter/plugin_registrar.h>
+#include <flutter/plugin_registrar_glfw.h>
 #include <flutter/standard_method_codec.h>
 #include <sys/utsname.h>
+
+#include <map>
 #include <memory>
 #include <sstream>
 
 namespace {
 
-class ExamplePlugin : public flutter::Plugin {
+// *** Rename this class to match the linux pluginClass in your pubspec.yaml.
+class SamplePlugin : public flutter::Plugin {
  public:
-  static void RegisterWithRegistrar(flutter::PluginRegistrar *registrar);
+  static void RegisterWithRegistrar(flutter::PluginRegistrarGlfw *registrar);
 
-  // Creates a plugin that communicates on the given channel.
-  ExamplePlugin(
-      std::unique_ptr<flutter::MethodChannel<flutter::EncodableValue>> channel);
+  SamplePlugin();
 
-  virtual ~ExamplePlugin();
+  virtual ~SamplePlugin();
 
  private:
-  // Called when a method is called on |channel_|;
+  // Called when a method is called on this plugin's channel from Dart.
   void HandleMethodCall(
       const flutter::MethodCall<flutter::EncodableValue> &method_call,
       std::unique_ptr<flutter::MethodResult<flutter::EncodableValue>> result);
-
-  // The MethodChannel used for communication with the Flutter engine.
-  std::unique_ptr<flutter::MethodChannel<flutter::EncodableValue>> channel_;
 };
 
 // static
-void ExamplePlugin::RegisterWithRegistrar(flutter::PluginRegistrar *registrar) {
+void SamplePlugin::RegisterWithRegistrar(
+    flutter::PluginRegistrarGlfw *registrar) {
+  // *** Replace the "getPlatformVersion" check with your plugin's method names.
+  // See:
+  // https://github.com/flutter/engine/tree/master/shell/platform/common/cpp/client_wrapper/include/flutter
+  // and
+  // https://github.com/flutter/engine/tree/master/shell/platform/glfw/client_wrapper/include/flutter
+  // for the relevant Flutter APIs.
   auto channel =
       std::make_unique<flutter::MethodChannel<flutter::EncodableValue>>(
-          registrar->messenger(), "example_plugin",
+          registrar->messenger(), "sample_plugin",
           &flutter::StandardMethodCodec::GetInstance());
-  auto *channel_pointer = channel.get();
+  auto plugin = std::make_unique<SamplePlugin>();
 
-  auto plugin = std::make_unique<ExamplePlugin>(std::move(channel));
-
-  channel_pointer->SetMethodCallHandler(
+  channel->SetMethodCallHandler(
       [plugin_pointer = plugin.get()](const auto &call, auto result) {
         plugin_pointer->HandleMethodCall(call, std::move(result));
       });
 
   registrar->AddPlugin(std::move(plugin));
 }
 
-ExamplePlugin::ExamplePlugin(
-    std::unique_ptr<flutter::MethodChannel<flutter::EncodableValue>> channel)
-    : channel_(std::move(channel)) {}
+SamplePlugin::SamplePlugin() {}
 
-ExamplePlugin::~ExamplePlugin(){};
+SamplePlugin::~SamplePlugin() {}
 
-void ExamplePlugin::HandleMethodCall(
+void SamplePlugin::HandleMethodCall(
     const flutter::MethodCall<flutter::EncodableValue> &method_call,
     std::unique_ptr<flutter::MethodResult<flutter::EncodableValue>> result) {
+  // *** Replace the "getPlatformVersion" check with your plugin's method names.
   if (method_call.method_name().compare("getPlatformVersion") == 0) {
     struct utsname uname_data = {};
     uname(&uname_data);
@@ -83,11 +85,15 @@ void ExamplePlugin::HandleMethodCall(
 
 }  // namespace
 
-void ExamplePluginRegisterWithRegistrar(
+void SamplePluginRegisterWithRegistrar(
     FlutterDesktopPluginRegistrarRef registrar) {
-  // The plugin registrar owns the plugin, registered callbacks, etc., so must
-  // remain valid for the life of the application.
-  static auto *plugin_registrar = new flutter::PluginRegistrar(registrar);
-
-  ExamplePlugin::RegisterWithRegistrar(plugin_registrar);
+  // The plugin registrar wrappers owns the plugins, registered callbacks, etc.,
+  // so must remain valid for the life of the application.
+  static auto *plugin_registrars =
+      new std::map<FlutterDesktopPluginRegistrarRef,
+                   std::unique_ptr<flutter::PluginRegistrarGlfw>>;
+  auto insert_result = plugin_registrars->emplace(
+      registrar, std::make_unique<flutter::PluginRegistrarGlfw>(registrar));
+
+  SamplePlugin::RegisterWithRegistrar(insert_result.first->second.get());
 }
diff --git a/...ins/example_plugin/linux/example_plugin.h → plugins/sample/linux/sample_plugin.h b/...ins/example_plugin/linux/example_plugin.h → plugins/sample/linux/sample_plugin.h
@@ -11,8 +11,10 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-#ifndef PLUGINS_EXAMPLE_LINUX_EXAMPLE_PLUGIN_H_
-#define PLUGINS_EXAMPLE_LINUX_EXAMPLE_PLUGIN_H_
+
+// *** Replace SAMPLE with your plugin's name here.
+#ifndef FLUTTER_PLUGIN_SAMPLE_H_
+#define FLUTTER_PLUGIN_SAMPLE_H_
 
 #include <flutter_plugin_registrar.h>
 
@@ -26,11 +28,12 @@
 extern "C" {
 #endif
 
-FLUTTER_PLUGIN_EXPORT void ExamplePluginRegisterWithRegistrar(
+// *** Replace Sample with your plugin's name here.
+FLUTTER_PLUGIN_EXPORT void SamplePluginRegisterWithRegistrar(
     FlutterDesktopPluginRegistrarRef registrar);
 
 #if defined(__cplusplus)
 }  // extern "C"
 #endif
 
-#endif  // PLUGINS_EXAMPLE_LINUX_EXAMPLE_PLUGIN_H_
+#endif  // FLUTTER_PLUGIN_SAMPLE_H_
diff --git a/..._plugin/macos/Classes/ExamplePlugin.swift → ...s/sample/macos/Classes/SamplePlugin.swift b/..._plugin/macos/Classes/ExamplePlugin.swift → ...s/sample/macos/Classes/SamplePlugin.swift
@@ -15,10 +15,10 @@
 import Cocoa
 import FlutterMacOS
 
-public class ExamplePlugin: NSObject, FlutterPlugin {
+public class SamplePlugin: NSObject, FlutterPlugin {
   public static func register(with registrar: FlutterPluginRegistrar) {
-    let channel = FlutterMethodChannel(name: "example_plugin", binaryMessenger: registrar.messenger)
-    let instance = ExamplePlugin()
+    let channel = FlutterMethodChannel(name: "sample_plugin", binaryMessenger: registrar.messenger)
+    let instance = SamplePlugin()
     registrar.addMethodCallDelegate(instance, channel: channel)
   }