From b0c417c86b7551ff1254926b4b177a35f7e8bce5 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Fri, 1 Mar 2024 13:57:19 +0100 Subject: Documentation: Change Enum page to be a proper decorator Split out QFlag to a separate page for proper indexing. Task-number: PYSIDE-1106 Task-number: PYSIDE-2215 Change-Id: Ibf4e1ad045c272adfa7c0a47bb2fe7ff1781d100 Reviewed-by: Adrian Herrmann --- sources/pyside6/doc/extras/QtCore.QEnum.rst | 84 ++++------------------------- sources/pyside6/doc/extras/QtCore.QFlag.rst | 74 +++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 74 deletions(-) create mode 100644 sources/pyside6/doc/extras/QtCore.QFlag.rst (limited to 'sources/pyside6/doc') diff --git a/sources/pyside6/doc/extras/QtCore.QEnum.rst b/sources/pyside6/doc/extras/QtCore.QEnum.rst index d42da91ab..7ea35d8af 100644 --- a/sources/pyside6/doc/extras/QtCore.QEnum.rst +++ b/sources/pyside6/doc/extras/QtCore.QEnum.rst @@ -1,23 +1,19 @@ .. currentmodule:: PySide6.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. +.. py:decorator:: QEnum +This class decorator is equivalent to the `Q_ENUM` macro from Qt. The decorator +is used to register a Python Enum derived class 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 enum import Enum, auto - from PySide6.QtCore import QEnum, QFlag, QObject + from PySide6.QtCore import QEnum, QObject class Demo(QObject): @@ -25,67 +21,7 @@ Example 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 `_. - - -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): - ... +See :deco:`QFlag` for registering Python Flag derived classes. -Meanwhile we have converted all enums and flags to Python Enums (optional in ``PySide 6.3``, -default in ``PySide 6.4``), see the :ref:`NewEnumSystem` section. +Meanwhile all enums and flags have been converted to Python Enums +(default since ``PySide 6.4``), see the :ref:`NewEnumSystem` section. diff --git a/sources/pyside6/doc/extras/QtCore.QFlag.rst b/sources/pyside6/doc/extras/QtCore.QFlag.rst new file mode 100644 index 000000000..dd4f02800 --- /dev/null +++ b/sources/pyside6/doc/extras/QtCore.QFlag.rst @@ -0,0 +1,74 @@ +.. currentmodule:: PySide6.QtCore +.. py:decorator:: QFlag + +QFlag handles 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 `_. + +Example +------- + +:: + + from enum import Flag, auto + + from PySide6.QtCore import QFlag, QObject + + class Demo(QObject): + + @QFlag + class Color(Flag): + RED = auto() + BLUE = auto() + GREEN = auto() + WHITE = RED | BLUE | GREEN + + +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): + ... + +See :deco:`QEnum` for registering Python Enum derived classes. + +Meanwhile all enums and flags have been converted to Python Enums +(default since ``PySide 6.4``), see the :ref:`NewEnumSystem` section. -- cgit v1.2.3