Application and Window Lifecycle
This document summarizes the Application/Window lifecycle and DX in MewUI, from startup to shutdown. It clarifies the boundary between “before Run” and “after Run”.
1. Pre-run configuration
Section titled “1. Pre-run configuration”This section describes how to configure the platform host and graphics backend before calling Application.Run(...).
MewUI aims to avoid a core-level enum/switch selection for platform/graphics backends.
Instead, each package provides registration and selection to remain trim/AOT-friendly.
1.1 Recommended approach
Section titled “1.1 Recommended approach”Register the platform/backend packages before calling Application.Run(...).
using Aprillz.MewUI;
// Detect OS at runtime and register only the platform/backend valid for that OS.if (OperatingSystem.IsWindows()){ Win32Platform.Register(); Direct2DBackend.Register(); // or GdiBackend.Register() / MewVGWin32Backend.Register()}else if (OperatingSystem.IsLinux()){ X11Platform.Register(); MewVGX11Backend.Register();}else if (OperatingSystem.IsMacOS()){ MacOSPlatform.Register(); MewVGMacOSBackend.Register();}else{ throw new PlatformNotSupportedException("Unsupported OS.");}
Application.Run(mainWindow);A WebAssembly build registers BrowserPlatform and MewVGBrowserBackend, and starts with Application.RunAsync. See 2.5.
1.2 Single-target Apps: Application.Create() Chain
Section titled “1.2 Single-target Apps: Application.Create() Chain”If your app is fixed to one platform + one graphics backend (e.g., Windows-only), an Application.Create() chain is the simplest.
Assumptions:
- Your project references the platform/backend packages (so extension methods like
.UseWin32()are available). - The build and package references are already fixed; you are not selecting OS at runtime.
using Aprillz.MewUI;
Application.Create() .UseWin32() .UseDirect2D() .Run(mainWindow);1.3 Multi-target Apps: Fixing the chain
Section titled “1.3 Multi-target Apps: Fixing the chain”Instead of runtime OS branching, you can define symbols via csproj conditions (typically RID/CI publish) and then fix the chain with #if.
This is also convenient for trimming/distribution, because you can structure package references so that each build only includes what it needs.
1.3.1 Define symbols in csproj (example)
Section titled “1.3.1 Define symbols in csproj (example)”<PropertyGroup> <TargetFrameworks>net10.0-windows;net10.0</TargetFrameworks> <!-- assume CI/publish injects the RID via: dotnet publish -r ... --> <RuntimeIdentifiers>win-x64;linux-x64;osx-x64;osx-arm64</RuntimeIdentifiers></PropertyGroup>
<!-- dev runs (RID is often empty): use the runtime OS branching path --><PropertyGroup Condition="'$(RuntimeIdentifier)' == ''"> <DefineConstants>$(DefineConstants);DEV</DefineConstants></PropertyGroup>
<!-- publish/CI (RID is set): fix OS symbols based on RID --><PropertyGroup Condition="'$(RuntimeIdentifier)' != '' and $(RuntimeIdentifier.StartsWith('win-'))"> <DefineConstants>$(DefineConstants);WINDOWS</DefineConstants></PropertyGroup><PropertyGroup Condition="'$(RuntimeIdentifier)' != '' and $(RuntimeIdentifier.StartsWith('linux-'))"> <DefineConstants>$(DefineConstants);LINUX</DefineConstants></PropertyGroup><PropertyGroup Condition="'$(RuntimeIdentifier)' != '' and $(RuntimeIdentifier.StartsWith('osx-'))"> <DefineConstants>$(DefineConstants);MACOS</DefineConstants></PropertyGroup>1.3.2 Fix the chain in Program.cs (example)
Section titled “1.3.2 Fix the chain in Program.cs (example)”using Aprillz.MewUI;
Application.Create()
#if WINDOWS || DEV .UseWin32() .UseDirect2D()#elif LINUX .UseX11() .UseMewVGX11()#elif MACOS .UseMacOS() .UseMewVGMetal()#else .ThrowPlatformNotSupported()#endif .Run(mainWindow);1.4 Runtime branching while keeping a builder chain
Section titled “1.4 Runtime branching while keeping a builder chain”If you must branch at runtime and still keep a chain-like style, you can use a builder variable and continue chaining after the branch.
- Only configurable before Run: after Run, changing core app settings should throw or be ignored (the policy must be consistent in code).
- Plugin-based registration: platform/backend packages provide Register/selection.
2. Application Startup Flow
Section titled “2. Application Startup Flow”2.1 Application.Run
Section titled “2.1 Application.Run”When Application.Run(Window) is called, the flow is:
- Set
Application.Current - Create the PlatformHost and initialize the Dispatcher
- Register and show the Window
- Enter the message loop
Example: Minimal Setup
Section titled “Example: Minimal Setup”// The platform host and the backend are registered first (see 1.1); without them the// first control that measures text throws InvalidOperationException.Win32Platform.Register();Direct2DBackend.Register();
var window = new Window() .Title("Hello") .Content(new TextBlock().Text("Hello, MewUI"));
Application.Run(window);Use the startup overload when initialization must run after dispatcher installation but before the window is shown.
Application.Run(window, () =>{ // The Dispatcher and UI SynchronizationContext are installed, // and the window has not been shown yet. InitializeServices();});2.2 Starting without a main window
Section titled “2.2 Starting without a main window”Application.Run(Action) starts the dispatcher and platform message loop without creating or showing a main window. The required startup callback runs once on the UI thread after dispatcher installation. It may show ordinary windows immediately or from later dispatcher work.
Application.Run(() =>{ Application.Current.ShutdownMode = ShutdownMode.OnExplicitShutdown; RegisterGlobalHotkey(() => Application.Current.Dispatcher!.BeginInvoke( () => new PaletteWindow().Show()));});Windowless execution does not set OnExplicitShutdown automatically. Set it explicitly when closing the last palette or utility window must leave the process running.
With the builder, configure OnStartup and omit the main window factory. WithShutdownMode applies the policy before startup runs.
Application.Create() .WithShutdownMode(ShutdownMode.OnExplicitShutdown) .OnStartup(RegisterGlobalHotkey) .Run();When both BuildMainWindow(...) and OnStartup(...) are configured, startup runs before the factory-created main window is shown. Calling OnStartup again replaces the previous callback.
2.3 Startup callback arguments
Section titled “2.3 Startup callback arguments”Every startup entry point has an overload taking Action<string[]>. The framework supplies the command-line arguments without the executable path, so startup logic assembled outside the entry point does not have to thread args through itself.
Application.Create() .OnStartup(args => { if (args.Contains("--minimized")) StartMinimized(); }) .Run<MainWindow>();2.4 Theme configuration
Section titled “2.4 Theme configuration”For ThemeVariant/Accent/ThemeSeed/ThemeMetrics configuration, see:
The default font family is decided when the platform package registers (Win32Platform.Register(), UseWin32(), and their X11/macOS/browser equivalents), which precedes Application.Create() and window construction. Reading ThemeMetrics.Default.FontFamily or ThemeManager.DefaultMetrics.FontFamily after that point reports the family that will actually be used. See Theme documentation for how an unspecified family follows the system UI font.
2.5 Browser lifetime (WebAssembly)
Section titled “2.5 Browser lifetime (WebAssembly)”The browser host differs from the desktop hosts in how a run starts, ends, and renders.
Application.RunAsyncis the entry point.Application.RunthrowsNotSupportedException, because the JavaScript event loop must keep running while the application is alive.RunAsyncinstalls the dispatcher, runs the startup callback, shows the main window and returns immediately. The task it returns completes at shutdown.- The host page drives the frames: it calls the render entry point from its own animation-frame loop, so MewUI runs no loop of its own.
- One top-level
Window. Showing a second one throwsNotSupportedException, since the page surface is the only one. ShowDialogAsyncis the only modal form;ShowDialogthrowsNotSupportedExceptionbecause this host runs no nested loop. Dialogs, popups and menus are drawn inside the single surface.Application.Shutdown()completes theRunAsynctask and stops the frames. The page itself stays loaded, since a tab cannot close itself.- Closing the single window shuts the application down whatever
ShutdownModesays.
3. Window Startup Flow
Section titled “3. Window Startup Flow”3.1 Constructing a Window
Section titled “3.1 Constructing a Window”new Window() only creates the object; no native handle exists yet.
3.2 Show
Section titled “3.2 Show”At Window.Show() time:
- Register into Application
- Create backend resources (WindowHandle)
- Raise Loaded
- Perform first Layout & Render
3.3 ShowDialogAsync (Modal)
Section titled “3.3 ShowDialogAsync (Modal)”ShowDialogAsync shows a window as a modal dialog and completes when it is closed.
When an owner is provided, the owner window is disabled while the dialog is open (platform dependent).
In the browser it is the only modal form available (see 2.5).
var dialog = new Window() .Title("Dialog") .Content(new TextBlock().Text("Hello from dialog"));
await dialog.ShowDialogAsync(owner: main);Example: Multiple Windows
Section titled “Example: Multiple Windows”var main = new Window() .Title("Main") .Content(new TextBlock().Text("Main window"));
var tools = new Window() .Title("Tools") .Content(new TextBlock().Text("Tools window"));
main.OnLoaded(() => tools.Show());Application.Run(main);4. RenderLoopSettings
Section titled “4. RenderLoopSettings”RenderLoop behavior is controlled via Application.Current.RenderLoopSettings:
Mode:OnRequest/ContinuousTargetFps: 0 means unlimitedVSyncEnabled: controls backend present/swap behavior
In the browser, Continuous and VSyncEnabled still decide whether every frame repaints, while TargetFps has no effect: the page’s animation frames set the cadence.
Example: RenderLoop Settings
Section titled “Example: RenderLoop Settings”Application.Current.RenderLoopSettings.SetContinuous(true);Application.Current.RenderLoopSettings.VSyncEnabled = false;Application.Current.RenderLoopSettings.TargetFps = 0; // unlimited5. Shutdown Flow
Section titled “5. Shutdown Flow”5.1 Closing a window
Section titled “5.1 Closing a window”Window.Close() (and the platform close button) runs the full close lifecycle:
Closingis raised; setargs.Cancel = trueto keep the window open- The native window is destroyed
Closedis raised and the window is unregistered from the Application
Windows shown with an owner (Show(owner) / ShowDialogAsync(owner)) close together when their owner closes.
On macOS an owned window stays in front of its owner only while the application is active, as macOS windows do. A modal dialog drops back behind the active application’s windows when the user switches away, and a window shown with Show(owner) hides until the application is active again. A window that must stay visible over other applications is shown without an owner and with Topmost set.
Example: Confirm before closing
Section titled “Example: Confirm before closing”window.Closing += args =>{ if (hasUnsavedChanges && !ConfirmDiscard()) args.Cancel = true;};
window.Closed += () => SaveWindowPlacement();5.2 When the application exits
Section titled “5.2 When the application exits”Application.ShutdownMode decides whether closing a window terminates the message loop.
OnLastWindowClose(the default): exits when the last window closes. This also applies to a window opened afterApplication.Run(Action)started without one.OnMainWindowClose: exits when the main window closes. The window-basedRunoverloads record that identity; a run started without a main window has none until one is assigned (see 5.3).OnExplicitShutdown: window closes never exit the loop; the application waits forApplication.Shutdown().
The browser host has one window and ends the run when it closes, so the policy makes no difference there.
The policy is scoped to one run and starts at OnLastWindowClose every time. Configure it before the run with the builder, or assign Application.Current.ShutdownMode from the startup callback.
Application.Create() .WithShutdownMode(ShutdownMode.OnExplicitShutdown) .OnStartup(StartBackgroundApplication) .Run();5.3 Application.MainWindow
Section titled “5.3 Application.MainWindow”Application.Current.MainWindow is the identity OnMainWindowClose watches. The window-based Run overloads (Run(Window), BuildMainWindow(...), Run<TWindow>()) set it, and it is also assignable while the run is in progress.
Assigning it is the only way a run started without a main window can use OnMainWindowClose: promote a window opened later.
Application.Create() .WithShutdownMode(ShutdownMode.OnMainWindowClose) .OnStartup(() => { var dashboard = new DashboardWindow(); dashboard.Show(); Application.Current.MainWindow = dashboard; // closing this one ends the run }) .Run();- The identity is scoped to one run; the next run starts with none.
- Startup runs after the run window is recorded, so an assignment there overrides the window the builder supplied.
- Assigning
nullclears the identity, which leavesOnMainWindowClosewith nothing to trigger on. - The builder path bundles identity with “show at start”. Assigning the property gives identity alone, so a window can be shown (or not) on your own terms.
- The preview host captures the main window when the session starts, so a window promoted later is not reflected in preview targets. See Preview.
5.4 Application.Shutdown
Section titled “5.4 Application.Shutdown”Application.Shutdown() terminates the message loop immediately:
- Open windows do not get a
Closingcallback, so nothing can cancel the exit - The per-window close lifecycle is not guaranteed on this path; do not rely on
Closing/Closedhandlers for save prompts or persistence when shutting down - Platform resources are torn down and
Application.Run(...)returns
Shutdown(int exitCode) also assigns Environment.ExitCode. Run stays void, so the code survives even when a fatal UI-thread exception makes Run throw instead of returning.
Application.Shutdown(2); // loop ends, process exits with 2On macOS and Linux, SIGTERM (sent by kill or a service manager stopping the application) calls Application.Shutdown(), so Run returns instead of the process ending in place.
5.5 Recommended patterns
Section titled “5.5 Recommended patterns”- Default: let the user close windows; the app exits with the last one.
- An “Exit” menu/button that should honor confirmation: call
mainWindow.Close()so theClosinghandler can prompt and cancel. - Main window ends the application: subscribe
Application.Shutdownto the main window’sClosed. - Immediate exit with no prompts (state already saved, watchdog restart, etc.):
Application.Shutdown().
Example: Main window ends the application
Section titled “Example: Main window ends the application”The canonical recipe ties the app lifetime to the main window. Everything routes through main.Close(), so the confirmation stays in one place and keeps its veto; Shutdown only runs after the close actually went through, ending the app even if tool/background windows are still open.
// 1) Confirmation (optional): one Closing handler guards every exit path.main.Closing += args =>{ if (hasUnsavedChanges && !ConfirmDiscard()) args.Cancel = true;};
// 2) Persistence: runs only when the close was allowed.main.Closed += SaveSession;
// 3) Main window = app lifetime.main.Closed += Application.Shutdown;
// 4) Every exit command goes through Close, never straight to Shutdown.new Button().Content("Exit").OnClick(() => main.Close());For an unconditional exit (state already saved, watchdog restart), call Application.Shutdown() directly - no Closing/Closed handlers run.
Sequencing Close and Shutdown
Section titled “Sequencing Close and Shutdown”main.Close();Application.Shutdown();This sequence means “close gracefully if allowed, but exit regardless” - useful for logout, fatal-error exit, or restart-after-update flows. Close() runs the close lifecycle before Shutdown() takes effect on every platform (synchronously on X11/macOS; on Win32 the posted WM_CLOSE is drained before the loop exits).
- If
Closingdoes not cancel:Closedcleanup runs, then the app exits. - If
Closingcancels: the exit still happens, and that window skips itsClosedcleanup (it is torn down by the Shutdown path).
The synchronous sequence is only safe while no Closing handler defers. With a deferral (see 5.6), Close() returns with the decision still pending and Shutdown() ends the loop before it resolves. CloseAsync expresses the same intent and waits for the decision either way:
await main.CloseAsync(); // full close lifecycle, deferrals includedApplication.Shutdown(); // exit regardless of the outcomePrefer this form for the “exit regardless” flows.
Pick by intent: when a confirmation should be able to keep the app running, use main.Closed += Application.Shutdown with main.Close(); use the sequence only when the exit must happen regardless.
5.6 Async close: CloseAsync and Closing deferrals
Section titled “5.6 Async close: CloseAsync and Closing deferrals”Window.CloseAsync() requests a close and reports the outcome:
bool closed = await window.CloseAsync(); // true = closed, false = cancelled by Closing- An already-closed window completes with
true(idempotent). - Concurrent close requests join one pending decision;
Closingruns once.
When the close decision itself is asynchronous (a confirmation dialog, an async save), take a deferral inside Closing instead of cancelling and re-closing:
window.Closing += async args =>{ using (args.GetDeferral()) // take it before the first await { if (!await ConfirmDiscardAsync()) args.Cancel = true; } // the deferral completes here - the decision is submitted};- The window stays open until every deferral completes; the aggregated
Cancelthen decides (any cancel wins). - Once allowed, the close proceeds without raising
Closingagain. CloseAsynccompletes only after the deferrals resolve, so its result stays truthful with async handlers.- Close requests arriving while a decision is pending join it - the confirmation is not shown twice.
This also enables multi-window exit orchestration:
foreach (var w in openWindows) if (!await w.CloseAsync()) return; // one cancel aborts the exit// all closed - the app exits by the last-window rule5.7 Quit requests from the system: ShutdownRequested
Section titled “5.7 Quit requests from the system: ShutdownRequested”When the operating system asks the application to quit, Application.ShutdownRequested is raised.
Application.Current.ShutdownRequested += args =>{ if (backgroundJob.IsRunning) args.Cancel = true; // keep running; no window is asked};Unless the event cancels, the windows are asked to close one by one, newest first, through the normal close path:
- Each window’s
Closingcan cancel, including through a deferral; a cancel ends the attempt and the application keeps running. Windows already closed by then stay closed. - Once every window has closed, the run ends and
Application.Run(...)returns, whateverShutdownModesays. - A second request while one is still closing windows joins it.
| Platform | Requests | Notes |
|---|---|---|
| macOS | Quit from the Dock, logout, restart, shut down | The application ends the process itself, so macOS sees the request as refused: a logout stops once and has to be repeated after the application has quit. |
| Windows | Sign out, restart, shut down, an installer closing running applications | Windows needs the answer at once. A window whose Closing waits on a deferral holds the session open, and Windows lists the application as preventing it until the user decides. Once the session ends the process can be stopped at any moment, so code after Run is not guaranteed to finish; ShutdownRequested, Closing and Closed run before the answer. A forced end of the session (low battery) asks nothing and calls Application.Shutdown(). |
| Linux (X11) | Logout through a session manager (GNOME, KDE, Xfce) that lets applications talk to the user | A cancel cancels the logout. Without a session manager nothing is raised. |
| Browser | Closing the tab or leaving the page | Only the event is raised, since the page cannot wait for windows; a cancel makes the browser ask the user whether to leave. The page has to forward its beforeunload event; see Browser bootstrap. |
6. Exception Handling
Section titled “6. Exception Handling”- Exceptions on the UI thread are routed to
Application.DispatcherUnhandledException - Unhandled exceptions are treated as fatal by default
Example: Handling DispatcherUnhandledException
Section titled “Example: Handling DispatcherUnhandledException”Application.DispatcherUnhandledException += e =>{ try { MessageBox.Show(e.Exception.ToString(), "Unhandled UI exception"); } catch { // ignore } e.Handled = true;};7. Summary
Section titled “7. Summary”- The core flow is: pre-run configuration → Run → message loop
- Theme/RenderLoop should be decided before Run
- A Window only acquires native resources at Show time
- By default the app exits when the last window closes; select another lifetime with
ShutdownMode.Window.Close()is the graceful (cancellable) path, whileApplication.Shutdown()is immediate