Implement the QEnum/QFlag decorator, V2

This implementation allows module-level and scoped QEnums
which are Python enum types. Scoped types are registered in Qt's meta
object system.

Usage of QEnum/QFlag with decorator or function call:

    from enum import Enum, Flag, auto

    from PySide2.QtCore import QEnum, QFlag, QObject

    class Compass(QObject):

        @QEnum
        class Orientation(Enum):
            North, East, South, West = range(4)

        class Color(Flag):
            RED = auto()
            BLUE = auto()
            GREEN = auto()
            WHITE = RED | BLUE | GREEN

        QFlag(Color)

Fixes: PYSIDE-957
Change-Id: Ie15f45cbd932c816b50724a96eee0c14ae1fdee8
Task-number: PYSIDE-487
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

1 files changed, 92 insertions, 0 deletions

diff --git a/sources/pyside2/doc/extras/QtCore.QEnum.rst b/sources/pyside2/doc/extras/QtCore.QEnum.rst
new file mode 100644
index 000000000..a5a2e31fd
--- /dev/null
+++ b/sources/pyside2/doc/extras/QtCore.QEnum.rst
@@ -0,0 +1,92 @@
+.. currentmodule:: PySide2.QtCore
+.. _QEnum:
+
+QEnum/QFlag
+***********
+
+This class decorator is equivalent to the `Q_ENUM` macro from Qt.
+The decorator is used to register an Enum to the meta-object system,
+which is available via `QObject.staticMetaObject`.
+The enumerator must be in a QObject derived class to be registered.
+
+
+Example
+-------
+
+::
+
+    from enum import Enum, Flag, auto
+
+    from PySide2.QtCore import QEnum, QFlag, QObject
+
+    class Demo(QObject):
+
+        @QEnum
+        class Orientation(Enum):
+            North, East, South, West = range(4)
+
+        class Color(Flag):
+            RED = auto()
+            BLUE = auto()
+            GREEN = auto()
+            WHITE = RED | BLUE | GREEN
+
+        QFlag(Color)    # identical to @QFlag usage
+
+
+Caution:
+--------
+
+QEnum registers a Python Enum derived class.
+QFlag treats a variation of the Python Enum, the Flag class.
+
+Please do not confuse that with the Qt QFlags concept. Python does
+not use that concept, it has its own class hierarchy, instead.
+For more details, see the `Python enum documentation <https://docs.python.org/3/library/enum.html>`_.
+
+
+Details about Qt Flags:
+-----------------------
+
+There are some small differences between Qt flags and Python flags.
+In Qt, we have for instance these declarations:
+
+::
+
+    enum    QtGui::RenderHint { Antialiasing, TextAntialiasing, SmoothPixmapTransform,
+                                HighQualityAntialiasing, NonCosmeticDefaultPen }
+    flags   QtGui::RenderHints
+
+The equivalent Python notation would look like this:
+
+::
+
+    @QFlag
+    class RenderHints(enum.Flag)
+        Antialiasing = auto()
+        TextAntialiasing = auto()
+        SmoothPixmapTransform = auto()
+        HighQualityAntialiasing = auto()
+        NonCosmeticDefaultPen = auto()
+
+
+As another example, the Qt::AlignmentFlag flag has 'AlignmentFlag' as the enum
+name, but 'Alignment' as the type name. Non flag enums have the same type and
+enum names.
+
+::
+
+    enum Qt::AlignmentFlag
+    flags Qt::Alignment
+
+The Python way to specify this would be
+
+::
+
+    @QFlag
+    class Alignment(enum.Flag):
+        ...
+
+We are considering to map all builtin enums and flags to Python enums as well
+in a later release.
+