271 lines
11 KiB
C
271 lines
11 KiB
C
// Copyright 2013 The Flutter Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style license that can be
|
|
// found in the LICENSE file.
|
|
|
|
#ifndef FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_H_
|
|
#define FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_H_
|
|
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
#include <windows.h>
|
|
|
|
#include "flutter_export.h"
|
|
#include "flutter_messenger.h"
|
|
#include "flutter_plugin_registrar.h"
|
|
|
|
#ifdef WINUWP
|
|
#include <windows.applicationmodel.activation.h>
|
|
#include <windows.ui.core.h>
|
|
#endif
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
// Opaque reference to a Flutter window controller.
|
|
typedef struct FlutterDesktopViewControllerState*
|
|
FlutterDesktopViewControllerRef;
|
|
|
|
// Opaque reference to a Flutter window.
|
|
struct FlutterDesktopView;
|
|
typedef struct FlutterDesktopView* FlutterDesktopViewRef;
|
|
|
|
// Opaque reference to a Flutter engine instance.
|
|
struct FlutterDesktopEngine;
|
|
typedef struct FlutterDesktopEngine* FlutterDesktopEngineRef;
|
|
|
|
// Properties for configuring a Flutter engine instance.
|
|
typedef struct {
|
|
// The path to the flutter_assets folder for the application to be run.
|
|
// This can either be an absolute path or a path relative to the directory
|
|
// containing the executable.
|
|
const wchar_t* assets_path;
|
|
|
|
// The path to the icudtl.dat file for the version of Flutter you are using.
|
|
// This can either be an absolute path or a path relative to the directory
|
|
// containing the executable.
|
|
const wchar_t* icu_data_path;
|
|
|
|
// The path to the AOT library file for your application, if any.
|
|
// This can either be an absolute path or a path relative to the directory
|
|
// containing the executable. This can be nullptr for a non-AOT build, as
|
|
// it will be ignored in that case.
|
|
const wchar_t* aot_library_path;
|
|
|
|
// Number of elements in the array passed in as dart_entrypoint_argv.
|
|
int dart_entrypoint_argc;
|
|
|
|
// Array of Dart entrypoint arguments. This is deep copied during the call
|
|
// to FlutterDesktopEngineCreate.
|
|
const char** dart_entrypoint_argv;
|
|
|
|
} FlutterDesktopEngineProperties;
|
|
|
|
// ========== View Controller ==========
|
|
|
|
// Creates a view that hosts and displays the given engine instance.
|
|
//
|
|
// This takes ownership of |engine|, so FlutterDesktopEngineDestroy should no
|
|
// longer be called on it, as it will be called internally when the view
|
|
// controller is destroyed. If creating the view controller fails, the engine
|
|
// will be destroyed immediately.
|
|
//
|
|
// If |engine| is not already running, the view controller will start running
|
|
// it automatically before displaying the window.
|
|
//
|
|
// The caller owns the returned reference, and is responsible for calling
|
|
// FlutterDesktopViewControllerDestroy. Returns a null pointer in the event of
|
|
// an error.
|
|
#ifdef WINUWP
|
|
// The CoreApplicationView implementation accepts a pointer to the host
|
|
// CoreApplicationView and view hookup is performed in the construction path.
|
|
FLUTTER_EXPORT FlutterDesktopViewControllerRef
|
|
FlutterDesktopViewControllerCreateFromCoreApplicationView(
|
|
ABI::Windows::ApplicationModel::Core::CoreApplicationView* window,
|
|
ABI::Windows::ApplicationModel::Activation::IActivatedEventArgs* args,
|
|
FlutterDesktopEngineRef engine);
|
|
#else //! WINUWP
|
|
// The Win32 implementation accepts width, height
|
|
// with view hookup explicitly performed using the caller using HWND parenting.
|
|
FLUTTER_EXPORT FlutterDesktopViewControllerRef
|
|
FlutterDesktopViewControllerCreate(int width,
|
|
int height,
|
|
FlutterDesktopEngineRef engine);
|
|
#endif
|
|
|
|
// Shuts down the engine instance associated with |controller|, and cleans up
|
|
// associated state.
|
|
//
|
|
// |controller| is no longer valid after this call.
|
|
FLUTTER_EXPORT void FlutterDesktopViewControllerDestroy(
|
|
FlutterDesktopViewControllerRef controller);
|
|
|
|
// Returns the handle for the engine running in FlutterDesktopViewControllerRef.
|
|
//
|
|
// Its lifetime is the same as the |controller|'s.
|
|
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopViewControllerGetEngine(
|
|
FlutterDesktopViewControllerRef controller);
|
|
// Returns the view managed by the given controller.
|
|
|
|
FLUTTER_EXPORT FlutterDesktopViewRef
|
|
FlutterDesktopViewControllerGetView(FlutterDesktopViewControllerRef controller);
|
|
|
|
// Requests new frame from engine and repaints the view
|
|
FLUTTER_EXPORT void FlutterDesktopViewControllerForceRedraw(
|
|
FlutterDesktopViewControllerRef controller);
|
|
|
|
#ifndef WINUWP
|
|
// Allows the Flutter engine and any interested plugins an opportunity to
|
|
// handle the given message.
|
|
//
|
|
// If the WindowProc was handled and further handling should stop, this returns
|
|
// true and |result| will be populated. |result| is not set if returning false.
|
|
FLUTTER_EXPORT bool FlutterDesktopViewControllerHandleTopLevelWindowProc(
|
|
FlutterDesktopViewControllerRef controller,
|
|
HWND hwnd,
|
|
UINT message,
|
|
WPARAM wparam,
|
|
LPARAM lparam,
|
|
LRESULT* result);
|
|
#endif
|
|
|
|
// ========== Engine ==========
|
|
|
|
// Creates a Flutter engine with the given properties.
|
|
//
|
|
// The caller owns the returned reference, and is responsible for calling
|
|
// FlutterDesktopEngineDestroy. The lifetime of |engine_properties| is required
|
|
// to extend only until the end of this call.
|
|
FLUTTER_EXPORT FlutterDesktopEngineRef FlutterDesktopEngineCreate(
|
|
const FlutterDesktopEngineProperties* engine_properties);
|
|
|
|
// Shuts down and destroys the given engine instance. Returns true if the
|
|
// shutdown was successful, or if the engine was not running.
|
|
//
|
|
// |engine| is no longer valid after this call.
|
|
FLUTTER_EXPORT bool FlutterDesktopEngineDestroy(FlutterDesktopEngineRef engine);
|
|
|
|
// Starts running the given engine instance and optional entry point in the Dart
|
|
// project. If the entry point is null, defaults to main().
|
|
//
|
|
// If provided, entry_point must be the name of a top-level function from the
|
|
// same Dart library that contains the app's main() function, and must be
|
|
// decorated with `@pragma(vm:entry-point)` to ensure the method is not
|
|
// tree-shaken by the Dart compiler.
|
|
//
|
|
// Returns false if running the engine failed.
|
|
FLUTTER_EXPORT bool FlutterDesktopEngineRun(FlutterDesktopEngineRef engine,
|
|
const char* entry_point);
|
|
|
|
#ifndef WINUWP
|
|
// DEPRECATED: This is no longer necessary to call, Flutter will take care of
|
|
// processing engine messages transparently through DispatchMessage.
|
|
//
|
|
// Processes any pending events in the Flutter engine, and returns the
|
|
// number of nanoseconds until the next scheduled event (or max, if none).
|
|
//
|
|
// This should be called on every run of the application-level runloop, and
|
|
// a wait for native events in the runloop should never be longer than the
|
|
// last return value from this function.
|
|
FLUTTER_EXPORT uint64_t
|
|
FlutterDesktopEngineProcessMessages(FlutterDesktopEngineRef engine);
|
|
#endif
|
|
|
|
FLUTTER_EXPORT void FlutterDesktopEngineReloadSystemFonts(
|
|
FlutterDesktopEngineRef engine);
|
|
|
|
FLUTTER_EXPORT void FlutterDesktopEngineReloadPlatformBrightness(
|
|
FlutterDesktopEngineRef engine);
|
|
|
|
// Returns the plugin registrar handle for the plugin with the given name.
|
|
//
|
|
// The name must be unique across the application.
|
|
FLUTTER_EXPORT FlutterDesktopPluginRegistrarRef
|
|
FlutterDesktopEngineGetPluginRegistrar(FlutterDesktopEngineRef engine,
|
|
const char* plugin_name);
|
|
|
|
// Returns the messenger associated with the engine.
|
|
FLUTTER_EXPORT FlutterDesktopMessengerRef
|
|
FlutterDesktopEngineGetMessenger(FlutterDesktopEngineRef engine);
|
|
|
|
// Returns the texture registrar associated with the engine.
|
|
FLUTTER_EXPORT FlutterDesktopTextureRegistrarRef
|
|
FlutterDesktopEngineGetTextureRegistrar(
|
|
FlutterDesktopTextureRegistrarRef texture_registrar);
|
|
|
|
// ========== View ==========
|
|
|
|
#ifdef WINUWP
|
|
// Return backing CoreApplicationView for manipulation of CoreWindow and
|
|
// CoreTitleBar in host application.
|
|
FLUTTER_EXPORT ABI::Windows::ApplicationModel::Core::CoreApplicationView*
|
|
FlutterDesktopViewGetCoreApplicationView(FlutterDesktopViewRef view);
|
|
#else
|
|
// Return backing HWND for manipulation in host application.
|
|
FLUTTER_EXPORT HWND FlutterDesktopViewGetHWND(FlutterDesktopViewRef view);
|
|
#endif
|
|
|
|
// ========== Plugin Registrar (extensions) ==========
|
|
// These are Windows-specific extensions to flutter_plugin_registrar.h
|
|
|
|
// Function pointer type for top level WindowProc delegate registration.
|
|
//
|
|
// The user data will be whatever was passed to
|
|
// FlutterDesktopRegisterTopLevelWindowProcHandler.
|
|
//
|
|
// Implementations should populate |result| and return true if the WindowProc
|
|
// was handled and further handling should stop. |result| is ignored if the
|
|
// function returns false.
|
|
typedef bool (*FlutterDesktopWindowProcCallback)(HWND /* hwnd */,
|
|
UINT /* uMsg */,
|
|
WPARAM /*wParam*/,
|
|
LPARAM /* lParam*/,
|
|
void* /* user data */,
|
|
LRESULT* result);
|
|
|
|
// Returns the view associated with this registrar's engine instance.
|
|
FLUTTER_EXPORT FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(
|
|
FlutterDesktopPluginRegistrarRef registrar);
|
|
|
|
#ifndef WINUWP
|
|
FLUTTER_EXPORT void
|
|
FlutterDesktopPluginRegistrarRegisterTopLevelWindowProcDelegate(
|
|
FlutterDesktopPluginRegistrarRef registrar,
|
|
FlutterDesktopWindowProcCallback delegate,
|
|
void* user_data);
|
|
|
|
FLUTTER_EXPORT void
|
|
FlutterDesktopPluginRegistrarUnregisterTopLevelWindowProcDelegate(
|
|
FlutterDesktopPluginRegistrarRef registrar,
|
|
FlutterDesktopWindowProcCallback delegate);
|
|
#endif
|
|
|
|
// ========== Freestanding Utilities ==========
|
|
|
|
// Gets the DPI for a given |hwnd|, depending on the supported APIs per
|
|
// windows version and DPI awareness mode. If nullptr is passed, returns the DPI
|
|
// of the primary monitor.
|
|
//
|
|
// This uses the same logic and fallback for older Windows versions that is used
|
|
// internally by Flutter to determine the DPI to use for displaying Flutter
|
|
// content, so should be used by any code (e.g., in plugins) that translates
|
|
// between Windows and Dart sizes/offsets.
|
|
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForHWND(HWND hwnd);
|
|
|
|
// Gets the DPI for a given |monitor|. If the API is not available, a default
|
|
// DPI of 96 is returned.
|
|
//
|
|
// See FlutterDesktopGetDpiForHWND for more information.
|
|
FLUTTER_EXPORT UINT FlutterDesktopGetDpiForMonitor(HMONITOR monitor);
|
|
|
|
// Reopens stdout and stderr and resysncs the standard library output streams.
|
|
// Should be called if output is being directed somewhere in the runner process
|
|
// (e.g., after an AllocConsole call).
|
|
FLUTTER_EXPORT void FlutterDesktopResyncOutputStreams();
|
|
|
|
#if defined(__cplusplus)
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#endif // FLUTTER_SHELL_PLATFORM_WINDOWS_PUBLIC_FLUTTER_WINDOWS_H_
|