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>

7 files changed, 338 insertions, 2 deletions

diff --git a/tests/auto/corelib/global/CMakeLists.txt b/tests/auto/corelib/global/CMakeLists.txt
index 29c696e121..4dab15eaab 100644
--- a/tests/auto/corelib/global/CMakeLists.txt
+++ b/tests/auto/corelib/global/CMakeLists.txt
@@ -11,6 +11,7 @@ add_subdirectory(qlogging)
 add_subdirectory(qtendian)
 add_subdirectory(qglobalstatic)
 add_subdirectory(qhooks)
+add_subdirectory(qkeycombination)
 if(WIN32)
     add_subdirectory(qwinregistry)
 endif()
diff --git a/tests/auto/corelib/global/global.pro b/tests/auto/corelib/global/global.pro
index 8af353728d..f3d1bbaaf5 100644
--- a/tests/auto/corelib/global/global.pro
+++ b/tests/auto/corelib/global/global.pro
@@ -6,6 +6,7 @@ SUBDIRS=\
     qglobal \
     qnumeric \
     qfloat16 \
+    qkeycombination \
     qrandomgenerator \
     qlogging \
     qtendian \
diff --git a/tests/auto/corelib/global/qkeycombination/.gitignore b/tests/auto/corelib/global/qkeycombination/.gitignore
new file mode 100644
index 0000000000..9ce23dd85c
--- /dev/null
+++ b/tests/auto/corelib/global/qkeycombination/.gitignore
@@ -0,0 +1 @@
+tst_qkeycombination
diff --git a/tests/auto/corelib/global/qkeycombination/CMakeLists.txt b/tests/auto/corelib/global/qkeycombination/CMakeLists.txt
new file mode 100644
index 0000000000..894e1e973f
--- /dev/null
+++ b/tests/auto/corelib/global/qkeycombination/CMakeLists.txt
@@ -0,0 +1,10 @@
+# Generated from qkeycombination.pro.
+
+#####################################################################
+## tst_qkeycombination Test:
+#####################################################################
+
+qt_add_test(tst_qkeycombination
+    SOURCES
+        tst_qkeycombination.cpp
+)
diff --git a/tests/auto/corelib/global/qkeycombination/qkeycombination.pro b/tests/auto/corelib/global/qkeycombination/qkeycombination.pro
new file mode 100644
index 0000000000..e2dd431055
--- /dev/null
+++ b/tests/auto/corelib/global/qkeycombination/qkeycombination.pro
@@ -0,0 +1,5 @@
+CONFIG += testcase
+TARGET = tst_qkeycombination
+QT = core testlib
+SOURCES = tst_qkeycombination.cpp
+
diff --git a/tests/auto/corelib/global/qkeycombination/tst_qkeycombination.cpp b/tests/auto/corelib/global/qkeycombination/tst_qkeycombination.cpp
new file mode 100644
index 0000000000..7e70cdb70f
--- /dev/null
+++ b/tests/auto/corelib/global/qkeycombination/tst_qkeycombination.cpp
@@ -0,0 +1,317 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 Klarälvdalens 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 test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL-EXCEPT$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 as published by the Free Software
+** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QObject>
+#include <QTest>
+
+class tst_QKeyCombination : public QObject
+{
+    Q_OBJECT
+private slots:
+    void construction();
+    void operator_eq();
+    void operator_or();
+};
+
+constexpr int bitwiseOr()
+{
+    return 0;
+}
+
+template <typename ...T>
+constexpr auto bitwiseOr(T ... args)
+{
+    return (... | ((int)args));
+}
+
+void tst_QKeyCombination::construction()
+{
+    {
+        QKeyCombination combination;
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers{});
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::Key_unknown));
+    }
+
+    {
+        QKeyCombination combination(Qt::CTRL); // explicit
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::ControlModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::ControlModifier, Qt::Key_unknown));
+    }
+
+    {
+        QKeyCombination combination(Qt::SHIFT); // explicit
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::ShiftModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::ShiftModifier, Qt::Key_unknown));
+    }
+
+    {
+        QKeyCombination combination(Qt::AltModifier); // explicit
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::AltModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::AltModifier, Qt::Key_unknown));
+    }
+
+    {
+        QKeyCombination combination(Qt::AltModifier | Qt::ControlModifier); // explicit
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::AltModifier | Qt::ControlModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::AltModifier, Qt::ControlModifier, Qt::Key_unknown));
+    }
+
+    {
+        QKeyCombination combination = Qt::Key_A; // implicit
+        QCOMPARE(combination.key(), Qt::Key_A);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers{});
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::Key_A));
+    }
+
+    {
+        QKeyCombination combination = Qt::Key_F1; // implicit
+        QCOMPARE(combination.key(), Qt::Key_F1);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers{});
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::Key_F1));
+    }
+
+    {
+        QKeyCombination combination(Qt::SHIFT, Qt::Key_F1);
+        QCOMPARE(combination.key(), Qt::Key_F1);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::ShiftModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::SHIFT, Qt::Key_F1));
+    }
+
+    {
+        QKeyCombination combination(Qt::SHIFT | Qt::CTRL, Qt::Key_F1);
+        QCOMPARE(combination.key(), Qt::Key_F1);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::ShiftModifier | Qt::ControlModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::SHIFT, Qt::CTRL, Qt::Key_F1));
+    }
+
+    {
+        QKeyCombination combination(Qt::AltModifier, Qt::Key_F1);
+        QCOMPARE(combination.key(), Qt::Key_F1);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::AltModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::AltModifier, Qt::Key_F1));
+    }
+
+    // corner cases
+    {
+        QKeyCombination combination = Qt::Key_Alt;
+        QCOMPARE(combination.key(), Qt::Key_Alt);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers{});
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::Key_Alt));
+    }
+
+    {
+        QKeyCombination combination(Qt::ALT, Qt::Key_Alt);
+        QCOMPARE(combination.key(), Qt::Key_Alt);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::AltModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::ALT, Qt::Key_Alt));
+    }
+
+    {
+        QKeyCombination combination(Qt::Key_unknown);
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers{});
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::Key_unknown));
+    }
+
+    {
+        QKeyCombination combination(Qt::CTRL | Qt::SHIFT, Qt::Key_unknown);
+        QCOMPARE(combination.key(), Qt::Key_unknown);
+        QCOMPARE(combination.keyboardModifiers(), Qt::KeyboardModifiers(Qt::ControlModifier | Qt::ShiftModifier));
+        QCOMPARE(combination.toCombined(), bitwiseOr(Qt::CTRL, Qt::SHIFT, Qt::Key_unknown));
+    }
+}
+
+void tst_QKeyCombination::operator_eq()
+{
+    // default
+    {
+        QKeyCombination a, b;
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    // key only
+    {
+        QKeyCombination a;
+        QKeyCombination b(Qt::Key_X);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::Key_Y);
+        QKeyCombination b;
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::Key_Y);
+        QKeyCombination b(Qt::Key_X);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::Key_F1);
+        QKeyCombination b(Qt::Key_F1);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    // modifier only
+    {
+        QKeyCombination a;
+        QKeyCombination b(Qt::CTRL);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::CTRL);
+        QKeyCombination b;
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::CTRL);
+        QKeyCombination b(Qt::SHIFT);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::CTRL);
+        QKeyCombination b(Qt::CTRL);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    {
+        QKeyCombination a(Qt::CTRL);
+        QKeyCombination b(Qt::ControlModifier);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    {
+        QKeyCombination a(Qt::ControlModifier);
+        QKeyCombination b(Qt::CTRL);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    {
+        QKeyCombination a(Qt::ControlModifier);
+        QKeyCombination b(Qt::ControlModifier);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    // key and modifier
+    {
+        QKeyCombination a(Qt::Key_A);
+        QKeyCombination b(Qt::SHIFT, Qt::Key_A);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::CTRL, Qt::Key_A);
+        QKeyCombination b(Qt::SHIFT, Qt::Key_A);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::SHIFT, Qt::Key_A);
+        QKeyCombination b(Qt::SHIFT, Qt::Key_A);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    {
+        QKeyCombination a(Qt::SHIFT, Qt::Key_A);
+        QKeyCombination b(Qt::SHIFT, Qt::Key_Escape);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::SHIFT, Qt::Key_A);
+        QKeyCombination b(Qt::ShiftModifier, Qt::Key_A);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    {
+        QKeyCombination a(Qt::SHIFT | Qt::CTRL, Qt::Key_A);
+        QKeyCombination b(Qt::ControlModifier | Qt::ShiftModifier, Qt::Key_A);
+        QVERIFY(a == b);
+        QVERIFY(!(a != b));
+    }
+
+    // corner cases
+    {
+        QKeyCombination a(Qt::CTRL);
+        QKeyCombination b(Qt::Key_Control);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+
+    {
+        QKeyCombination a(Qt::ALT);
+        QKeyCombination b(Qt::Key_Alt);
+        QVERIFY(a != b);
+        QVERIFY(!(a == b));
+    }
+}
+
+void tst_QKeyCombination::operator_or()
+{
+    // note tha operator+ between enumerators of the same enumeration
+    // yields int, so one can't do
+    //    Qt::SHIFT + Qt::CTRL + Qt::Key_A
+    // but one can do
+    //    Qt::SHIFT | Qt::CTRL | Qt::Key_A
+
+    QCOMPARE(Qt::SHIFT | Qt::Key_A, QKeyCombination(Qt::SHIFT, Qt::Key_A));
+    QCOMPARE(Qt::AltModifier | Qt::Key_F1, QKeyCombination(Qt::AltModifier, Qt::Key_F1));
+    QCOMPARE(Qt::SHIFT | Qt::ALT | Qt::Key_F1, QKeyCombination(Qt::SHIFT | Qt::ALT, Qt::Key_F1));
+    QCOMPARE(Qt::ControlModifier | Qt::Key_Escape, QKeyCombination(Qt::ControlModifier, Qt::Key_Escape));
+}
+
+QTEST_APPLESS_MAIN(tst_QKeyCombination)
+
+#include "tst_qkeycombination.moc"
diff --git a/tests/auto/gui/kernel/qkeysequence/tst_qkeysequence.cpp b/tests/auto/gui/kernel/qkeysequence/tst_qkeysequence.cpp
index c1272dc4cf..107c91507b 100644
--- a/tests/auto/gui/kernel/qkeysequence/tst_qkeysequence.cpp
+++ b/tests/auto/gui/kernel/qkeysequence/tst_qkeysequence.cpp
@@ -181,8 +181,9 @@ void tst_QKeySequence::swap()
     QKeySequence ks1(Qt::CTRL+Qt::Key_O);
     QKeySequence ks2(Qt::CTRL+Qt::Key_L);
     ks1.swap(ks2);
-    QCOMPARE(ks1[0], int(Qt::CTRL+Qt::Key_L));
-    QCOMPARE(ks2[0], int(Qt::CTRL+Qt::Key_O));
+
+    QCOMPARE(ks1[0], Qt::CTRL+Qt::Key_L);
+    QCOMPARE(ks2[0], Qt::CTRL+Qt::Key_O);
 }
 
 void tst_QKeySequence::operatorQString_data()