API — ICoreEssentials/UI/Backends/WinUI/Windows

The public contract of 12 header(s) under ICoreEssentials/UI/Backends/WinUI/Windows — 13 class/struct definition(s), 88 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreWinUIDialogContent.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIDialogContent.h

How a widget becomes the content of an ICoreDialog on this backend.

(Planning row named in the .cpp, not here -- the docs generator lifts header banners onto public API pages.)

⚠⚠ IT EXISTS BECAUSE new ICoreWidget(dialog) DID NOTHING AND SAID NOTHING. ICoreWidget::setParentWidget adopts a child only into an ICoreWidget parent -- it needs the parent's Impl for its child list and its Children() collection -- and ICoreDialog is not one and cannot be: it is a parallel wrapper around a XAML Window, exactly as ICoreWindow is. So a dialog built the way the Qt seat's callers build one --

auto* dialog = new ICoreDialog(parent); auto* body = new ICoreWidget(dialog); // <- silently orphaned

Declares no class of its own — see the file.

ICoreWinUIDialogFields.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIDialogFields.h

The WinUI backend's modality seat, DECIDING half.

(The planning row is named in the .cpp rather than here: the docs generator lifts a header's banner onto a generated API page.)

NO WIN32 AND NO WINRT IN THIS HEADER. A prompt is a button list, a default, an escape answer and a mapping from "which button came back" to the answer the public surface promises -- all of it plain data, all of it driven by testingLabs/tests/winui_dialog_fields with no comctl32 and no App SDK. The half that calls TaskDialogIndirect decides nothing.

⚠⚠ WHY TaskDialogIndirect AND NOT ContentDialog, MEASURED RATHER THAN PREFERRED. The row title offers "ContentDialog or owned AppWindow" and the first is not available to this class at all: a ContentDialog needs a

ICoreWinUIPromptButton#

ICoreWinUIDialogFields.h:59 · struct · 0 declaration(s)

One button in the plan.

struct ICoreWinUIPromptButton {
public:
    int id = 0;
    std::string label;
};
};

ICoreWinUIPromptPlan#

ICoreWinUIDialogFields.h:78 · struct · 0 declaration(s)

The whole of one prompt, as values.

struct ICoreWinUIPromptPlan {
public:
    ICoreWinUIPromptIcon icon = ICoreWinUIPromptIcon::None;
    std::string title;
    std::string text;
    std::vector<ICoreWinUIPromptButton> buttons;

    // Which button Return activates.
    int defaultId = 0;

    // ⚠ WHAT ESCAPE AND THE TITLE-BAR CLOSE ANSWER, AND IT IS A SEPARATE FIELD
    // FROM defaultId BECAUSE ON A DESTRUCTIVE PROMPT THEY ARE DIFFERENT
    // BUTTONS. TaskDialogIndirect reports both as IDCANCEL, and it only allows
    // either at all when the dialog is cancellable -- so this field is also
    // what tells the seat to set TDF_ALLOW_DIALOG_CANCELLATION.
    int escapeId = 0;

    // Width for the whole dialog, in DIALOG UNITS, or 0 for "let the platform
    // size it". See icoreWinUIDialogUnitsFromPixels().
    unsigned int widthInDialogUnits = 0;
};
};

File-scope declarations#

// The six shapes of prompt this application actually raises. There is no
// general button-set builder, deliberately -- the public header has six statics
// and no seventh is expressible, so an open-ended plan type would model
// combinations no caller can ask for and would have to be tested for them.
enum class ICoreWinUIPromptKind {
    Critical,
    Warning,
    Information,
    Question,            // Yes / No
    Confirm,             // <labelled affirmative> / Cancel
    SaveDiscardCancel,
};

// Which stock icon the platform's alert wears. Values are this header's own --
// the .cpp maps them onto the TD_*_ICON pseudo-handles, which cannot be named
// here without windows.h.
enum class ICoreWinUIPromptIcon { None, Information, Warning, Error };

// The three-way answer. Values match ICoreMessageBox::SaveAnswer's order and
// the .cpp static_asserts that, so the two cannot drift.
enum class ICoreWinUISaveAnswer { Save, Discard, Cancel };

ICoreWinUIElementWindow.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIElementWindow.h

From an element, up to the window that contains it.

⚠⚠ THIS IS THE JOIN THE WINDOW SEAT NAMED AND DID NOT BUILD. That seat can resolve its OWN handle -- it holds the XAML Window and asks IWindowNative -- and its cell says so out loud: turning an arbitrary UIElement into an HWND is XamlRoot -> ContentIsland, and belongs to the widget tier. This is that.

