Listen to window notifications to update application lifecycle (flutter#43558)

Use `WM_SIZE, WM_SHOWWINDOW, WM_SETFOCUS, and WM_KILLFOCUS` to update
the application lifecycle state on Windows.

flutter#103637

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide] and the [C++,
Objective-C, Java style guides].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I added new tests to check the change I am making or feature I am
adding, or Hixie said the PR is test-exempt. See [testing the engine]
for instructions on writing and running engine tests.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [ ] I signed the [CLA].
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[C++, Objective-C, Java style guides]:
https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
[testing the engine]:
https://github.com/flutter/flutter/wiki/Testing-the-engine
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat

---------

Co-authored-by: Brandon DeRosier <bdero@google.com>
Co-authored-by: skia-flutter-autoroll <skia-flutter-autoroll@skia.org>

Author: 3 people

ci/licenses_golden/excluded_files

@@ -351,6 +351,7 @@
 ../../../flutter/shell/platform/windows/text_input_plugin_unittest.cc
 ../../../flutter/shell/platform/windows/window_proc_delegate_manager_unittests.cc
 ../../../flutter/shell/platform/windows/window_unittests.cc
+../../../flutter/shell/platform/windows/windows_lifecycle_manager_unittests.cc
 ../../../flutter/shell/profiling/sampling_profiler_unittest.cc
 ../../../flutter/shell/testing
 ../../../flutter/shell/vmservice/.dart_tool

shell/platform/windows/BUILD.gn

@@ -221,6 +221,7 @@ executable("flutter_windows_unittests") {
     "text_input_plugin_unittest.cc",
     "window_proc_delegate_manager_unittests.cc",
     "window_unittests.cc",
+    "windows_lifecycle_manager_unittests.cc",
   ]
 
   configs +=

shell/platform/windows/client_wrapper/flutter_engine.cc

@@ -100,6 +100,19 @@ void FlutterEngine::SetNextFrameCallback(std::function<void()> callback) {
       this);
 }
 
+std::optional<LRESULT> FlutterEngine::ProcessExternalWindowMessage(
+    HWND hwnd,
+    UINT message,
+    WPARAM wparam,
+    LPARAM lparam) {
+  LRESULT result;
+  if (FlutterDesktopEngineProcessExternalWindowMessage(
+          engine_, hwnd, message, wparam, lparam, &result)) {
+    return result;
+  }
+  return std::nullopt;
+}
+
 FlutterDesktopEngineRef FlutterEngine::RelinquishEngine() {
   owns_engine_ = false;
   return engine_;

shell/platform/windows/client_wrapper/flutter_engine_unittests.cc

@@ -56,6 +56,17 @@ class TestFlutterWindowsApi : public testing::StubFlutterWindowsApi {
   // |flutter::testing::StubFlutterWindowsApi|
   void EngineReloadSystemFonts() override { reload_fonts_called_ = true; }
 
+  // |flutter::testing::StubFlutterWindowsApi|
+  bool EngineProcessExternalWindowMessage(FlutterDesktopEngineRef engine,
+                                          HWND hwnd,
+                                          UINT message,
+                                          WPARAM wparam,
+                                          LPARAM lparam,
+                                          LRESULT* result) override {
+    last_external_message_ = message;
+    return false;
+  }
+
   bool create_called() { return create_called_; }
 
   bool run_called() { return run_called_; }
@@ -74,6 +85,8 @@ class TestFlutterWindowsApi : public testing::StubFlutterWindowsApi {
     next_frame_callback_ = nullptr;
   }
 
+  UINT last_external_message() { return last_external_message_; }
+
  private:
   bool create_called_ = false;
   bool run_called_ = false;
@@ -82,6 +95,7 @@ class TestFlutterWindowsApi : public testing::StubFlutterWindowsApi {
   std::vector<std::string> dart_entrypoint_arguments_;
   VoidCallback next_frame_callback_ = nullptr;
   void* next_frame_user_data_ = nullptr;
+  UINT last_external_message_ = 0;
 };
 
 }  // namespace
@@ -201,4 +215,16 @@ TEST(FlutterEngineTest, SetNextFrameCallback) {
   EXPECT_TRUE(success);
 }
 
+TEST(FlutterEngineTest, ProcessExternalWindowMessage) {
+  testing::ScopedStubFlutterWindowsApi scoped_api_stub(
+      std::make_unique<TestFlutterWindowsApi>());
+  auto test_api = static_cast<TestFlutterWindowsApi*>(scoped_api_stub.stub());
+
+  FlutterEngine engine(DartProject(L"fake/project/path"));
+
+  engine.ProcessExternalWindowMessage(reinterpret_cast<HWND>(1), 1234, 0, 0);
+
+  EXPECT_EQ(test_api->last_external_message(), 1234);
+}
+
 }  // namespace flutter

