Flutter Windows Embedder
host_window.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_HOST_WINDOW_H_
6 #define FLUTTER_SHELL_PLATFORM_WINDOWS_HOST_WINDOW_H_
7 
8 #include <shobjidl.h>
9 #include <windows.h>
10 #include <wrl/client.h>
11 #include <memory>
12 #include <optional>
13 #include <string>
14 
15 #include "flutter/fml/macros.h"
16 #include "flutter/shell/geometry/geometry.h"
19 
20 namespace flutter {
21 
22 class WindowManager;
23 class WindowsProcTable;
24 class FlutterWindowsView;
25 class FlutterWindowsViewSizingDelegate;
26 class FlutterWindowsViewController;
27 
28 // A Win32 window that hosts a |FlutterWindow| in its client area.
29 class HostWindow {
30  public:
31  virtual ~HostWindow();
32 
33  // Creates a regular Win32 window with a child view confined to its client
34  // area. |window_manager| is a pointer to the window manager that manages the
35  // |HostWindow|. |engine| is a pointer to the engine that manages
36  // the window manager. |preferred_size| is the preferred size of the window.
37  // |preferred_constraints| are the constraints set on the window's size.
38  // |title| is the title of the window.
39  //
40  // On success, a valid window handle can be retrieved
41  // via |HostWindow::GetWindowHandle|. |nullptr| will be returned
42  // on failure.
43  static std::unique_ptr<HostWindow> CreateRegularWindow(
44  WindowManager* window_manager,
45  FlutterWindowsEngine* engine,
46  const WindowSizeRequest& preferred_size,
47  const WindowConstraints& preferred_constraints,
48  LPCWSTR title,
49  bool sized_to_content,
50  bool resizable);
51 
52  // Creates a dialog Win32 window with a child view confined to its client
53  // area. |window_manager| is a pointer to the window manager that manages the
54  // |HostWindow|. |engine| is a pointer to the engine that manages
55  // the window manager. |preferred_size| is the preferred size of the window.
56  // |preferred_constraints| are the constraints set on the window's size.
57  // |title| is the title of the window. |parent| is the parent of this dialog,
58  // which can be `nullptr`.
59  //
60  // On success, a valid window handle can be retrieved
61  // via |HostWindow::GetWindowHandle|. `nullptr` will be returned
62  // on failure.
63  static std::unique_ptr<HostWindow> CreateDialogWindow(
64  WindowManager* window_manager,
65  FlutterWindowsEngine* engine,
66  const WindowSizeRequest& preferred_size,
67  const WindowConstraints& preferred_constraints,
68  LPCWSTR title,
69  HWND parent,
70  bool sized_to_content,
71  bool resizable);
72 
73  // Creates a tooltip Win32 window with a child view confined to its client
74  // area. |window_manager| is a pointer to the window manager that manages the
75  // |HostWindow|. |engine| is a pointer to the engine that manages
76  // the window manager. |preferred_constraints| are the constraints set on
77  // the window's size. |get_position_callback| is a callback
78  // that determines the position of the tooltip window. It is invoked on the
79  // platform thread whenever the rendered content size of the tooltip changes,
80  // including after the initial frame is rendered and on any subsequent content
81  // resize. It is not called in response to parent window movement or other
82  // Win32 window messages. |parent| is the parent of this tooltip, which must
83  // be non-null.
84  static std::unique_ptr<HostWindow> CreateTooltipWindow(
85  WindowManager* window_manager,
86  FlutterWindowsEngine* engine,
87  const WindowConstraints& preferred_constraints,
88  GetWindowPositionCallback get_position_callback,
89  HWND parent);
90 
91  // Creates a popup Win32 window with a child view confined to its client
92  // area. |window_manager| is a pointer to the window manager that manages the
93  // |HostWindow|. |engine| is a pointer to the engine that manages
94  // the window manager. |preferred_constraints| are the constraints set on
95  // the window's size. |get_position_callback| is a callback that determines
96  // the position of the popup window. It is invoked on the platform thread
97  // whenever the rendered content size of the popup changes, including after
98  // the initial frame is rendered and on any subsequent content resize. It is
99  // not called in response to parent window movement or other Win32 window
100  // messages. |parent| is the parent of this popup, which must be non-null.
101  static std::unique_ptr<HostWindow> CreatePopupWindow(
102  WindowManager* window_manager,
103  FlutterWindowsEngine* engine,
104  const WindowConstraints& preferred_constraints,
105  GetWindowPositionCallback get_position_callback,
106  HWND parent);
107 
108  // Creates a satellite Win32 window with a child view confined to its client
109  // area. |window_manager| is a pointer to the window manager that manages the
110  // |HostWindow|. |engine| is a pointer to the engine that manages the window
111  // manager. |preferred_size| is the requested content size, which is required
112  // unless |sized_to_content| is true. |preferred_constraints| are the
113  // constraints set on the window's size. |get_position_callback| is a callback
114  // that determines the initial position of the satellite window; unlike for
115  // tooltips and popups it is invoked only once, for the initial placement.
116  // |parent| is the window this satellite is anchored to, which must be
117  // non-null. |title| is the window title. When |sized_to_content| is true the
118  // window is resized to fit its rendered content after the first frame. When
119  // |resizable| is true the user can resize the window manually.
120  //
121  // A satellite follows its parent's movement, retaining the offset it has from
122  // it, and cannot be minimized on its own.
123  static std::unique_ptr<HostWindow> CreateSatelliteWindow(
124  WindowManager* window_manager,
125  FlutterWindowsEngine* engine,
126  const WindowSizeRequest& preferred_size,
127  const WindowConstraints& preferred_constraints,
128  GetWindowPositionCallback get_position_callback,
129  HWND parent,
130  LPCWSTR title,
131  bool sized_to_content,
132  bool resizable);
133 
134  // Returns the instance pointer for |hwnd| or nullptr if invalid.
135  static HostWindow* GetThisFromHandle(HWND hwnd);
136 
137  // Returns the backing window handle, or nullptr if the native window is not
138  // created or has already been destroyed.
139  HWND GetWindowHandle() const;
140 
141  // Returns the HWND of the FlutterView hosted in this window.
142  HWND GetFlutterViewWindowHandle() const;
143 
144  // Resizes the window to accommodate a client area of the given
145  // |size|. If the size does not satisfy the constraints, the window will be
146  // resized to the minimum or maximum size as appropriate.
147  void SetContentSize(const WindowSizeRequest& size);
148 
149  // Sets the constaints on the client area of the window.
150  // If the current window size does not satisfy the new constraints,
151  // the window will be resized to satisy thew new constraints.
152  void SetConstraints(const WindowConstraints& constraints);
153 
154  // Set the fullscreen state. |display_id| indicates the display where
155  // the window should be shown fullscreen; std::nullopt indicates
156  // that no display was specified, so the current display may be used.
157  virtual void SetFullscreen(bool fullscreen,
158  std::optional<FlutterEngineDisplayId> display_id);
159 
160  // Returns |true| if this window is fullscreen, otherwise |false|.
161  virtual bool GetFullscreen() const;
162 
163  // Given a window identifier, returns the window content size of the
164  // window.
165  static ActualWindowSize GetWindowContentSize(HWND hwnd);
166 
167  // Returns the owner window, or nullptr if none.
168  HostWindow* GetOwnerWindow() const;
169 
170  // This method is called when a dialog is created or destroyed.
171  // It walks the path of child windows to make sure that the right
172  // windows are enabled or disabled.
173  void UpdateModalStateLayer();
174 
175  protected:
176  // Returns the archetype of this window.
178 
183  const BoxConstraints& box_constraints;
185  LPCWSTR title;
186  std::optional<HWND> const& owner_window;
187  int nCmdShow = SW_SHOWNORMAL;
189  bool is_sized_to_content = false;
190  };
191 
192  // Initialize the underlying native window and the Flutter view.
193  //
194  // See:
195  // - https://learn.microsoft.com/windows/win32/winmsg/window-styles
196  // - https://learn.microsoft.com/windows/win32/winmsg/extended-window-styles
198 
200 
201  // Information saved before going into fullscreen mode, used to restore the
202  // window afterwards.
204  LONG style;
205  LONG ex_style;
206  RECT rect;
208  int dpi;
209  HMONITOR monitor;
210  MONITORINFO monitor_info;
211  };
212 
213  // Construct a host window.
214  //
215  // Derived classes should call InitializeFlutterView() after construction to
216  // set up the native window and the Flutter view.
217  HostWindow(WindowManager* window_manager, FlutterWindowsEngine* engine);
218 
219  // Calculates the required window size, in physical coordinates, to
220  // accommodate the given |client_size|, in logical coordinates, constrained by
221  // optional |smallest| and |biggest|, for a window with the specified
222  // |window_style| and |extended_window_style|. If |owner_hwnd| is not null,
223  // the DPI of the display with the largest area of intersection with
224  // |owner_hwnd| is used for the calculation; otherwise, the primary display's
225  // DPI is used. The resulting size includes window borders, non-client areas,
226  // and drop shadows. On error, returns std::nullopt and logs an error message.
227  static std::optional<Size> GetWindowSizeForClientSize(
228  WindowsProcTable const& win32,
229  Size const& client_size,
230  std::optional<Size> smallest,
231  std::optional<Size> biggest,
232  DWORD window_style,
233  DWORD extended_window_style,
234  std::optional<HWND> const& owner_hwnd);
235 
236  // Calculates the initial window size, in physical coordinates, of a window
237  // with the specified |window_style| and |extended_window_style|, owned by
238  // |owner_window|. If |sized_to_content| is true, the window is sized to the
239  // smallest size allowed by |constraints|, which gives the view valid metrics
240  // until the window is resized to fit its content after the first frame;
241  // otherwise, the window is sized to |preferred_size|. On error, returns
242  // std::nullopt and logs an error message.
243  static std::optional<Size> GetInitialWindowSize(
244  FlutterWindowsEngine* engine,
245  const WindowSizeRequest& preferred_size,
246  const BoxConstraints& constraints,
247  DWORD window_style,
248  DWORD extended_window_style,
249  std::optional<HWND> const& owner_window,
250  bool sized_to_content);
251 
252  // Moves the window so that the origin of its window frame, rather than the
253  // origin of its window rectangle (which includes the invisible drop-shadow
254  // border), lands on the position the window was last placed at. Does nothing
255  // if the window has no drop-shadow border.
256  void AlignOriginWithFrame();
257 
258  // Called on the platform thread after this window's view has presented its
259  // first frame, just before the window is shown for the first time. Overridden
260  // by archetypes that must finish their initialization once the view has
261  // rendered, so that the work is not visible to the user. The default
262  // implementation does nothing.
263  virtual void OnFirstFrame();
264 
265  // Processes and routes salient window messages for mouse handling,
266  // size change and DPI. Delegates handling of these to member overloads that
267  // inheriting classes can handle.
268  virtual LRESULT HandleMessage(HWND hwnd,
269  UINT message,
270  WPARAM wparam,
271  LPARAM lparam);
272 
273  // Sets the focus to the child view window of |window|.
274  static void FocusRootViewOf(HostWindow* window);
275 
276  // Handles a WM_ACTIVATE message for |hwnd| with the given |wparam|. When the
277  // window is being activated, focus its view; if the window is disabled
278  // (e.g. it owns a modal dialog), activation is instead redirected to the
279  // first enabled descendant. Does nothing when the window is being
280  // deactivated, so that a deactivated window does not reactivate itself and
281  // jump back to the top of the z-order.
282  void HandleWindowActivation(HWND hwnd, WPARAM wparam);
283 
284  // Enables or disables mouse and keyboard input to this window and all its
285  // descendants.
286  void EnableRecursively(bool enable);
287 
288  // Returns the first enabled descendant window. If the current window itself
289  // is enabled, returns the current window. If no window is enabled, returns
290  // `nullptr`.
292 
293  // Returns windows owned by this window.
294  std::vector<HostWindow*> GetOwnedWindows() const;
295 
296  // Disables mouse and keyboard input to the window and all its descendants.
297  void DisableRecursively();
298 
299  // OS callback called by message pump. Handles the WM_NCCREATE message which
300  // is passed when the non-client area is being created and enables automatic
301  // non-client DPI scaling so that the non-client area automatically
302  // responds to changes in DPI. Delegates other messages to the controller.
303  static LRESULT WndProc(HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam);
304 
305  // Controller for this window.
306  WindowManager* const window_manager_ = nullptr;
307 
308  // The Flutter engine that owns this window.
310 
311  // Controller for the view hosted in this window. Value-initialized if the
312  // window is created from an existing top-level native window created by the
313  // runner.
314  std::unique_ptr<FlutterWindowsViewController> view_controller_;
315 
316  // Used to detect whether this window is still alive from tasks that are
317  // posted from the raster thread and run on the platform thread: the window
318  // has been destroyed if a weak pointer to this token can no longer be locked.
319  std::shared_ptr<int> alive_ = std::make_shared<int>(0);
320 
321  // The window archetype.
323 
324  // Backing handle for this window.
326 
327  // The constraints on the window's client area.
328  BoxConstraints box_constraints_;
329 
330  // True while handling WM_DESTROY; used to detect in-progress destruction.
331  bool is_being_destroyed_ = false;
332 
333  // Whether or not the window is currently in a fullscreen state.
334  bool is_fullscreen_ = false;
335 
336  // Saved window information from before entering fullscreen mode.
338 
339  // Used to mark a window as fullscreen.
340  Microsoft::WRL::ComPtr<ITaskbarList2> task_bar_list_;
341 
343 };
344 
345 } // namespace flutter
346 
347 #endif // FLUTTER_SHELL_PLATFORM_WINDOWS_HOST_WINDOW_H_
Microsoft::WRL::ComPtr< ITaskbarList2 > task_bar_list_
Definition: host_window.h:340
HWND GetWindowHandle() const
Definition: host_window.cc:377
BoxConstraints box_constraints_
Definition: host_window.h:328
static std::unique_ptr< HostWindow > CreatePopupWindow(WindowManager *window_manager, FlutterWindowsEngine *engine, const WindowConstraints &preferred_constraints, GetWindowPositionCallback get_position_callback, HWND parent)
Definition: host_window.cc:218
static std::unique_ptr< HostWindow > CreateDialogWindow(WindowManager *window_manager, FlutterWindowsEngine *engine, const WindowSizeRequest &preferred_size, const WindowConstraints &preferred_constraints, LPCWSTR title, HWND parent, bool sized_to_content, bool resizable)
Definition: host_window.cc:192
WindowArchetype archetype_
Definition: host_window.h:322
virtual void OnFirstFrame()
Definition: host_window.cc:326
void InitializeFlutterView(HostWindowInitializationParams const &params)
Definition: host_window.cc:249
void HandleWindowActivation(HWND hwnd, WPARAM wparam)
Definition: host_window.cc:392
SavedWindowInfo saved_window_info_
Definition: host_window.h:337
FML_DISALLOW_COPY_AND_ASSIGN(HostWindow)
std::unique_ptr< FlutterWindowsViewController > view_controller_
Definition: host_window.h:314
static std::optional< Size > GetInitialWindowSize(FlutterWindowsEngine *engine, const WindowSizeRequest &preferred_size, const BoxConstraints &constraints, DWORD window_style, DWORD extended_window_style, std::optional< HWND > const &owner_window, bool sized_to_content)
Definition: host_window.cc:852
static LRESULT WndProc(HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
Definition: host_window.cc:416
HostWindow * GetOwnerWindow() const
Definition: host_window.cc:923
static std::unique_ptr< HostWindow > CreateTooltipWindow(WindowManager *window_manager, FlutterWindowsEngine *engine, const WindowConstraints &preferred_constraints, GetWindowPositionCallback get_position_callback, HWND parent)
Definition: host_window.cc:207
static ActualWindowSize GetWindowContentSize(HWND hwnd)
Definition: host_window.cc:792
void EnableRecursively(bool enable)
Definition: host_window.cc:878
void SetContentSize(const WindowSizeRequest &size)
Definition: host_window.cc:559
static std::unique_ptr< HostWindow > CreateSatelliteWindow(WindowManager *window_manager, FlutterWindowsEngine *engine, const WindowSizeRequest &preferred_size, const WindowConstraints &preferred_constraints, GetWindowPositionCallback get_position_callback, HWND parent, LPCWSTR title, bool sized_to_content, bool resizable)
Definition: host_window.cc:229
void UpdateModalStateLayer()
Definition: host_window.cc:939
static std::unique_ptr< HostWindow > CreateRegularWindow(WindowManager *window_manager, FlutterWindowsEngine *engine, const WindowSizeRequest &preferred_size, const WindowConstraints &preferred_constraints, LPCWSTR title, bool sized_to_content, bool resizable)
Definition: host_window.cc:178
static void FocusRootViewOf(HostWindow *window)
Definition: host_window.cc:385
HWND GetFlutterViewWindowHandle() const
Definition: host_window.cc:381
FlutterWindowsEngine * engine_
Definition: host_window.h:309
static HostWindow * GetThisFromHandle(HWND hwnd)
Definition: host_window.cc:362
HostWindow(WindowManager *window_manager, FlutterWindowsEngine *engine)
Definition: host_window.cc:245
std::vector< HostWindow * > GetOwnedWindows() const
Definition: host_window.cc:900
WindowArchetype GetArchetype() const
Definition: host_window.h:177
virtual bool GetFullscreen() const
Definition: host_window.cc:788
void SetConstraints(const WindowConstraints &constraints)
Definition: host_window.cc:601
std::shared_ptr< int > alive_
Definition: host_window.h:319
virtual void SetFullscreen(bool fullscreen, std::optional< FlutterEngineDisplayId > display_id)
Definition: host_window.cc:642
virtual LRESULT HandleMessage(HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
Definition: host_window.cc:432
static std::optional< Size > GetWindowSizeForClientSize(WindowsProcTable const &win32, Size const &client_size, std::optional< Size > smallest, std::optional< Size > biggest, DWORD window_style, DWORD extended_window_style, std::optional< HWND > const &owner_hwnd)
Definition: host_window.cc:805
HostWindow * FindFirstEnabledDescendant() const
Definition: host_window.cc:886
WindowManager *const window_manager_
Definition: host_window.h:306
Win32Message message
void(* GetWindowPositionCallback)(const WindowSize &child_size, const WindowRect &parent_rect, const WindowRect &display_rect, WindowRect &output_rect)
WindowArchetype
Definition: windowing.h:11
FlutterWindowsViewSizingDelegate * sizing_delegate
Definition: host_window.h:188