⚠ THE ROUTE, AND WHY IT IS THIS ONE. Four ways exist and three are not available here:

Window::AppWindow() what the window seat uses -- but it starts from the WINDOW, which is the thing we are trying to find. No use from an element. Win32Interop::Get... Microsoft::UI::Win32Interop is NOT in the

Declares no class of its own — see the file.

ICoreWinUIModalRun.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIModalRun.h

One nested modal run: disable the owner, pump until the caller says it is done, restore the owner however the run ends.

(Planning row named in the .cpp, not here -- the docs generator lifts header banners onto public API pages.)

NO WIN32 AND NO WINRT IN THIS HEADER: the owner crosses as a void*, which is what every seam in this backend does with an HWND.

⚠⚠ IT EXISTS BECAUSE TWO SEATS NEED IT AND ONE MECHANISM IS THE POINT. ICoreDialog::exec() and ICoreInputDialog's two prompts are both "show a window, block, return what the user chose", and a second copy of this loop would be a second place that could get the pump wrong. It is the same argument icoreWinUIPumpOnce() makes one level down, at the same seam: there

Declares no class of its own — see the file.

ICoreWinUIOwnerWindow.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIOwnerWindow.h

The owner HWND for a platform dialog, starting from the parent its caller passed.

(Planning row named in the .cpp, not here -- the docs generator lifts header banners onto public API pages.)

NO WIN32 AND NO WINRT IN THIS HEADER: the handle leaves as a void*, which is what every other seam in this backend does with an HWND.

⚠⚠ W7.2 SAYS THIS IS IMPOSSIBLE AND IT IS NOT -- IT STOPPED BEING IMPOSSIBLE WHEN W1.3 LANDED, AND NOBODY NOTICED FOR THREE DAYS. Printing's seat records, in bold, that "hwndOwner wants an HWND and this backend cannot turn an ICoreNativeWidget into one in this configure", and passes NULL. The reason it gives is true and is about a DIFFERENT step: GetWindowFromWindowId needs an

Declares no class of its own — see the file.

ICoreWinUIPickerFields.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIPickerFields.h

The WinUI backend's seat for the three pickers, DECIDING half.

(The planning row is named in the .cpp rather than here: the docs generator lifts a header's banner onto a generated API page read by people who cannot open this repository, so a board filename in one is noise to every reader it reaches.)

NO WIN32 AND NO WINRT IN THIS HEADER. Everything below takes and returns plain strings and plain structs, so the whole of it runs in a suite with no COM apartment, no shell and no App SDK -- which is the only kind of proof available in this configure. The half that actually raises IFileOpenDialog decides nothing and is proved by compiling.

⚠⚠ THE HARD PART IS THE FILTER STRING, AND IT IS HARD IN A DIFFERENT PLACE

ICoreWinUIFileFilter#

ICoreWinUIPickerFields.h:35 · struct · 0 declaration(s)

One Name (patterns) group out of a Qt filter string.

struct ICoreWinUIFileFilter {
public:
    // What the user reads in the combo box. "Images", out of
    // "Images (*.png *.jpg)". May be empty -- see the parse rules below.
    std::string label;

    // The patterns exactly as Qt spelled them, in order, duplicates removed:
    // {"*.png", "*.jpg"}. NOT bare extensions, which is the whole difference
    // from the AppKit peer's struct -- the shell filters on globs, so there is
    // nothing here to reduce and reducing would lose `*.tar.gz`.
    std::vector<std::string> patterns;
};
};

ICoreWinUISaveTarget#

ICoreWinUIPickerFields.h:115 · struct · 0 declaration(s)

What a save dialog should be pointed at, out of the ONE string Qt takes for both jobs.

struct ICoreWinUISaveTarget {
public:
    // Empty means "leave the shell's own default folder alone" -- which is what
    // an empty `directory`, and a `directory` that is a bare file name, both
    // mean.
    std::string folder;

    // Empty means "no suggested name".
    std::string fileName;
};
};

ICoreWinUIShortcutHook.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIShortcutHook.h

The toolkit half of the shortcut path: the things ICoreWinUIShortcuts deliberately cannot do for itself, and the tap that makes it fire at all.

NO WINRT IN THIS HEADER, which is what lets ICoreShortcut.cpp -- the wrapper seat -- be plain C++ that names no toolkit. Everything below is implemented in the .cpp beside it, and that .cpp is the only file in this backend that knows what the registry's opaque host and focused pointers really are.

