强大而灵活的Qt应用全局热键库 —— QHotkey

【免费下载链接】QHotkey A global shortcut/hotkey for Desktop Qt-Applications 项目地址: https://gitcode.com/gh_mirrors/qh/QHotkey

在桌面应用程序开发中，全局热键（或快捷键）扮演着至关重要的角色，它们可以帮助用户快速执行特定操作，提高效率。QHotkey是一个专为Qt应用设计的开源库，支持Windows、Mac和X11系统，让开发者轻松创建即使在后台也能响应的全局热键。

项目简介

QHotkey库的核心特性在于其能够实现即使在应用程序不活动、最小化甚至不可见的情况下仍然可以捕捉到热键事件。这使得你的应用能随时随地对用户的指令作出反应，极大地提升了用户体验。

技术分析

QHotkey库基于C++编写，并兼容Qt5和Qt6框架。它提供了易于使用的API，可以直接利用Qt的QKeySequence来定义快捷键。库内包含了对大部分常见按键和修饰键的支持，并允许直接输入组合键。此外，QHotkey还支持同一快捷键的多个实例（已优化），以及线程安全的设计，可以在任何线程中安全地使用。

值得注意的是，虽然目前QHotkey不支持Wayland，但开发者正在寻找解决方案以实现在Wayland环境下的热键功能。

应用场景

QHotkey广泛适用于各种需要热键功能的应用场景：

• 快速打开或关闭程序
• 在多任务环境下切换应用功能
• 实时保存、撤销或重做等常用操作
• 控制音乐播放器或视频播放器的播放、暂停和音量调节

项目特点

1. 跨平台：支持Windows、Mac和X11操作系统
2. 易用性：采用QKeySequence进行快捷键设置，直观且方便
3. 全面覆盖：几乎支持所有常见键盘按键和修饰键
4. 多实例支持：允许多个QHotkey实例绑定相同的快捷键，无需担心冲突问题
5. 线程安全：可在任意线程中安全使用，确保程序稳定性
6. 文档丰富：提供详细的Doxygen和Qt-Help文件，便于开发者理解和集成

构建和安装

构建和安装QHotkey十分简单，通过CMake或qmake，结合qpm工具，你可以轻松地将这个库添加到自己的Qt项目中。QHotkey支持Qt6和Qt5，当使用Qt6时需要6.2.0或更高版本。

CMake构建

使用CMake构建系统，可以通过设置QT_DEFAULT_MAJOR_VERSION变量控制使用Qt的版本：

cd QHotkey
cmake -B build -S . -DQT_DEFAULT_MAJOR_VERSION=6
cmake --build build

通过qpmx安装

qpmx是qpm的前端工具，提供额外功能，是安装包的推荐方式：

1. 安装qpmx和qpm
2. 在项目根目录运行：qpmx install de.skycoder42.qhotkey

通过qpm安装

1. 安装qpm
2. 在项目根目录运行：qpm install de.skycoder42.qhotkey
3. 在.pro文件中添加：include(vendor/vendor.pri)

使用示例

QHotkey的使用非常简单，创建QHotkey实例并注册特定热键，然后连接到热键按下时发出的信号即可。

以下示例展示了创建一个在后台运行的应用，按下Ctrl+Alt+Q（Mac上为⌘+⌥+Q）组合键时退出应用：

#include <QHotkey>
#include <QApplication>
#include <QDebug>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QHotkey hotkey(QKeySequence("Ctrl+Alt+Q"), true, &app);
    qDebug() << "Is registered:" << hotkey.isRegistered();

    QObject::connect(&hotkey, &QHotkey::activated, qApp, [&](){
        qDebug() << "Hotkey Activated - the application will quit now";
        qApp->quit();
    });

    return app.exec();
}

测试应用

项目中包含测试应用QHotkeyTest，位于HotkeyTest目录，可以帮助开发者进行功能验证和调试。测试应用包含四个部分：

• Playground：可以输入序列并尝试不同的键组合
• Testings：预选的热键列表，测试哪些在你的系统上工作
• Threading：将热键移动到单独线程进行测试
• Native Shortcut：尝试直接使用原生快捷键

技术细节

线程安全性

QHotkey类本身是可重入的，可以在任何线程上创建任意数量的实例。但是，不应该在与实例所属线程不同的线程上使用QHotkey实例。内部系统使用单例实例处理热键事件并将其分发到QHotkey实例，这个内部类是完全线程安全的。

日志记录

默认情况下，QHotkey会在出现问题时打印一些警告消息。所有QHotkey消息都分组到"QHotkey"的QLoggingCategory中。要禁用日志记录，可以在代码中调用：

QLoggingCategory::setFilterRules(QStringLiteral("QHotkey.warning=false"));

已知限制

• 仅支持单键/修饰符组合
• Qt::Key不区分普通数字和小键盘数字
• 不支持所有键，但支持大多数常用键
• 注册的键将被QHotkey"占用"，不会发送到活动应用程序
• X11上某些私有键无法注册

许可证

QHotkey使用MIT许可证，允许自由使用、修改和分发。

总的来说，无论你是个人开发者还是团队成员，QHotkey都是一个值得尝试的高效工具，它能让你的应用具备专业级的快捷键体验。

【免费下载链接】QHotkey A global shortcut/hotkey for Desktop Qt-Applications 项目地址: https://gitcode.com/gh_mirrors/qh/QHotkey