HWND, сопоставлению и отслеживанию оконСправочная карта по нативным дескрипторам окон, преобразованию сырого HWND, перечислению окон, сопоставлению, отслеживанию foreground-окна и изменений границ окна.
Интерактивный выбор окна описан в osd/selection.md.
HWND / IntPtr в IWindowHandle.IWindowHandle — это обёртка PoeShared над нативным окном.IWindowHandleProvider преобразует сырые handle в обёртки.IWindowListProvider отвечает за живое перечисление, ignored windows, blacklists и определение foreground window.IWindowMatcher выполняет stateless-сопоставление по выражению.IWindowSelector хранит stateful active target на основе match expression.IWindowHandleMatcher и IComplexWindowHandleMatcher — это инфраструктурные include/exclude predicates.PoeShared.Native.IWindowHandle
Handle только там, где действительно нужен сырой IntPtr.ProcessId, ProcessName, Title, Bounds и метаданные owner/parent/state.PoeShared.Native.IWindowHandleProvider
GetByWindowHandle(IntPtr hwnd) преобразует сырой handle.GetMonitorByWindowHandle(IntPtr hwnd) определяет monitor context.IWindowListProvider
AllWindowList, WindowList, IgnoredWindows, BlacklistedWindows.ResolveByHandle(IntPtr), GetForegroundWindow(), RefreshWindowList().IWindowMatcher
IsMatch(...) и FindMatches(...) для WindowMatchExpression.IWindowSelector
TargetWindow, ActiveWindow, MatchingWindowList, OnlyVisible, WindowFilter.WindowSelectorExtensions
FindWindow(...) устанавливает TargetWindow и возвращает выбранное ActiveWindow, либо null, если совпадений нет.GetWindow(...) устанавливает TargetWindow и возвращает выбранное ActiveWindow; используйте его, когда отсутствие окна считается исключительной ситуацией.TargetWindow вместе с ActiveWindow, если отсутствие окна ожидаемо и его нужно обрабатывать без исключений, при этом коду важно сохранить состояние selector.IWindowMatcher.FindMatches(...), если коду намеренно нужны несколько совпадений или сопоставление по переданному списку.WindowHandleExtensions
Activate(...) выводит IWindowHandle на передний план.Activate(...) делегирует вызов в UnsafeNative.ActivateWindow(...).ToWindowMatchExpressionOrDefault(...) создаёт переиспользуемое match expression из известного handle окна.UnsafeNative.ActivateWindow(...)
IntPtr, IWindowHandle, timeout и log.WindowHandleExtensions.Activate(...).IForegroundWindowTracker, IWindowTracker
IWindowBoundsTrackerFactory
Сырой handle в обёртку:
IntPtr hwnd;IWindowHandleProvider.GetByWindowHandle(hwnd);IWindowHandle.Постоянный выбор целевого окна:
IWindowSelector;TargetWindow;ActiveWindow и MatchingWindowList.Поиск одного целевого окна:
IWindowSelector;FindWindow(...), если отсутствие окна ожидаемо и должно обрабатываться без исключения;GetWindow(...) только если отсутствие окна — исключительная ситуация;TargetWindow вместе с ActiveWindow, если коду нужно постоянное состояние selector;IWindowHandle, а не запрашивайте окно повторно по сырому handle или строке.Несколько совпадений или stateless-запрос:
IWindowListProvider и IWindowMatcher;WindowsProvider.WindowList.Items;IWindowMatcher.FindMatches(..., targetExpression).Одноразовая проверка "окно активно":
IWindowListProvider и IWindowMatcher;IWindowListProvider.GetForegroundWindow();IWindowMatcher.IsMatch(foregroundWindow, targetExpression).Активация найденного окна:
IWindowSelector;FindWindow(...), если сценарий с отсутствующим окном должен обрабатываться явно;GetWindow(...) только если отсутствие окна — исключительная ситуация;Activate(...) у handle.Базовые правила WindowMatchExpression:
/pattern/ — это regex;0x... или &H... сопоставляется с нативным handle;#2 выбирает второе подходящее окно;&& и || объединяют более простые выражения;[type=toplevel], [type=child], [visible] и [focus] дополнительно ограничивают сопоставление.Отслеживание bounds:
IWindowBoundsTrackerFactory;Track(window);IWindowHandle после выбора/разрешения окна.IWindowHandleProvider только для преобразования сырого handle.IWindowSelector.IWindowSelector.FindWindow(...).IWindowSelector.GetWindow(...) используйте только когда отсутствие окна — исключительная ситуация.IWindowMatcher вместе с IWindowListProvider.IntPtr как долгоживущий контракт.IWindowHandleProvider как selector или enumerator.WinTitle tokens вроде ahk_exe или ahk_class напрямую в WindowMatchExpression; переносите их осознанно.IWindowHandle, IWindowHandleProvider, IWindowListProvider,IWindowMatcher, IWindowSelector, WindowMatchExpression,WindowSelectorExtensions, WindowHandleExtensions,UnsafeNative.ActivateWindow,IWindowHandleMatcher, IComplexWindowHandleMatcher,IForegroundWindowTracker, IWindowBoundsTrackerFactory,IWinEventHookWrapper.osd/selection.mdosd/screen-overlay.mdwindows-subsystems/input-hooks-hotkeys.mdmemory/processes.md