Warning, file /frameworks/kguiaddons/src/util/kmodifierkeyinfo.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 /*
0002     SPDX-FileCopyrightText: 2009 Michael Leupold <lemma@confuego.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0005 */
0006 
0007 #ifndef KMODIFIERKEYINFO_H
0008 #define KMODIFIERKEYINFO_H
0009 
0010 #include <kguiaddons_export.h>
0011 
0012 #include <QExplicitlySharedDataPointer>
0013 #include <QObject>
0014 
0015 class KModifierKeyInfoProvider;
0016 
0017 /**
0018  * @class KModifierKeyInfo kmodifierkeyinfo.h KModifierKeyInfo
0019  *
0020  * Get information about the state of the keyboard's modifier keys.
0021  *
0022  * This class provides cross-platform information about the state of the
0023  * keyboard's modifier keys and the mouse buttons and allows to change the
0024  * state as well.
0025  *
0026  * It recognizes two states a key can be in:
0027  * @li @em locked: eg. caps-locked (a.k.a. toggled)
0028  * @li @em latched the key is temporarily locked but will be unlocked upon
0029  *                          the next keypress.
0030  *
0031  * An application can either query the states synchronously (isKeyLatched(),
0032  * isKeyLocked()) or connect to KModifierKeyInfo's signals to be notified about
0033  * changes (keyLatched(), keyLocked()).
0034  */
0035 class KGUIADDONS_EXPORT KModifierKeyInfo : public QObject
0036 {
0037     Q_OBJECT
0038 
0039 public:
0040     /**
0041      * Default constructor
0042      */
0043     explicit KModifierKeyInfo(QObject *parent = nullptr);
0044 
0045     /**
0046      * Destructor
0047      */
0048     ~KModifierKeyInfo() override;
0049 
0050     /**
0051      * Check if a key is known by the underlying window system and can be queried.
0052      *
0053      * @param key The key to check
0054      * @return true if the key is available, false if it is unknown
0055      */
0056     bool knowsKey(Qt::Key key) const;
0057 
0058     /**
0059      * Get a list of known keys.
0060      *
0061      * @return A list of known keys of which states will be reported.
0062      */
0063     const QList<Qt::Key> knownKeys() const;
0064 
0065     /**
0066      * Synchronously check if a key is pressed.
0067      *
0068      * @param key The key to check
0069      * @return true if the key is pressed, false if the key is not pressed or unknown.
0070      * @see isKeyLatched, @see isKeyLocked, @see keyPressed
0071      */
0072     bool isKeyPressed(Qt::Key key) const;
0073 
0074     /**
0075      * Synchronously check if a key is latched.
0076      *
0077      * @param key The key to check
0078      * @return true if the key is latched, false if the key is not latched or unknown.
0079      * @see isKeyPressed, @see isKeyLocked, @see keyLatched
0080      */
0081     bool isKeyLatched(Qt::Key key) const;
0082 
0083     /**
0084      * Set the latched state of a key.
0085      *
0086      * @param key The key to latch
0087      * @param latched true to latch the key, false to unlatch it.
0088      * @return false if the key is unknown. true doesn't guarantee you the
0089      *         operation worked.
0090      */
0091     bool setKeyLatched(Qt::Key key, bool latched);
0092 
0093     /**
0094      * Synchronously check if a key is locked.
0095      *
0096      * @param key The key to check
0097      * @return true if the key is locked, false if the key is not locked or unknown.
0098      * @see isKeyPressed, @see isKeyLatched, @see keyLocked
0099      */
0100     bool isKeyLocked(Qt::Key key) const;
0101 
0102     /**
0103      * Set the locked state of a key.
0104      *
0105      * @param key The key to lock
0106      * @param latched true to lock the key, false to unlock it.
0107      * @return false if the key is unknown. true doesn't guarantee you the
0108      *         operation worked.
0109      */
0110     bool setKeyLocked(Qt::Key key, bool locked);
0111 
0112     /**
0113      * Synchronously check if a mouse button is pressed.
0114      *
0115      * @param button The mouse button to check
0116      * @return true if the mouse button is pressed, false if the mouse button
0117      *         is not pressed or its state is unknown.
0118      */
0119     bool isButtonPressed(Qt::MouseButton button) const;
0120 
0121 Q_SIGNALS:
0122     /**
0123      * This signal is emitted whenever the pressed state of a key changes
0124      * (key press or key release).
0125      *
0126      * @param key The key that changed state
0127      * @param pressed true if the key is now pressed, false if is released.
0128      */
0129     void keyPressed(Qt::Key key, bool pressed);
0130 
0131     /**
0132      * This signal is emitted whenever the latched state of a key changes.
0133      *
0134      * @param key The key that changed state
0135      * @param latched true if the key is now latched, false if it isn't
0136      */
0137     void keyLatched(Qt::Key key, bool latched);
0138 
0139     /**
0140      * This signal is emitted whenever the locked state of a key changes.
0141      *
0142      * @param key The key that changed state
0143      * @param locked true if the key is now locked, false if it isn't
0144      */
0145     void keyLocked(Qt::Key key, bool locked);
0146 
0147     /**
0148      * This signal is emitted whenever the pressed state of a mouse button
0149      * changes (mouse button press or release).
0150      *
0151      * @param button The mouse button that changed state
0152      * @param pressed true if the mouse button is now pressed, false if
0153      *                is released.
0154      */
0155     void buttonPressed(Qt::MouseButton button, bool pressed);
0156 
0157     /**
0158      * This signal is emitted whenever a new modifier is found due to
0159      * the keyboard mapping changing.
0160      *
0161      * @param key The key that was discovered
0162      */
0163     void keyAdded(Qt::Key key);
0164 
0165     /**
0166      * This signal is emitted whenever a previously known modifier no
0167      * longer exists due to the keyboard mapping changing.
0168      *
0169      * @param key The key that vanished
0170      */
0171     void keyRemoved(Qt::Key key);
0172 
0173 private:
0174     Q_DISABLE_COPY(KModifierKeyInfo)
0175     QExplicitlySharedDataPointer<KModifierKeyInfoProvider> const p; // krazy:exclude=dpointer
0176 };
0177 
0178 #endif