1.. currentmodule:: PySide2.QtCore
2.. _QEnum:
3
4QEnum/QFlag
5***********
6
7This class decorator is equivalent to the `Q_ENUM` macro from Qt.
8The decorator is used to register an Enum to the meta-object system,
9which is available via `QObject.staticMetaObject`.
10The enumerator must be in a QObject derived class to be registered.
11
12
13Example
14-------
15
16::
17
18    from enum import Enum, Flag, auto
19
20    from PySide2.QtCore import QEnum, QFlag, QObject
21
22    class Demo(QObject):
23
24        @QEnum
25        class Orientation(Enum):
26            North, East, South, West = range(4)
27
28        class Color(Flag):
29            RED = auto()
30            BLUE = auto()
31            GREEN = auto()
32            WHITE = RED | BLUE | GREEN
33
34        QFlag(Color)    # identical to @QFlag usage
35
36
37Caution:
38--------
39
40QEnum registers a Python Enum derived class.
41QFlag treats a variation of the Python Enum, the Flag class.
42
43Please do not confuse that with the Qt QFlags concept. Python does
44not use that concept, it has its own class hierarchy, instead.
45For more details, see the `Python enum documentation <https://docs.python.org/3/library/enum.html>`_.
46
47
48Details about Qt Flags:
49-----------------------
50
51There are some small differences between Qt flags and Python flags.
52In Qt, we have for instance these declarations:
53
54::
55
56    enum    QtGui::RenderHint { Antialiasing, TextAntialiasing, SmoothPixmapTransform,
57                                HighQualityAntialiasing, NonCosmeticDefaultPen }
58    flags   QtGui::RenderHints
59
60The equivalent Python notation would look like this:
61
62::
63
64    @QFlag
65    class RenderHints(enum.Flag)
66        Antialiasing = auto()
67        TextAntialiasing = auto()
68        SmoothPixmapTransform = auto()
69        HighQualityAntialiasing = auto()
70        NonCosmeticDefaultPen = auto()
71
72
73As another example, the Qt::AlignmentFlag flag has 'AlignmentFlag' as the enum
74name, but 'Alignment' as the type name. Non flag enums have the same type and
75enum names.
76
77::
78
79    enum Qt::AlignmentFlag
80    flags Qt::Alignment
81
82The Python way to specify this would be
83
84::
85
86    @QFlag
87    class Alignment(enum.Flag):
88        ...
89
90We are considering to map all builtin enums and flags to Python enums as well
91in a later release.
92
93