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