⚠⚠ WITHOUT THE TAP THE REGISTRY IS A CORRECT PROGRAM THAT NEVER RUNS, AND THE OTHER NATIVE BACKEND SHIPPED EXACTLY THAT. ICoreAppKitShortcuts had a full suite, a green build and ZERO production callers of its monitor installer, which meant every shortcut in a shipping appkit build was registered and never fired, with every check green -- A3.5's own header says so, in the past tense, as something it had to go and measure. The same hole

Declares no class of its own — see the file.

ICoreWinUIShortcuts.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIShortcuts.h

The WinUI backend's shortcut registry: ICoreShortcut's seat, and the peer of ICoreAppKitShortcuts.

NO WINDOWS TYPES AND NO WinRT IN THIS HEADER. Hosts arrive as opaque pointers and keystrokes as plain integers -- the same integers W1.4's tables produce from a KeyRoutedEventArgs or from a raw MSG. That is what lets the whole registry be checked with a compiler and no Windows App SDK.

⚠ WHY A REGISTRY AND NOT XAML KeyboardAccelerators, WHICH THE ROW NAMES. A KeyboardAccelerator hangs off a UIElement and fires for the element and its subtree. That serves WidgetWithChildren well, serves Window only by putting the accelerator on the window's root, and cannot serve Application at all without one accelerator per window kept in step. ICoreShortcut has all three scopes and no menu presence, so the registry is ONE dispatch point

ICoreWinUIShortcuts#

ICoreWinUIShortcuts.h:76 · class · 11 declaration(s)

class ICoreWinUIShortcuts {
public:
    // Register one shortcut. Returns an id, never zero, never reused.
    //
    // `key` and `modifiers` are ICore values -- W1.4's tables produce them.
    // `host` is the opaque element the shortcut is scoped to; it may be null
    // only for Application scope, since the other two resolve against it and a
    // null host can never match.
    // `window` is the opaque top-level the host belongs to, used for Window
    // scope. Null means "no window" -- but see ICoreWinUIWindowResolver: when
    // it is null and a resolver is set, the window is resolved from the host at
    // DISPATCH time instead, which is what every caller in this tree needs and
    // what a caller registering before its host is in a tree must rely on.
    // With no resolver set, a null window still matches nothing.
    //
    // `scope` takes ICoreShortcutScope's values, pinned to Qt's numbering:
    // Window = 1, Application = 2, WidgetWithChildren = 3.
    //
    // ⚠ `host` MUST OUTLIVE THE REGISTRATION. remove() is what ends it, and
    // the seat above this file calls remove() from ~ICoreShortcut, so the rule
    // holds by construction there. It matters because the window resolver
    // DEREFERENCES the host, unlike everything else here, which only compares.
    static int add(ICoreKey key,
                   ICoreKeyModifiers modifiers,
                   void* host,
                   void* window,
                   int scope,
                   std::function<void()> onActivated);

    // Consulted in dispatch() BEFORE the chord is claimed: an entry whose
    // predicate answers false is skipped like a disabled one, so the keystroke
    // carries on to the focused element instead of being swallowed by a
    // shortcut that had already decided not to act. See
    // ICoreShortcut::setEligibility for the measurement that asked for it.
    static void setEligibility(int id, std::function<bool()> isEligible);

    static void remove(int id);
    static void setEnabled(int id, bool enabled);
    [[nodiscard]] static bool isEnabled(int id);
    [[nodiscard]] static int count();
    static void removeAll();

    // Supply the tree walk described above. Until one is set, a
    // WidgetWithChildren shortcut can only match when host == focused, which
    // is correct but narrow -- a key pressed in a child would not reach it.
    static void setScopePredicate(ICoreWinUIScopePredicate predicate);
    static void clearScopePredicate();

    // Supply the host-to-window walk described above. Until one is set, a
    // Window-scoped shortcut can only match on the `window` add() was given --
    // which is the behaviour every check written before the resolver existed
    // pins, and it is unchanged.
    static void setWindowResolver(ICoreWinUIWindowResolver resolver);
    static void clearWindowResolver();

