|
| 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_ |
0 commit comments