File indexing completed on 2024-12-01 12:33:00

 /*
     SPDX-FileCopyrightText: 2009 Michael Leupold <lemma@confuego.org>
 
     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
 */
 
 #ifndef KMODIFIERKEYINFO_H
 #define KMODIFIERKEYINFO_H
 
 #include <kguiaddons_export.h>
 
 #include <QExplicitlySharedDataPointer>
 #include <QObject>
 
 class KModifierKeyInfoProvider;
 
 /**
  * @class KModifierKeyInfo kmodifierkeyinfo.h KModifierKeyInfo
  *
  * Get information about the state of the keyboard's modifier keys.
  *
  * This class provides cross-platform information about the state of the
  * keyboard's modifier keys and the mouse buttons and allows to change the
  * state as well.
  *
  * It recognizes two states a key can be in:
  * @li @em locked: eg. caps-locked (a.k.a. toggled)
  * @li @em latched the key is temporarily locked but will be unlocked upon
  *                          the next keypress.
  *
  * An application can either query the states synchronously (isKeyLatched(),
  * isKeyLocked()) or connect to KModifierKeyInfo's signals to be notified about
  * changes (keyLatched(), keyLocked()).
  */
 class KGUIADDONS_EXPORT KModifierKeyInfo : public QObject
 {
     Q_OBJECT
 
 public:
     /**
      * Default constructor
      */
     explicit KModifierKeyInfo(QObject *parent = nullptr);
 
     /**
      * Destructor
      */
     ~KModifierKeyInfo() override;
 
     /**
      * Check if a key is known by the underlying window system and can be queried.
      *
      * @param key The key to check
      * @return true if the key is available, false if it is unknown
      */
     bool knowsKey(Qt::Key key) const;
 
     /**
      * Get a list of known keys.
      *
      * @return A list of known keys of which states will be reported.
      */
     const QList<Qt::Key> knownKeys() const;
 
     /**
      * Synchronously check if a key is pressed.
      *
      * @param key The key to check
      * @return true if the key is pressed, false if the key is not pressed or unknown.
      * @see isKeyLatched, @see isKeyLocked, @see keyPressed
      */
     bool isKeyPressed(Qt::Key key) const;
 
     /**
      * Synchronously check if a key is latched.
      *
      * @param key The key to check
      * @return true if the key is latched, false if the key is not latched or unknown.
      * @see isKeyPressed, @see isKeyLocked, @see keyLatched
      */
     bool isKeyLatched(Qt::Key key) const;
 
     /**
      * Set the latched state of a key.
      *
      * @param key The key to latch
      * @param latched true to latch the key, false to unlatch it.
      * @return false if the key is unknown. true doesn't guarantee you the
      *         operation worked.
      */
     bool setKeyLatched(Qt::Key key, bool latched);
 
     /**
      * Synchronously check if a key is locked.
      *
      * @param key The key to check
      * @return true if the key is locked, false if the key is not locked or unknown.
      * @see isKeyPressed, @see isKeyLatched, @see keyLocked
      */
     bool isKeyLocked(Qt::Key key) const;
 
     /**
      * Set the locked state of a key.
      *
      * @param key The key to lock
      * @param latched true to lock the key, false to unlock it.
      * @return false if the key is unknown. true doesn't guarantee you the
      *         operation worked.
      */
     bool setKeyLocked(Qt::Key key, bool locked);
 
     /**
      * Synchronously check if a mouse button is pressed.
      *
      * @param button The mouse button to check
      * @return true if the mouse button is pressed, false if the mouse button
      *         is not pressed or its state is unknown.
      */
     bool isButtonPressed(Qt::MouseButton button) const;
 
 Q_SIGNALS:
     /**
      * This signal is emitted whenever the pressed state of a key changes
      * (key press or key release).
      *
      * @param key The key that changed state
      * @param pressed true if the key is now pressed, false if is released.
      */
     void keyPressed(Qt::Key key, bool pressed);
 
     /**
      * This signal is emitted whenever the latched state of a key changes.
      *
      * @param key The key that changed state
      * @param latched true if the key is now latched, false if it isn't
      */
     void keyLatched(Qt::Key key, bool latched);
 
     /**
      * This signal is emitted whenever the locked state of a key changes.
      *
      * @param key The key that changed state
      * @param locked true if the key is now locked, false if it isn't
      */
     void keyLocked(Qt::Key key, bool locked);
 
     /**
      * This signal is emitted whenever the pressed state of a mouse button
      * changes (mouse button press or release).
      *
      * @param button The mouse button that changed state
      * @param pressed true if the mouse button is now pressed, false if
      *                is released.
      */
     void buttonPressed(Qt::MouseButton button, bool pressed);
 
     /**
      * This signal is emitted whenever a new modifier is found due to
      * the keyboard mapping changing.
      *
      * @param key The key that was discovered
      */
     void keyAdded(Qt::Key key);
 
     /**
      * This signal is emitted whenever a previously known modifier no
      * longer exists due to the keyboard mapping changing.
      *
      * @param key The key that vanished
      */
     void keyRemoved(Qt::Key key);
 
 private:
     Q_DISABLE_COPY(KModifierKeyInfo)
     QExplicitlySharedDataPointer<KModifierKeyInfoProvider> const p; // krazy:exclude=dpointer
 };
 
 #endif