    // Dispatch one keystroke against the registry.
    //
    // Returns true if a shortcut matched and was invoked, which is what the
    // caller uses to mark the event handled. Public so the suite can drive it
    // with no window, no XAML and no message loop.
    //
    // ⚠ MODIFIERS MUST MATCH EXACTLY, not by subset. Ctrl+Shift+S must not
    // fire a Ctrl+S shortcut: the two are different commands in this
    // application, and a subset test makes the more specific one unreachable
    // because the less specific one always matches first.
    //
    // ⚠ Keypad is IGNORED in the comparison. Qt reports KeypadModifier on the
    // numeric keypad, so a shortcut registered as Ctrl+Plus would not fire
    // from the keypad's plus if the bit were compared -- and W1.4's
    // icoreWinUIIsKeypadKey() exists precisely because Windows makes that bit
    // available. It is deliberately dropped here rather than never computed,
    // because an event handler still wants it.
    static bool dispatch(ICoreKey key,
                         ICoreKeyModifiers modifiers,
                         void* focused,
                         void* activeWindow);

};

File-scope declarations#

// How the registry decides whether a host is in scope for a keystroke.
// 
// ⚠ THIS IS INJECTED BECAUSE IT IS THE ONLY PART THAT NEEDS A TOOLKIT, and
// injecting it is what keeps the rest provable. Given the host a shortcut was
// registered against and the element that had focus when the key arrived, the
// backend answers "is `focused` inside `host`?" -- one XAML tree walk it is
using ICoreWinUIScopePredicate = std::function<bool(void* host, void* focused)>;

// How the registry finds the window a host belongs to, ASKED AT DISPATCH TIME
// rather than at registration.
// 
// ⚠⚠ IT EXISTS BECAUSE TAKING THE WINDOW IN add() IS WRONG FOR EVERY REAL CALL
// SITE IN THIS TREE, AND SILENTLY SO. add() has always accepted a `window`, and
// a shortcut whose window is null matches nothing (see dispatch()) -- which is
using ICoreWinUIWindowResolver = std::function<void*(void* host)>;

ICoreWinUIThemedPrompt.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIThemedPrompt.h

ICoreWinUIThemedPrompt#

ICoreWinUIThemedPrompt.h:51 · class · pImpl · 6 declaration(s)

One modal prompt drawn with THIS APPLICATION'S widgets: an ICoreDialog whose body is an ICoreWidget, whose ground and ink are theme tokens, and whose buttons are ICoreButtons wearing the same varia...

class ICoreWinUIThemedPrompt {
public:
    ICoreWinUIThemedPrompt(ICoreNativeWidget* parent, const ICoreWinUIPromptPlan& plan);
    ~ICoreWinUIThemedPrompt();

    ICoreWinUIThemedPrompt(const ICoreWinUIThemedPrompt&) = delete;
    ICoreWinUIThemedPrompt& operator=(const ICoreWinUIThemedPrompt&) = delete;

    // Put one editing widget between the message and the button row -- a line
    // edit or a combo box, built by the caller so that reading the answer back
    // stays the caller's business.
    //
    // ⚠ CALL IT BEFORE run() OR NOT AT ALL. The frame is finished inside run(),
    // because the dialog's height cannot be settled until it is known whether
    // there is a field in it.
    void addField(ICoreNativeWidget* field, int height);

    // Which button id ended the prompt, or 0 if it could not be raised at all.
    //
    // ⚠ 0 IS WHAT EVERY MAPPING IN ICoreWinUIDialogFields READS AS A REFUSAL,
    // and it is a real answer rather than a defensive one: `icoreWinUIRunModal`
    // reports false when there is no application to pump, which is the state a
    // suite and a headless caller run in. A prompt nobody could answer must not
    // be read as consent.
    int run();

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreWinUITitleBarSeat.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUITitleBarSeat.h

ICoreWinUITitleBarSeat#

ICoreWinUITitleBarSeat.h:21 · class · bases public ICoreTitleBarHost · pImpl · 16 declaration(s)

The WinUI seat for ICoreTitleBar: one per ICoreWindow and one per ICoreDialog, because both own an ICoreWinUIWindow and both need the same thing done to it.

class ICoreWinUITitleBarSeat : public ICoreTitleBarHost {
public:
    // `relayoutContent` re-sizes and re-places the owner's content; the seat
    // calls it whenever the strip above the content appears, disappears or
    // changes height, because the content's origin moved with it.
    ICoreWinUITitleBarSeat(ICoreWinUIWindow& window,
                           ICoreTitleBarRole role,
                           std::function<void()> relayoutContent);
    ~ICoreWinUITitleBarSeat() override;
    ICoreWinUITitleBarSeat(const ICoreWinUITitleBarSeat&) = delete;
    ICoreWinUITitleBarSeat& operator=(const ICoreWinUITitleBarSeat&) = delete;

