Flutter Engine
flutter_engine.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_SHELL_PLATFORM_WINDOWS_CLIENT_WRAPPER_INCLUDE_FLUTTER_FLUTTER_ENGINE_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_CLIENT_WRAPPER_INCLUDE_FLUTTER_FLUTTER_ENGINE_H_
7 
8 #include <flutter_windows.h>
9 
10 #include <chrono>
11 #include <memory>
12 #include <string>
13 
14 #include "binary_messenger.h"
15 #include "dart_project.h"
16 #include "plugin_registrar.h"
17 #include "plugin_registry.h"
18 
19 namespace flutter {
20 
21 // An instance of a Flutter engine.
22 //
23 // In the future, this will be the API surface used for all interactions with
24 // the engine, rather than having them duplicated on FlutterViewController.
25 // For now it is only used in the rare where you need a headless Flutter engine.
26 class FlutterEngine : public PluginRegistry {
27  public:
28  // Creates a new engine for running the given project.
29  explicit FlutterEngine(const DartProject& project);
30 
31  virtual ~FlutterEngine();
32 
33  // Prevent copying.
34  FlutterEngine(FlutterEngine const&) = delete;
35  FlutterEngine& operator=(FlutterEngine const&) = delete;
36 
37  // Starts running the engine, with an optional entry point.
38  //
39  // If provided, entry_point must be the name of a top-level function from the
40  // same Dart library that contains the app's main() function, and must be
41  // decorated with `@pragma(vm:entry-point)` to ensure the method is not
42  // tree-shaken by the Dart compiler. If not provided, defaults to main().
43  bool Run(const char* entry_point = nullptr);
44 
45  // Terminates the running engine.
46  void ShutDown();
47 
48  // Processes any pending events in the Flutter engine, and returns the
49  // nanosecond delay until the next scheduled event (or max, if none).
50  //
51  // This should be called on every run of the application-level runloop, and
52  // a wait for native events in the runloop should never be longer than the
53  // last return value from this function.
54  std::chrono::nanoseconds ProcessMessages();
55 
56  // Tells the engine that the system font list has changed. Should be called
57  // by clients when OS-level font changes happen (e.g., WM_FONTCHANGE in a
58  // Win32 application).
59  void ReloadSystemFonts();
60 
61  // flutter::PluginRegistry:
63  const std::string& plugin_name) override;
64 
65  // Returns the messenger to use for creating channels to communicate with the
66  // Flutter engine.
67  //
68  // This pointer will remain valid for the lifetime of this instance.
69  BinaryMessenger* messenger() { return messenger_.get(); }
70 
71  private:
72  // For access to RelinquishEngine.
73  friend class FlutterViewController;
74 
75  // Gives up ownership of |engine_|, but keeps a weak reference to it.
76  //
77  // This is intended to be used by FlutterViewController, since the underlying
78  // C API for view controllers takes over engine ownership.
79  FlutterDesktopEngineRef RelinquishEngine();
80 
81  // Handle for interacting with the C API's engine reference.
82  FlutterDesktopEngineRef engine_ = nullptr;
83 
84  // Messenger for communicating with the engine.
85  std::unique_ptr<BinaryMessenger> messenger_;
86 
87  // Whether or not this wrapper owns |engine_|.
88  bool owns_engine_ = true;
89 
90  // Whether the engine has been run. This will be true if Run has been called,
91  // or if RelinquishEngine has been called (since the view controller will
92  // run the engine if it hasn't already been run).
93  bool has_been_run_ = false;
94 };
95 
96 } // namespace flutter
97 
98 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_CLIENT_WRAPPER_INCLUDE_FLUTTER_FLUTTER_ENGINE_H_
BinaryMessenger * messenger()
FlutterDesktopPluginRegistrarRef GetRegistrarForPlugin(const std::string &plugin_name) override
FlutterEngine & operator=(FlutterEngine const &)=delete
bool Run(const char *entry_point=nullptr)
std::chrono::nanoseconds ProcessMessages()