| Flutter Windows Embedder |

platform_handler.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_PLATFORM_HANDLER_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_PLATFORM_HANDLER_H_
7
8 #include <Windows.h>
9
10 #include <functional>
11 #include <memory>
12 #include <optional>
13 #include <variant>
14
15 #include "flutter/fml/macros.h"
16 #include "flutter/shell/platform/common/client_wrapper/include/flutter/binary_messenger.h"
17 #include "flutter/shell/platform/common/client_wrapper/include/flutter/method_channel.h"
18 #include "rapidjson/document.h"
19
20 namespace flutter {
21
22 class FlutterWindowsEngine;
23 class ScopedClipboardInterface;
24
25 // Indicates whether an exit request may be canceled by the framework.
26 // These values must be kept in sync with kExitTypeNames in platform_handler.cc
27 enum class AppExitType {
28 required,
29 cancelable,
30 };
31
32 // Handler for internal system channels.
33 class PlatformHandler {
34 public:
35 explicit PlatformHandler(
36 BinaryMessenger* messenger,
37 FlutterWindowsEngine* engine,
38 std::optional<std::function<std::unique_ptr<ScopedClipboardInterface>()>>
39 scoped_clipboard_provider = std::nullopt);
40
41 virtual ~PlatformHandler();
42
43 // String values used for encoding/decoding exit requests.
44 static constexpr char kExitTypeCancelable[] = "cancelable";
45 static constexpr char kExitTypeRequired[] = "required";
46
47 // Send a request to the framework to test if a cancelable exit request
48 // should be canceled or honored. hwnd is std::nullopt for a request to quit
49 // the process, otherwise it holds the HWND of the window that initiated the
50 // quit request.
51 virtual void RequestAppExit(std::optional<HWND> hwnd,
52 std::optional<WPARAM> wparam,
53 std::optional<LPARAM> lparam,
54 AppExitType exit_type,
55 UINT exit_code);
56
57 protected:
58 // Gets plain text from the clipboard and provides it to |result| as the
59 // value in a dictionary with the given |key|.
60 virtual void GetPlainText(
61 std::unique_ptr<MethodResult<rapidjson::Document>> result,
62 std::string_view key);
63
64 // Provides a boolean to |result| as the value in a dictionary at key
65 // "value" representing whether or not the clipboard has a non-empty string.
66 virtual void GetHasStrings(
67 std::unique_ptr<MethodResult<rapidjson::Document>> result);
68
69 // Sets the clipboard's plain text to |text|, and reports the result (either
70 // an error, or null for success) to |result|.
71 virtual void SetPlainText(
72 const std::string& text,
73 std::unique_ptr<MethodResult<rapidjson::Document>> result);
74
75 virtual void SystemSoundPlay(
76 const std::string& sound_type,
77 std::unique_ptr<MethodResult<rapidjson::Document>> result);
78
79 // Handle a request from the framework to exit the application.
80 virtual void SystemExitApplication(
81 AppExitType exit_type,
82 UINT exit_code,
83 std::unique_ptr<MethodResult<rapidjson::Document>> result);
84
85 // Actually quit the application with the provided exit code. hwnd is
86 // std::nullopt for a request to quit the process, otherwise it holds the HWND
87 // of the window that initiated the quit request.
88 virtual void QuitApplication(std::optional<HWND> hwnd,
89 std::optional<WPARAM> wparam,
90 std::optional<LPARAM> lparam,
91 UINT exit_code);
92
93 // Callback from when the cancelable exit request response request is
94 // answered by the framework. hwnd is std::nullopt for a request to quit the
95 // process, otherwise it holds the HWND of the window that initiated the quit
96 // request.
97 virtual void RequestAppExitSuccess(std::optional<HWND> hwnd,
98 std::optional<WPARAM> wparam,
99 std::optional<LPARAM> lparam,
100 const rapidjson::Document* result,
101 UINT exit_code);
102
103 // A error type to use for error responses.
104 static constexpr char kClipboardError[] = "Clipboard error";
105
106 static constexpr char kSoundTypeAlert[] = "SystemSoundType.alert";
107 static constexpr char kSoundTypeClick[] = "SystemSoundType.click";
108 static constexpr char kSoundTypeTick[] = "SystemSoundType.tick";
109
110 private:
111 WNDCLASS RegisterWindowClass();
112
113 // Called when a method is called on |channel_|;
114 void HandleMethodCall(
115 const MethodCall<rapidjson::Document>& method_call,
116 std::unique_ptr<MethodResult<rapidjson::Document>> result);
117
118 static LRESULT CALLBACK WndProc(HWND const window,
119 UINT const message,
120 WPARAM const wparam,
121 LPARAM const lparam) noexcept;
122
123 // The MethodChannel used for communication with the Flutter engine.
124 std::unique_ptr<MethodChannel<rapidjson::Document>> channel_;
125
126 // A reference to the Flutter engine.
127 FlutterWindowsEngine* engine_;
128
129 HWND window_handle_ = nullptr;
130
131 // A scoped clipboard provider that can be passed in for mocking in tests.
132 // Use this to acquire clipboard in each operation to avoid blocking clipboard
133 // unnecessarily. See flutter/flutter#103205.
134 std::function<std::unique_ptr<ScopedClipboardInterface>()>
135 scoped_clipboard_provider_;
136
137 FML_DISALLOW_COPY_AND_ASSIGN(PlatformHandler);
138 };
139
140 // A public interface for ScopedClipboard, so that it can be injected into
141 // PlatformHandler.
142 class ScopedClipboardInterface {
143 public:
144 virtual ~ScopedClipboardInterface() {};
145
146 // Attempts to open the clipboard for the given window, returning the error
147 // code in the case of failure and 0 otherwise.
148 virtual int Open(HWND window) = 0;
149
150 // Returns true if there is string data available to get.
151 virtual bool HasString() = 0;
152
153 // Returns string data from the clipboard.
154 //
155 // If getting a string fails, returns the error code.
156 //
157 // Open(...) must have succeeded to call this method.
158 virtual std::variant<std::wstring, int> GetString() = 0;
159
160 // Sets the string content of the clipboard, returning the error code on
161 // failure and 0 otherwise.
162 //
163 // Open(...) must have succeeded to call this method.
164 virtual int SetString(const std::wstring string) = 0;
165 };
166
167 } // namespace flutter
168
169 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_PLATFORM_HANDLER_H_
binary_messenger.h
flutter::BinaryMessenger
Definition: binary_messenger.h:28
flutter::FlutterWindowsEngine
Definition: flutter_windows_engine.h:92
flutter::MethodCall
Definition: method_call.h:18
flutter::MethodResult
Definition: method_result.h:17
flutter::PlatformHandler
Definition: platform_handler.h:33
flutter::PlatformHandler::QuitApplication
virtual void QuitApplication(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, UINT exit_code)
Definition: platform_handler.cc:447
flutter::PlatformHandler::GetHasStrings
virtual void GetHasStrings(std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:313
flutter::PlatformHandler::kSoundTypeTick
static constexpr char kSoundTypeTick[]
Definition: platform_handler.h:108
flutter::PlatformHandler::RequestAppExitSuccess
virtual void RequestAppExitSuccess(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, const rapidjson::Document *result, UINT exit_code)
Definition: platform_handler.cc:428
flutter::PlatformHandler::kClipboardError
static constexpr char kClipboardError[]
Definition: platform_handler.h:104
flutter::PlatformHandler::PlatformHandler
PlatformHandler(BinaryMessenger *messenger, FlutterWindowsEngine *engine, std::optional< std::function< std::unique_ptr< ScopedClipboardInterface >()>> scoped_clipboard_provider=std::nullopt)
Definition: platform_handler.cc:224
flutter::PlatformHandler::kSoundTypeClick
static constexpr char kSoundTypeClick[]
Definition: platform_handler.h:107
flutter::PlatformHandler::SystemSoundPlay
virtual void SystemSoundPlay(const std::string &sound_type, std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:366
flutter::PlatformHandler::kExitTypeCancelable
static constexpr char kExitTypeCancelable[]
Definition: platform_handler.h:44
flutter::PlatformHandler::SystemExitApplication
virtual void SystemExitApplication(AppExitType exit_type, UINT exit_code, std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:383
flutter::PlatformHandler::GetPlainText
virtual void GetPlainText(std::unique_ptr< MethodResult< rapidjson::Document >> result, std::string_view key)
Definition: platform_handler.cc:276
flutter::PlatformHandler::~PlatformHandler
virtual ~PlatformHandler()
Definition: platform_handler.cc:268
flutter::PlatformHandler::RequestAppExit
virtual void RequestAppExit(std::optional< HWND > hwnd, std::optional< WPARAM > wparam, std::optional< LPARAM > lparam, AppExitType exit_type, UINT exit_code)
Definition: platform_handler.cc:408
flutter::PlatformHandler::kExitTypeRequired
static constexpr char kExitTypeRequired[]
Definition: platform_handler.h:45
flutter::PlatformHandler::kSoundTypeAlert
static constexpr char kSoundTypeAlert[]
Definition: platform_handler.h:106
flutter::PlatformHandler::SetPlainText
virtual void SetPlainText(const std::string &text, std::unique_ptr< MethodResult< rapidjson::Document >> result)
Definition: platform_handler.cc:343
flutter::ScopedClipboardInterface
Definition: platform_handler.h:142
flutter::ScopedClipboardInterface::GetString
virtual std::variant< std::wstring, int > GetString()=0
flutter::ScopedClipboardInterface::SetString
virtual int SetString(const std::wstring string)=0
flutter::ScopedClipboardInterface::HasString
virtual bool HasString()=0
flutter::ScopedClipboardInterface::Open
virtual int Open(HWND window)=0
flutter::ScopedClipboardInterface::~ScopedClipboardInterface
virtual ~ScopedClipboardInterface()
Definition: platform_handler.h:144
key
int key
Definition: keyboard_key_handler_unittests.cc:114
text
std::u16string text
Definition: keyboard_unittests.cc:332
message
Win32Message message
Definition: keyboard_unittests.cc:137
method_channel.h
flutter
Definition: accessibility_bridge_windows.cc:11
flutter::AppExitType
AppExitType
Definition: platform_handler.h:27
flutter::AppExitType::required
@ required
flutter::AppExitType::cancelable
@ cancelable