    // The explicit choice: a bar, or nullptr for the system caption. Either
    // one opts the window out of ICoreTitleBarProvider.
    void setBar(ICoreTitleBar* bar);
    [[nodiscard]] ICoreTitleBar* bar() const;

    // Ask ICoreTitleBarProvider for a bar, ONCE, if nothing was chosen
    // explicitly and the window is decorated. Called on every show; only the
    // first call can do anything.
    void adoptDefaultIfNeeded();

    // Size the bar to the window's current width. Owners call it from the same
    // place they size their content.
    void layoutBar();

    // W10.126. Where popups opened from the bar go: the window's content, asked
    // for when a popup opens (see icoreWinUIRegisterCaptionBar). Without one, a
    // popup from the bar falls back to the newest visible window.
    void setContentResolver(std::function<ICoreNativeWidget*()> contentOf);

    [[nodiscard]] bool titleBarDragsItself() const override;
    void titleBarBeginMove() override;
    void titleBarDoubleClicked() override;
    void titleBarMinimize() override;
    void titleBarToggleMaximize() override;
    void titleBarClose() override;
    void titleBarChanged() override;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreWinUIWindow.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIWindow.h

For rootPanel() below -- the typed half of rootElement(). See its comment: reconstructing a Panel from that void* is an interface reinterpretation, so the projection type has to be nameable here (W8.1).

ICoreWinUIWindow#

ICoreWinUIWindow.h:41 · class · pImpl · nested CaptionColor · 55 declaration(s)

The WinUI backend's window seat: one Microsoft::UI::Xaml::Window, the Microsoft::UI::Windowing::AppWindow behind it, and the display queries that go with them.

class ICoreWinUIWindow {
public:
    ICoreWinUIWindow();
    ~ICoreWinUIWindow();
    ICoreWinUIWindow(const ICoreWinUIWindow&) = delete;
    ICoreWinUIWindow& operator=(const ICoreWinUIWindow&) = delete;

    // Applies the presenter, the chrome, the always-on-top level, the switcher
    // entry and the focus behaviour in one place. Safe to call more than once:
    // the window is reconfigured, not rebuilt, so content already installed
    // survives.
    void setNature(ICoreWinUIWindowNature nature);
    [[nodiscard]] ICoreWinUIWindowNature nature() const;

    // The HWND, as an opaque pointer. This is the registry key and the argument
    // to the handful of Win32 calls WinUI has no answer for.
    [[nodiscard]] void* nativeWindowHandle() const;

    // The AppWindow's id, as its raw integer, or 0.
    //
    // ⚠ A SECOND REGISTRY KEY, AND IT EXISTS BECAUSE THE HWND CANNOT BE
    // REACHED FROM AN ELEMENT IN THIS CONFIGURE. A widget asking "which window
    // am I in" gets an AppWindowId out of its XamlRoot's content island; the
    // step from there to an HWND is GetWindowFromWindowId, which lives in the
    // App SDK's Microsoft.UI.Interop.h -- and THAT header includes an ABI
    // `Microsoft.UI.h` which the generated projection does not produce and the
    // Windows SDK does not ship (searched, not assumed). So the two sides of
    // the join meet on the window ID instead, which both can produce with no
    // interop header at all.
    [[nodiscard]] unsigned long long windowIdValue() const;

    // ⚠ THE ROOT ELEMENT IS OWNED HERE AND IS WHAT THE WINDOW HANDS OUT AS ITS
    // NATIVE WIDGET, exactly as the AppKit seat owns a content view for a class
    // that is not a view. The seat installs a root panel as `Window::Content()`
    // once, at construction, and the central widget becomes that panel's child.
    //
    // Replacing `Window::Content()` per setCentralWidget() instead would throw
    // away the element already handed out through nativeWidgetHandle() -- and
    // several callers in this tree call setCentralWidget more than once, which
    // would leave every earlier handle pointing at a detached element.
    [[nodiscard]] void* rootElement() const;

    // The same root, TYPED -- and the reason both exist is a hazard rather than
    // taste (W8.1). `rootElement()` hands back `get_abi(Grid)`, which is the
    // **IGrid** interface pointer; `copy_from_abi`-ing that into a `Panel`
    // reinterprets one interface as another without a QueryInterface, which is
    // the trap this backend already records elsewhere. A caller that wants the
    // panel takes it from here and never round-trips through the void*.
    [[nodiscard]] winrt::Microsoft::UI::Xaml::Controls::Panel rootPanel() const;

