Flutter Engine
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 <stddef.h>
9 #include <stdint.h>
10 #include <windows.h>
11 
12 #include "flutter_export.h"
13 #include "flutter_messenger.h"
15 
16 #ifdef WINUWP
17 #include <windows.applicationmodel.activation.h>
18 #include <windows.ui.core.h>
19 #endif
20 
21 #if defined(__cplusplus)
22 extern "C" {
23 #endif
24 
25 // Opaque reference to a Flutter window controller.
28 
29 // Opaque reference to a Flutter window.
30 struct FlutterDesktopView;
31 typedef struct FlutterDesktopView* FlutterDesktopViewRef;
32 
33 // Opaque reference to a Flutter engine instance.
34 struct FlutterDesktopEngine;
35 typedef struct FlutterDesktopEngine* FlutterDesktopEngineRef;
36 
37 // Properties for configuring a Flutter engine instance.
38 typedef struct {
39  // The path to the flutter_assets folder for the application to be run.
40  // This can either be an absolute path or a path relative to the directory
41  // containing the executable.
42  const wchar_t* assets_path;
43 
44  // The path to the icudtl.dat file for the version of Flutter you are using.
45  // This can either be an absolute path or a path relative to the directory
46  // containing the executable.
47  const wchar_t* icu_data_path;
48 
49  // The path to the AOT library file for your application, if any.
50  // This can either be an absolute path or a path relative to the directory
51  // containing the executable. This can be nullptr for a non-AOT build, as
52  // it will be ignored in that case.
53  const wchar_t* aot_library_path;
54 
55  // Number of elements in the array passed in as dart_entrypoint_argv.
57 
58  // Array of Dart entrypoint arguments. This is deep copied during the call
59  // to FlutterDesktopEngineCreate.
60  const char** dart_entrypoint_argv;
61 
63 
64 // ========== View Controller ==========
65 
66 // Creates a view that hosts and displays the given engine instance.
67 //
68 // This takes ownership of |engine|, so FlutterDesktopEngineDestroy should no
69 // longer be called on it, as it will be called internally when the view
70 // controller is destroyed. If creating the view controller fails, the engine
71 // will be destroyed immediately.
72 //
73 // If |engine| is not already running, the view controller will start running
74 // it automatically before displaying the window.
75 //
76 // The caller owns the returned reference, and is responsible for calling
77 // FlutterDesktopViewControllerDestroy. Returns a null pointer in the event of
78 // an error.
79 #ifdef WINUWP
80 // The CoreApplicationView implementation accepts a pointer to the host
81 // CoreApplicationView and view hookup is performed in the construction path.
82 FLUTTER_EXPORT FlutterDesktopViewControllerRef
84  ABI::Windows::ApplicationModel::Core::CoreApplicationView* window,
85  ABI::Windows::ApplicationModel::Activation::IActivatedEventArgs* args,
86  FlutterDesktopEngineRef engine);
87 #else //! WINUWP
88 // The Win32 implementation accepts width, height
89 // with view hookup explicitly performed using the caller using HWND parenting.
90 FLUTTER_EXPORT FlutterDesktopViewControllerRef
92  int height,
93  FlutterDesktopEngineRef engine);
94 #endif
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.
101  FlutterDesktopViewControllerRef controller);
102 
103 // Returns the handle for the engine running in FlutterDesktopViewControllerRef.
104 //
105 // Its lifetime is the same as the |controller|'s.
107  FlutterDesktopViewControllerRef controller);
108 // Returns the view managed by the given controller.
109 
110 FLUTTER_EXPORT FlutterDesktopViewRef
111 FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller);
112 
113 // Requests new frame from engine and repaints the view
115  FlutterDesktopViewControllerRef controller);
116 
117 #ifndef WINUWP
118 // Allows the Flutter engine and any interested plugins an opportunity to
119 // handle the given message.
120 //
121 // If the WindowProc was handled and further handling should stop, this returns
122 // true and |result| will be populated. |result| is not set if returning false.
124  FlutterDesktopViewControllerRef controller,
125  HWND hwnd,
126  UINT message,
127  WPARAM wparam,
128  LPARAM lparam,
129  LRESULT* result);
130 #endif
131 
132 // ========== Engine ==========
133 
134 // Creates a Flutter engine with the given properties.
135 //
136 // The caller owns the returned reference, and is responsible for calling
137 // FlutterDesktopEngineDestroy. The lifetime of |engine_properties| is required
138 // to extend only until the end of this call.
139 FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(
140  const FlutterDesktopEngineProperties* engine_properties);
141 
142 // Shuts down and destroys the given engine instance. Returns true if the
143 // shutdown was successful, or if the engine was not running.
144 //
145 // |engine| is no longer valid after this call.
146 FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine);
147 
148 // Starts running the given engine instance and optional entry point in the Dart
149 // project. If the entry point is null, defaults to main().
150 //
151 // If provided, entry_point must be the name of a top-level function from the
152 // same Dart library that contains the app's main() function, and must be
153 // decorated with `@pragma(vm:entry-point)` to ensure the method is not
154 // tree-shaken by the Dart compiler.
155 //
156 // Returns false if running the engine failed.
157 FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine,
158  const char* entry_point);
159 
160 #ifndef WINUWP
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 #endif
173 
175  FlutterDesktopEngineRef engine);
176 
178  FlutterDesktopEngineRef engine);
179 
180 // Returns the plugin registrar handle for the plugin with the given name.
181 //
182 // The name must be unique across the application.
184 FlutterDesktopEngineGetPluginRegistrar(FlutterDesktopEngineRef engine,
185  const char* plugin_name);
186 
187 // Returns the messenger associated with the engine.
189 FlutterDesktopEngineGetMessenger(FlutterDesktopEngineRef engine);
190 
191 // Returns the texture registrar associated with the engine.
194  FlutterDesktopTextureRegistrarRef texture_registrar);
195 
196 // ========== View ==========
197 
198 #ifdef WINUWP
199 // Return backing CoreApplicationView for manipulation of CoreWindow and
200 // CoreTitleBar in host application.
201 FLUTTER_EXPORT ABI::Windows::ApplicationModel::Core::CoreApplicationView*
202 FlutterDesktopViewGetCoreApplicationView(FlutterDesktopViewRef view);
203 #else
204 // Return backing HWND for manipulation in host application.
205 FLUTTER_EXPORT HWND FlutterDesktopViewGetHWND(FlutterDesktopViewRef view);
206 #endif
207 
208 // ========== Plugin Registrar (extensions) ==========
209 // These are Windows-specific extensions to flutter_plugin_registrar.h
210 
211 // Function pointer type for top level WindowProc delegate registration.
212 //
213 // The user data will be whatever was passed to
214 // FlutterDesktopRegisterTopLevelWindowProcHandler.
215 //
216 // Implementations should populate |result| and return true if the WindowProc
217 // was handled and further handling should stop. |result| is ignored if the
218 // function returns false.
219 typedef bool (*FlutterDesktopWindowProcCallback)(HWND /* hwnd */,
220  UINT /* uMsg */,
221  WPARAM /*wParam*/,
222  LPARAM /* lParam*/,
223  void* /* user data */,
224  LRESULT* result);
225 
226 // Returns the view associated with this registrar's engine instance.
229 
230 #ifndef WINUWP
231 FLUTTER_EXPORT void
235  void* user_data);
236 
237 FLUTTER_EXPORT void
241 #endif
242 
243 // ========== Freestanding Utilities ==========
244 
245 // Gets the DPI for a given |hwnd|, depending on the supported APIs per
246 // windows version and DPI awareness mode. If nullptr is passed, returns the DPI
247 // of the primary monitor.
248 //
249 // This uses the same logic and fallback for older Windows versions that is used
250 // internally by Flutter to determine the DPI to use for displaying Flutter
251 // content, so should be used by any code (e.g., in plugins) that translates
252 // between Windows and Dart sizes/offsets.
254 
255 // Gets the DPI for a given |monitor|. If the API is not available, a default
256 // DPI of 96 is returned.
257 //
258 // See FlutterDesktopGetDpiForHWND for more information.
259 FLUTTER_EXPORT UINT FlutterDesktopGetDpiForMonitor(HMONITOR monitor);
260 
261 // Reopens stdout and stderr and resysncs the standard library output streams.
262 // Should be called if output is being directed somewhere in the runner process
263 // (e.g., after an AllocConsole call).
265 
266 #if defined(__cplusplus)
267 } // extern "C"
268 #endif
269 
270 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_WINDOWS_H_
G_BEGIN_DECLS FlValue * args
FLUTTER_EXPORT void FlutterDesktopViewControllerForceRedraw(FlutterDesktopViewControllerRef controller)
FLUTTER_EXPORT FlutterDesktopViewControllerRef FlutterDesktopViewControllerCreate(int width, int height, FlutterDesktopEngineRef engine)
WINUWP.
FLUTTER_EXPORT void FlutterDesktopResyncOutputStreams()
void * user_data
GAsyncResult * result
LONG_PTR LRESULT
Definition: windows_types.h:61
FlutterDesktopViewControllerRef FlutterDesktopViewControllerCreateFromCoreApplicationView(ABI::Windows::ApplicationModel::Core::CoreApplicationView *application_view, ABI::Windows::ApplicationModel::Activation::IActivatedEventArgs *args, FlutterDesktopEngineRef engine)
FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine, const char *entry_point)
struct FlutterDesktopTextureRegistrar * FlutterDesktopTextureRegistrarRef
UINT_PTR WPARAM
Definition: windows_types.h:59
FLUTTER_EXPORT FlutterDesktopMessengerRef FlutterDesktopEngineGetMessenger(FlutterDesktopEngineRef engine)
struct FlutterDesktopView * FlutterDesktopViewRef
FLUTTER_EXPORT void FlutterDesktopPluginRegistrarRegisterTopLevelWindowProcDelegate(FlutterDesktopPluginRegistrarRef registrar, FlutterDesktopWindowProcCallback delegate, void *user_data)
FLUTTER_EXPORT void FlutterDesktopPluginRegistrarUnregisterTopLevelWindowProcDelegate(FlutterDesktopPluginRegistrarRef registrar, FlutterDesktopWindowProcCallback delegate)
FLUTTER_EXPORT void FlutterDesktopViewControllerDestroy(FlutterDesktopViewControllerRef controller)
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopViewControllerGetEngine(FlutterDesktopViewControllerRef controller)
FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine)
struct FlutterDesktopEngine * FlutterDesktopEngineRef
int32_t width
bool(* FlutterDesktopWindowProcCallback)(HWND, UINT, WPARAM, LPARAM, void *, LRESULT *result)
int32_t height
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForHWND(HWND hwnd)
FLUTTER_EXPORT void FlutterDesktopEngineReloadSystemFonts(FlutterDesktopEngineRef engine)
LONG_PTR LPARAM
Definition: windows_types.h:60
FlView * view
FLUTTER_EXPORT uint64_t FlutterDesktopEngineProcessMessages(FlutterDesktopEngineRef engine)
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(const FlutterDesktopEngineProperties *engine_properties)
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(FlutterDesktopPluginRegistrarRef registrar)
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller)
unsigned int UINT
Definition: windows_types.h:32
FLUTTER_EXPORT bool FlutterDesktopViewControllerHandleTopLevelWindowProc(FlutterDesktopViewControllerRef controller, HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam, LRESULT *result)
FLUTTER_EXPORT FlutterDesktopTextureRegistrarRef FlutterDesktopEngineGetTextureRegistrar(FlutterDesktopTextureRegistrarRef texture_registrar)
struct FlutterDesktopViewControllerState * FlutterDesktopViewControllerRef
FLUTTER_EXPORT void FlutterDesktopEngineReloadPlatformBrightness(FlutterDesktopEngineRef engine)
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForMonitor(HMONITOR monitor)
#define FLUTTER_EXPORT
FLUTTER_EXPORT HWND FlutterDesktopViewGetHWND(FlutterDesktopViewRef view)
FLUTTER_EXPORT FlutterDesktopPluginRegistrarRef FlutterDesktopEngineGetPluginRegistrar(FlutterDesktopEngineRef engine, const char *plugin_name)