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