qk.Window:窗口
桌面上的顶层窗口本身(查找、激活、移动/缩放、置顶、关闭等);窗口里的按钮、输入框等界面元素见 qk.Uia。不按目标管理员权限、完整性级别或 UIAccess 身份额外拦截;实际操作仍受 Windows 限制。Win 仅本次运行有效;子窗口只能查询,不能激活/排列/关闭。常见错误码:WINDOW_LIMIT_EXCEEDED(超出次数或枚举上限)、WINDOW_REF_STALE(窗口已关闭)、WINDOW_UNAVAILABLE(窗口隐藏/最小化或无法校验,不能用于该操作)、WINDOW_CHANGED(操作期间窗口被移动、改变大小或遮挡)。
Window.GetForeground
Win? GetForeground()
当前前台窗口(顶层);取不到时回退到动作启动时的活动窗口。
返回类型:Win?。空值、用户取消和异常行为以成员及域说明为准。
Window.FromPoint
Win? FromPoint(Pt? point = null, bool root = true)
指定点下的窗口;没有返回 null。
| 参数声明 | 说明 |
|---|---|
Pt? point = null | 屏幕点;null 为当前鼠标位置。 |
bool root = true | true(默认)返回顶层窗口;false 返回点下最深的子窗口/控件(如给 Edit 发 WM_SETTEXT;对顶层窗口发 WM_SETTEXT 改的是标题)。子窗口只能查询与发消息。 |
返回类型:Win?。空值、用户取消和异常行为以成员及域说明为准。
Window.Find
Win? Find(string title = "", string process = "", string className = "", bool regex = false, bool hidden = false)
查找首个匹配的顶层窗口;无则返回 null。候选窗口超过枚举上限仍未确定结果时抛 WINDOW_LIMIT_EXCEEDED。
| 参数声明 | 说明 |
|---|---|
string title = "" | 标题包含匹配,不区分大小写(regex 为 true 时为正则)。 |
string process = "" | 进程名,完整匹配、不区分大小写,可带 .exe(notepad 或 notepad.exe)。 |
string className = "" | 窗口类名(完整匹配,不区分大小写)。 |
bool regex = false | 见本成员和所在域的说明。 |
bool hidden = false | 包含不可见窗口。 |
返回类型:Win?。空值、用户取消和异常行为以成员及域说明为准。
Window.FindAll
Win[] FindAll(string title = "", string process = "", string className = "", bool regex = false, bool hidden = false, int limit = 64)
列出匹配的可见顶层窗口(含空标题窗口;只需标题/进程时直接读 w.Title/w.Process);候选窗口超过枚举上限且结果不足 limit 时抛 WINDOW_LIMIT_EXCEEDED。
| 参数声明 | 说明 |
|---|---|
string title = "" | 见本成员和所在域的说明。 |
string process = "" | 见本成员和所在域的说明。 |
string className = "" | 见本成员和所在域的说明。 |
bool regex = false | 见本成员和所在域的说明。 |
bool hidden = false | 包含不可见窗口(同 Find)。 |
int limit = 64 | 最多返回数量(1–64)。 |
返回类型:Win[]。空值、用户取消和异常行为以成员及域说明为准。
Window.FindAllInfo
WinInfo[] FindAllInfo(string title = "", string process = "", string className = "", bool regex = false, bool hidden = false, int limit = 64)
与 FindAll 相同的匹配与上限,但一次返回各窗口的信息快照(含 Bounds/State 与可继续操作的 Window 引用);整次只计 1 次窗口观察,适合“列出后按位置/状态筛选”。
| 参数声明 | 说明 |
|---|---|
string title = "" | 见本成员和所在域的说明。 |
string process = "" | 见本成员和所在域的说明。 |
string className = "" | 见本成员和所在域的说明。 |
bool regex = false | 见本成员和所在域的说明。 |
bool hidden = false | 包含不可见窗口(同 Find)。 |
int limit = 64 | 最多返回数量(1–64)。 |
返回类型:WinInfo[]。空值、用户取消和异常行为以成员及域说明为准。
Window.ListChildren
Win[] ListChildren(Win window, string title = "", string className = "")
列出后代子窗口(最多 64 个);子窗口只可查询,不能激活/排列/关闭。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
string title = "" | 见本成员和所在域的说明。 |
string className = "" | 见本成员和所在域的说明。 |
返回类型:Win[]。空值、用户取消和异常行为以成员及域说明为准。
Window.Info
WinInfo Info(Win window)
重新验证窗口并读取最新信息(可返回)。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
返回类型:WinInfo。空值、用户取消和异常行为以成员及域说明为准。
Window.Activate
void Activate(Win window)
激活顶层窗口(切换为前台;最小化的窗口会先还原);无返回值,需要最新状态时调用 Info。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.ActivateProcess
Win? ActivateProcess(string process, string? path = null, string? title = null, string? className = null, bool regex = false, string? hotkey = null, bool launch = true)
进程已运行则激活其主窗口,否则按 path 以普通权限启动并等待窗口;未运行且不启动时返回 null。目标窗口的身份和状态仍由宿主校验。
| 参数声明 | 说明 |
|---|---|
string process | 进程名。 |
string? path = null | 未运行时启动的目标:exe/.lnk(普通权限),或网址、shell:AppsFolder\…、其他文件(系统 Shell 打开)。 |
string? title = null | 窗口标题:包含匹配、不区分大小写(regex 为 true 时为正则,无效正则报 INVALID_ARGUMENT)。 |
string? className = null | 窗口类名:完整匹配、不区分大小写(regex 为 true 时为正则)。 |
bool regex = false | title/className 按 .NET 正则匹配。 |
string? hotkey = null | 唤出窗口的快捷键(如托盘程序的唤醒键),只接受单个组合键如 "Ctrl+Alt+Q";经输入会话发送。 |
bool launch = true | 未运行时是否启动。 |
返回类型:Win?。空值、用户取消和异常行为以成员及域说明为准。
Window.RestoreForeground
void RestoreForeground()
回到弹出面板前的前台窗口;没有记录时不操作。
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.SetBounds
void SetBounds(Win window, Rect bounds)
设置顶层窗口位置和大小(物理像素)。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
Rect bounds | 见本成员和所在域的说明。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.SetState
void SetState(Win window, string state)
设置顶层窗口状态(普通/最小化/最大化)。隐藏/显示用 SetVisible,置于其他窗口之下用 SendToBack。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
string state | normal|minimized|maximized。 取值:normal、minimized、maximized。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.Snap
bool Snap(Win window, string position, string? screen = null)
把顶层窗口吸附到屏幕的某个位置(取目标屏幕的工作区 WorkArea:已排除任务栏,物理像素;DPI 与窗口不可见的缩放边框由宿主处理,使可见部分紧贴工作区)。最大化/最小化的窗口先还原(等还原完成)再摆放;跨 DPI 屏幕移动后系统可能重算窗口大小,宿主在窗口稳定后复核并最多补一次。目标须为顶层窗口,拒绝 Quicker 自身窗口;计 1–4 次排列操作。移动与状态改变异步投递,目标窗口无响应(挂起)时 Snap 不会阻塞脚本。返回 bool:窗口稳定(连续两次读取相隔 50 毫秒相同,最多约 1 秒)后核实最终可见边界(maximize/restore 核实状态)在几个像素内才为 true,否则 false(不报错)。最多补一次且仅在稳定时。
| 参数声明 | 说明 |
|---|---|
Win window | 要吸附的顶层窗口。 |
string position | left | right | top | bottom(半屏)| topLeft | topRight | bottomLeft | bottomRight(四分之一屏)| maximize(最大化)| center(保持当前大小并居中,超出工作区时收缩)| restore(还原为普通状态,不移动,此时忽略 screen);不区分大小写,不接受别名。 取值:left、right、top、bottom、topLeft、topRight、bottomLeft、bottomRight、maximize、center、restore。 |
string? screen = null | qk.Screen.List() 的 ScreenInfo.Id,或 primary(主屏)| mouse(鼠标所在屏);null 为窗口当前所在的屏幕(注意:与 Sys.GetBrightness 默认 mouse 不同);找不到该 Id 报 INVALID_ARGUMENT。 取值:primary、mouse。也接受其他值,详见成员说明。 |
返回类型:bool。空值、用户取消和异常行为以成员及域说明为准。
Window.SetVisible
void SetVisible(Win window, bool visible)
隐藏或显示顶层窗口(不激活);异步投递,不等待目标窗口处理。隐藏后可用 FindAll(hidden: true) 找回。不能隐藏任务栏、桌面等外壳窗口(INVALID_ARGUMENT)。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
bool visible | false 隐藏,true 显示。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.SendToBack
void SendToBack(Win window)
把顶层窗口置于其他窗口之下(先取消置顶);异步投递,不等待目标窗口处理。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.SetTopmost
bool SetTopmost(Win window, bool topmost = true)
设置或取消置顶;返回调用后的实际置顶状态。需要切换时写 SetTopmost(w, !qk.Window.Info(w).Topmost)。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
bool topmost = true | true 置顶,false 取消。 |
返回类型:bool。空值、用户取消和异常行为以成员及域说明为准。
Window.SetOpacity
void SetOpacity(Win window, int alpha)
设置窗口不透明度。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
int alpha | 0–255(0 全透明,255 不透明)。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.Close
void Close(Win window, bool kill = false)
发送关闭请求(程序可能询问保存);不能关闭 Quicker 自身的窗口。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
bool kill = false | 未及时关闭时强制结束窗口所属程序(可能丢失未保存数据);不能用于资源管理器/桌面与 Quicker 及其辅助进程。 |
返回类型:void。空值、用户取消和异常行为以成员及域说明为准。
Window.WaitFor
Win? WaitFor(string title = "", string process = "", string className = "", string state = "exists", int timeoutMs = 10000)
等待窗口达到状态;满足时返回窗口,超时返回 null。等待窗口关闭用 WaitForClose。
| 参数声明 | 说明 |
|---|---|
string title = "" | 见本成员和所在域的说明。 |
string process = "" | 见本成员和所在域的说明。 |
string className = "" | 见本成员和所在域的说明。 |
string state = "exists" | exists|visible|foreground。 取值:exists、visible、foreground。 |
int timeoutMs = 10000 | 超时毫秒(最长 1 小时);同时受动作超时约束(默认 30 秒墙钟),长等待需在编辑器调大动作超时。 |
返回类型:Win?。空值、用户取消和异常行为以成员及域说明为准。
Window.WaitForClose
bool WaitForClose(string title = "", string process = "", string className = "", int timeoutMs = 10000)
等待匹配的窗口全部关闭(含不可见窗口;本来就没有也算关闭):关闭返回 true,超时返回 false(超时不抛错)。
| 参数声明 | 说明 |
|---|---|
string title = "" | 见本成员和所在域的说明。 |
string process = "" | 见本成员和所在域的说明。 |
string className = "" | 见本成员和所在域的说明。 |
int timeoutMs = 10000 | 超时毫秒(最长 1 小时);同时受动作超时约束。 |
返回类型:bool。空值、用户取消和异常行为以成员及域说明为准。
Window.ToScreen
Pt ToScreen(Win window, Pt offset, string anchor = "topLeft")
DWM 可见边界的锚点加 offset,读取失败时回退窗口外框,返回屏幕物理像素。前台 CaptureWindow 按外框采集,两者原点可能不同;不要用本方法转换截图/OCR 图内点,也不要猜边框补偿。屏幕 Vision.Find* 的结果已是屏幕坐标。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
Pt offset | 相对锚点的偏移(Pt,窗口相对的物理像素)。 |
string anchor = "topLeft" | topLeft|topRight|bottomLeft|bottomRight|center;右/下边界为可见外沿,向内偏移用负数。 取值:topLeft、topRight、bottomLeft、bottomRight、center。 |
返回类型:Pt。空值、用户取消和异常行为以成员及域说明为准。
Window.SendMessage
long SendMessage(Win window, int message, long wParam = 0, object? lParam = null, bool post = false, int timeoutMs = 5000)
向窗口(可为子控件)发送窗口消息并返回结果。拒绝 Quicker 自身窗口;计 1 次排列操作。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
int message | 见本成员和所在域的说明。 |
long wParam = 0 | 见本成员和所在域的说明。 |
object? lParam = null | null/整数;string 只允许 WM_SETTEXT(0x000C) 与 WM_COPYDATA(0x004A,宿主封装 COPYDATASTRUCT,dwData 取 wParam),不能 post;其他消息带 string 报 INVALID_ARGUMENT。系统按指针封送的消息(WM_GETTEXT、EM_GETLINE 等)只接受 0。 |
bool post = false | true:PostMessage(不等待,返回 0)。 |
int timeoutMs = 5000 | 同步发送的超时 1–60000 毫秒;目标无响应报 WINDOW_MESSAGE_TIMEOUT。 |
返回类型:long。空值、用户取消和异常行为以成员及域说明为准。
Window.CloseSimilar
int CloseSimilar(Win window, bool keepCurrent = false)
向同一程序(可执行文件路径相同;资源管理器只限文件夹窗口)的顶层窗口发送关闭请求(程序可能询问保存或拒绝关闭),返回已发出的请求数(不等于实际关闭数);部分失败时返回成功数;共享宿主进程或不适用的窗口报 WINDOW_ARRANGE_FAILED;计 1 次排列操作。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
bool keepCurrent = false | 保留 window 本身(只关闭其他类似窗口)。 |
返回类型:int。空值、用户取消和异常行为以成员及域说明为准。
Window.MinimizeSimilar
int MinimizeSimilar(Win window)
最小化同一程序的顶层窗口(不抢焦点),返回受影响的窗口数(已最小化的不计);其余规则同 CloseSimilar。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
返回类型:int。空值、用户取消和异常行为以成员及域说明为准。
Window.RestoreSimilar
int RestoreSimilar(Win window)
还原同一程序中已最小化的顶层窗口(不抢焦点),返回还原的窗口数;其余规则同 CloseSimilar。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
返回类型:int。空值、用户取消和异常行为以成员及域说明为准。
Window.ActivateSimilar
Win? ActivateSimilar(Win window, bool previous = false)
切换到同一程序的下一个(previous 为 true 时上一个)窗口并激活,返回该窗口;没有其他窗口返回 null。计 1 次激活操作。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
bool previous = false | 见本成员和所在域的说明。 |
返回类型:Win?。空值、用户取消和异常行为以成员及域说明为准。
Window.SetEdgeHide
bool SetEdgeHide(Win window, bool enabled = true, string edge = "auto")
贴边隐藏(由 Quicker 托管,脚本结束或停止后继续生效,需要撤销时显式 SetEdgeHide(window, false)):enabled 为 true 启用、false 停用;返回调用后的实际状态(是否启用)。启用时窗口置顶;停用时停在贴边处的可见位置并取消置顶(不还原原位置)。计 1 次排列操作。
| 参数声明 | 说明 |
|---|---|
Win window | 见本成员和所在域的说明。 |
bool enabled = true | 见本成员和所在域的说明。 |
string edge = "auto" | auto|left|top|right|bottom;已启用时再次启用不改变贴靠的边。 取值:auto、left、top、right、bottom。 |
返回类型:bool。空值、用户取消和异常行为以成员及域说明为准。