    // Puts `uiElementAbi` -- a UIElement, as W1.3's widget base will hand it out
    // -- in the root panel, replacing whatever was there. Null empties it.
    void setChildElement(void* uiElementAbi);

    void setTitle(const std::string& utf8);
    [[nodiscard]] std::string title() const;

    // Outer rectangle, physical.
    void setFrame(int x, int y, int width, int height);
    void frame(int& x, int& y, int& width, int& height) const;
    void move(int x, int y);
    void resize(int width, int height);

    // Client area, physical. This is what ICoreWindow::resize() reaches.
    void setClientSize(int width, int height);
    void clientSize(int& width, int& height) const;

    // ⚠ HONOURED ON EVERY SIZE THIS SEAT APPLIES AND ON NOTHING ELSE. Windows
    // App SDK 1.5 has no per-window minimum: OverlappedPresenter gained
    // PreferredMinimumWidth/Height in 1.6, and the projection this configure
    // generates carries neither name. So a user dragging the frame smaller is
    // not stopped. Closing that gap needs either the 1.6 presenter or a
    // WM_GETMINMAXINFO subclass on the HWND; it is owed, it is named on W1.2's
    // row, and it is not silently absent.
    void setMinimumClientSize(int width, int height);

    // Whether the user may drag this window's edges. See the definition for why
    // this is the presenter's property rather than a pinned minimum, and for
    // what a factory-fixed presenter does with it.
    void setResizable(bool resizable);

    // Centre this window on `ownerHandle` -- an HWND, or null for the primary
    // display's work area. See the definition for why the OWNER'S DISPLAY is
    // what this is really for.
    void centerOnOwner(void* ownerHandle);
    void minimumClientSize(int& width, int& height) const;

    void show();
    void showWithoutActivating();
    void hide();
    void raise();
    void activate();
    // Asks the window to close, which raises the closing hook below. It is a
    // request: the hook can refuse it.
    void close();

    [[nodiscard]] bool isVisible() const;
    [[nodiscard]] bool isMinimized() const;
    [[nodiscard]] bool isMaximized() const;
    [[nodiscard]] bool isActive() const;
    void restoreFromMinimized();
    void maximize();

    // ⚠ WHOLE-WINDOW ALPHA IS A WIN32 CAPABILITY HERE, NOT A XAML ONE. Neither
    // Window nor AppWindow publishes an opacity, so this goes through
    // WS_EX_LAYERED + SetLayeredWindowAttributes -- which is what the one caller
    // in the tree (ICoreFloatingElementsWindow, 0.6) actually asked for. An
    // opacity of 1 removes the layered style again rather than leaving the
    // window on the layered path for nothing.
    void setOpacity(double opacity);
    [[nodiscard]] double opacity() const;

    // XamlRoot::RasterizationScale, live -- it changes when the window moves
    // between displays of different DPI, so this asks every time rather than
    // caching. Falls back to the HWND's DPI before the window has content,
    // which is the state every window is in between construction and its first
    // setContentElement().
    [[nodiscard]] double rasterizationScale() const;

    // ⚠ RETURNS THE ANSWER RATHER THAN LETTING THE CALLER CLOSE. AppWindow's
    // Closing event wants a synchronous Cancel inside the handler, so "call
    // close() if you agree" -- the shape the AppKit seat uses, where the veto is
    // simply returning -- would mean re-entering Close() from inside Closing.
    // True lets the window go; false cancels it.
    void setClosingHook(std::function<bool()> hook);
    void setActivatedHook(std::function<void()> hook);
    // Physical client size, on size changes only.
    void setResizedHook(std::function<void(int width, int height)> hook);

    // ⚠⚠ THE RASTERIZATION SCALE CHANGED, AND THIS IS A SEPARATE EDGE FROM
    // setResizedHook BECAUSE THE TOOLKIT REPORTS THE TWO SEPARATELY AND IN THE
    // WRONG ORDER. A window dragged onto a display of a different DPI raises
    // AppWindow::Changed with the new PHYSICAL client size while XamlRoot is
    // still reporting the OLD scale -- so the resized hook, whose whole job is
    // physical / scale, divides a 100% size by 1.5 and the content is laid out
    // two thirds too small. Nothing follows it: AppWindow::Changed does not
    // fire again once XamlRoot catches up, so the wrong size is the final one.
    //
    // XamlRoot::Changed is the notification that DOES carry the new density.
    // The argument is the new scale; a handler that re-reads clientSize() and
    // re-does the division has, at that moment, two numbers that agree.
    //
    // ⚠ IT FIRES ONLY WHEN THE SCALE ACTUALLY CHANGED, not on every
    // XamlRoot::Changed -- that event also carries plain size changes, which
    // the resized hook above already serves and which must not be handled
    // twice.
    void setScaleChangedHook(std::function<void(double scale)> hook);

