Update README.md

This commit is contained in:
Felix Barz
2016-12-04 17:42:12 +01:00
committed by GitHub
parent 898e3b9b6d
commit 71534b3167
+8 -6
View File
@@ -10,9 +10,10 @@ The QHotkey is a class that can be used to create hotkeys/global shortcuts, aka
- Allows direct input of Key/Modifier-Combinations
- Supports multiple QHotkey-instances for the same shortcut (with optimisations)
- Thread-Safe - Can be used on all threads (See section Thread safety)
- Allows usage of native keycodes and modifiers, if needed
## Usage
Just copy the `./QHotkey` folder into you application and add the line `include(./QHotkey/qhotkey.pri)` to your .pro-file. This way all files and required libraries will automatically be added. Use `#include <QHotkey>` to access the class.
Just copy the repository into you application (preferebly by adding it as a git submodule) and add the line `include(./QHotkey/qhotkey.pri)` to your .pro-file. This way all files and required libraries will automatically be added. Use `#include <QHotkey>` to access the class.
### Example
The following example shows a simple application that will run without a window in the background until you press the key-combination <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Q</kbd> (<kbd>⌘</kbd>+<kbd>⌥</kbd>+<kbd>Q</kbd> on Mac). This will quit the application. The debug output will tell if the hotkey was successfully registered and that it was pressed.
@@ -40,10 +41,11 @@ int main(int argc, char *argv[])
**Note:** You need the .pri include for this to work.
### Testing
By running the example in `./HotkeyTest` you can test out the QHotkey class. There are 3 sections:
By running the example in `./HotkeyTest` you can test out the QHotkey class. There are 4 sections:
- **Playground:** You can enter some sequences here and try it out with different key combinations.
- **Testings:** A list of selected hotkeys. Activate it and try out which ones work for you (*Hint:* Depending on OS and keyboard layout, it's very possible that a few don't work).
- **Threading:** Activate the checkbox to move 2 Hotkeys of the playground to seperate threads. It should work without a difference.
- **Native Shortcut**: Allows you to try out the direct usage of native shortcuts
### Logging
By default, QHotkey prints some warning messages if something goes wrong (For example, a key that cannot be translated). All messages of QHotkey are grouped into the [QLoggingCategory](https://doc.qt.io/qt-5/qloggingcategory.html) `"QHotkey"`. If you want to simply disable the logging, call the folling function somewhere in your code:
@@ -60,18 +62,18 @@ However, this singleton instance only runs on the main thread. (One reason is th
For you this means: QHotkey instances on other threads than the main thread may take a little longer to register/unregister/translate hotkeys, because they have to wait for the main thread to do this for them. **Important:** there is however, one additional limitation that comes with that feature: QHotkey instances on other threads but the main thread *must* be unregistered or destroyed *before* the main eventloop ends. Otherwise, your application will hangup on destruction of the hotkey. This limitation does not apply for instances on the main thread. Furthermore, the same happens if you change the shortcut or register/unregister before the loop started, until it actually starts.
## Documentation
The documentation is available within the releases and on [github pages](https://skycoder42.github.io/QHotkey/).
The documentation is available as release and on [github pages](https://skycoder42.github.io/QHotkey/).
The documentation was created using [doxygen](http://www.doxygen.org). It includes an HTML-documentation and Qt-Help files that can be included into QtCreator (QtAssistant) to show F1-Help (See [Adding External Documentation](https://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation) for more details).
## Technical
### Requirements
- I built it with Qt 5.5.1, but may work with earlier versions, too
- I built it with Qt 5.7, but may work with earlier versions, too
- At least the QtGui-Module (a QGuiApplication). Hotkeys on console based applications are not supported. (By the operating systems)
- C++11
### Known Limitations
- Only single key/modifier combinations are possible. If using QKeySequence, only the first key+modifier of the sequence will be used.
- Qt::Key makes no difference between normal numbers and the Numpad numbers. Most keyboards however require this. Thus, you can't register shortcuts for the numpad.
- Supports not all keys, but most of the common ones. There are differences between platforms and it depends on the Keyboard-Layout. "Delete", for example, works on windows and mac, but not on X11 (At least on my test machines). I tried to use OS-Functions where possible, but since the Qt::Key values need to be converted into native keys, there are some limitations.
- Qt::Key makes no difference between normal numbers and the Numpad numbers. Most keyboards however require this. Thus, you can't register shortcuts for the numpad, unless you use a native shortcut.
- Supports not all keys, but most of the common ones. There are differences between platforms and it depends on the Keyboard-Layout. "Delete", for example, works on windows and mac, but not on X11 (At least on my test machines). I tried to use OS-Functions where possible, but since the Qt::Key values need to be converted into native keys, there are some limitations. I can use need such a key, try using the native shortcut
- The registered keys will be "taken" by QHotkey. This means after a hotkey was cosumend by your application, it will not be sent to the active application. This is done this way by the operating systems and cannot be changed.