diff --git a/QHotkey/qhotkey.cpp b/QHotkey/qhotkey.cpp index 1a141fb..55f74df 100644 --- a/QHotkey/qhotkey.cpp +++ b/QHotkey/qhotkey.cpp @@ -34,11 +34,6 @@ QHotkey::~QHotkey() QHotkeyPrivate::instance()->removeShortcut(this); } -bool QHotkey::isKeyCaptured(Qt::Key key, Qt::KeyboardModifiers modifiers) -{ - return QHotkeyPrivate::instance()->hasShortcut(key, modifiers); -} - QKeySequence QHotkey::shortcut() const { if(this->key == Qt::Key_unknown) @@ -86,6 +81,13 @@ bool QHotkey::setShortcut(Qt::Key key, Qt::KeyboardModifiers modifiers, bool aut return false; } + if(key == Qt::Key_unknown) { + this->key = Qt::Key_unknown; + this->mods = Qt::NoModifier; + this->nativeShortcut = NativeShortcut(); + return true; + } + this->key = key; this->mods = modifiers; this->nativeShortcut = QHotkeyPrivate::instance()->nativeShortcut(key, modifiers); @@ -163,11 +165,6 @@ QHotkey::NativeShortcut QHotkeyPrivate::nativeShortcut(Qt::Key keycode, Qt::Keyb return res; } -bool QHotkeyPrivate::hasShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers) -{ - return this->shortcuts.contains(this->nativeShortcut(keycode, modifiers)); -} - bool QHotkeyPrivate::addShortcut(QHotkey *hotkey) { if(hotkey->registered) diff --git a/QHotkey/qhotkey.h b/QHotkey/qhotkey.h index c74e987..3f92d77 100644 --- a/QHotkey/qhotkey.h +++ b/QHotkey/qhotkey.h @@ -24,22 +24,19 @@ public: //! Constructor explicit QHotkey(QObject *parent = 0); //! Constructs a hotkey with a shortcut and optionally registers it - explicit QHotkey(const QKeySequence &shortcut, bool autoRegister = true, QObject *parent = 0); + explicit QHotkey(const QKeySequence &shortcut, bool autoRegister = false, QObject *parent = 0); //! Constructs a hotkey with a key and modifiers and optionally registers it - explicit QHotkey(Qt::Key key, Qt::KeyboardModifiers modifiers, bool autoRegister = true, QObject *parent = 0); + explicit QHotkey(Qt::Key key, Qt::KeyboardModifiers modifiers, bool autoRegister = false, QObject *parent = 0); //! Destructor ~QHotkey(); - //! Test if a certain key with modifiers is currently registered somewhere or not - static bool isKeyCaptured(Qt::Key key, Qt::KeyboardModifiers modifiers); - //! READ-Accessor for QHotkey::registered bool isRegistered() const; - //! READ-Accessor for QHotkey::shortcut + //! READ-Accessor for QHotkey::shortcut - the key and modifiers as a QKeySequence QKeySequence shortcut() const; - //! The key-code of the current shortcut + //! READ-Accessor for QHotkey::shortcut - the key only Qt::Key keyCode() const; - //! The modifiers of the current shortcut + //! READ-Accessor for QHotkey::shortcut - the modifiers only Qt::KeyboardModifiers modifiers() const; public slots: @@ -47,15 +44,15 @@ public slots: bool setRegistered(bool registered); //! WRITE-Accessor for QHotkey::shortcut - bool setShortcut(const QKeySequence& shortcut, bool autoRegister = true); + bool setShortcut(const QKeySequence &shortcut, bool autoRegister = false); //! WRITE-Accessor for QHotkey::shortcut - bool setShortcut(Qt::Key key, Qt::KeyboardModifiers modifiers, bool autoRegister = true); + bool setShortcut(Qt::Key key, Qt::KeyboardModifiers modifiers, bool autoRegister = false); //! RESET-Accessor for QHotkey::shortcut bool resetShortcut(); signals: //! Will be emitted if the shortcut is pressed - void activated(); + void activated(QPrivateSignal); //! NOTIFY-Accessor for QHotkey::registered void registeredChanged(bool registered); diff --git a/QHotkey/qhotkey_p.h b/QHotkey/qhotkey_p.h index 7d49163..12e7349 100644 --- a/QHotkey/qhotkey_p.h +++ b/QHotkey/qhotkey_p.h @@ -20,8 +20,6 @@ public: QHotkey::NativeShortcut nativeShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers); - bool hasShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers); - bool addShortcut(QHotkey *hotkey); bool removeShortcut(QHotkey *hotkey); diff --git a/README.md b/README.md index dde3712..7bc29ba 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ The QHotkey class itself is reentrant - wich means you can create as many instan However, this singleton instance only runs on the main thread. (One reason is that some of the OS-Functions are not thread safe). To make threaded hotkeys possible, the critical functions (registering/unregistering hotkeys and keytranslation) are all run on the mainthread too. The QHotkey instances on other threads use `QMetaObject::invokeMethod` with a `Qt::BlockingQueuedConnection`. -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. +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. ## Technical ### Requirements @@ -69,6 +69,7 @@ For you this means: QHotkey instances on other threads than the main thread may - 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. - 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. diff --git a/doc/qhotkey.dox b/doc/qhotkey.dox index e69de29..450defa 100644 --- a/doc/qhotkey.dox +++ b/doc/qhotkey.dox @@ -0,0 +1,154 @@ +/*! +@class QHotkey + +Each instance of QHotkey represents one shortcut, i.e. one key + modifiers. These shortcuts, once registered, will be activated if the +user presses that combination - no matter in which application he currently is. + +For more details and an example, check the main page. + +@sa @ref index "Mainpage" +*/ + +/*! +@property QHotkey::registered + +@default{`false`} + +If a hotkey is registered, this means that it is set active in the OS and hotkey events will be send to the application. +If it is registered and the keys are pressed, the activated() signal will be emitted. + +@warning Registering/Unregistering hotkeys on other threads but the main thread is allowed, but will block the calling +thread until the applications eventloop has the time to handle it. If the loop is not running, the function will block until +it does. This does not happen if used from the main thread. + +@accessors{ + @readAc{isRegistered()} + @writeAc{setRegistered()} + @notifyAc{registeredChanged()} +} + +In addition to the normal accessors, a modification of the QHotkey::shortcut property can change this property, too. + +@sa QHotkey::shortcut, QHotkey::activated, QHotkey::isKeyCaptured +*/ + +/*! +@property QHotkey::shortcut + +@default{`QKeySequence()` (`Qt::Key_unknown` + `Qt::NoModifier`)} + +Holds the shortcut this hotkey will be registered on. It can be used as QKeySequence or as a combination of +a Qt::Key and Qt::KeyboardModifiers. All write-accessors specifiy an additional parameter to immediatly register +the hotkey. + +@note Since the operating systems do not support hotkeys that consist of multiple key-combinations in a sequence, +only the first key/modifier combination of a QKeySequence will be used. + +@warning changing the shortcut on other threads but the main thread is allowed, but will block the calling +thread until the applications eventloop has the time to handle it. If the loop is not running, the function will block until +it does. This does not happen if used from the main thread. + +@accessors{ + @readAc{ + shortcut()
+ keyCode()
+ modifiers() + } + @writeAc{ + setShortcut(const QKeySequence &, bool)
+ setShortcut(Qt::Key, Qt::KeyboardModifiers, bool) + } +} + +@sa QHotkey::registered, QHotkey::isKeyCaptured +*/ + +/*! +@typedef QHotkey::NativeShortcut + + + + + + + + + + + + + + +
MemberDetails
firstThe keycode of the key to be pressed
secondThe modifiers that have to be pressed together with the key
+ +The NativeShortcut is used internally only and holds the native keycode and modifiers, after they have been translated +from Qt::Key and Qt::Modifiers into the native ones. +*/ + +/*! +@fn QHotkey::QHotkey(QObject *) + +@overload +@param parent The parent object + +@overloads{ + @povElem{QHotkey::QHotkey(QObject *)} + @ovElem{QHotkey::QHotkey(const QKeySequence &, bool, QObject *)} + @ovElem{QHotkey::QHotkey(Qt::Key, Qt::KeyboardModifiers, bool, QObject *)} +} +*/ + +/*! +@fn QHotkey::QHotkey(const QKeySequence &, bool, QObject *) + +@overload +@param parent The parent object +@param shortcut The shortcut this hotkey should be registered for +@param autoRegister Specifies, whether the hotkey should be automatically registered or not + +@overloads{ + @povElem{QHotkey::QHotkey(QObject *)} + @ovElem{QHotkey::QHotkey(const QKeySequence &, bool, QObject *)} + @ovElem{QHotkey::QHotkey(Qt::Key, Qt::KeyboardModifiers, bool, QObject *)} +} + +@sa QHotkey::shortcut, QHotkey::registered +*/ + +/*! +@fn QHotkey::QHotkey(Qt::Key, Qt::KeyboardModifiers, bool, QObject *) + +@overload +@param parent The parent object +@param key The key this hotkey should be registered for +@param modifiers The modifiers that have to be pressed together with the `key` +@param autoRegister Specifies, whether the hotkey should be automatically registered or not + +@overloads{ + @povElem{QHotkey::QHotkey(QObject *)} + @ovElem{QHotkey::QHotkey(const QKeySequence &, bool, QObject *)} + @ovElem{QHotkey::QHotkey(Qt::Key, Qt::KeyboardModifiers, bool, QObject *)} +} + +@sa QHotkey::shortcut, QHotkey::registered +*/ + +/*! +@fn QHotkey::~QHotkey + +If the hotkey is still registered on destruction, it will automatically unregister itself. + +@warning If using a hotkey on a thread other than the main thread, make shure the QApplication is still running it's eventloop. +Otherwise your application will hang up. + +@sa QHotkey::registered +*/ + +/*! +@fn QHotkey::activated + +This signal can only be emitted if Hotkey::registered is set to true (with a valid key-sequence). The signal will always be emitted +from the thread this instance lives on. + +@note This is a private signal. It can be used in signal connections but cannot be emitted by the user. +*/ diff --git a/doc/qhotkey.doxy b/doc/qhotkey.doxy index abdb554..495c78f 100644 --- a/doc/qhotkey.doxy +++ b/doc/qhotkey.doxy @@ -251,8 +251,11 @@ ALIASES = "accessors{1}=< userAc{1}= \ "constantAc=" \ "finalAc=" \ - "default{1}=Default: \1
" \ - "overload=This is an overloaded function." + "default{1}=Default: \1
" \ + overloads{1}=Overloads: \ + ovElem{1}=
  • \1
  • \ + "overload=This is an overloaded function." \ + "povElem{1}=
  • \1 (primary, check for more details)
  • " # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" @@ -365,7 +368,7 @@ IDL_PROPERTY_SUPPORT = YES # all members of a group must be documented explicitly. # The default value is: NO. -DISTRIBUTE_GROUP_DOC = YES +DISTRIBUTE_GROUP_DOC = NO # If one adds a struct or class to a group and this option is enabled, then also # any nested class or struct is added to the same group. By default this option
    Accessors
    USER\1
    CONSTANT
    FINAL