[linux/windows] Add FlutterWindowController

Creates an initial C++ object as the primary intaction point for the
embedder calls. This provides a simpler API surface than embedder.h,
and folds in some common code (e.g., error logging).

This also serves to insulate clients from the embedder.h API layer,
so that future incremental changes done for google#230 will cause less churn
for embedders.

Author: stuartmorgan-g

example/linux_fde/flutter_embedder_example.cc

@@ -24,9 +24,9 @@
 #include <menubar/menubar_plugin.h>
 
 #ifdef USE_FLATTENED_INCLUDES
-#include <flutter_desktop_embedding/embedder.h>
+#include <flutter_desktop_embedding/flutter_window_controller.h>
 #else
-#include <flutter_desktop_embedding/glfw/embedder.h>
+#include <flutter_desktop_embedding/glfw/flutter_window_controller.h>
 #endif
 
 namespace {
@@ -53,11 +53,6 @@ std::string GetExecutableDirectory() {
 }  // namespace
 
 int main(int argc, char **argv) {
-  if (!flutter_desktop_embedding::FlutterInit()) {
-    std::cerr << "Unable to init GLFW; exiting." << std::endl;
-    return EXIT_FAILURE;
-  }
-
   // Resources are located relative to the executable.
   std::string base_directory = GetExecutableDirectory();
   if (base_directory.empty()) {
@@ -72,27 +67,27 @@ int main(int argc, char **argv) {
 #ifdef NDEBUG
   arguments.push_back("--disable-dart-asserts");
 #endif
+
+  flutter_desktop_embedding::FlutterWindowController flutter_controller(
+      icu_data_path);
+
   // Start the engine.
-  auto window = flutter_desktop_embedding::CreateFlutterWindow(
-      640, 480, assets_path, icu_data_path, arguments);
-  if (window == nullptr) {
-    flutter_desktop_embedding::FlutterTerminate();
-    std::cerr << "Unable to create Flutter window; exiting." << std::endl;
+  if (!flutter_controller.CreateWindow(640, 480, assets_path, arguments)) {
     return EXIT_FAILURE;
   }
 
   // Register any native plugins.
   plugins_menubar::MenubarPlugin::RegisterWithRegistrar(
-      flutter_desktop_embedding::GetRegistrarForPlugin(
-          window, "plugins_menubar::MenubarPlugin"));
+      flutter_controller.GetRegistrarForPlugin(
+          "plugins_menubar::MenubarPlugin"));
   plugins_color_panel::ColorPanelPlugin::RegisterWithRegistrar(
-      flutter_desktop_embedding::GetRegistrarForPlugin(
-          window, "plugins_color_panel::ColorPanelPlugin"));
+      flutter_controller.GetRegistrarForPlugin(
+          "plugins_color_panel::ColorPanelPlugin"));
   plugins_file_chooser::FileChooserPlugin::RegisterWithRegistrar(
-      flutter_desktop_embedding::GetRegistrarForPlugin(
-          window, "plugins_file_chooser::FileChooserPlugin"));
+      flutter_controller.GetRegistrarForPlugin(
+          "plugins_file_chooser::FileChooserPlugin"));
 
-  flutter_desktop_embedding::FlutterWindowLoop(window);
-  glfwTerminate();
+  // Run until the window is closed.
+  flutter_controller.RunEventLoop();
   return EXIT_SUCCESS;
 }

example/windows_fde/flutter_embedder_example.cpp

@@ -13,32 +13,32 @@
 // limitations under the License.
 
 #include <iostream>
+#include <string>
 #include <vector>
 
-#include "flutter_desktop_embedding/glfw/embedder.h"
+#include "flutter_desktop_embedding/glfw/flutter_window_controller.h"
 
 int main(int argc, char **argv) {
-  if (!flutter_desktop_embedding::FlutterInit()) {
-    std::cerr << "Unable to init GLFW; exiting." << std::endl;
-    return EXIT_FAILURE;
-  }
+  // TODO: Make paths relative to the executable so it can be run from anywhere.
+  std::string assets_path =
+      "..\\..\\example\\flutter_app\\build\\flutter_assets";
+  std::string icu_data_path =
+      "..\\..\\library\\windows\\dependencies\\engine\\icudtl.dat";
+
   // Arguments for the Flutter Engine.
   std::vector<std::string> arguments;
 #ifndef _DEBUG
   arguments.push_back("--disable-dart-asserts");
 #endif
+  flutter_desktop_embedding::FlutterWindowController flutter_controller(
+      icu_data_path);
+
   // Start the engine.
-  // TODO: Make paths relative to the executable so it can be run from anywhere.
-  auto window = flutter_desktop_embedding::CreateFlutterWindow(
-      640, 480, "..\\build\\flutter_assets",
-      "..\\..\\library\\windows\\dependencies\\engine\\icudtl.dat", arguments);
-  if (window == nullptr) {
-    flutter_desktop_embedding::FlutterTerminate();
-    std::cerr << "Unable to create Flutter window; exiting." << std::endl;
+  if (!flutter_controller.CreateWindow(640, 480, assets_path, arguments)) {
     return EXIT_FAILURE;
   }
 
-  flutter_desktop_embedding::FlutterWindowLoop(window);
-  flutter_desktop_embedding::FlutterTerminate();
+  // Run until the window is closed.
+  flutter_controller.RunEventLoop();
   return EXIT_SUCCESS;
 }

library/BUILD.gn

@@ -21,9 +21,11 @@ published_shared_library("flutter_embedder") {
   if (is_linux || is_win) {
     public = [
       "include/flutter_desktop_embedding/glfw/embedder.h",
+      "include/flutter_desktop_embedding/glfw/flutter_window_controller.h",
     ]
     sources = [
       "common/glfw/embedder.cc",
+      "common/glfw/flutter_window_controller.cc",
       "common/glfw/key_event_handler.cc",
       "common/glfw/key_event_handler.h",
       "common/glfw/keyboard_hook_handler.h",

library/common/glfw/flutter_window_controller.cc

@@ -0,0 +1,68 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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 "library/include/flutter_desktop_embedding/glfw/flutter_window_controller.h"
+
+#include <iostream>
+
+namespace flutter_desktop_embedding {
+
+FlutterWindowController::FlutterWindowController(std::string &icu_data_path)
+    : icu_data_path_(icu_data_path) {
+  init_succeeded_ = FlutterInit();
+}
+
+FlutterWindowController::~FlutterWindowController() {
+  if (init_succeeded_) {
+    FlutterTerminate();
+  }
+}
+
+bool FlutterWindowController::CreateWindow(
+    size_t width, size_t height, const std::string &assets_path,
+    const std::vector<std::string> &arguments) {
+  if (!init_succeeded_) {
+    std::cerr << "Could not create window; FlutterInit failed." << std::endl;
+    return false;
+  }
+
+  if (window_) {
+    std::cerr << "Only one Flutter window can exist at a time." << std::endl;
+    return false;
+  }
+
+  window_ = CreateFlutterWindow(width, height, assets_path, icu_data_path_,
+                                arguments);
+  if (!window_) {
+    std::cerr << "Failed to create window." << std::endl;
+    return false;
+  }
+  return true;
+}
+
+PluginRegistrar *FlutterWindowController::GetRegistrarForPlugin(
+    const std::string &plugin_name) {
+  if (!window_) {
+    return nullptr;
+  }
+  return flutter_desktop_embedding::GetRegistrarForPlugin(window_, plugin_name);
+}
+
+void FlutterWindowController::RunEventLoop() {
+  if (window_) {
+    FlutterWindowLoop(window_);
+  }
+}
+
+}  // namespace flutter_desktop_embedding

library/include/flutter_desktop_embedding/glfw/flutter_window_controller.h

@@ -0,0 +1,94 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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 LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_GLFW_FLUTTER_WINDOW_CONTROLLER_H_
+#define LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_GLFW_FLUTTER_WINDOW_CONTROLLER_H_
+
+#include <string>
+#include <vector>
+
+#include "embedder.h"
+
+#ifdef USE_FLATTENED_INCLUDES
+#include "fde_export.h"
+#include "plugin_registrar.h"
+#else
+#include "../fde_export.h"
+#include "../plugin_registrar.h"
+#endif
+
+namespace flutter_desktop_embedding {
+
+// A controller for a window displaying Flutter content.
+//
+// This is the primary wrapper class for the desktop embedding C API.
+// If you use this class, you should not call any of the setup or teardown
+// methods in embedder.h directly, as this class will do that internally.
+//
+// This class is a singleton, as Flutter does not support multiple engines in
+// one process, or multiple views in one engine.
+//
+// Note: This is an early implementation (using GLFW internally) which
+// requires control of the application's event loop, and is thus useful
+// primarily for building a simple one-window shell hosting a Flutter
+// application. The final implementation and API will be very different.
+class FDE_EXPORT FlutterWindowController {
+ public:
+  // There must be only one instance of this class in an application at any
+  // given time, as Flutter does not support multiple engines in one process,
+  // or multiple views in one engine.
+  explicit FlutterWindowController(std::string &icu_data_path);
+
+  ~FlutterWindowController();
+
+  // Creates and displays a window for displaying Flutter content.
+  //
+  // The |assets_path| is the path to the flutter_assets folder for the Flutter
+  // application to be run. |icu_data_path| is the path to the icudtl.dat file
+  // for the version of Flutter you are using.
+  //
+  // The |arguments| are passed to the Flutter engine. See:
+  // https://github.com/flutter/engine/blob/master/shell/common/switches.h for
+  // for details. Not all arguments will apply to embedding mode.
+  //
+  // There must be only one instance of this class in an application at any
+  // given time, as Flutter does not support multiple engines in one process,
+  // or multiple views in one engine.
+  bool CreateWindow(size_t width, size_t height, const std::string &assets_path,
+                    const std::vector<std::string> &arguments);
+
+  // Returns the PluginRegistrar to register a plugin with the given name.
+  //
+  // The name must be unique across the application, so the recommended approach
+  // is to use the fully namespace-qualified name of the plugin class.
+  PluginRegistrar *GetRegistrarForPlugin(const std::string &plugin_name);
+
+  // Loops on Flutter window events until termination.
+  void RunEventLoop();
+
+ private:
+  // The path to the ICU data file. Set at creation time since it is the same
+  // for any window created.
+  std::string icu_data_path_;
+
+  // Whether or not FlutterInit succeeded at creation time.
+  bool init_succeeded_ = false;
+
+  // The curent Flutter window, if any.
+  GLFWwindow *window_ = nullptr;
+};
+
+}  // namespace flutter_desktop_embedding
+
+#endif  // LIBRARY_INCLUDE_FLUTTER_DESKTOP_EMBEDDING_GLFW_FLUTTER_WINDOW_CONTROLLER_H_