shell/platform/windows/client_wrapper/include/flutter/flutter_engine.h

@@ -9,6 +9,7 @@
 
 #include <chrono>
 #include <memory>
+#include <optional>
 #include <string>
 
 #include "binary_messenger.h"
@@ -84,6 +85,16 @@ class FlutterEngine : public PluginRegistry {
   // once on the platform thread.
   void SetNextFrameCallback(std::function<void()> callback);
 
+  // Called to pass an external window message to the engine for lifecycle
+  // state updates. This does not consume the window message. Non-Flutter
+  // windows must call this method in their WndProc in order to be included in
+  // the logic for application lifecycle state updates. Returns a result when
+  // the message has been consumed.
+  std::optional<LRESULT> ProcessExternalWindowMessage(HWND hwnd,
+                                                      UINT message,
+                                                      WPARAM wparam,
+                                                      LPARAM lparam);
+
  private:
   // For access to RelinquishEngine.
   friend class FlutterViewController;

shell/platform/windows/client_wrapper/testing/stub_flutter_windows_api.cc

@@ -162,6 +162,20 @@ IDXGIAdapter* FlutterDesktopViewGetGraphicsAdapter(FlutterDesktopViewRef view) {
   return nullptr;
 }
 
+bool FlutterDesktopEngineProcessExternalWindowMessage(
+    FlutterDesktopEngineRef engine,
+    HWND hwnd,
+    UINT message,
+    WPARAM wparam,
+    LPARAM lparam,
+    LRESULT* result) {
+  if (s_stub_implementation) {
+    return s_stub_implementation->EngineProcessExternalWindowMessage(
+        engine, hwnd, message, wparam, lparam, result);
+  }
+  return false;
+}
+
 FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(
     FlutterDesktopPluginRegistrarRef controller) {
   // The stub ignores this, so just return an arbitrary non-zero value.

shell/platform/windows/client_wrapper/testing/stub_flutter_windows_api.h

@@ -89,6 +89,17 @@ class StubFlutterWindowsApi {
   // FlutterDesktopPluginRegistrarUnregisterTopLevelWindowProcDelegate.
   virtual void PluginRegistrarUnregisterTopLevelWindowProcDelegate(
       FlutterDesktopWindowProcCallback delegate) {}
+
+  // Claled for FlutterDesktopEngineProcessExternalWindowMessage.
+  virtual bool EngineProcessExternalWindowMessage(
+      FlutterDesktopEngineRef engine,
+      HWND hwnd,
+      UINT message,
+      WPARAM wparam,
+      LPARAM lparam,
+      LRESULT* result) {
+    return false;
+  }
 };
 
 // A test helper that owns a stub implementation, making it the test stub for

shell/platform/windows/flutter_window.cc

@@ -74,11 +74,19 @@ FlutterWindow::FlutterWindow(int width, int height)
   current_cursor_ = ::LoadCursor(nullptr, IDC_ARROW);
 }
 
-FlutterWindow::~FlutterWindow() {}
+FlutterWindow::~FlutterWindow() {
+  OnWindowStateEvent(WindowStateEvent::kHide);
+}
 
 void FlutterWindow::SetView(WindowBindingHandlerDelegate* window) {
   binding_handler_delegate_ = window;
   direct_manipulation_owner_->SetBindingHandlerDelegate(window);
+  if (restored_) {
+    OnWindowStateEvent(WindowStateEvent::kShow);
+  }
+  if (focused_) {
+    OnWindowStateEvent(WindowStateEvent::kFocus);
+  }
 }
 
 WindowsRenderTarget FlutterWindow::GetRenderTarget() {
@@ -328,4 +336,26 @@ bool FlutterWindow::NeedsVSync() {
   return true;
 }
 
+void FlutterWindow::OnWindowStateEvent(WindowStateEvent event) {
+  switch (event) {
+    case WindowStateEvent::kShow:
+      restored_ = true;
+      break;
+    case WindowStateEvent::kHide:
+      restored_ = false;
+      focused_ = false;
+      break;
+    case WindowStateEvent::kFocus:
+      focused_ = true;
+      break;
+    case WindowStateEvent::kUnfocus:
+      focused_ = false;
+      break;
+  }
+  HWND hwnd = GetPlatformWindow();
+  if (hwnd && binding_handler_delegate_) {
+    binding_handler_delegate_->OnWindowStateEvent(hwnd, event);
+  }
+}
+
 }  // namespace flutter

shell/platform/windows/flutter_window.h

@@ -162,6 +162,9 @@ class FlutterWindow : public Window, public WindowBindingHandler {
   // |Window|
   ui::AXFragmentRootDelegateWin* GetAxFragmentRootDelegate() override;
 
+  // |Window|
+  void OnWindowStateEvent(WindowStateEvent event) override;
+
  private:
   // A pointer to a FlutterWindowsView that can be used to update engine
   // windowing and input state.
@@ -173,6 +176,12 @@ class FlutterWindow : public Window, public WindowBindingHandler {
   // The cursor rect set by Flutter.
   RECT cursor_rect_;
 
+  // The window receives resize and focus messages before its view is set, so
+  // these values cache the state of the window in the meantime so that the
+  // proper application lifecycle state can be updated once the view is set.
+  bool restored_ = false;
+  bool focused_ = false;
+
   FML_DISALLOW_COPY_AND_ASSIGN(FlutterWindow);
 };
 

shell/platform/windows/flutter_window_unittests.cc

@@ -27,7 +27,7 @@ class MockFlutterWindow : public FlutterWindow {
     ON_CALL(*this, GetDpiScale())
         .WillByDefault(Return(this->FlutterWindow::GetDpiScale()));
   }
-  virtual ~MockFlutterWindow() {}
+  virtual ~MockFlutterWindow() { SetView(nullptr); }
 
   // Wrapper for GetCurrentDPI() which is a protected method.
   UINT GetDpi() { return GetCurrentDPI(); }
@@ -229,6 +229,10 @@ TEST(FlutterWindowTest, OnPointerStarSendsDeviceType) {
                           kDefaultPointerDeviceId, WM_LBUTTONDOWN);
   win32window.OnPointerLeave(10.0, 10.0, kFlutterPointerDeviceKindStylus,
                              kDefaultPointerDeviceId);
+
+  // Destruction of win32window sends a HIDE update. In situ, the window is
+  // owned by the delegate, and so is destructed first. Not so here.
+  win32window.SetView(nullptr);
 }
 
 // Tests that calls to OnScroll in turn calls GetScrollOffsetMultiplier
@@ -324,5 +328,61 @@ TEST(FlutterWindowTest, AlertNode) {
   EXPECT_EQ(role.lVal, ROLE_SYSTEM_ALERT);
 }
 
+TEST(FlutterWindowTest, LifecycleFocusMessages) {
+  MockFlutterWindow win32window;
+  ON_CALL(win32window, GetPlatformWindow).WillByDefault([]() {
+    return reinterpret_cast<HWND>(1);
+  });
+  MockWindowBindingHandlerDelegate delegate;
+  win32window.SetView(&delegate);
+
+  WindowStateEvent last_event;
+  ON_CALL(delegate, OnWindowStateEvent)
+      .WillByDefault([&last_event](HWND hwnd, WindowStateEvent event) {
+        last_event = event;
+      });
+
+  win32window.InjectWindowMessage(WM_SIZE, 0, 0);
+  EXPECT_EQ(last_event, WindowStateEvent::kHide);
+
+  win32window.InjectWindowMessage(WM_SIZE, 0, MAKEWORD(1, 1));
+  EXPECT_EQ(last_event, WindowStateEvent::kShow);
+
+  win32window.InjectWindowMessage(WM_SETFOCUS, 0, 0);
+  EXPECT_EQ(last_event, WindowStateEvent::kFocus);
+
+  win32window.InjectWindowMessage(WM_KILLFOCUS, 0, 0);
+  EXPECT_EQ(last_event, WindowStateEvent::kUnfocus);
+}
+
+TEST(FlutterWindowTest, CachedLifecycleMessage) {
+  MockFlutterWindow win32window;
+  ON_CALL(win32window, GetPlatformWindow).WillByDefault([]() {
+    return reinterpret_cast<HWND>(1);
+  });
+
+  // Restore
+  win32window.InjectWindowMessage(WM_SIZE, 0, MAKEWORD(1, 1));
+
+  // Focus
+  win32window.InjectWindowMessage(WM_SETFOCUS, 0, 0);
+
+  MockWindowBindingHandlerDelegate delegate;
+  bool focused = false;
+  bool restored = false;
+  ON_CALL(delegate, OnWindowStateEvent)
+      .WillByDefault([&](HWND hwnd, WindowStateEvent event) {
+        if (event == WindowStateEvent::kFocus) {
+          focused = true;
+        } else if (event == WindowStateEvent::kShow) {
+          restored = true;
+        }
+      });
+
+  win32window.SetView(&delegate);
+  EXPECT_TRUE(focused);
+  EXPECT_TRUE(restored);
+}
+
 }  // namespace testing
 }  // namespace flutter