| 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).
70 void ReloadPlatformBrightness();
71
72 // flutter::PluginRegistry:
73 FlutterDesktopPluginRegistrarRef GetRegistrarForPlugin(
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 the engine handle.
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 |Run| has been called successfully.
117 //
118 // This is used to improve error messages. This can be false while the engine
119 // is running if the engine was started by creating a view.
120 bool run_succeeded_ = false;
121
122 // The callback to execute once the next frame is drawn.
123 std::function<void()> next_frame_callback_ = nullptr;
124 };
125
126 } // namespace flutter
127
128 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_CLIENT_WRAPPER_INCLUDE_FLUTTER_FLUTTER_ENGINE_H_
binary_messenger.h
flutter::BinaryMessenger
Definition: binary_messenger.h:29
flutter::DartProject
Definition: dart_project.h:39
flutter::FlutterEngine
Definition: flutter_engine.h:28
flutter::FlutterEngine::ProcessExternalWindowMessage
std::optional< LRESULT > ProcessExternalWindowMessage(HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
Definition: flutter_engine.cc:108
flutter::FlutterEngine::FlutterEngine
FlutterEngine(FlutterEngine const &)=delete
flutter::FlutterEngine::ProcessMessages
std::chrono::nanoseconds ProcessMessages()
Definition: flutter_engine.cc:77
flutter::FlutterEngine::GetRegistrarForPlugin
FlutterDesktopPluginRegistrarRef GetRegistrarForPlugin(const std::string &plugin_name) override
Definition: flutter_engine.cc:85
flutter::FlutterEngine::Run
bool Run()
Definition: flutter_engine.cc:49
flutter::FlutterEngine::messenger
BinaryMessenger * messenger()
Definition: flutter_engine.h:80
flutter::FlutterEngine::ReloadSystemFonts
void ReloadSystemFonts()
Definition: flutter_engine.cc:81
flutter::FlutterEngine::ReloadPlatformBrightness
void ReloadPlatformBrightness()
flutter::FlutterEngine::FlutterEngine
FlutterEngine(const DartProject &project)
Definition: flutter_engine.cc:15
flutter::FlutterEngine::SetNextFrameCallback
void SetNextFrameCallback(std::function< void()> callback)
Definition: flutter_engine.cc:96
flutter::FlutterEngine::operator=
FlutterEngine & operator=(FlutterEngine const &)=delete
flutter::FlutterEngine::ShutDown
void ShutDown()
Definition: flutter_engine.cc:70
flutter::FlutterEngine::~FlutterEngine
virtual ~FlutterEngine()
Definition: flutter_engine.cc:45
flutter::FlutterViewController
Definition: flutter_view_controller.h:25
flutter::PluginRegistry
Definition: plugin_registry.h:18
dart_project.h
flutter_windows.h
FlutterDesktopEngineRef
struct FlutterDesktopEngine * FlutterDesktopEngineRef
Definition: flutter_windows.h:33
callback
FlutterDesktopBinaryReply callback
Definition: flutter_windows_view_unittests.cc:52
message
Win32Message message
Definition: keyboard_unittests.cc:137
flutter
Definition: accessibility_bridge_windows.cc:11
plugin_registrar.h
plugin_registry.h
FlutterDesktopPluginRegistrar
Definition: window_state.h:23