Long live QKeyCombination!

C++20 via P1120 is deprecating arithmetic operations between
unrelated enumeration types, and GCC 10 is already complaining.
Hence, these operations might become illegal in C++23 or C++26 at
the latest.

A case of this that affects Qt is in key combinations: a
QKeySequence can be constructed by summing / ORing modifiers and a
key, for instance:

  Qt::CTRL + Qt::Key_A
  Qt::SHIFT | Qt::CTRL | Qt::Key_G (recommended, see below)

The problem is that the modifiers and the key belong to different
enumerations (and there's 2 enumerations for the modifier, and one
for the key).

To solve this: add a dedicated class to represent a combination of
keys, and operators between those enumerations to build instances
of this class.

I would've simply defined operator|, but again docs and pre-existing
code use operator+ as well, so added both to at least tackle simple
cases (modifier + key).

Multiple modifiers create a problem: operator+ between them yields
int, not the corresponding flags type (because operator+ is not
overloaded for this use case):

  Qt::CTRL + Qt::SHIFT + Qt::Key_A
  \__________________/      /
          int              /
           \______________/
                  int

Not only this loses track of the datatypes involved, but it would
also then "add" the key (with NO warnings, now its int + enum, so
it's not mixing enums!) and yielding int again.

I don't want to special-case this; the point of the class is
that int is the wrong datatype. Everything works just fine when
using operator| instead:

  Qt::CTRL | Qt::SHIFT | Qt::Key_A
  \__________________/      /
      Qt::Modifiers        /
           \______________/
            QKeyCombination

So I'm defining operator+ so that the simple cases still work,
but also deprecating it.

Port some code around Qt to the new class. In certain cases,
it's a huge win for clarity. In some others, I've just added
the necessary casts to make it still compile without warnings,
without attempting refactorings.

[ChangeLog][QtCore][QKeyCombination] New class to represent
a combination of a key and zero or more modifiers, to be used
when defining shortcuts or similar.

[ChangeLog][Potentially Source-Incompatible Changes] A keyboard
modifier (such as Qt::CTRL, Qt::AltModifier, etc.) should be
combined with a key (such as Qt::Key_A, Qt::Key_F1, etc.) by using
operator|, not operator+.  The result is now an object of type
QKeyCombination, that stores the key and the modifiers.

Change-Id: I657a3a328232f059023fff69c5031ee31cc91dd6
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

5 files changed, 382 insertions, 0 deletions

diff --git a/src/corelib/global/qnamespace.h b/src/corelib/global/qnamespace.h
index a531bc627b..0c4b4fc8bf 100644
--- a/src/corelib/global/qnamespace.h
+++ b/src/corelib/global/qnamespace.h
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2020 Klaralvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -1094,6 +1095,8 @@ namespace Qt {
         ALT           = Qt::AltModifier,
         MODIFIER_MASK = KeyboardModifierMask,
     };
+    Q_DECLARE_FLAGS(Modifiers, Modifier)
+    Q_DECLARE_OPERATORS_FOR_FLAGS(Modifiers)
 
     enum ArrowType {
         NoArrow,
@@ -1785,6 +1788,9 @@ namespace Qt {
     Q_ENUM_NS(SortOrder)
     Q_ENUM_NS(CaseSensitivity)
     Q_FLAG_NS(MatchFlags)
+    Q_ENUM_NS(Modifier)
+    Q_FLAG_NS(Modifiers)
+    Q_ENUM_NS(KeyboardModifier)
     Q_FLAG_NS(KeyboardModifiers)
     Q_FLAG_NS(MouseButtons)
     Q_ENUM_NS(WindowType)
@@ -1863,6 +1869,156 @@ public:
     static bool activateCallbacks(Callback, void **);
 };
 
+class QKeyCombination
+{
+    int combination;
+
+public:
+    constexpr /* implicit */ QKeyCombination(Qt::Key key = Qt::Key_unknown) noexcept
+        : combination(int(key))
+    {}
+
+    constexpr explicit QKeyCombination(Qt::Modifiers modifiers, Qt::Key key = Qt::Key_unknown) noexcept
+        : combination(int(modifiers) | int(key))
+    {}
+
+    constexpr explicit QKeyCombination(Qt::KeyboardModifiers modifiers, Qt::Key key = Qt::Key_unknown) noexcept
+        : combination(int(modifiers) | int(key))
+    {}
+
+    constexpr Qt::KeyboardModifiers keyboardModifiers() const noexcept
+    {
+        return Qt::KeyboardModifiers(combination & Qt::KeyboardModifierMask);
+    }
+
+    constexpr Qt::Key key() const noexcept
+    {
+        return Qt::Key(combination & ~Qt::KeyboardModifierMask);
+    }
+
+    static constexpr QKeyCombination fromCombined(int combined)
+    {
+        QKeyCombination result;
+        result.combination = combined;
+        return result;
+    }
+
+    constexpr int toCombined() const noexcept
+    {
+        return combination;
+    }
+
+#if QT_DEPRECATED_SINCE(6, 0)
+    QT_DEPRECATED_VERSION_X(6, 0, "Use QKeyCombination instead of int")
+    constexpr /* implicit */ operator int() const noexcept
+    {
+        return combination;
+    }
+#endif
+
+    friend constexpr bool operator==(QKeyCombination lhs, QKeyCombination rhs) noexcept
+    {
+        return lhs.combination == rhs.combination;
+    }
+
+    friend constexpr bool operator!=(QKeyCombination lhs, QKeyCombination rhs) noexcept
+    {
+        return lhs.combination != rhs.combination;
+    }
+};
+
+Q_DECLARE_TYPEINFO(QKeyCombination, Q_MOVABLE_TYPE);
+
+constexpr QKeyCombination operator|(Qt::Modifier modifier, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+constexpr QKeyCombination operator|(Qt::Modifiers modifiers, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+constexpr QKeyCombination operator|(Qt::KeyboardModifier modifier, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+constexpr QKeyCombination operator|(Qt::KeyboardModifiers modifiers, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+constexpr QKeyCombination operator|(Qt::Key key, Qt::Modifier modifier) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+constexpr QKeyCombination operator|(Qt::Key key, Qt::Modifiers modifiers) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+constexpr QKeyCombination operator|(Qt::Key key, Qt::KeyboardModifier modifier) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+constexpr QKeyCombination operator|(Qt::Key key, Qt::KeyboardModifiers modifiers) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+#if QT_DEPRECATED_SINCE(6, 0)
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::Modifier modifier, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::Modifiers modifiers, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::KeyboardModifier modifier, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::KeyboardModifiers modifiers, Qt::Key key) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::Key key, Qt::Modifier modifier) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::Key key, Qt::Modifiers modifiers) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::Key key, Qt::KeyboardModifier modifier) noexcept
+{
+    return QKeyCombination(modifier, key);
+}
+
+QT_DEPRECATED_VERSION_X(6, 0, "Use operator| instead")
+constexpr QKeyCombination operator+(Qt::Key key, Qt::KeyboardModifiers modifiers) noexcept
+{
+    return QKeyCombination(modifiers, key);
+}
+#endif
+
 QT_END_NAMESPACE
 
 #endif // QNAMESPACE_H
diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 95a73c4439..b5d44cb1cb 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2020 Klaralvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com>
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -3246,3 +3247,201 @@
   \sa QLabel::picture()
   \sa QLabel::pixmap()
 */
+
+/*!
+  \class QKeyCombination
+  \inmodule QtCore
+  \since 6.0
+  \brief The QKeyCombination class stores a combination of a key with optional modifiers.
+
+  The QKeyCombination class can be used to represent a combination of a key
+  with zero or more keyboard modifiers.
+
+  \sa QKeySequence
+*/
+
+/*!
+  \fn QKeyCombination::QKeyCombination(Qt::Key key = Qt::Key_unknown) noexcept
+
+  Constructs a QKeyCombination object that represents the key \a key
+  and no modifiers.
+
+  \sa key()
+*/
+
+/*!
+  \fn QKeyCombination::QKeyCombination(Qt::Modifiers modifiers, Qt::Key key = Qt::Key_unknown) noexcept
+
+  Constructs a QKeyCombination object that represents the combination
+  of \a key with the modifiers \a modifiers.
+
+  \sa key(), keyboardModifiers()
+*/
+
+/*!
+  \fn QKeyCombination::QKeyCombination(Qt::KeyboardModifiers modifiers, Qt::Key key = Qt::Key_unknown) noexcept
+
+  Constructs a QKeyCombination object that represents the combination
+  of \a key with the modifiers \a modifiers.
+
+  \sa key(), keyboardModifiers()
+*/
+
+/*!
+  \fn Qt::KeyboardModifiers QKeyCombination::keyboardModifiers() const noexcept
+
+  Returns the keyboard modifiers represented by this QKeyCombination object.
+
+  \sa key()
+*/
+
+/*!
+  \fn Qt::Key QKeyCombination::key() const noexcept
+
+  Returns the key represented by this QKeyCombination object.
+
+  \sa keyboardModifiers()
+*/
+
+/*!
+  \fn QKeyCombination QKeyCombination::fromCombined(int combined)
+
+  Constructs a QKeyCombination object by extracting the key and the
+  modifiers out of \a combined, which must be the result of a bitwise
+  OR between a value of type Qt::Key and value of type
+  Qt::KeyboardModifiers. toCombined() can be used in order to produce
+  valid values for \a combined.
+
+  \sa toCombined()
+*/
+
+/*!
+  \fn int QKeyCombination::toCombined() const noexcept
+
+  Returns an integer value obtained by applying a bitwise OR between
+  the values of key() and keyboardModifiers() represented
+  by this object. A QKeyCombination object can be created from the
+  returned integer value by using fromCombined().
+
+  \sa fromCombined(), key(), keyboardModifiers()
+*/
+
+#if QT_DEPRECATED_SINCE(6, 0)
+/*!
+  \fn QKeyCombination::operator int() const noexcept
+  \obsolete
+
+  Use toCombined() instead.
+*/
+#endif
+
+/*!
+  \fn bool operator==(QKeyCombination lhs, QKeyCombination rhs) noexcept
+  \relates QKeyCombination
+
+  Returns \c true if \a lhs and \a rhs have the same combination
+  of key and modifiers, and \c false otherwise.
+*/
+
+/*!
+  \fn bool operator!=(QKeyCombination lhs, QKeyCombination rhs) noexcept
+  \relates QKeyCombination
+
+  Returns \c true if \a lhs and \a rhs have different combinations
+  of key and modifiers, otherwise \c false.
+*/
+
+/*!
+  \fn QKeyCombination operator|(Qt::Modifier modifier, Qt::Key key) noexcept
+  \fn QKeyCombination operator|(Qt::KeyboardModifier modifier, Qt::Key key) noexcept
+  \fn QKeyCombination operator|(Qt::Key key, Qt::Modifier modifier) noexcept
+  \fn QKeyCombination operator|(Qt::Key key, Qt::KeyboardModifier modifier) noexcept
+
+  \relates QKeyCombination
+
+  Returns a QKeyCombination object that represents the combination
+  of \a key with the modifier \a modifier.
+*/
+
+/*!
+  \fn QKeyCombination operator|(Qt::Modifiers modifiers, Qt::Key key) noexcept
+  \fn QKeyCombination operator|(Qt::KeyboardModifiers modifiers, Qt::Key key) noexcept
+  \fn QKeyCombination operator|(Qt::Key key, Qt::Modifiers modifiers) noexcept
+  \fn QKeyCombination operator|(Qt::Key key, Qt::KeyboardModifiers modifiers) noexcept
+
+  \relates QKeyCombination
+
+  Returns a QKeyCombination object that represents the combination
+  of \a key with the modifiers \a modifiers.
+*/
+
+/*!
+  \fn QKeyCombination operator+(Qt::Modifier modifier, Qt::Key key) noexcept
+  \fn QKeyCombination operator+(Qt::KeyboardModifier modifier, Qt::Key key) noexcept
+  \fn QKeyCombination operator+(Qt::Key key, Qt::Modifier modifier) noexcept
+  \fn QKeyCombination operator+(Qt::Key key, Qt::KeyboardModifier modifier) noexcept
+
+  \relates QKeyCombination
+  \obsolete
+
+  Use operator| instead.
+
+  Returns a QKeyCombination object that represents the combination
+  of \a key with the modifier \a modifier.
+*/
+
+/*!
+  \fn QKeyCombination operator+(Qt::Modifiers modifiers, Qt::Key key) noexcept
+  \fn QKeyCombination operator+(Qt::KeyboardModifiers modifiers, Qt::Key key) noexcept
+  \fn QKeyCombination operator+(Qt::Key key, Qt::Modifiers modifiers) noexcept
+  \fn QKeyCombination operator+(Qt::Key key, Qt::KeyboardModifiers modifiers) noexcept
+
+  \relates QKeyCombination
+  \obsolete
+
+  Use operator| instead.
+
+  Returns a QKeyCombination object that represents the combination
+  of \a key with the modifiers \a modifiers.
+*/
+
+/*!
+  \fn size_t qHash(QKeyCombination key, size_t seed = 0) noexcept
+  \relates QKeyCombination
+
+  Returns the hash value for the \a key, using \a seed to seed the calculation.
+*/
+
+#ifndef QT_NO_DEBUG_STREAM
+/*!
+  \fn QDebug operator<<(QDebug debug, QKeyCombination combination)
+  \relates QKeyCombination
+
+  Writes the combination \a combination into the debug object \a debug for
+  debugging purposes.
+
+  \sa {Debugging Techniques}
+*/
+#endif
+
+#ifndef QT_NO_DATASTREAM
+/*!
+  \fn QDataStream &operator<<(QDataStream &out, QKeyCombination combination)
+  \relates QKeyCombination
+
+  Writes the combination \a combination into the stream \a out.
+  Returns \a out.
+
+  \sa {Serializing Qt Data Types}
+*/
+
+/*!
+  \fn QDataStream &operator>>(QDataStream &in, QKeyCombination &combination)
+  \relates QKeyCombination
+
+  Reads the combination \a combination from the stream \a in.
+  Returns \a in.
+
+  \sa {Serializing Qt Data Types}
+*/
+#endif
diff --git a/src/corelib/io/qdebug.h b/src/corelib/io/qdebug.h
index 2463095743..b3787f9e78 100644
--- a/src/corelib/io/qdebug.h
+++ b/src/corelib/io/qdebug.h
@@ -446,6 +446,17 @@ inline QDebug operator<<(QDebug debug, const QFlags<T> &flags)
     return qt_QMetaEnum_flagDebugOperator_helper(debug, flags);
 }
 
+inline QDebug operator<<(QDebug debug, QKeyCombination combination)
+{
+    QDebugStateSaver saver(debug);
+    debug.nospace() << "QKeyCombination("
+                    << combination.keyboardModifiers()
+                    << ", "
+                    << combination.key()
+                    << ")";
+    return debug;
+}
+
 #ifdef Q_OS_MAC
 
 // We provide QDebug stream operators for commonly used Core Foundation
diff --git a/src/corelib/serialization/qdatastream.h b/src/corelib/serialization/qdatastream.h
index 19188c3d91..32ccf7d6cc 100644
--- a/src/corelib/serialization/qdatastream.h
+++ b/src/corelib/serialization/qdatastream.h
@@ -43,6 +43,7 @@
 #include <QtCore/qscopedpointer.h>
 #include <QtCore/qiodevicebase.h>
 #include <QtCore/qcontainerfwd.h>
+#include <QtCore/qnamespace.h>
 
 #ifdef Status
 #error qdatastream.h must be included before any header file that defines Status
@@ -510,6 +511,19 @@ inline QDataStreamIfHasOStreamOperators<T1, T2> operator<<(QDataStream& s, const
 }
 #endif
 
+inline QDataStream &operator>>(QDataStream &s, QKeyCombination &combination)
+{
+    int combined;
+    s >> combined;
+    combination = QKeyCombination::fromCombined(combined);
+    return s;
+}
+
+inline QDataStream &operator<<(QDataStream &s, QKeyCombination combination)
+{
+    return s << combination.toCombined();
+}
+
 #endif // QT_NO_DATASTREAM
 
 QT_END_NAMESPACE
diff --git a/src/corelib/tools/qhashfunctions.h b/src/corelib/tools/qhashfunctions.h
index 716b81e186..94c6e13b1c 100644
--- a/src/corelib/tools/qhashfunctions.h
+++ b/src/corelib/tools/qhashfunctions.h
@@ -162,6 +162,8 @@ inline Q_DECL_PURE_FUNCTION size_t qHash(const QString &key, size_t seed = 0) no
 #endif
 Q_CORE_EXPORT Q_DECL_PURE_FUNCTION size_t qHash(const QBitArray &key, size_t seed = 0) noexcept;
 Q_CORE_EXPORT Q_DECL_PURE_FUNCTION size_t qHash(QLatin1String key, size_t seed = 0) noexcept;
+Q_DECL_CONST_FUNCTION constexpr inline size_t qHash(QKeyCombination key, size_t seed = 0) noexcept
+{ return qHash(key.toCombined(), seed); }
 Q_CORE_EXPORT Q_DECL_PURE_FUNCTION uint qt_hash(QStringView key, uint chained = 0) noexcept;
 
 template<typename T> inline size_t qHash(const T &t, size_t seed)