    // ⚠ THE KEY EVENT ARRIVES AT THE ROOT ELEMENT, NOT AT THE WINDOW, and
    // that is the closest thing this toolkit has to QMainWindow::keyPressEvent.
    // Microsoft::UI::Xaml::Window raises no keyboard event at all; KeyDown is a
    // ROUTED event that starts at the focused element and bubbles, so the root
    // panel sees every keystroke no descendant consumed -- which is exactly
    // when Qt hands the event to the window. Answering true marks it handled
    // and stops the bubble.
    void setKeyPressedHook(std::function<bool(const ICoreKeyEvent&)> hook);

    // The keystroke BEFORE the focused element sees it, which is a different
    // event from the one above and not a variant of it.
    //
    // ⚠⚠ KeyDown BUBBLES AND PreviewKeyDown TUNNELS, so this hook runs FIRST
    // -- root, then down to whatever has focus -- while setKeyPressedHook's
    // runs LAST, on what nothing consumed. Both exist because this tree needs
    // both halves of what one toolkit gave for free: Qt dispatches SHORTCUTS
    // before the focus widget's keyPressEvent and delivers the window's own
    // keyPressEvent after it, and those are the two ends of the same routed
    // event here.
    //
    // Answering true marks the event Handled, which on the tunnelling side
    // means the focused element never sees the key at all. Its one consumer is
    // W3.5's shortcut tap; ICoreWinUIShortcutHook.cpp states what pre-empting
    // the focused control costs and why no call site pays it today.
    void setKeyPreviewHook(std::function<bool(const ICoreKeyEvent&)> hook);

    // --- the custom caption (W10.125) --------------------------------------
    //
    // ⚠⚠ ONCE A CAPTION ELEMENT IS INSTALLED, "CLIENT" MEANS THE AREA BELOW IT.
    // The content is extended into the title bar, so the Win32 client rect
    // grows by the caption strip -- and every caller of clientSize(),
    // setClientSize(), setMinimumClientSize() and the resized hook means the
    // area its CONTENT gets, which is what those four went on meaning under the
    // system caption. So all four subtract (or add) the strip here, in one
    // place, and neither ICoreWindow nor ICoreDialog has to know a bar exists.
    //
    // Put `uiElementAbi` (a UIElement ABI pointer, as setChildElement takes) in
    // a strip `logicalHeight` DIPs tall across the top of the window, extend
    // the content into the title bar, and keep the DWM caption buttons on top
    // of it. Null puts the system caption back.
    //
    // ⚠ THE ONE LOGICAL NUMBER IN THIS CLASS. A Grid row is sized in DIPs, and
    // a caption must keep its DIP height when the window is dragged to a
    // display of another density -- so the height is stored as the DIPs it was
    // asked for and converted to physical on every question, never cached.
    void setCaptionElement(void* uiElementAbi, double logicalHeight);
    [[nodiscard]] double captionLogicalHeight() const;
    [[nodiscard]] int captionPhysicalHeight() const;

    // The strips the caption BUTTONS occupy at each edge, physical. Zero when
    // no caption element is installed.
    void captionButtonInsets(int& left, int& right) const;

    // One colour for the DWM caption buttons. `valid == false` leaves the
    // platform's own.
    struct CaptionColor {
        bool valid = false;
        unsigned char a = 255;
        unsigned char r = 0;
        unsigned char g = 0;
        unsigned char b = 0;
    };
    void setCaptionButtonColors(const CaptionColor& background,
                                const CaptionColor& foreground,
                                const CaptionColor& hoverBackground,
                                const CaptionColor& pressedBackground,
                                const CaptionColor& inactiveForeground);

    // The parts of the caption strip that take clicks instead of dragging the
    // window, physical, client-relative. Everything else in the strip, less
    // the button insets, is handed to the platform as the caption region --
    // which is what gives it the native drag, Aero Snap, the double-click
    // maximise and the system menu.
    void setCaptionPassthrough(const std::vector<ICoreWinUIRect>& rects);

