QHotkey

Introduction to QHotkey

QHotkey is a versatile class designed for Qt desktop applications, providing the ability to establish global shortcuts, also known as hotkeys. These hotkeys are functional across the board, regardless of the application's state—whether active, inactive, minimized, or invisible.

Key Features of QHotkey

• Cross-platform Compatibility: Works on Windows, Mac, and X11, with the current exception of Wayland.
• Ease of Use: Utilizes QKeySequence, making shortcut creation intuitive and straightforward.
• Comprehensive Key Support: Compatible with nearly all common keys, though support depends on the operating system and keyboard layout.
• Flexible Input: Facilitates direct entry of key and modifier combinations.
• Optimized Handling: Supports multiple QHotkey instances for the same shortcut with enhanced efficiency.
• Thread Safety: Thread-safe design allows use of QHotkey in all threads.
• Native Codes and Modifiers: Enables use of native keycodes if necessary.

Building QHotkey

QHotkey supports both Qt5 and Qt6, with a requirement for version 6.2.0 or later if using Qt6. It employs the CMake build system, with the QT_DEFAULT_MAJOR_VERSION variable determining which Qt version is used.

Steps to Build with CMake

$ cd QHotkey
$ cmake -B build -S . -DQT_DEFAULT_MAJOR_VERSION=6
$ cmake --build build
# cmake --install build

To include the example application, include the -DQHOTKEY_EXAMPLES=ON flag.

Installation Options

Preferred Method: qpmx

1. Install qpmx and qpm by following the instructions on their respective GitHub pages.
2. Run qpmx install de.skycoder42.qhotkey in your project root.

Alternative Method: qpm

1. Install qpm, as instructed on GitHub.
2. Execute qpm install de.skycoder42.qhotkey in your project root.
3. Include qpm in your project by adding include(vendor/vendor.pri) to your .pro file.

Important for Windows Users: If using QPM version 0.10.0 (available on the website), download the latest dev build for a working version on Windows.

Usage and Example

The primary use of QHotkey is to create instances for specific hotkeys, register them, and connect them to signals when activated. For instance, a background application can be created that terminates upon pressing Ctrl+Alt+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();
}

Testing and Logging

The QHotkey package includes a testing application HotkeyTest to explore its features:

• Playground: Test with different sequences.
• Testings: Evaluate pre-selected hotkeys.
• Threading: Experiment with hotkeys on separate threads.
• Native Shortcut: Explore native shortcut functionality.

For logging, QHotkey categorizes messages under "QHotkey". To suppress warnings, you can adjust the logging settings accordingly.

Thread Safety Considerations

QHotkey is reentrant, supporting multiple instances across various threads thanks to an internal singleton managing hotkey events. It is crucial that instances be unregistered or destroyed on supporting threads before exiting the main event loop to avoid hangups.

Documentation

Comprehensive documentation is provided via GitHub Pages, created with Doxygen, including Qt-help files for integration with QtCreator.

Technical Requirements and Limitations

• Requires at least the QtGui module; console-based applications are unsupported.
• Supports single key/modifier combinations only.
• Known limitations include minor discrepancies in key support across platforms and lack of numpad specificity without native shortcuts.
• Registering hotkeys claims them from other applications, as controlled by operating systems.

QHotkey is a robust, adaptable tool for implementing global shortcuts in Qt desktop applications, ensuring seamless functionality across diverse environments and configurations.