doc ready and add QPrivateSignal to activated

This commit is contained in:
Skycoder42
2016-02-08 15:33:52 +01:00
parent c6da3ca9c0
commit 3c40d30190
6 changed files with 177 additions and 27 deletions
+7 -10
View File
@@ -34,11 +34,6 @@ QHotkey::~QHotkey()
QHotkeyPrivate::instance()->removeShortcut(this); QHotkeyPrivate::instance()->removeShortcut(this);
} }
bool QHotkey::isKeyCaptured(Qt::Key key, Qt::KeyboardModifiers modifiers)
{
return QHotkeyPrivate::instance()->hasShortcut(key, modifiers);
}
QKeySequence QHotkey::shortcut() const QKeySequence QHotkey::shortcut() const
{ {
if(this->key == Qt::Key_unknown) if(this->key == Qt::Key_unknown)
@@ -86,6 +81,13 @@ bool QHotkey::setShortcut(Qt::Key key, Qt::KeyboardModifiers modifiers, bool aut
return false; 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->key = key;
this->mods = modifiers; this->mods = modifiers;
this->nativeShortcut = QHotkeyPrivate::instance()->nativeShortcut(key, modifiers); this->nativeShortcut = QHotkeyPrivate::instance()->nativeShortcut(key, modifiers);
@@ -163,11 +165,6 @@ QHotkey::NativeShortcut QHotkeyPrivate::nativeShortcut(Qt::Key keycode, Qt::Keyb
return res; return res;
} }
bool QHotkeyPrivate::hasShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers)
{
return this->shortcuts.contains(this->nativeShortcut(keycode, modifiers));
}
bool QHotkeyPrivate::addShortcut(QHotkey *hotkey) bool QHotkeyPrivate::addShortcut(QHotkey *hotkey)
{ {
if(hotkey->registered) if(hotkey->registered)
+8 -11
View File
@@ -24,22 +24,19 @@ public:
//! Constructor //! Constructor
explicit QHotkey(QObject *parent = 0); explicit QHotkey(QObject *parent = 0);
//! Constructs a hotkey with a shortcut and optionally registers it //! 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 //! 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 //! Destructor
~QHotkey(); ~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 //! READ-Accessor for QHotkey::registered
bool isRegistered() const; bool isRegistered() const;
//! READ-Accessor for QHotkey::shortcut //! READ-Accessor for QHotkey::shortcut - the key and modifiers as a QKeySequence
QKeySequence shortcut() const; QKeySequence shortcut() const;
//! The key-code of the current shortcut //! READ-Accessor for QHotkey::shortcut - the key only
Qt::Key keyCode() const; Qt::Key keyCode() const;
//! The modifiers of the current shortcut //! READ-Accessor for QHotkey::shortcut - the modifiers only
Qt::KeyboardModifiers modifiers() const; Qt::KeyboardModifiers modifiers() const;
public slots: public slots:
@@ -47,15 +44,15 @@ public slots:
bool setRegistered(bool registered); bool setRegistered(bool registered);
//! WRITE-Accessor for QHotkey::shortcut //! 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 //! 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 //! RESET-Accessor for QHotkey::shortcut
bool resetShortcut(); bool resetShortcut();
signals: signals:
//! Will be emitted if the shortcut is pressed //! Will be emitted if the shortcut is pressed
void activated(); void activated(QPrivateSignal);
//! NOTIFY-Accessor for QHotkey::registered //! NOTIFY-Accessor for QHotkey::registered
void registeredChanged(bool registered); void registeredChanged(bool registered);
-2
View File
@@ -20,8 +20,6 @@ public:
QHotkey::NativeShortcut nativeShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers); QHotkey::NativeShortcut nativeShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers);
bool hasShortcut(Qt::Key keycode, Qt::KeyboardModifiers modifiers);
bool addShortcut(QHotkey *hotkey); bool addShortcut(QHotkey *hotkey);
bool removeShortcut(QHotkey *hotkey); bool removeShortcut(QHotkey *hotkey);
+2 -1
View File
@@ -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`. 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 ## Technical
### Requirements ### Requirements
@@ -69,6 +69,7 @@ For you this means: QHotkey instances on other threads than the main thread may
- C++11 - C++11
### Known Limitations ### 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. - 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. - 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. - 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.
+154
View File
@@ -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{
<b>shortcut()</b><br/>
keyCode()<br/>
modifiers()
}
@writeAc{
<b>setShortcut(const QKeySequence &, bool)</b><br/>
setShortcut(Qt::Key, Qt::KeyboardModifiers, bool)
}
}
@sa QHotkey::registered, QHotkey::isKeyCaptured
*/
/*!
@typedef QHotkey::NativeShortcut
<table>
<tr>
<th>Member</th>
<th>Details</th>
</tr>
<tr>
<td>first</td>
<td>The keycode of the key to be pressed</td>
</tr>
<tr>
<td>second</td>
<td>The modifiers that have to be pressed together with the key</td>
</tr>
</table>
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.
*/
+5 -2
View File
@@ -252,7 +252,10 @@ ALIASES = "accessors{1}=<table><tr><th colspan= 2>Accessors</th><
"constantAc=<tr><td colspan= 2><b>CONSTANT</b></td></tr>" \ "constantAc=<tr><td colspan= 2><b>CONSTANT</b></td></tr>" \
"finalAc=<tr><td colspan= 2><b>FINAL</b></td></tr>" \ "finalAc=<tr><td colspan= 2><b>FINAL</b></td></tr>" \
"default{1}=<b>Default:</b> \1 <br>" \ "default{1}=<b>Default:</b> \1 <br>" \
"overload=<i>This is an overloaded function.</i>" overloads{1}=<b>Overloads:</b><ul>\1</ul> \
ovElem{1}=<li>\1</li> \
"overload=<i>This is an overloaded function.</i>" \
"povElem{1}=<li>\1 <i>(primary, check for more details)</i></li>"
# This tag can be used to specify a number of word-keyword mappings (TCL only). # 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" # 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. # all members of a group must be documented explicitly.
# The default value is: NO. # 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 # 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 # any nested class or struct is added to the same group. By default this option