Flutter Windows Embedder
flutter_windows_view.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_FLUTTER_WINDOWS_VIEW_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_FLUTTER_WINDOWS_VIEW_H_
7 
8 #include <memory>
9 #include <mutex>
10 #include <string>
11 #include <unordered_map>
12 #include <utility>
13 #include <vector>
14 
15 #include "flutter/fml/macros.h"
18 #include "flutter/shell/platform/embedder/embedder.h"
27 
28 namespace flutter {
29 
30 // ID for the window frame buffer.
31 inline constexpr uint32_t kWindowFrameBufferID = 0;
32 
33 // An OS-windowing neutral abstration for a Flutter view that works
34 // with win32 HWNDs.
36  public:
37  // Creates a FlutterWindowsView with the given implementor of
38  // WindowBindingHandler.
39  //
40  // In order for object to render Flutter content the SetEngine method must be
41  // called with a valid FlutterWindowsEngine instance.
43  std::unique_ptr<WindowBindingHandler> window_binding,
44  std::shared_ptr<WindowsProcTable> windows_proc_table = nullptr);
45 
46  virtual ~FlutterWindowsView();
47 
48  // Configures the window instance with an instance of a running Flutter
49  // engine.
50  void SetEngine(FlutterWindowsEngine* engine);
51 
52  // Creates rendering surface for Flutter engine to draw into.
53  // Should be called before calling FlutterEngineRun using this view.
54  void CreateRenderSurface();
55 
56  // Destroys current rendering surface if one has been allocated.
57  void DestroyRenderSurface();
58 
59  // Return the currently configured HWND.
60  virtual HWND GetWindowHandle() const;
61 
62  // Returns the engine backing this view.
64 
65  // Tells the engine to generate a new frame
66  void ForceRedraw();
67 
68  // Swap the view's surface buffers. Must be called on the engine's raster
69  // thread. Returns true if the buffers were swapped.
70  //
71  // If the view is resizing, this returns false if the frame is not the target
72  // size. Otherwise, it unblocks the platform thread and blocks the raster
73  // thread until the v-blank.
74  bool SwapBuffers();
75 
76  // Callback for presenting a software bitmap.
77  bool PresentSoftwareBitmap(const void* allocation,
78  size_t row_bytes,
79  size_t height);
80 
81  // Send initial bounds to embedder. Must occur after engine has initialized.
82  void SendInitialBounds();
83 
84  // Set the text of the alert, and create it if it does not yet exist.
85  void AnnounceAlert(const std::wstring& text);
86 
87  // |WindowBindingHandlerDelegate|
88  void OnHighContrastChanged() override;
89 
90  // Returns the frame buffer id for the engine to render to.
91  uint32_t GetFrameBufferId(size_t width, size_t height);
92 
93  // Sets the cursor that should be used when the mouse is over the Flutter
94  // content. See mouse_cursor.dart for the values and meanings of cursor_name.
95  void UpdateFlutterCursor(const std::string& cursor_name);
96 
97  // Sets the cursor directly from a cursor handle.
98  void SetFlutterCursor(HCURSOR cursor);
99 
100  // |WindowBindingHandlerDelegate|
101  void OnWindowSizeChanged(size_t width, size_t height) override;
102 
103  // |WindowBindingHandlerDelegate|
104  void OnWindowRepaint() override;
105 
106  // |WindowBindingHandlerDelegate|
107  void OnPointerMove(double x,
108  double y,
109  FlutterPointerDeviceKind device_kind,
110  int32_t device_id,
111  int modifiers_state) override;
112 
113  // |WindowBindingHandlerDelegate|
114  void OnPointerDown(double x,
115  double y,
116  FlutterPointerDeviceKind device_kind,
117  int32_t device_id,
118  FlutterPointerMouseButtons button) override;
119 
120  // |WindowBindingHandlerDelegate|
121  void OnPointerUp(double x,
122  double y,
123  FlutterPointerDeviceKind device_kind,
124  int32_t device_id,
125  FlutterPointerMouseButtons button) override;
126 
127  // |WindowBindingHandlerDelegate|
128  void OnPointerLeave(double x,
129  double y,
130  FlutterPointerDeviceKind device_kind,
131  int32_t device_id = 0) override;
132 
133  // |WindowBindingHandlerDelegate|
134  virtual void OnPointerPanZoomStart(int32_t device_id) override;
135 
136  // |WindowBindingHandlerDelegate|
137  virtual void OnPointerPanZoomUpdate(int32_t device_id,
138  double pan_x,
139  double pan_y,
140  double scale,
141  double rotation) override;
142 
143  // |WindowBindingHandlerDelegate|
144  virtual void OnPointerPanZoomEnd(int32_t device_id) override;
145 
146  // |WindowBindingHandlerDelegate|
147  void OnText(const std::u16string&) override;
148 
149  // |WindowBindingHandlerDelegate|
150  void OnKey(int key,
151  int scancode,
152  int action,
153  char32_t character,
154  bool extended,
155  bool was_down,
156  KeyEventCallback callback) override;
157 
158  // |WindowBindingHandlerDelegate|
159  void OnComposeBegin() override;
160 
161  // |WindowBindingHandlerDelegate|
162  void OnComposeCommit() override;
163 
164  // |WindowBindingHandlerDelegate|
165  void OnComposeEnd() override;
166 
167  // |WindowBindingHandlerDelegate|
168  void OnComposeChange(const std::u16string& text, int cursor_pos) override;
169 
170  // |WindowBindingHandlerDelegate|
171  void OnScroll(double x,
172  double y,
173  double delta_x,
174  double delta_y,
175  int scroll_offset_multiplier,
176  FlutterPointerDeviceKind device_kind,
177  int32_t device_id) override;
178 
179  // |WindowBindingHandlerDelegate|
180  void OnScrollInertiaCancel(int32_t device_id) override;
181 
182  // |WindowBindingHandlerDelegate|
183  virtual void OnUpdateSemanticsEnabled(bool enabled) override;
184 
185  // |WindowBindingHandlerDelegate|
186  virtual gfx::NativeViewAccessible GetNativeViewAccessible() override;
187 
188  // Notifies the delegate of the updated the cursor rect in Flutter root view
189  // coordinates.
190  virtual void OnCursorRectUpdated(const Rect& rect);
191 
192  // Notifies the delegate that the system IME composing state should be reset.
193  virtual void OnResetImeComposing();
194 
195  // Called when a WM_ONCOMPOSITIONCHANGED message is received.
197 
198  // Get a pointer to the alert node for this view.
199  ui::AXPlatformNodeWin* AlertNode() const;
200 
201  // |WindowBindingHandlerDelegate|
202  virtual ui::AXFragmentRootDelegateWin* GetAxFragmentRootDelegate() override;
203 
204  // Called to re/set the accessibility bridge pointer.
205  virtual void UpdateSemanticsEnabled(bool enabled);
206 
207  std::weak_ptr<AccessibilityBridgeWindows> accessibility_bridge() {
208  return accessibility_bridge_;
209  }
210 
211  // |WindowBindingHandlerDelegate|
212  void OnWindowStateEvent(HWND hwnd, WindowStateEvent event) override;
213 
214  protected:
215  virtual void NotifyWinEventWrapper(ui::AXPlatformNodeWin* node,
216  ax::mojom::Event event);
217 
218  // Create an AccessibilityBridgeWindows using this view.
219  virtual std::shared_ptr<AccessibilityBridgeWindows>
221 
222  private:
223  // Struct holding the state of an individual pointer. The engine doesn't keep
224  // track of which buttons have been pressed, so it's the embedding's
225  // responsibility.
226  struct PointerState {
227  // The device kind.
228  FlutterPointerDeviceKind device_kind = kFlutterPointerDeviceKindMouse;
229 
230  // A virtual pointer ID that is unique across all device kinds.
231  int32_t pointer_id = 0;
232 
233  // True if the last event sent to Flutter had at least one button pressed.
234  bool flutter_state_is_down = false;
235 
236  // True if kAdd has been sent to Flutter. Used to determine whether
237  // to send a kAdd event before sending an incoming pointer event, since
238  // Flutter expects pointers to be added before events are sent for them.
239  bool flutter_state_is_added = false;
240 
241  // The currently pressed buttons, as represented in FlutterPointerEvent.
242  uint64_t buttons = 0;
243 
244  // The x position where the last pan/zoom started.
245  double pan_zoom_start_x = 0;
246 
247  // The y position where the last pan/zoom started.
248  double pan_zoom_start_y = 0;
249  };
250 
251  // States a resize event can be in.
252  enum class ResizeState {
253  // When a resize event has started but is in progress.
254  kResizeStarted,
255  // After a resize event starts and the framework has been notified to
256  // generate a frame for the right size.
257  kFrameGenerated,
258  // Default state for when no resize is in progress. Also used to indicate
259  // that during a resize event, a frame with the right size has been rendered
260  // and the buffers have been swapped.
261  kDone,
262  };
263 
264  // Sends a window metrics update to the Flutter engine using current window
265  // dimensions in physical
266  void SendWindowMetrics(size_t width, size_t height, double dpiscale) const;
267 
268  // Reports a mouse movement to Flutter engine.
269  void SendPointerMove(double x, double y, PointerState* state);
270 
271  // Reports mouse press to Flutter engine.
272  void SendPointerDown(double x, double y, PointerState* state);
273 
274  // Reports mouse release to Flutter engine.
275  void SendPointerUp(double x, double y, PointerState* state);
276 
277  // Reports mouse left the window client area.
278  //
279  // Win32 api doesn't have "mouse enter" event. Therefore, there is no
280  // SendPointerEnter method. A mouse enter event is tracked then the "move"
281  // event is called.
282  void SendPointerLeave(double x, double y, PointerState* state);
283 
284  void SendPointerPanZoomStart(int32_t device_id, double x, double y);
285 
286  void SendPointerPanZoomUpdate(int32_t device_id,
287  double pan_x,
288  double pan_y,
289  double scale,
290  double rotation);
291 
292  void SendPointerPanZoomEnd(int32_t device_id);
293 
294  // Reports a keyboard character to Flutter engine.
295  void SendText(const std::u16string&);
296 
297  // Reports a raw keyboard message to Flutter engine.
298  void SendKey(int key,
299  int scancode,
300  int action,
301  char32_t character,
302  bool extended,
303  bool was_down,
305 
306  // Reports an IME compose begin event.
307  //
308  // Triggered when the user begins editing composing text using a multi-step
309  // input method such as in CJK text input.
310  void SendComposeBegin();
311 
312  // Reports an IME compose commit event.
313  //
314  // Triggered when the user commits the current composing text while using a
315  // multi-step input method such as in CJK text input. Composing continues with
316  // the next keypress.
317  void SendComposeCommit();
318 
319  // Reports an IME compose end event.
320  //
321  // Triggered when the user commits the composing text while using a multi-step
322  // input method such as in CJK text input.
323  void SendComposeEnd();
324 
325  // Reports an IME composing region change event.
326  //
327  // Triggered when the user edits the composing text while using a multi-step
328  // input method such as in CJK text input.
329  void SendComposeChange(const std::u16string& text, int cursor_pos);
330 
331  // Reports scroll wheel events to Flutter engine.
332  void SendScroll(double x,
333  double y,
334  double delta_x,
335  double delta_y,
336  int scroll_offset_multiplier,
337  FlutterPointerDeviceKind device_kind,
338  int32_t device_id);
339 
340  // Reports scroll inertia cancel events to Flutter engine.
341  void SendScrollInertiaCancel(int32_t device_id, double x, double y);
342 
343  // Creates a PointerState object unless it already exists.
344  PointerState* GetOrCreatePointerState(FlutterPointerDeviceKind device_kind,
345  int32_t device_id);
346 
347  // Sets |event_data|'s phase to either kMove or kHover depending on the
348  // current primary mouse button state.
349  void SetEventPhaseFromCursorButtonState(FlutterPointerEvent* event_data,
350  const PointerState* state) const;
351 
352  // Sends a pointer event to the Flutter engine based on given data. Since
353  // all input messages are passed in physical pixel values, no translation is
354  // needed before passing on to engine.
355  void SendPointerEventWithData(const FlutterPointerEvent& event_data,
356  PointerState* state);
357 
358  // If true, rendering to the window should synchronize with the vsync
359  // to prevent screen tearing.
360  bool NeedsVsync() const;
361 
362  // The engine associated with this view.
363  FlutterWindowsEngine* engine_ = nullptr;
364 
365  // Mocks win32 APIs.
366  std::shared_ptr<WindowsProcTable> windows_proc_table_;
367 
368  // Keeps track of pointer states in relation to the window.
369  std::unordered_map<int32_t, std::unique_ptr<PointerState>> pointer_states_;
370 
371  // Currently configured WindowBindingHandler for view.
372  std::unique_ptr<WindowBindingHandler> binding_handler_;
373 
374  // Resize events are synchronized using this mutex and the corresponding
375  // condition variable.
376  std::mutex resize_mutex_;
377  std::condition_variable resize_cv_;
378 
379  // Indicates the state of a window resize event. Platform thread will be
380  // blocked while this is not done. Guarded by resize_mutex_.
381  ResizeState resize_status_ = ResizeState::kDone;
382 
383  // Target for the window width. Valid when resize_pending_ is set. Guarded by
384  // resize_mutex_.
385  size_t resize_target_width_ = 0;
386 
387  // Target for the window width. Valid when resize_pending_ is set. Guarded by
388  // resize_mutex_.
389  size_t resize_target_height_ = 0;
390 
391  // True when flutter's semantics tree is enabled.
392  bool semantics_enabled_ = false;
393 
394  // The accessibility bridge associated with this view.
395  std::shared_ptr<AccessibilityBridgeWindows> accessibility_bridge_;
396 
397  FML_DISALLOW_COPY_AND_ASSIGN(FlutterWindowsView);
398 };
399 
400 } // namespace flutter
401 
402 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_FLUTTER_WINDOWS_VIEW_H_
flutter::FlutterWindowsView::OnPointerMove
void OnPointerMove(double x, double y, FlutterPointerDeviceKind device_kind, int32_t device_id, int modifiers_state) override
Definition: flutter_windows_view.cc:181
flutter::FlutterWindowsView::OnPointerUp
void OnPointerUp(double x, double y, FlutterPointerDeviceKind device_kind, int32_t device_id, FlutterPointerMouseButtons button) override
Definition: flutter_windows_view.cc:203
flutter::WindowStateEvent
WindowStateEvent
An event representing a change in window state that may update the.
Definition: windows_lifecycle_manager.h:24
flutter::FlutterWindowsView::OnWindowStateEvent
void OnWindowStateEvent(HWND hwnd, WindowStateEvent event) override
Definition: flutter_windows_view.cc:699
flutter::FlutterWindowsView::CreateRenderSurface
void CreateRenderSurface()
Definition: flutter_windows_view.cc:622
flutter::FlutterWindowsView::OnWindowSizeChanged
void OnWindowSizeChanged(size_t width, size_t height) override
Definition: flutter_windows_view.cc:143
flutter::FlutterWindowsView::OnUpdateSemanticsEnabled
virtual void OnUpdateSemanticsEnabled(bool enabled) override
Definition: flutter_windows_view.cc:287
flutter::FlutterWindowsView::OnComposeCommit
void OnComposeCommit() override
Definition: flutter_windows_view.cc:258
flutter::FlutterWindowsView
Definition: flutter_windows_view.h:35
scancode
int scancode
Definition: keyboard_key_handler_unittests.cc:115
flutter::FlutterWindowsView::~FlutterWindowsView
virtual ~FlutterWindowsView()
Definition: flutter_windows_view.cc:85
geometry.h
was_down
bool was_down
Definition: keyboard_key_handler_unittests.cc:119
extended
bool extended
Definition: keyboard_key_handler_unittests.cc:118
plugin_registrar.h
flutter::FlutterWindowsView::OnPointerDown
void OnPointerDown(double x, double y, FlutterPointerDeviceKind device_kind, int32_t device_id, FlutterPointerMouseButtons button) override
Definition: flutter_windows_view.cc:190
flutter::FlutterWindowsEngine
Definition: flutter_windows_engine.h:78
character
char32_t character
Definition: keyboard_key_handler_unittests.cc:117
flutter::FlutterWindowsView::OnComposeChange
void OnComposeChange(const std::u16string &text, int cursor_pos) override
Definition: flutter_windows_view.cc:266
flutter::FlutterWindowsView::accessibility_bridge
std::weak_ptr< AccessibilityBridgeWindows > accessibility_bridge()
Definition: flutter_windows_view.h:207
flutter::FlutterWindowsView::OnScrollInertiaCancel
void OnScrollInertiaCancel(int32_t device_id) override
Definition: flutter_windows_view.cc:282
flutter::FlutterWindowsView::ForceRedraw
void ForceRedraw()
Definition: flutter_windows_view.cc:136
flutter::FlutterWindowsView::DestroyRenderSurface
void DestroyRenderSurface()
Definition: flutter_windows_view.cc:635
flutter::FlutterWindowsView::OnPointerPanZoomStart
virtual void OnPointerPanZoomStart(int32_t device_id) override
Definition: flutter_windows_view.cc:223
flutter::WindowBindingHandlerDelegate
Definition: window_binding_handler_delegate.h:18
angle_surface_manager.h
flutter::Rect
Definition: geometry.h:56
flutter::FlutterWindowsView::AnnounceAlert
void AnnounceAlert(const std::wstring &text)
Definition: flutter_windows_view.cc:653
flutter::kWindowFrameBufferID
constexpr uint32_t kWindowFrameBufferID
Definition: flutter_windows_view.h:31
windows_proc_table.h
flutter::FlutterWindowsView::GetWindowHandle
virtual HWND GetWindowHandle() const
Definition: flutter_windows_view.cc:645
flutter::FlutterWindowsView::OnPointerPanZoomUpdate
virtual void OnPointerPanZoomUpdate(int32_t device_id, double pan_x, double pan_y, double scale, double rotation) override
Definition: flutter_windows_view.cc:228
flutter::FlutterWindowsView::OnWindowRepaint
void OnWindowRepaint() override
Definition: flutter_windows_view.cc:177
flutter::WindowBindingHandlerDelegate::KeyEventCallback
std::function< void(bool)> KeyEventCallback
Definition: window_binding_handler_delegate.h:20
flutter::FlutterWindowsView::OnComposeEnd
void OnComposeEnd() override
Definition: flutter_windows_view.cc:262
text
std::u16string text
Definition: keyboard_unittests.cc:332
flutter::FlutterWindowsView::SwapBuffers
bool SwapBuffers()
Definition: flutter_windows_view.cc:576
flutter::FlutterWindowsView::OnHighContrastChanged
void OnHighContrastChanged() override
Definition: flutter_windows_view.cc:641
accessibility_bridge_windows.h
window_binding_handler.h
window_state.h
flutter
Definition: accessibility_bridge_windows.cc:11
flutter::FlutterWindowsView::UpdateFlutterCursor
void UpdateFlutterCursor(const std::string &cursor_name)
Definition: flutter_windows_view.cc:128
flutter::FlutterWindowsView::SetFlutterCursor
void SetFlutterCursor(HCURSOR cursor)
Definition: flutter_windows_view.cc:132
flutter::FlutterWindowsView::OnPointerLeave
void OnPointerLeave(double x, double y, FlutterPointerDeviceKind device_kind, int32_t device_id=0) override
Definition: flutter_windows_view.cc:216
flutter::FlutterWindowsView::OnText
void OnText(const std::u16string &) override
Definition: flutter_windows_view.cc:240
flutter::FlutterWindowsView::PresentSoftwareBitmap
bool PresentSoftwareBitmap(const void *allocation, size_t row_bytes, size_t height)
Definition: flutter_windows_view.cc:615
flutter::FlutterWindowsView::OnCursorRectUpdated
virtual void OnCursorRectUpdated(const Rect &rect)
Definition: flutter_windows_view.cc:299
flutter::FlutterWindowsView::AlertNode
ui::AXPlatformNodeWin * AlertNode() const
Definition: flutter_windows_view.cc:674
flutter::FlutterWindowsView::SetEngine
void SetEngine(FlutterWindowsEngine *engine)
Definition: flutter_windows_view.cc:95
flutter::FlutterWindowsView::OnPointerPanZoomEnd
virtual void OnPointerPanZoomEnd(int32_t device_id) override
Definition: flutter_windows_view.cc:236
flutter::FlutterWindowsView::OnDwmCompositionChanged
void OnDwmCompositionChanged()
Definition: flutter_windows_view.cc:695
flutter::FlutterWindowsView::NotifyWinEventWrapper
virtual void NotifyWinEventWrapper(ui::AXPlatformNodeWin *node, ax::mojom::Event event)
Definition: flutter_windows_view.cc:663
flutter_windows_engine.h
flutter::FlutterWindowsView::UpdateSemanticsEnabled
virtual void UpdateSemanticsEnabled(bool enabled)
Definition: flutter_windows_view.cc:683
flutter::FlutterWindowsView::OnComposeBegin
void OnComposeBegin() override
Definition: flutter_windows_view.cc:254
flutter_windows.h
flutter::FlutterWindowsView::SendInitialBounds
void SendInitialBounds()
Definition: flutter_windows_view.cc:319
flutter::FlutterWindowsView::CreateAccessibilityBridge
virtual std::shared_ptr< AccessibilityBridgeWindows > CreateAccessibilityBridge()
Definition: flutter_windows_view.cc:679
action
int action
Definition: keyboard_key_handler_unittests.cc:116
flutter::FlutterWindowsView::OnScroll
void OnScroll(double x, double y, double delta_x, double delta_y, int scroll_offset_multiplier, FlutterPointerDeviceKind device_kind, int32_t device_id) override
Definition: flutter_windows_view.cc:271
flutter::FlutterWindowsView::GetAxFragmentRootDelegate
virtual ui::AXFragmentRootDelegateWin * GetAxFragmentRootDelegate() override
Definition: flutter_windows_view.cc:670
key
int key
Definition: keyboard_key_handler_unittests.cc:114
window_binding_handler_delegate.h
flutter::FlutterWindowsView::OnKey
void OnKey(int key, int scancode, int action, char32_t character, bool extended, bool was_down, KeyEventCallback callback) override
Definition: flutter_windows_view.cc:244
flutter::FlutterWindowsView::GetNativeViewAccessible
virtual gfx::NativeViewAccessible GetNativeViewAccessible() override
Definition: flutter_windows_view.cc:291
flutter::FlutterWindowsView::OnResetImeComposing
virtual void OnResetImeComposing()
Definition: flutter_windows_view.cc:303
flutter::FlutterWindowsView::GetEngine
FlutterWindowsEngine * GetEngine()
Definition: flutter_windows_view.cc:649
flutter::FlutterWindowsView::GetFrameBufferId
uint32_t GetFrameBufferId(size_t width, size_t height)
Definition: flutter_windows_view.cc:109
flutter::FlutterWindowsView::FlutterWindowsView
FlutterWindowsView(std::unique_ptr< WindowBindingHandler > window_binding, std::shared_ptr< WindowsProcTable > windows_proc_table=nullptr)
Definition: flutter_windows_view.cc:72
callback
FlutterDesktopBinaryReply callback
Definition: flutter_windows_view_unittests.cc:48