Reintroduce Windows lifecycle with guard for posthumous OnWindowStateEvent (#44344)

Previously, destruction of `Window` called `DestroyWindow`, which may
send `WM_KILLFOCUS` to the to-be-destroyed window. Because `Window`'s
destructor is called after `FlutterWindow`'s, the `FlutterWindow` vtable
was already destroyed at this point, and the subsequent call to the
virtual method `OnWindowStateEvent` would cause a crash. This PR
reintroduces the reverted changes for Windows lifecycle with a check
before calling the virtual method that the `FlutterWindow` object has
not yet been destructed.

flutter/flutter#131872

*If you had to change anything in the [flutter/tests] repo, include a
link to the migration guide as per the [breaking change policy].*

## 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: Loïc Sharma <737941+loic-sharma@users.noreply.github.com>

Author: yaakovschectman

ci/licenses_golden/excluded_files

@@ -354,6 +354,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,15 @@ 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. 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 if the message should be 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) {}
+
+  // Called 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,20 @@ FlutterWindow::FlutterWindow(int width, int height)
   current_cursor_ = ::LoadCursor(nullptr, IDC_ARROW);
 }
 
-FlutterWindow::~FlutterWindow() {}
+FlutterWindow::~FlutterWindow() {
+  OnWindowStateEvent(WindowStateEvent::kHide);
+  Destroy();
+}
 
 void FlutterWindow::SetView(WindowBindingHandlerDelegate* window) {
   binding_handler_delegate_ = window;
   direct_manipulation_owner_->SetBindingHandlerDelegate(window);
+  if (restored_ && window) {
+    OnWindowStateEvent(WindowStateEvent::kShow);
+  }
+  if (focused_ && window) {
+    OnWindowStateEvent(WindowStateEvent::kFocus);
+  }
 }
 
 WindowsRenderTarget FlutterWindow::GetRenderTarget() {
@@ -328,4 +337,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|
+  virtual 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

@@ -23,11 +23,16 @@ static constexpr int32_t kDefaultPointerDeviceId = 0;
 
 class MockFlutterWindow : public FlutterWindow {
  public:
-  MockFlutterWindow() : FlutterWindow(800, 600) {
+  MockFlutterWindow(bool reset_view_on_exit = true)
+      : FlutterWindow(800, 600), reset_view_on_exit_(reset_view_on_exit) {
     ON_CALL(*this, GetDpiScale())
         .WillByDefault(Return(this->FlutterWindow::GetDpiScale()));
   }
-  virtual ~MockFlutterWindow() {}
+  virtual ~MockFlutterWindow() {
+    if (reset_view_on_exit_) {
+      SetView(nullptr);
+    }
+  }
 
   // Wrapper for GetCurrentDPI() which is a protected method.
   UINT GetDpi() { return GetCurrentDPI(); }
@@ -61,6 +66,7 @@ class MockFlutterWindow : public FlutterWindow {
   MOCK_METHOD1(Win32MapVkToChar, uint32_t(uint32_t));
   MOCK_METHOD0(GetPlatformWindow, HWND());
   MOCK_METHOD0(GetAxFragmentRootDelegate, ui::AXFragmentRootDelegateWin*());
+  MOCK_METHOD1(OnWindowStateEvent, void(WindowStateEvent));
 
  protected:
   // |KeyboardManager::WindowDelegate|
@@ -72,6 +78,7 @@ class MockFlutterWindow : public FlutterWindow {
   }
 
  private:
+  bool reset_view_on_exit_;
   FML_DISALLOW_COPY_AND_ASSIGN(MockFlutterWindow);
 };
 
@@ -229,6 +236,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 +335,100 @@ 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;
+      });
+  ON_CALL(win32window, OnWindowStateEvent)
+      .WillByDefault([&](WindowStateEvent event) {
+        win32window.FlutterWindow::OnWindowStateEvent(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);
+  });
+  ON_CALL(win32window, OnWindowStateEvent)
+      .WillByDefault([&](WindowStateEvent event) {
+        win32window.FlutterWindow::OnWindowStateEvent(event);
+      });
+
+  // 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);
+}
+
+TEST(FlutterWindowTest, PosthumousWindowMessage) {
+  MockWindowBindingHandlerDelegate delegate;
+  int msg_count = 0;
+  HWND hwnd;
+  ON_CALL(delegate, OnWindowStateEvent)
+      .WillByDefault([&](HWND hwnd, WindowStateEvent event) { msg_count++; });
+
+  {
+    MockFlutterWindow win32window(false);
+    ON_CALL(win32window, GetPlatformWindow).WillByDefault([&]() {
+      return win32window.FlutterWindow::GetPlatformWindow();
+    });
+    ON_CALL(win32window, OnWindowStateEvent)
+        .WillByDefault([&](WindowStateEvent event) {
+          win32window.FlutterWindow::OnWindowStateEvent(event);
+        });
+    win32window.SetView(&delegate);
+    win32window.InitializeChild("Title", 1, 1);
+    hwnd = win32window.GetPlatformWindow();
+    SendMessage(hwnd, WM_SIZE, 0, MAKEWORD(1, 1));
+    SendMessage(hwnd, WM_SETFOCUS, 0, 0);
+
+    // By setting this to zero before exiting the scope that contains
+    // win32window, and then checking its value afterwards, enforce that the
+    // window receive and process messages from its destructor without
+    // accessing out-of-bounds memory.
+    msg_count = 0;
+  }
+  EXPECT_GE(msg_count, 1);
+}
+
 }  // namespace testing
 }  // namespace flutter

shell/platform/windows/flutter_windows.cc

@@ -207,6 +207,22 @@ IDXGIAdapter* FlutterDesktopViewGetGraphicsAdapter(FlutterDesktopViewRef view) {
   return nullptr;
 }
 
+bool FlutterDesktopEngineProcessExternalWindowMessage(
+    FlutterDesktopEngineRef engine,
+    HWND hwnd,
+    UINT message,
+    WPARAM wparam,
+    LPARAM lparam,
+    LRESULT* result) {
+  std::optional<LRESULT> lresult =
+      EngineFromHandle(engine)->ProcessExternalWindowMessage(hwnd, message,
+                                                             wparam, lparam);
+  if (result && lresult.has_value()) {
+    *result = lresult.value();
+  }
+  return lresult.has_value();
+}
+
 FlutterDesktopViewRef FlutterDesktopPluginRegistrarGetView(
     FlutterDesktopPluginRegistrarRef registrar) {
   return HandleForView(registrar->engine->view());