| Flutter Windows Embedder |

flutter_windows.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_PUBLIC_FLUTTER_WINDOWS_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_WINDOWS_H_
7
8 #include <dxgi.h>
9 #include <stddef.h>
10 #include <stdint.h>
11 #include <windows.h>
12
13 #include "flutter_export.h"
14 #include "flutter_messenger.h"
15 #include "flutter_plugin_registrar.h"
16
17 #if defined(__cplusplus)
18 extern "C" {
19 #endif
20
21 typedef void (*VoidCallback)(void* /* user data */);
22
23 // Opaque reference to a Flutter view controller.
24 struct FlutterDesktopViewController;
25 typedef struct FlutterDesktopViewController* FlutterDesktopViewControllerRef;
26
27 // Opaque reference to a Flutter window.
28 struct FlutterDesktopView;
29 typedef struct FlutterDesktopView* FlutterDesktopViewRef;
30
31 // Opaque reference to a Flutter engine instance.
32 struct FlutterDesktopEngine;
33 typedef struct FlutterDesktopEngine* FlutterDesktopEngineRef;
34
35 // The unique identifier for a view.
36 typedef int64_t FlutterDesktopViewId;
37
38 // Configures how the Flutter engine selects a GPU.
39 typedef enum {
40 // No preference.
41 NoPreference,
42 // Prefer energy efficiency over performance, such as an integrated GPU.
43 // This falls back to a high performance GPU if no low power GPU is
44 // available.
45 LowPowerPreference,
46 // Prefer performance over energy efficiency, such as a discrete GPU or
47 // dedicated GPU.
48 // This falls back to a low power GPU if no high performance GPU is available.
49 HighPerformancePreference,
50 } FlutterDesktopGpuPreference;
51
52 // Configures the thread policy for running the UI isolate.
53 typedef enum {
54 // Default value. Currently will run the UI isolate on separate thread,
55 // later will be changed to running the UI isolate on platform thread.
56 Default,
57 // Run the UI isolate on platform thread.
58 RunOnPlatformThread,
59 // Run the UI isolate on a separate thread.
60 RunOnSeparateThread,
61 } FlutterDesktopUIThreadPolicy;
62
63 // Properties for configuring a Flutter engine instance.
64 typedef struct {
65 // The path to the flutter_assets folder for the application to be run.
66 // This can either be an absolute path or a path relative to the directory
67 // containing the executable.
68 const wchar_t* assets_path;
69
70 // The path to the icudtl.dat file for the version of Flutter you are using.
71 // This can either be an absolute path or a path relative to the directory
72 // containing the executable.
73 const wchar_t* icu_data_path;
74
75 // The path to the AOT library file for your application, if any.
76 // This can either be an absolute path or a path relative to the directory
77 // containing the executable. This can be nullptr for a non-AOT build, as
78 // it will be ignored in that case.
79 const wchar_t* aot_library_path;
80
81 // The name of the top-level Dart entrypoint function. If null or the empty
82 // string, 'main' is assumed. If a custom entrypoint is used, this parameter
83 // must specifiy the name of a top-level function in the same Dart library as
84 // the app's main() function. Custom entrypoint functions must be decorated
85 // with `@pragma('vm:entry-point')` to ensure the method is not tree-shaken
86 // by the Dart compiler.
87 const char* dart_entrypoint;
88
89 // Number of elements in the array passed in as dart_entrypoint_argv.
90 int dart_entrypoint_argc;
91
92 // Array of Dart entrypoint arguments. This is deep copied during the call
93 // to FlutterDesktopEngineCreate.
94 const char** dart_entrypoint_argv;
95
96 // GPU choice preference
97 FlutterDesktopGpuPreference gpu_preference;
98
99 // Policy for the thread that runs UI isolate.
100 FlutterDesktopUIThreadPolicy ui_thread_policy;
101 } FlutterDesktopEngineProperties;
102
103 // ========== View Controller ==========
104
105 // Creates a view that hosts and displays the given engine instance.
106 //
107 // This takes ownership of |engine|, so FlutterDesktopEngineDestroy should no
108 // longer be called on it, as it will be called internally when the view
109 // controller is destroyed. If creating the view controller fails, the engine
110 // will be destroyed immediately.
111 //
112 // If |engine| is not already running, the view controller will start running
113 // it automatically before displaying the window.
114 //
115 // The caller owns the returned reference, and is responsible for calling
116 // FlutterDesktopViewControllerDestroy. Returns a null pointer in the event of
117 // an error.
118 //
119 // The Win32 implementation accepts width, height with view hookup explicitly
120 // performed using the caller using HWND parenting.
121 FLUTTER_EXPORT FlutterDesktopViewControllerRef
122 FlutterDesktopViewControllerCreate(int width,
123 int height,
124 FlutterDesktopEngineRef engine);
125
126 // Shuts down the engine instance associated with |controller|, and cleans up
127 // associated state.
128 //
129 // |controller| is no longer valid after this call.
130 FLUTTER_EXPORT void FlutterDesktopViewControllerDestroy(
131 FlutterDesktopViewControllerRef controller);
132
133 // Returns the view controller's view ID.
134 FLUTTER_EXPORT FlutterDesktopViewId FlutterDesktopViewControllerGetViewId(
135 FlutterDesktopViewControllerRef view_controller);
136
137 // Returns the handle for the engine running in FlutterDesktopViewControllerRef.
138 //
139 // Its lifetime is the same as the |controller|'s.
140 FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopViewControllerGetEngine(
141 FlutterDesktopViewControllerRef controller);
142
143 // Returns the view managed by the given controller.
144 FLUTTER_EXPORT FlutterDesktopViewRef
145 FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller);
146
147 // Requests new frame from the engine and repaints the view.
148 FLUTTER_EXPORT void FlutterDesktopViewControllerForceRedraw(
149 FlutterDesktopViewControllerRef controller);
150
151 // Allows the Flutter engine and any interested plugins an opportunity to
152 // handle the given message.
153 //
154 // If the WindowProc was handled and further handling should stop, this returns
155 // true and |result| will be populated. |result| is not set if returning false.
156 FLUTTER_EXPORT bool FlutterDesktopViewControllerHandleTopLevelWindowProc(
157 FlutterDesktopViewControllerRef controller,
158 HWND hwnd,
159 UINT message,
160 WPARAM wparam,
161 LPARAM lparam,
162 LRESULT* result);
163
164 // ========== Engine ==========
165
166 // Creates a Flutter engine with the given properties.
167 //
168 // The caller owns the returned reference, and is responsible for calling
169 // FlutterDesktopEngineDestroy. The lifetime of |engine_properties| is required
170 // to extend only until the end of this call.
171 FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(
172 const FlutterDesktopEngineProperties* engine_properties);
173
174 // Shuts down and destroys the given engine instance. Returns true if the
175 // shutdown was successful, or if the engine was not running.
176 //
177 // |engine| is no longer valid after this call.
178 FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine);
179
180 // Starts running the given engine instance.
181 //
182 // The entry_point parameter is deprecated but preserved for
183 // backward-compatibility. If desired, a custom Dart entrypoint function can be
184 // set in the dart_entrypoint field of the FlutterDesktopEngineProperties
185 // struct passed to FlutterDesktopEngineCreate.
186 //
187 // If specified, entry_point must be the name of a top-level function from the
188 // same Dart library that contains the app's main() function, and must be
189 // decorated with `@pragma(vm:entry-point)` to ensure the method is not
190 // tree-shaken by the Dart compiler. If conflicting non-null values are passed
191 // to this function and via the FlutterDesktopEngineProperties struct, the run
192 // will fail.
193 //
194 // Returns false if running the engine failed.
195 FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine,
196 const char* entry_point);
197
198 // DEPRECATED: This is no longer necessary to call, Flutter will take care of
199 // processing engine messages transparently through DispatchMessage.
200 //
201 // Processes any pending events in the Flutter engine, and returns the
202 // number of nanoseconds until the next scheduled event (or max, if none).
203 //
204 // This should be called on every run of the application-level runloop, and
205 // a wait for native events in the runloop should never be longer than the
206 // last return value from this function.
207 FLUTTER_EXPORT uint64_t
208 FlutterDesktopEngineProcessMessages(FlutterDesktopEngineRef engine);
209
210 FLUTTER_EXPORT void FlutterDesktopEngineReloadSystemFonts(
211 FlutterDesktopEngineRef engine);
212
213 // Returns the plugin registrar handle for the plugin with the given name.
214 //
215 // The name must be unique across the application.
216 FLUTTER_EXPORT FlutterDesktopPluginRegistrarRef
217 FlutterDesktopEngineGetPluginRegistrar(FlutterDesktopEngineRef engine,
218 const char* plugin_name);
219
220 // Returns the messenger associated with the engine.
221 //
222 // This does not provide an owning reference, so should *not* be balanced with a
223 // call to |FlutterDesktopMessengerRelease|.
224 //
225 // Callers should use |FlutterDesktopMessengerAddRef| if the returned pointer
226 // will potentially outlive 'engine', such as when passing it to another thread.
227 FLUTTER_EXPORT FlutterDesktopMessengerRef
228 FlutterDesktopEngineGetMessenger(FlutterDesktopEngineRef engine);
229
230 // Returns the texture registrar associated with the engine.
231 FLUTTER_EXPORT FlutterDesktopTextureRegistrarRef
232 FlutterDesktopEngineGetTextureRegistrar(FlutterDesktopEngineRef engine);
233
234 // Schedule a callback to be called after the next frame is drawn.
235 //
236 // This must be called from the platform thread. The callback is executed only
237 // once on the platform thread.
238 FLUTTER_EXPORT void FlutterDesktopEngineSetNextFrameCallback(
239 FlutterDesktopEngineRef engine,
240 VoidCallback callback,
241 void* user_data);
242
243 // ========== View ==========
244
245 // Returns the backing HWND for manipulation in host application.
246 FLUTTER_EXPORT HWND FlutterDesktopViewGetHWND(FlutterDesktopViewRef view);
247
248 // Returns the DXGI adapter used for rendering or nullptr in case of error.
249 FLUTTER_EXPORT IDXGIAdapter* FlutterDesktopViewGetGraphicsAdapter(
250 FlutterDesktopViewRef view);
251
252 // Called to pass an external window message to the engine for lifecycle
253 // state updates. Non-Flutter windows must call this method in their WndProc
254 // in order to be included in the logic for application lifecycle state
255 // updates. Returns a result if the message should be consumed.
256 FLUTTER_EXPORT bool FlutterDesktopEngineProcessExternalWindowMessage(
257 FlutterDesktopEngineRef engine,
258 HWND hwnd,
259 UINT message,
260 WPARAM wparam,
261 LPARAM lparam,
262 LRESULT* result);
263
264 // ========== Plugin Registrar (extensions) ==========
265 // These are Windows-specific extensions to flutter_plugin_registrar.h
266
267 // Function pointer type for top level WindowProc delegate registration.
268 //
269 // The user data will be whatever was passed to
270 // FlutterDesktopRegisterTopLevelWindowProcHandler.
271 //
272 // Implementations should populate |result| and return true if the WindowProc
273 // was handled and further handling should stop. |result| is ignored if the
274 // function returns false.
275 typedef bool (*FlutterDesktopWindowProcCallback)(HWND /* hwnd */,
276 UINT /* uMsg */,
277 WPARAM /*wParam*/,
278 LPARAM /* lParam*/,
279 void* /* user data */,
280 LRESULT* result);
281
282 // Returns the implicit view associated with this registrar's engine instance,
283 // or null if there is no implicit view.
284 //
285 // See:
286 // https://api.flutter.dev/flutter/dart-ui/PlatformDispatcher/implicitView.html
287 //
288 // DEPRECATED: Use |FlutterDesktopPluginRegistrarGetViewById| instead.
289 FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(
290 FlutterDesktopPluginRegistrarRef registrar);
291
292 // Returns the view associated with the registrar's engine instance, or null if
293 // the view does not exist.
294 FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetViewById(
295 FlutterDesktopPluginRegistrarRef registrar,
296 FlutterDesktopViewId view_id);
297
298 FLUTTER_EXPORT void
299 FlutterDesktopPluginRegistrarRegisterTopLevelWindowProcDelegate(
300 FlutterDesktopPluginRegistrarRef registrar,
301 FlutterDesktopWindowProcCallback delegate,
302 void* user_data);
303
304 FLUTTER_EXPORT void
305 FlutterDesktopPluginRegistrarUnregisterTopLevelWindowProcDelegate(
306 FlutterDesktopPluginRegistrarRef registrar,
307 FlutterDesktopWindowProcCallback delegate);
308
309 // ========== Freestanding Utilities ==========
310
311 // Gets the DPI for a given |hwnd|, depending on the supported APIs per
312 // windows version and DPI awareness mode. If nullptr is passed, returns the DPI
313 // of the primary monitor.
314 //
315 // This uses the same logic and fallback for older Windows versions that is used
316 // internally by Flutter to determine the DPI to use for displaying Flutter
317 // content, so should be used by any code (e.g., in plugins) that translates
318 // between Windows and Dart sizes/offsets.
319 FLUTTER_EXPORT UINT FlutterDesktopGetDpiForHWND(HWND hwnd);
320
321 // Gets the DPI for a given |monitor|. If the API is not available, a default
322 // DPI of 96 is returned.
323 //
324 // See FlutterDesktopGetDpiForHWND for more information.
325 FLUTTER_EXPORT UINT FlutterDesktopGetDpiForMonitor(HMONITOR monitor);
326
327 // Reopens stdout and stderr and resysncs the standard library output streams.
328 // Should be called if output is being directed somewhere in the runner process
329 // (e.g., after an AllocConsole call).
330 FLUTTER_EXPORT void FlutterDesktopResyncOutputStreams();
331
332 #if defined(__cplusplus)
333 } // extern "C"
334 #endif
335
336 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_WINDOWS_H_
flutter_export.h
FLUTTER_EXPORT
#define FLUTTER_EXPORT
Definition: flutter_export.h:23
flutter_messenger.h
FlutterDesktopMessengerRef
struct FlutterDesktopMessenger * FlutterDesktopMessengerRef
Definition: flutter_messenger.h:19
flutter_plugin_registrar.h
FlutterDesktopTextureRegistrarRef
struct FlutterDesktopTextureRegistrar * FlutterDesktopTextureRegistrarRef
Definition: flutter_texture_registrar.h:19
FlutterDesktopResyncOutputStreams
FLUTTER_EXPORT void FlutterDesktopResyncOutputStreams()
Definition: flutter_windows.cc:331
FlutterDesktopViewControllerGetView
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller)
Definition: flutter_windows.cc:154
FlutterDesktopEngineGetTextureRegistrar
FLUTTER_EXPORT FlutterDesktopTextureRegistrarRef FlutterDesktopEngineGetTextureRegistrar(FlutterDesktopEngineRef engine)
Definition: flutter_windows.cc:240
FlutterDesktopViewControllerRef
struct FlutterDesktopViewController * FlutterDesktopViewControllerRef
Definition: flutter_windows.h:25
FlutterDesktopViewControllerDestroy
FLUTTER_EXPORT void FlutterDesktopViewControllerDestroy(FlutterDesktopViewControllerRef controller)
Definition: flutter_windows.cc:136
FlutterDesktopWindowProcCallback
bool(* FlutterDesktopWindowProcCallback)(HWND, UINT, WPARAM, LPARAM, void *, LRESULT *result)
Definition: flutter_windows.h:275
FlutterDesktopEngineRef
struct FlutterDesktopEngine * FlutterDesktopEngineRef
Definition: flutter_windows.h:33
FlutterDesktopEngineRun
FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine, const char *entry_point)
Definition: flutter_windows.cc:207
FlutterDesktopUIThreadPolicy
FlutterDesktopUIThreadPolicy
Definition: flutter_windows.h:53
RunOnPlatformThread
@ RunOnPlatformThread
Definition: flutter_windows.h:58
RunOnSeparateThread
@ RunOnSeparateThread
Definition: flutter_windows.h:60
Default
@ Default
Definition: flutter_windows.h:56
FlutterDesktopEngineProcessExternalWindowMessage
FLUTTER_EXPORT bool FlutterDesktopEngineProcessExternalWindowMessage(FlutterDesktopEngineRef engine, HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam, LRESULT *result)
Definition: flutter_windows.cc:273
FlutterDesktopViewId
int64_t FlutterDesktopViewId
Definition: flutter_windows.h:36
FlutterDesktopViewGetHWND
FLUTTER_EXPORT HWND FlutterDesktopViewGetHWND(FlutterDesktopViewRef view)
Definition: flutter_windows.cc:253
FlutterDesktopViewControllerForceRedraw
FLUTTER_EXPORT void FlutterDesktopViewControllerForceRedraw(FlutterDesktopViewControllerRef controller)
Definition: flutter_windows.cc:160
FlutterDesktopEngineGetMessenger
FLUTTER_EXPORT FlutterDesktopMessengerRef FlutterDesktopEngineGetMessenger(FlutterDesktopEngineRef engine)
Definition: flutter_windows.cc:235
FlutterDesktopViewRef
struct FlutterDesktopView * FlutterDesktopViewRef
Definition: flutter_windows.h:29
FlutterDesktopGpuPreference
FlutterDesktopGpuPreference
Definition: flutter_windows.h:39
LowPowerPreference
@ LowPowerPreference
Definition: flutter_windows.h:45
HighPerformancePreference
@ HighPerformancePreference
Definition: flutter_windows.h:49
NoPreference
@ NoPreference
Definition: flutter_windows.h:41
FlutterDesktopPluginRegistrarRegisterTopLevelWindowProcDelegate
FLUTTER_EXPORT void FlutterDesktopPluginRegistrarRegisterTopLevelWindowProcDelegate(FlutterDesktopPluginRegistrarRef registrar, FlutterDesktopWindowProcCallback delegate, void *user_data)
Definition: flutter_windows.cc:308
FlutterDesktopViewGetGraphicsAdapter
FLUTTER_EXPORT IDXGIAdapter * FlutterDesktopViewGetGraphicsAdapter(FlutterDesktopViewRef view)
Definition: flutter_windows.cc:257
VoidCallback
void(* VoidCallback)(void *)
Definition: flutter_windows.h:21
FlutterDesktopPluginRegistrarGetViewById
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetViewById(FlutterDesktopPluginRegistrarRef registrar, FlutterDesktopViewId view_id)
Definition: flutter_windows.cc:302
FlutterDesktopEngineDestroy
FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine)
Definition: flutter_windows.cc:191
FlutterDesktopViewControllerGetEngine
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopViewControllerGetEngine(FlutterDesktopViewControllerRef controller)
Definition: flutter_windows.cc:148
FlutterDesktopGetDpiForHWND
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForHWND(HWND hwnd)
Definition: flutter_windows.cc:323
FlutterDesktopEngineGetPluginRegistrar
FLUTTER_EXPORT FlutterDesktopPluginRegistrarRef FlutterDesktopEngineGetPluginRegistrar(FlutterDesktopEngineRef engine, const char *plugin_name)
Definition: flutter_windows.cc:225
FlutterDesktopPluginRegistrarUnregisterTopLevelWindowProcDelegate
FLUTTER_EXPORT void FlutterDesktopPluginRegistrarUnregisterTopLevelWindowProcDelegate(FlutterDesktopPluginRegistrarRef registrar, FlutterDesktopWindowProcCallback delegate)
Definition: flutter_windows.cc:316
FlutterDesktopGetDpiForMonitor
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForMonitor(HMONITOR monitor)
Definition: flutter_windows.cc:327
FlutterDesktopEngineReloadSystemFonts
FLUTTER_EXPORT void FlutterDesktopEngineReloadSystemFonts(FlutterDesktopEngineRef engine)
Definition: flutter_windows.cc:221
FlutterDesktopViewControllerGetViewId
FLUTTER_EXPORT FlutterDesktopViewId FlutterDesktopViewControllerGetViewId(FlutterDesktopViewControllerRef view_controller)
Definition: flutter_windows.cc:142
FlutterDesktopEngineCreate
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(const FlutterDesktopEngineProperties *engine_properties)
Definition: flutter_windows.cc:184
FlutterDesktopViewControllerCreate
FLUTTER_EXPORT FlutterDesktopViewControllerRef FlutterDesktopViewControllerCreate(int width, int height, FlutterDesktopEngineRef engine)
Definition: flutter_windows.cc:122
FlutterDesktopViewControllerHandleTopLevelWindowProc
FLUTTER_EXPORT bool FlutterDesktopViewControllerHandleTopLevelWindowProc(FlutterDesktopViewControllerRef controller, HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam, LRESULT *result)
Definition: flutter_windows.cc:166
FlutterDesktopEngineSetNextFrameCallback
FLUTTER_EXPORT void FlutterDesktopEngineSetNextFrameCallback(FlutterDesktopEngineRef engine, VoidCallback callback, void *user_data)
Definition: flutter_windows.cc:246
FlutterDesktopEngineProcessMessages
FLUTTER_EXPORT uint64_t FlutterDesktopEngineProcessMessages(FlutterDesktopEngineRef engine)
Definition: flutter_windows.cc:217
FlutterDesktopPluginRegistrarGetView
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(FlutterDesktopPluginRegistrarRef registrar)
Definition: flutter_windows.cc:297
user_data
void * user_data
Definition: flutter_windows_view_unittests.cc:53
callback
FlutterDesktopBinaryReply callback
Definition: flutter_windows_view_unittests.cc:52
message
Win32Message message
Definition: keyboard_unittests.cc:137
FlutterDesktopEngineProperties
Definition: flutter_windows.h:64
FlutterDesktopEngineProperties::dart_entrypoint
const char * dart_entrypoint
Definition: flutter_windows.h:87
FlutterDesktopEngineProperties::icu_data_path
const wchar_t * icu_data_path
Definition: flutter_windows.h:73
FlutterDesktopEngineProperties::dart_entrypoint_argc
int dart_entrypoint_argc
Definition: flutter_windows.h:90
FlutterDesktopEngineProperties::assets_path
const wchar_t * assets_path
Definition: flutter_windows.h:68
FlutterDesktopEngineProperties::dart_entrypoint_argv
const char ** dart_entrypoint_argv
Definition: flutter_windows.h:94
FlutterDesktopEngineProperties::ui_thread_policy
FlutterDesktopUIThreadPolicy ui_thread_policy
Definition: flutter_windows.h:100
FlutterDesktopEngineProperties::aot_library_path
const wchar_t * aot_library_path
Definition: flutter_windows.h:79
FlutterDesktopEngineProperties::gpu_preference
FlutterDesktopGpuPreference gpu_preference
Definition: flutter_windows.h:97
FlutterDesktopPluginRegistrar
Definition: window_state.h:23