AI Windows: Window Handles
AI-first map of window handles, selectors, matchers, and providers.
Window Handles / Matching / Tracking Discovery Map
Reference map for native window handles, raw HWND conversion, window
enumeration, matching, foreground tracking, and bounds tracking.
Interactive picking belongs to osd/selection.md.
User Intents
- Convert raw
HWND/IntPtrintoIWindowHandle. - Read process id, title, bounds, owner, parent, and visibility for a window.
- Enumerate known windows.
- Match windows by title, process, path, handle, or expression.
- Keep live target-window selection.
- Track foreground window or bounds changes.
Concept Model
IWindowHandleis the PoeShared wrapper around a native window.IWindowHandleProviderconverts raw handles into wrappers.IWindowListProviderowns live enumeration, ignored windows, blacklists, and foreground resolution.IWindowMatcherperforms stateless expression matching.IWindowSelectorkeeps a stateful active target from a match expression.IWindowHandleMatcherandIComplexWindowHandleMatcherare infrastructure include/exclude predicates.- Foreground and bounds trackers wrap native event hooks.
Find and activate a window
Open Notepad and run this top-level C# Action:
IFactory<IWindowSelector> WindowSelectorFactory { get; init; }
{
using var selector = WindowSelectorFactory.Create();
var window = selector.FindWindow("notepad.exe");
if (window == null)
{
Log.Info("No matching window yet");
return;
}
window.Activate(TimeSpan.FromMilliseconds(500));
Log.Info($"Selected window: {window.Title}");
}
This Run owns the selector and its subscriptions. The factory and handles are
borrowed host infrastructure. Ordinary classes receive the factory explicitly.
The desktop host needs native registrations and UI Core; SDK types alone do not
provide a live window list. FindWindow reads immediately and may return null;
GetWindow throws InvalidOperationException in that case. Selection is not OS
foreground. The current target is retained while it still matches.
OnlyVisible defaults to false. Target assignment defaults to top-level external
windows unless overridden. Plain text matches paths/titles/arguments or a whole
process name, so notepad.exe is not AHK's process-only restriction. Activation
is synchronous, may restore a minimized window, has no cancellation token and can
fail under Windows foreground policy. A zero foreground can extend the wait to
ten seconds; 500 ms is not a strict total-duration bound.
Wait for a window from one process
Start this top-level script, then open Notepad:
using System;
using System.IO;
using System.Threading.Tasks;
using EyeAuras.Shared.Services;
using PoeShared.Native;
using PoeShared.Prism;
{
var runToken = cancellationToken;
var factory = GetService<IFactory<IWindowSelector>>();
using var selector = factory.Create();
selector.OnlyVisible = true;
selector.WindowFilter = candidate => string.Equals(
Path.GetFileNameWithoutExtension(candidate.ProcessName),
"notepad", StringComparison.OrdinalIgnoreCase);
selector.TargetWindow = "#1";
IWindowHandle window;
while (true)
{
runToken.ThrowIfCancellationRequested();
window = selector.ActiveWindow;
if (window != null && window.IsWindow)
{
break;
}
await Task.Delay(250, runToken);
}
Log.Info($"Notepad found: {window.Title}");
}
#1 selects the first result after filtering, not necessarily a particular
Notepad document. Normalize the executable extension because ProcessName can
come from a file name or the fallback Process.ProcessName. Stop cancels the
delay and releases the selector. IsWindow is a point-in-time check, not a lock
against window closure. Re-read selector.ActiveWindow on every later iteration;
the local window variable does not follow future target changes.
Take a process window snapshot
This C# Script reads the shared provider without changing another selector:
using System;
using System.IO;
using System.Linq;
using EyeAuras.Shared.Services;
var provider = GetService<IWindowListProvider>();
provider.RefreshWindowList();
var snapshot = provider.WindowList.Items.ToArray();
var matches = snapshot.Where(w => w.IsWindow && string.Equals(
Path.GetFileNameWithoutExtension(w.ProcessName),
"notepad", StringComparison.OrdinalIgnoreCase)).ToArray();
foreach (var w in matches)
Log.Info($"{w.Title}, PID: {w.ProcessId}");
The array snapshots enumeration, not future window validity. Provider and handles
are borrowed. For a text expression across multiple fields, pass the materialized
array to IWindowMatcher.FindMatches(snapshot, expression); its contract takes
IReadOnlyList<IWindowHandle>, not an arbitrary lazy enumerable.
Check the foreground process
This query does not read or modify a selector:
using System;
using System.IO;
using EyeAuras.Shared.Services;
var foreground = GetService<IWindowListProvider>().GetForegroundWindow();
var isNotepad = foreground != null && foreground.Handle != IntPtr.Zero &&
foreground.IsWindow && string.Equals(
Path.GetFileNameWithoutExtension(foreground.ProcessName),
"notepad", StringComparison.OrdinalIgnoreCase);
Log.Info($"Notepad is foreground: {isNotepad}");
The provider may wrap a zero HWND, so a non-null managed reference is insufficient. Foreground can change immediately after the read.
Convert a frame-relative point
ToScreen(Point) and FromScreen(Point) add/subtract the origin of
DwmFrameBounds; invalid bounds throw. This is frame-relative geometry, not a
promise of Win32 client coordinates. Choose the input coordinate space and backend
before using an OSD matrix or sending mouse input.
Observe one window's bounds
Open Notepad, run this C# Action and move its window during the next ten seconds. The text expression is broad; use the earlier filter for process-only selection.
using System;
using System.Reactive.Linq;
using System.Threading.Tasks;
using EyeAuras.Shared.Services;
using EyeAuras.Shared.Scaffolding;
using PoeShared.Native;
using PoeShared.Prism;
{
using var selector = GetService<IFactory<IWindowSelector>>().Create();
var window = selector.FindWindow("notepad.exe");
if (window == null || !window.IsWindow)
{
Log.Info("No window yet; run this example again");
return;
}
var tracker = GetService<IWindowBoundsTrackerFactory>();
using var subscription = tracker.Track(window).Subscribe(
bounds => Log.Info(bounds.HasValue
? $"Bounds: {bounds.Value}"
: "Bounds unavailable"),
error => Log.Error("Bounds tracking failed", error));
await Task.Delay(TimeSpan.FromSeconds(10), cancellationToken);
}
The stream emits initial bounds and later changes. Ten seconds or Stop ends this subscription. It follows one HWND, not replacement selector targets. Nullable bounds do not guarantee a close event; the stream can fail. The factory is borrowed. The source does not establish native-hook disposal as a subscription completion barrier; do not assume a UI delivery thread or complete native teardown.
API Details
-
PoeShared.Native.IWindowHandle- Use
Handleonly when rawIntPtris required. - Prefer
ProcessId,ProcessName,Title,Bounds, owner/parent/state metadata over re-querying Win32.
- Use
-
PoeShared.Native.IWindowHandleProviderGetByWindowHandle(IntPtr hwnd)converts raw handles.GetMonitorByWindowHandle(IntPtr hwnd)resolves monitor context.- Does not select or enumerate windows.
-
IWindowListProviderAllWindowList,WindowList,IgnoredWindows,BlacklistedWindows.ResolveByHandle(IntPtr),GetForegroundWindow(),RefreshWindowList().
-
IWindowMatcherIsMatch(...)andFindMatches(...)forWindowMatchExpression.
-
IWindowSelectorTargetWindow,ActiveWindow,MatchingWindowList,OnlyVisible,WindowFilter.- Use when code needs a persistent selected target window that follows a match expression.
-
WindowSelectorExtensionsFindWindow(...)setsTargetWindowand returns the selectedActiveWindow, ornullwhen no match exists.GetWindow(...)setsTargetWindowand returns the selectedActiveWindow; use it when absence is exceptional.- Use
TargetWindowplusActiveWindowwhen absence is expected and should be handled without exceptions and the code wants persistent selector state. - Use
IWindowMatcher.FindMatches(...)when the code intentionally needs multiple matches or matching over a supplied list.
-
WindowHandleExtensionsActivate(...)brings anIWindowHandleto the foreground.Activate(...)delegates toUnsafeNative.ActivateWindow(...).ToWindowMatchExpressionOrDefault(...)creates a reusable match expression from a known window handle.
-
UnsafeNative.ActivateWindow(...)- Low-level activation helper with
IntPtr,IWindowHandle, timeout, and log overloads. - Restores minimized windows before activation and waits for the foreground switch.
- Throws when the target does not become foreground before the timeout.
- Prefer
WindowHandleExtensions.Activate(...)in script/docs examples.
- Low-level activation helper with
-
IForegroundWindowTracker,IWindowTracker- Foreground/active window tracking.
-
IWindowBoundsTrackerFactory- Tracks window rectangle changes.
Common Flows
-
Raw handle to wrapper:
- receive
IntPtr hwnd. - call
IWindowHandleProvider.GetByWindowHandle(hwnd). - pass
IWindowHandledownstream.
- receive
-
Persistent target selection:
- receive
IWindowSelector. - set
TargetWindow. - read
ActiveWindowandMatchingWindowList.
- receive
-
Single target lookup:
- receive
IWindowSelector. - call
FindWindow(...)when absence is expected and should be handled without exception. - call
GetWindow(...)only when absence is exceptional. - use
TargetWindowplusActiveWindowwhen the code wants persistent selector state. - keep the returned
IWindowHandleinstead of re-querying by raw handle or string.
- receive
-
Multiple-match or stateless query:
- receive
IWindowListProviderandIWindowMatcher. - read
WindowsProvider.WindowList.Items. - call
IWindowMatcher.FindMatches(..., targetExpression).
- receive
-
One-shot "window is active" query:
- receive
IWindowListProviderandIWindowMatcher. - call
IWindowListProvider.GetForegroundWindow(). - call
IWindowMatcher.IsMatch(foregroundWindow, targetExpression).
- receive
-
Activate a matched window:
- receive
IWindowSelector. - call
FindWindow(...)when the missing-window path should be handled explicitly. - call
GetWindow(...)only when absence is exceptional. - call
Activate(...)on the handle.
- receive
-
Window match expression basics:
- plain text matches process path, process name, or title.
- quoted text is strict.
/pattern/is regex.0x...or&H...matches a native handle.#2selects the second matching window.FindMatchesnarrows results with&&;||takes the first nonempty alternative, not a union.IsMatchaccepts a simple expression.- Text uses ordinal case-insensitive comparison; regex ignores case too.
- Selector consumes
[type=toplevel],[type=child]and[ownedBy=...]; parsed[visible]/[focus]are not automatic filters. UseOnlyVisible.
-
Track bounds:
- receive
IWindowBoundsTrackerFactory. - call
Track(window). - dispose the subscription with the owner lifetime.
- receive
Prefer
- Prefer
IWindowHandleafter selection/resolution. - Prefer
IWindowHandleProvideronly for raw handle conversion. - Prefer
IWindowSelectorfor live target matching. - Prefer
IWindowSelector.FindWindow(...)for non-throwing single-window lookup. - Prefer
IWindowSelector.GetWindow(...)only when absence is exceptional. - Prefer
IWindowMatcherplusIWindowListProviderfor multi-window matching, custom supplied lists, or active-window checks that should not mutate selector state. - Prefer direct window-handle APIs for thin window operations.
- Prefer trackers over raw native event hooks.
Avoid
- Avoid storing raw
IntPtras long-term contract. - Avoid using
IWindowHandleProvideras selector/enumerator. - Avoid using aura Actions, Triggers, or Overlays as lightweight wrappers for thin script/API operations. They are stateful Aura Tree runtime objects with configuration and lifecycle.
- Avoid copying AutoHotkey
WinTitletokens such asahk_exeorahk_classdirectly intoWindowMatchExpression; map them deliberately. - Avoid treating activation as guaranteed; foreground activation can time out or be blocked by Windows.
- Avoid direct low-level WinEvent code when trackers exist.
Research Anchors
IWindowHandle,IWindowHandleProvider,IWindowListProvider,IWindowMatcher,IWindowSelector,WindowMatchExpression,WindowSelectorExtensions,WindowHandleExtensions,UnsafeNative.ActivateWindow,IWindowHandleMatcher,IComplexWindowHandleMatcher,IForegroundWindowTracker,IWindowBoundsTrackerFactory,IWinEventHookWrapper.
Search Synonyms
- HWND
- IntPtr window handle
- window handle wrapper
- window selector
- window matcher
- foreground window
- active window
- target window
- window exists
- WinExist
- WinActive
- WinActivate
- window bounds tracker
- WinEvent hook