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 #if defined(__cplusplus)
17 extern "C" {
18 #endif
19 
20 // Opaque reference to a Flutter window controller.
23 
24 // Opaque reference to a Flutter window.
25 struct FlutterDesktopView;
26 typedef struct FlutterDesktopView* FlutterDesktopViewRef;
27 
28 // Opaque reference to a Flutter engine instance.
29 struct FlutterDesktopEngine;
30 typedef struct FlutterDesktopEngine* FlutterDesktopEngineRef;
31 
32 // Properties for configuring a Flutter engine instance.
33 typedef struct {
34  // The path to the flutter_assets folder for the application to be run.
35  // This can either be an absolute path or a path relative to the directory
36  // containing the executable.
37  const wchar_t* assets_path;
38 
39  // The path to the icudtl.dat file for the version of Flutter you are using.
40  // This can either be an absolute path or a path relative to the directory
41  // containing the executable.
42  const wchar_t* icu_data_path;
43 
44  // The path to the AOT libary file for your application, if any.
45  // This can either be an absolute path or a path relative to the directory
46  // containing the executable. This can be nullptr for a non-AOT build, as
47  // it will be ignored in that case.
48  const wchar_t* aot_library_path;
50 
51 // ========== View Controller ==========
52 
53 // Creates a view that hosts and displays the given engine instance.
54 //
55 // This takes ownership of |engine|, so FlutterDesktopEngineDestroy should no
56 // longer be called on it, as it will be called internally when the view
57 // controller is destroyed. If creating the view controller fails, the engine
58 // will be destroyed immediately.
59 //
60 // If |engine| is not already running, the view controller will start running
61 // it automatically before displaying the window.
62 //
63 // The caller owns the returned reference, and is responsible for calling
64 // FlutterDesktopViewControllerDestroy. Returns a null pointer in the event of
65 // an error.
66 FLUTTER_EXPORT FlutterDesktopViewControllerRef
68  int height,
69  FlutterDesktopEngineRef engine);
70 
71 // Shuts down the engine instance associated with |controller|, and cleans up
72 // associated state.
73 //
74 // |controller| is no longer valid after this call.
76  FlutterDesktopViewControllerRef controller);
77 
78 // Returns the handle for the engine running in FlutterDesktopViewControllerRef.
79 //
80 // Its lifetime is the same as the |controller|'s.
82  FlutterDesktopViewControllerRef controller);
83 // Returns the view managed by the given controller.
84 
85 FLUTTER_EXPORT FlutterDesktopViewRef
86 FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller);
87 
88 // Allows the Flutter engine and any interested plugins an opportunity to
89 // handle the given message.
90 //
91 // If the WindowProc was handled and further handling should stop, this returns
92 // true and |result| will be populated. |result| is not set if returning false.
94  FlutterDesktopViewControllerRef controller,
95  HWND hwnd,
96  UINT message,
97  WPARAM wparam,
98  LPARAM lparam,
99  LRESULT* result);
100 
101 // ========== Engine ==========
102 
103 // Creates a Flutter engine with the given properties.
104 //
105 // The caller owns the returned reference, and is responsible for calling
106 // FlutterDesktopEngineDestroy.
107 FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(
108  const FlutterDesktopEngineProperties& engine_properties);
109 
110 // Shuts down and destroys the given engine instance. Returns true if the
111 // shutdown was successful, or if the engine was not running.
112 //
113 // |engine| is no longer valid after this call.
114 FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine);
115 
116 // Starts running the given engine instance and optional entry point in the Dart
117 // project. If the entry point is null, defaults to main().
118 //
119 // If provided, entry_point must be the name of a top-level function from the
120 // same Dart library that contains the app's main() function, and must be
121 // decorated with `@pragma(vm:entry-point)` to ensure the method is not
122 // tree-shaken by the Dart compiler.
123 //
124 // Returns false if running the engine failed.
125 FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine,
126  const char* entry_point);
127 
128 // Processes any pending events in the Flutter engine, and returns the
129 // number of nanoseconds until the next scheduled event (or max, if none).
130 //
131 // This should be called on every run of the application-level runloop, and
132 // a wait for native events in the runloop should never be longer than the
133 // last return value from this function.
134 FLUTTER_EXPORT uint64_t
135 FlutterDesktopEngineProcessMessages(FlutterDesktopEngineRef engine);
136 
138  FlutterDesktopEngineRef engine);
139 
140 // Returns the plugin registrar handle for the plugin with the given name.
141 //
142 // The name must be unique across the application.
144 FlutterDesktopEngineGetPluginRegistrar(FlutterDesktopEngineRef engine,
145  const char* plugin_name);
146 
147 // Returns the messenger associated with the engine.
149 FlutterDesktopEngineGetMessenger(FlutterDesktopEngineRef engine);
150 
151 // ========== View ==========
152 
153 // Return backing HWND for manipulation in host application.
154 FLUTTER_EXPORT HWND FlutterDesktopViewGetHWND(FlutterDesktopViewRef view);
155 
156 // ========== Plugin Registrar (extensions) ==========
157 // These are Windows-specific extensions to flutter_plugin_registrar.h
158 
159 // Function pointer type for top level WindowProc delegate registration.
160 //
161 // The user data will be whatever was passed to
162 // FlutterDesktopRegisterTopLevelWindowProcHandler.
163 //
164 // Implementations should populate |result| and return true if the WindowProc
165 // was handled and further handling should stop. |result| is ignored if the
166 // function returns false.
167 typedef bool (*FlutterDesktopWindowProcCallback)(HWND /* hwnd */,
168  UINT /* uMsg */,
169  WPARAM /*wParam*/,
170  LPARAM /* lParam*/,
171  void* /* user data */,
172  LRESULT* result);
173 
174 // Returns the view associated with this registrar's engine instance.
177 
178 FLUTTER_EXPORT void
182  void* user_data);
183 
184 FLUTTER_EXPORT void
188 
189 // ========== Freestanding Utilities ==========
190 
191 // Gets the DPI for a given |hwnd|, depending on the supported APIs per
192 // windows version and DPI awareness mode. If nullptr is passed, returns the DPI
193 // of the primary monitor.
194 //
195 // This uses the same logic and fallback for older Windows versions that is used
196 // internally by Flutter to determine the DPI to use for displaying Flutter
197 // content, so should be used by any code (e.g., in plugins) that translates
198 // between Windows and Dart sizes/offsets.
200 
201 // Gets the DPI for a given |monitor|. If the API is not available, a default
202 // DPI of 96 is returned.
203 //
204 // See FlutterDesktopGetDpiForHWND for more information.
205 FLUTTER_EXPORT UINT FlutterDesktopGetDpiForMonitor(HMONITOR monitor);
206 
207 // Reopens stdout and stderr and resysncs the standard library output streams.
208 // Should be called if output is being directed somewhere in the runner process
209 // (e.g., after an AllocConsole call).
211 
212 #if defined(__cplusplus)
213 } // extern "C"
214 #endif
215 
216 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_WINDOWS_H_
FLUTTER_EXPORT FlutterDesktopViewControllerRef FlutterDesktopViewControllerCreate(int width, int height, FlutterDesktopEngineRef engine)
FLUTTER_EXPORT void FlutterDesktopResyncOutputStreams()
FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine, const char *entry_point)
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)
int32_t height
FLUTTER_EXPORT void FlutterDesktopViewControllerDestroy(FlutterDesktopViewControllerRef controller)
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopViewControllerGetEngine(FlutterDesktopViewControllerRef controller)
FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine)
int32_t width
struct FlutterDesktopEngine * FlutterDesktopEngineRef
bool(* FlutterDesktopWindowProcCallback)(HWND, UINT, WPARAM, LPARAM, void *, LRESULT *result)
G_BEGIN_DECLS FlMethodCall gpointer user_data
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForHWND(HWND hwnd)
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(const FlutterDesktopEngineProperties &engine_properties)
FLUTTER_EXPORT void FlutterDesktopEngineReloadSystemFonts(FlutterDesktopEngineRef engine)
FLUTTER_EXPORT uint64_t FlutterDesktopEngineProcessMessages(FlutterDesktopEngineRef engine)
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(FlutterDesktopPluginRegistrarRef registrar)
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller)
FLUTTER_EXPORT bool FlutterDesktopViewControllerHandleTopLevelWindowProc(FlutterDesktopViewControllerRef controller, HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam, LRESULT *result)
struct FlutterDesktopViewControllerState * FlutterDesktopViewControllerRef
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)