When you add any external windows to your Flutter app, you need to include them in the Window's app lifecycle logic. To include the window, its `WndProc` function should invoke `FlutterEngine::ProcessExternalWindowMessage`.
Original behavior
Not stated in the source.
New behavior
Implementing application lifecycle on Windows involves listening for Window messages in order to update the lifecycle state. In order for additional non-Flutter windows to affect the lifecycle state, they must forward their window messages to `FlutterEngine::ProcessExternalWindowMessage` from their `WndProc` functions. This function returns an `std::optional<LRESULT>`, which is `std::nullopt` when the message is received, but not consumed. When the returned result has a value, the message has been consumed, and further processing in `WndProc` should cease.
- Who is affected
- affect the lifecycle state, they must forward their
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
The following example WndProc procedure invokes
FlutterEngine::ProcessExternalWindowMessage:
LRESULT Window::Messagehandler(HWND hwnd, UINT msg, WPARAM wparam, LPARAM lparam) {
std::optional<LRESULT> result = flutter_controller_->engine()->ProcessExternalWindowMessage(hwnd, msg, wparam, lparam);
if (result.has_value()) {
return *result;
}
// Original contents of WndProc...
}AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.