    // Runs whenever something a title bar shows may have changed: activation
    // (both edges), size, maximised state, title. One slot.
    void setCaptionStateHook(std::function<void()> hook);

    void minimize();
    void restore();

    // --- displays, physical ------------------------------------------------
    [[nodiscard]] static int screenCount();
    // The work area of the display this window is on -- the desktop minus the
    // taskbar, which is what a centred or corner-placed window must fit inside.
    [[nodiscard]] bool workArea(ICoreWinUIRect& out) const;
    [[nodiscard]] static bool primaryWorkArea(ICoreWinUIRect& out);

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreWinUIWindowCore.h#

ICoreEssentials/UI/Backends/WinUI/Windows/ICoreWinUIWindowCore.h

The DECISIONS half of the WinUI window seat: everything ICoreWindow has to work out for itself, with the toolkit taken off the front.

⚠ NO WINRT TYPES, NO WINDOWS TYPES AND NO XAML IN THIS HEADER. Same split, and for the same reason, as ICoreWinUIEventFields.h beside the event tables: a window cannot be constructed outside a running XAML tree, so anything a suite is to check has to be reachable without one. ICoreWinUIWindow.h is the other half -- it names Microsoft::UI::Xaml::Window and Microsoft::UI::Windowing::AppWindow, and decides nothing.

Everything here is integers, doubles, strings and callbacks, so the suite beside it runs on a box with no Windows App SDK at all.

COORDINATES. Every rectangle and point below is in PHYSICAL pixels, because

ICoreWinUIRect#

ICoreWinUIWindowCore.h:37 · struct · 0 declaration(s)

A rectangle as Windows reports one: exclusive right and bottom edges.

struct ICoreWinUIRect {
public:
    int x = 0;
    int y = 0;
    int width = 0;
    int height = 0;
};
};

ICoreWinUIPoint#

ICoreWinUIWindowCore.h:44 · struct · 0 declaration(s)

struct ICoreWinUIPoint {
public:
    int x = 0;
    int y = 0;
};
};

ICoreWinUISize#

ICoreWinUIWindowCore.h:49 · struct · 0 declaration(s)

struct ICoreWinUISize {
public:
    int width = 0;
    int height = 0;
};
};

ICoreWinUIWindowGeometry#

ICoreWinUIWindowCore.h:126 · struct · 0 declaration(s)

What saveGeometry() writes and restoreGeometry() reads back.

struct ICoreWinUIWindowGeometry {
public:
    int x = 0;
    int y = 0;
    int width = 0;
    int height = 0;
    // How many displays existed when this was saved. See the parse note.
    int screenCount = 1;
    // Restoring a maximised window as a floating rectangle is a visible
    // regression the Qt blob does not have -- QWidget::saveGeometry carries the
    // state and QWidget::restoreGeometry re-maximises. The AppKit peer omits it
    // because AppKit has no maximised state to carry; Windows does.
    bool maximized = false;
    // The DPI the rectangle was measured at (96 = 100%). Physical pixels mean
    // nothing without it: the same window is 1280 wide at 100% and 1920 at
    // 150%. ⚠ A VERSION-1 RECORD HAS NO SUCH FIELD AND READS AS 96, and that
    // is a fact rather than a guess: every version-1 blob was written by an
    // ICoreBlocks.exe that declared no DPI awareness, so Windows virtualized its
    // pixels to 96 DPI. The manifest declared PerMonitorV2 on 2026-09-29.
    int dpi = 96;
};
};

ICoreWinUICloseOutcome#

ICoreWinUIWindowCore.h:184 · struct · 0 declaration(s)

What the seat does once icoreWinUIDecideClose() has run.

struct ICoreWinUICloseOutcome {
public:
    bool closeWindow = false;   // let the window go; false is the veto
    bool deleteShell = false;   // ...and the shell deletes itself afterwards
};
};

File-scope declarations#

// The four window personalities, named here rather than re-derived from the
// wide Qt-shaped flag set at each call site. The AppKit seat carries the same
// four (ICoreAppKitWindowNature) because the vocabulary is the editor's, not
// the toolkit's; what each one MEANS on this backend is in ICoreWinUIWindow.h.
enum class ICoreWinUIWindowNature {
    DecoratedWindow,   // border and title bar, the ordinary case
    FramelessWindow,   // chrome gone, focus kept
    Popup,             // menu level: no chrome, always on top, out of the switcher
    FloatingCard,      // tool window: no chrome, always on top, does not take focus
};