Flutter Windows Embedder
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 <optional>
13 #include <string>
14 
15 #include "binary_messenger.h"
16 #include "dart_project.h"
17 #include "plugin_registrar.h"
18 #include "plugin_registry.h"
19 
20 namespace flutter {
21 
22 // An instance of a Flutter engine.
23 //
24 // In the future, this will be the API surface used for all interactions with
25 // the engine, rather than having them duplicated on FlutterViewController.
26 // For now it is only used in the rare case where you need a headless Flutter
27 // engine.
28 class FlutterEngine : public PluginRegistry {
29  public:
30  // Creates a new engine for running the given project.
31  explicit FlutterEngine(const DartProject& project);
32 
33  virtual ~FlutterEngine();
34 
35  // Prevent copying.
36  FlutterEngine(FlutterEngine const&) = delete;
37  FlutterEngine& operator=(FlutterEngine const&) = delete;
38 
39  // Starts running the engine at the entrypoint function specified in the
40  // DartProject used to configure the engine, or main() by default.
41  bool Run();
42 
43  // Starts running the engine, with an optional entry point.
44  //
45  // If provided, entry_point must be the name of a top-level function from the
46  // same Dart library that contains the app's main() function, and must be
47  // decorated with `@pragma(vm:entry-point)` to ensure the method is not
48  // tree-shaken by the Dart compiler. If not provided, defaults to main().
49  bool Run(const char* entry_point);
50 
51  // Terminates the running engine.
52  void ShutDown();
53 
54  // Processes any pending events in the Flutter engine, and returns the
55  // nanosecond delay until the next scheduled event (or max, if none).
56  //
57  // This should be called on every run of the application-level runloop, and
58  // a wait for native events in the runloop should never be longer than the
59  // last return value from this function.
60  std::chrono::nanoseconds ProcessMessages();
61 
62  // Tells the engine that the system font list has changed. Should be called
63  // by clients when OS-level font changes happen (e.g., WM_FONTCHANGE in a
64  // Win32 application).
65  void ReloadSystemFonts();
66 
67  // Tells the engine that the platform brightness value has changed. Should be
68  // called by clients when OS-level theme changes happen (e.g.,
69  // WM_DWMCOLORIZATIONCOLORCHANGED in a Win32 application).
71 
72  // flutter::PluginRegistry:
74  const std::string& plugin_name) override;
75 
76  // Returns the messenger to use for creating channels to communicate with the
77  // Flutter engine.
78  //
79  // This pointer will remain valid for the lifetime of this instance.
80  BinaryMessenger* messenger() { return messenger_.get(); }
81 
82  // Schedule a callback to be called after the next frame is drawn.
83  //
84  // This must be called from the platform thread. The callback is executed only
85  // once on the platform thread.
86  void SetNextFrameCallback(std::function<void()> callback);
87 
88  // Called to pass an external window message to the engine for lifecycle
89  // state updates. Non-Flutter windows must call this method in their WndProc
90  // in order to be included in the logic for application lifecycle state
91  // updates. Returns a result if the message should be consumed.
92  std::optional<LRESULT> ProcessExternalWindowMessage(HWND hwnd,
93  UINT message,
94  WPARAM wparam,
95  LPARAM lparam);
96 
97  private:
98  // For access to RelinquishEngine.
99  friend class FlutterViewController;
100 
101  // Gives up ownership of |engine_|, but keeps a weak reference to it.
102  //
103  // This is intended to be used by FlutterViewController, since the underlying
104  // C API for view controllers takes over engine ownership.
105  FlutterDesktopEngineRef RelinquishEngine();
106 
107  // Handle for interacting with the C API's engine reference.
108  FlutterDesktopEngineRef engine_ = nullptr;
109 
110  // Messenger for communicating with the engine.
111  std::unique_ptr<BinaryMessenger> messenger_;
112 
113  // Whether or not this wrapper owns |engine_|.
114  bool owns_engine_ = true;
115 
116  // Whether the engine has been run. This will be true if Run has been called,
117  // or if RelinquishEngine has been called (since the view controller will
118  // run the engine if it hasn't already been run).
119  bool has_been_run_ = false;
120 
121  // The callback to execute once the next frame is drawn.
122  std::function<void()> next_frame_callback_ = nullptr;
123 };
124 
125 } // namespace flutter
126 
127 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_CLIENT_WRAPPER_INCLUDE_FLUTTER_FLUTTER_ENGINE_H_
dart_project.h
flutter::FlutterEngine
Definition: flutter_engine.h:28
plugin_registrar.h
flutter::DartProject
Definition: dart_project.h:14
flutter::FlutterEngine::SetNextFrameCallback
void SetNextFrameCallback(std::function< void()> callback)
Definition: flutter_engine.cc:91
binary_messenger.h
flutter::FlutterEngine::ReloadPlatformBrightness
void ReloadPlatformBrightness()
flutter::FlutterEngine::GetRegistrarForPlugin
FlutterDesktopPluginRegistrarRef GetRegistrarForPlugin(const std::string &plugin_name) override
Definition: flutter_engine.cc:80
flutter::FlutterEngine::Run
bool Run()
Definition: flutter_engine.cc:44
flutter::BinaryMessenger
Definition: binary_messenger.h:28
FlutterDesktopEngineRef
struct FlutterDesktopEngine * FlutterDesktopEngineRef
Definition: flutter_windows.h:33
plugin_registry.h
flutter::FlutterViewController
Definition: flutter_view_controller.h:25
flutter::FlutterEngine::ShutDown
void ShutDown()
Definition: flutter_engine.cc:65
flutter::FlutterEngine::ProcessExternalWindowMessage
std::optional< LRESULT > ProcessExternalWindowMessage(HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
Definition: flutter_engine.cc:103
flutter::FlutterEngine::~FlutterEngine
virtual ~FlutterEngine()
Definition: flutter_engine.cc:40
flutter
Definition: accessibility_bridge_windows.cc:11
flutter::FlutterEngine::ReloadSystemFonts
void ReloadSystemFonts()
Definition: flutter_engine.cc:76
flutter::FlutterEngine::operator=
FlutterEngine & operator=(FlutterEngine const &)=delete
flutter::PluginRegistry
Definition: plugin_registry.h:18
flutter_windows.h
message
Win32Message message
Definition: keyboard_unittests.cc:137
flutter::FlutterEngine::ProcessMessages
std::chrono::nanoseconds ProcessMessages()
Definition: flutter_engine.cc:72
FlutterDesktopPluginRegistrar
Definition: window_state.h:23
flutter::FlutterEngine::FlutterEngine
FlutterEngine(const DartProject &project)
Definition: flutter_engine.cc:14
callback
FlutterDesktopBinaryReply callback
Definition: flutter_windows_view_unittests.cc:51
flutter::FlutterEngine::messenger
BinaryMessenger * messenger()
Definition: flutter_engine.h:80