Pywayne Gui

Windows GUI automation toolkit for global hotkeys and window management. Use when users need to register global hotkeys, find/control windows, automate GUI operations, or perform Windows desktop automation. Requires Windows OS with pywin32, pyuserinput, and pyautogui dependencies.

Windows 图形用户界面自动化工具，提供全局热键监听和窗口操作功能。

Quick Start

python

from pywayne.gui import GlobalHotKeys, GuiOperation

# 全局热键
g = GlobalHotKeys()

@g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_SHIFT)
def shift_f1():
    print('Shift+F1 被按下')

# 启动监听（按 Q 或 Ctrl+C 退出）
GlobalHotKeys.listen()

Dependencies

包	用途	安装命令
pywin32	Windows API 封装	pip install pywin32
pyuserinput	键盘鼠标输入	pip install pyuserinput
pyautogui	GUI 自动化	pip install pyautogui

GlobalHotKeys - 全局热键

注册全局热键，在全局范围内监听键盘事件。

注册热键

python

from pywayne.gui import GlobalHotKeys

g = GlobalHotKeys()

# 装饰器方式注册
@g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_SHIFT)
def shift_f1():
    print('Shift+F1')

# 组合键修饰符（支持组合使用）
g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_CTRL | GlobalHotKeys.MOD_SHIFT)

# 直接调用 register 方法
def handler():
    print('Ctrl+A 被按下')
GlobalHotKeys.register(GlobalHotKeys.VK_A, GlobalHotKeys.MOD_CTRL, handler)

启动监听

python

# 启动消息循环，开始监听热键
GlobalHotKeys.listen()

停止条件

按以下任意组合键会停止监听循环：

• Q 键
• Ctrl + C

虚拟键码

常用虚拟键码（VK_*）：

按键	键码	组合键
A-Z	VK_A 到 VK_Z	ord('A') 到 ord('Z')
0-9	VK_0 到 VK_9	ord('0') 到 ord('9')
F1-F12	VK_F1 到 VK_F12	-

修饰键（MOD_*）：

修饰键	常量
Alt	MOD_ALT
Ctrl	MOD_CTRL
Shift	MOD_SHIFT
Win	MOD_WIN

修饰键可使用 | 组合，如 MOD_CTRL | MOD_SHIFT。

GuiOperation - 窗口操作

提供 Windows 窗口查找、控制和操作功能。

初始化

python

from pywayne.gui import GuiOperation

gui = GuiOperation()

find_window

查找包含指定关键字的窗口，返回窗口句柄列表。

python

# 查找包含"记事本"的窗口
notepad_handles = gui.find_window('记事本')

# 查找包含"微信"的窗口
wechat_handles = gui.find_window('微信')

# 多关键字匹配
handles = gui.find_window('Visual', 'Studio')

参数说明：

• *keys: 按关键字匹配窗口标题

返回值：

• 匹配的窗口句柄列表（hwnd）
• 未找到时返回空列表

get_windows_attr

获取指定窗口的属性信息。

python

hwnd = gui.find_window('记事本')[0]
title, class_name = gui.get_windows_attr(hwnd)
print(f"窗口标题: {title}")
print(f"窗口类名: {class_name}")

返回值：

• 找到窗口：(窗口标题, 窗口类名)
• 窗口不存在：('', '')

maximize_window

将指定窗口最大化。

python

hwnd = gui.find_window('记事本')[0]
gui.maximize_window(hwnd)

bring_to_top

将指定窗口置于顶层。

python

hwnd = gui.find_window('记事本')[0]
gui.bring_to_top(hwnd)

close_window

关闭指定窗口。

python

hwnd = gui.find_window('记事本')[0]
gui.close_window(hwnd)

change_window_name

修改指定窗口的标题。

python

hwnd = gui.find_window('记事本')[0]
gui.change_window_name(hwnd, '新标题')

get_window_rect

获取窗口的矩形坐标。

python

hwnd = gui.find_window('记事本')[0]
rect = gui.get_window_rect(hwnd)
print(f"窗口位置: {rect}")

返回值：(left, top, right, bottom)

get_child_windows

获取指定窗口的子窗口列表。

python

hwnd = gui.find_window('记事本')[0]
children = gui.get_child_windows(hwnd)
print(f"子窗口数量: {len(children)}")

使用示例

示例 1：热键自动化

python

from pywayne.gui import GlobalHotKeys

g = GlobalHotKeys()

@g.register(GlobalHotKeys.VK_F10, GlobalHotKeys.MOD_SHIFT)
def screenshot_hotkey():
    print('截图热键被触发')
    # 执行截图逻辑...

@g.register(GlobalHotKeys.VK_Q, GlobalHotKeys.MOD_CTRL)
def copy_hotkey():
    print('复制热键被触发')
    # 执行复制逻辑...

GlobalHotKeys.listen()

示例 2：窗口自动化

python

from pywayne.gui import GuiOperation
import time

gui = GuiOperation()

# 查找记事本窗口
notepad = gui.find_window('记事本')
if notepad:
    print('未找到记事本')
    exit()

# 置顶并最大化
gui.bring_to_top(notepad[0])
time.sleep(0.5)
gui.maximize_window(notepad[0])

# 修改窗口标题
gui.change_window_name(notepad[0], '自动化控制中...')

示例 3：综合自动化

python

from pywayne.gui import GuiOperation, GlobalHotKeys
from pywayne.gui import PyMouse, PyKeyboard

gui = GuiOperation()
g = GlobalHotKeys()

@g.register(GlobalHotKeys.VK_F1, GlobalHotKeys.MOD_SHIFT)
def auto_test():
    # 查找测试软件窗口
    st_window = gui.find_window('ST测试软件')
    if not st_window:
        return

    st_hwnd = st_window[0]
    gui.bring_to_top(st_hwnd)

    # 获取子窗口
    for child in gui.get_child_windows(st_hwnd):
        title, cls = gui.get_windows_attr(child)
        print(f'子窗口: {title}')

    # 操作完成后关闭
    gui.close_window(st_hwnd)

GlobalHotKeys.listen()

注意事项

1. 平台限制: 本模块仅支持 Windows 系统
2. 依赖安装: 使用前需确保已安装 pywin32、pyuserinput、pyautogui
3. 管理员权限: 某些操作可能需要管理员权限
4. 窗口状态: 查找和操作仅对可见且启用的窗口有效
5. 热键冲突: 注册的热键可能与其他软件冲突