diff options
Diffstat (limited to 'sources/pyside6/doc/extras')
33 files changed, 409 insertions, 539 deletions
diff --git a/sources/pyside6/doc/extras/QtBluetooth.rst b/sources/pyside6/doc/extras/QtBluetooth.rst index dda05f20b..965896752 100644 --- a/sources/pyside6/doc/extras/QtBluetooth.rst +++ b/sources/pyside6/doc/extras/QtBluetooth.rst @@ -56,7 +56,7 @@ the environment variable ``QT_EVENT_DISPATCHER_CORE_FOUNDATION=1`` to circumvent this issue. Applications that don't use Classic Bluetooth will find a subset of -`QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ is available, +`QtBluetooth`_ is available, as CoreBluetooth (Bluetooth LE) do not require either of :class:`QApplication<PySide6.QtWidgets.QApplication>` or :class:`QGuiApplication<PySide6.QtGui.QGuiApplication>` . @@ -71,32 +71,32 @@ Guides Logging Categories ^^^^^^^^^^^^^^^^^^ -The `QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ module +The `QtBluetooth`_ module exports the following :class:`logging categories<~.Configuring Categories>` : - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |Logging Category |Description | - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |qt.bluetooth |Enables logging of cross platform code path in `QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_| - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |qt.bluetooth.android|Enables logging of the Android implementation | - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |qt.bluetooth.bluez |Enables logging of the BLuez/Linux implementation | - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |qt.bluetooth.ios |Enables logging of the iOS implementation | - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |qt.bluetooth.osx |Enables logging of the macOS implementation | - +--------------------+--------------------------------------------------------------------------------------------------------------+ - |qt.bluetooth.windows|Enables logging of the Qt for Windows implementation | - +--------------------+--------------------------------------------------------------------------------------------------------------+ + +--------------------+-------------------------------------------------------------+ + |Logging Category |Description | + +--------------------+-------------------------------------------------------------+ + |qt.bluetooth |Enables logging of cross platform code path in `QtBluetooth`_| + +--------------------+-------------------------------------------------------------+ + |qt.bluetooth.android|Enables logging of the Android implementation | + +--------------------+-------------------------------------------------------------+ + |qt.bluetooth.bluez |Enables logging of the BLuez/Linux implementation | + +--------------------+-------------------------------------------------------------+ + |qt.bluetooth.ios |Enables logging of the iOS implementation | + +--------------------+-------------------------------------------------------------+ + |qt.bluetooth.osx |Enables logging of the macOS implementation | + +--------------------+-------------------------------------------------------------+ + |qt.bluetooth.windows|Enables logging of the Qt for Windows implementation | + +--------------------+-------------------------------------------------------------+ Logging categories can be used to enable additional warning and debug output -for `QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ . More -detailed information about logging can be found in +for `QtBluetooth`_ . More detailed information about logging can be found in :class:`QLoggingCategory<~.QLoggingCategory>` . A quick way to enable all -`QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ logging is to -add the following line to the ``main()`` function: +`QtBluetooth`_ logging is to add the following line to the ``main()`` +function:: - :: + QLoggingCategory.setFilterRules("qt.bluetooth* = true") - QLoggingCategory.setFilterRules("qt.bluetooth* = true") + +.. _QtBluetooth: https://doc.qt.io/qt-6/qtbluetooth-module.html diff --git a/sources/pyside6/doc/extras/QtCharts.rst b/sources/pyside6/doc/extras/QtCharts.rst index 8ff2a0386..8f2d768bf 100644 --- a/sources/pyside6/doc/extras/QtCharts.rst +++ b/sources/pyside6/doc/extras/QtCharts.rst @@ -15,3 +15,7 @@ directive: from PySide6 import QtCharts The module also provides `QML types <https://doc.qt.io/qt-6/qtcharts-qmlmodule.html>`_ . + +.. note:: An instance of QApplication is required for the QML types as the + module depends on Qt's \l{Graphics View Framework} for rendering. + QGuiApplication is not sufficient. diff --git a/sources/pyside6/doc/extras/QtCore.ClassInfo.rst b/sources/pyside6/doc/extras/QtCore.ClassInfo.rst index 0cb6d32ed..75445e1fc 100644 --- a/sources/pyside6/doc/extras/QtCore.ClassInfo.rst +++ b/sources/pyside6/doc/extras/QtCore.ClassInfo.rst @@ -1,11 +1,9 @@ .. currentmodule:: PySide6.QtCore -.. _ClassInfo: +.. py:decorator:: ClassInfo -ClassInfo -********* - -This class is used to associate extra information to the class, which is available -using QObject.metaObject(). Qt and PySide doesn't use this information. +This decorator is used to associate extra information to the class, which is available +using ``QObject.metaObject()``. This information is used by the +*Qt D-Bus* and *Qt Qml* modules. The extra information takes the form of a dictionary with key and value in a literal string. @@ -16,13 +14,13 @@ If the key needs to contain special characters (spaces, commas, '::', start with it is also possible to pass a python dictionary with arbitrary strings for both the key and value and enabling special characters in the key. -.. note:: This Class is a implementation of Q_CLASSINFO macro. +.. note:: This decorator is a implementation of the Q_CLASSINFO macro. Example ------- -:: +.. code-block:: python # Recommended syntax @ClassInfo(Author='PySide Team', URL='http://www.pyside.org') diff --git a/sources/pyside6/doc/extras/QtCore.Property.rst b/sources/pyside6/doc/extras/QtCore.Property.rst index 1912b8d23..9ed7de427 100644 --- a/sources/pyside6/doc/extras/QtCore.Property.rst +++ b/sources/pyside6/doc/extras/QtCore.Property.rst @@ -1,8 +1,5 @@ .. currentmodule:: PySide6.QtCore -.. _Property: - -Property -******** +.. py:class:: Property Detailed Description -------------------- @@ -16,7 +13,7 @@ They are equivalent to the ``Q_PROPERTY`` macro in the `Qt Docs`_. Here is an example that illustrates how to use this function: -.. code-block:: +.. code-block:: python :linenos: from PySide6.QtCore import QObject, Property @@ -40,20 +37,20 @@ function: The full options for ``QtCore.Property`` can be found with ``QtCore.Property.__doc__``: -.. code-block:: - - Property(self, type: type, - fget: Optional[Callable] = None, - fset: Optional[Callable] = None, - freset: Optional[Callable] = None, - fdel: Optional[Callable] = None, - doc: str = '', - notify: Optional[Callable] = None, - designable: bool = True, - scriptable: bool = True, - stored: bool = True, user: bool = False, - constant: bool = False, - final: bool = False) -> PySide6.QtCore.Property +.. code-block:: python + + Property(self, type: type, + fget: Optional[Callable] = None, + fset: Optional[Callable] = None, + freset: Optional[Callable] = None, + fdel: Optional[Callable] = None, + doc: str = '', + notify: Optional[Callable] = None, + designable: bool = True, + scriptable: bool = True, + stored: bool = True, user: bool = False, + constant: bool = False, + final: bool = False) -> PySide6.QtCore.Property Normally, only ``type``, ``fget``and ``fset`` are used. @@ -68,16 +65,16 @@ requires a ``type`` parameter. In the above example, the following lines would be equivalent properties: -.. code-block:: +.. code-block:: python - pp = QtCore.Property(int, readPP, setPP) # PySide version - pp = property(readPP, setPP) # Python version + pp = QtCore.Property(int, readPP, setPP) # PySide version + pp = property(readPP, setPP) # Python version As you know from the `Python Docs`_, ``Python`` allows to break the property creation into multiple steps, using the decorator syntax. We can do this in ``PySide`` as well: -.. code-block:: +.. code-block:: python :linenos: from PySide6.QtCore import QObject, Property @@ -110,12 +107,15 @@ If you are using properties of your objects in QML expressions, QML requires that the property changes are notified. Here is an example illustrating how to do this: -.. code-block:: +.. code-block:: python :linenos: from PySide6.QtCore import QObject, Signal, Property class Person(QObject): + + name_changed = Signal() + def __init__(self, name): QObject.__init__(self) self._person_name = name @@ -123,10 +123,6 @@ example illustrating how to do this: def _name(self): return self._person_name - @Signal - def name_changed(self): - pass - name = Property(str, _name, notify=name_changed) .. _`Python Docs`: https://docs.python.org/3/library/functions.html?highlight=property#property 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 <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): - ... +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 <https://docs.python.org/3/library/enum.html>`_. + +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. diff --git a/sources/pyside6/doc/extras/QtCore.Signal.rst b/sources/pyside6/doc/extras/QtCore.Signal.rst index b50c34148..c83a76a83 100644 --- a/sources/pyside6/doc/extras/QtCore.Signal.rst +++ b/sources/pyside6/doc/extras/QtCore.Signal.rst @@ -1,8 +1,5 @@ .. currentmodule:: PySide6.QtCore -.. _Signal: - -Signal -****** +.. py:class:: Signal Synopsis -------- @@ -10,19 +7,19 @@ Synopsis Functions ^^^^^^^^^ -+---------------------------------------------------------------------------------------------+ -|def :meth:`connect<Signal.connect>` (receiver) | -+---------------------------------------------------------------------------------------------+ -|def :meth:`disconnect<Signal.disconnect>` (receiver) | -+---------------------------------------------------------------------------------------------+ -|def :meth:`emit<Signal.disconnect>` (\*args) | -+---------------------------------------------------------------------------------------------+ ++-----------------------------------------------------+ +|def :meth:`connect<Signal.connect>` (receiver) | ++-----------------------------------------------------+ +|def :meth:`disconnect<Signal.disconnect>` (receiver) | ++-----------------------------------------------------+ +|def :meth:`emit<Signal.disconnect>` (\*args) | ++-----------------------------------------------------+ Detailed Description -------------------- - The :class:`~.Signal` class provides a way to declare and connect Qt - signals in a pythonic way. +The :class:`~.Signal` class provides a way to declare and connect Qt +signals in a pythonic way. .. class:: PySide6.QtCore.Signal([type1 [, type2...]] [, name="" [, arguments=[]]]) diff --git a/sources/pyside6/doc/extras/QtCore.Slot.rst b/sources/pyside6/doc/extras/QtCore.Slot.rst index 55c3d9fb7..98a1d465b 100644 --- a/sources/pyside6/doc/extras/QtCore.Slot.rst +++ b/sources/pyside6/doc/extras/QtCore.Slot.rst @@ -1,53 +1,42 @@ .. currentmodule:: PySide6.QtCore -.. _Slot: +.. py:decorator:: Slot([type1 [, type2...]] [, name="" [, result=None, [tag=""]]]) -Slot -**** + :param name: str + :param result: type + :param tag: str -Detailed Description --------------------- +``Slot`` takes a list of Python types of the arguments. - PySide6 adopt PyQt's new signal and slot syntax as-is. The PySide6 - implementation is functionally compatible with the PyQt one, with the - exceptions listed below. +The optional named argument ``name`` defines the slot name. If nothing is +passed, the slot name will be the decorated function name. - PyQt's new signal and slot style utilizes method and decorator names - specific to their implementation. These will be generalized according to - the table below: +The optional named argument ``result`` specifies the return type. - ======= ======================= ============= - Module PyQt factory function PySide class - ======= ======================= ============= - QtCore pyqtSignal Signal - QtCore pyqtSlot Slot - ======= ======================= ============= +The optional named argument ``tag`` specifies a value to be returned +by ``QMetaMethod.tag()``. - .. class:: PySide6.QtCore.Slot([type1 [, type2...]] [, name="" [, result=None]]) +This implementation is functionally compatible with the PyQt one. - :param name: str - :param result: type +======= =========== ====== +Module PyQt PySide +======= =========== ====== +QtCore pyqtSignal Signal +QtCore pyqtSlot Slot +======= =========== ====== - ``Slot`` takes a list of Python types of the arguments. - - The optional named argument ``name`` defines the slot name. If nothing is - passed, the slot name will be the decorated function name. - - The optional named argument ``result`` specifies the return type. - - .. seealso:: :ref:`signals-and-slots` +.. seealso:: :ref:`signals-and-slots` Q_INVOKABLE ----------- - There is no equivalent of the Q_INVOKABLE macro of Qt - since PySide6 slots can actually have return values. - If you need to create a invokable method that returns some value, - declare it as a slot, e.g.: - - :: +There is no equivalent of the Q_INVOKABLE macro of Qt +since PySide6 slots can actually have return values. +If you need to create a invokable method that returns some value, +declare it as a slot, e.g.: - class Foo(QObject): +:: - @Slot(float, result=int) - def getFloatReturnInt(self, f): - return int(f) + class Foo(QObject): + @Slot(float, result=int) + def getFloatReturnInt(self, f): + return int(f) diff --git a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerContainerExtension.rst b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerContainerExtension.rst index 1baa9e369..a3e5ef511 100644 --- a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerContainerExtension.rst +++ b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerContainerExtension.rst @@ -1,10 +1,9 @@ .. currentmodule:: PySide6.QtDesigner -.. _QPyDesignerContainerExtension: - -QPyDesignerContainerExtension -***************************** +.. py:class:: QPyDesignerContainerExtension QPyDesignerContainerExtension is the base class for implementing -`QDesignerContainerExtension <https://doc.qt.io/qt-6/qdesignercontainerextension.html>`_ -for a Qt Designer custom widget plugin in Python. +`QDesignerContainerExtension class`_ +for a *Qt Widgets Designer* custom widget plugin in Python. It provides the required inheritance from **QObject**. + +.. _QDesignerContainerExtension class: https://doc.qt.io/qt-6/qdesignercontainerextension.html diff --git a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerCustomWidgetCollection.rst b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerCustomWidgetCollection.rst index 00260860b..615ca4eec 100644 --- a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerCustomWidgetCollection.rst +++ b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerCustomWidgetCollection.rst @@ -1,8 +1,5 @@ .. currentmodule:: PySide6.QtDesigner -.. _QPyDesignerCustomWidgetCollection: - -QPyDesignerCustomWidgetCollection -********************************* +.. py:class:: QPyDesignerCustomWidgetCollection Synopsis -------- @@ -19,20 +16,21 @@ Functions Detailed Description -------------------- - The :class:`~.QPyDesignerCustomWidgetCollection` implements - `QDesignerCustomWidgetCollectionInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetcollectioninterface.html>`_ - and provides static helper functions for registering custom widgets by - type or by implementing - `QDesignerCustomWidgetInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html>`_ . +The :class:`~.QPyDesignerCustomWidgetCollection` implements +`QDesignerCustomWidgetCollectionInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetcollectioninterface.html>`_ +and provides static helper functions for registering custom widgets by +type or by implementing +`QDesignerCustomWidgetInterface`_ . - The usage is explained in :ref:`designer_custom_widgets`. +The usage is explained in :ref:`designer_custom_widgets`. .. py:staticmethod:: QPyDesignerCustomWidgetCollection.registerCustomWidget(type[, xml=""[, tool_tip=""[, icon=""[, group=""[container=False]]]]]) - Registers an instance of a Python-implemented QWidget by type with Qt Designer. + Registers an instance of a Python-implemented QWidget by type with + *Qt Widgets Designer*. The optional keyword arguments correspond to the getters of - `QDesignerCustomWidgetInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html>`_ : + `QDesignerCustomWidgetInterface`_ : :param str xml: A snippet of XML code in ``.ui`` format that specifies how the widget is created and sets initial property values. :param str tool_tip: Tool tip to be shown in the widget box. @@ -46,7 +44,9 @@ Detailed Description .. py:staticmethod:: QPyDesignerCustomWidgetCollection.addCustomWidget(custom_widget) Adds a custom widget (implementation of - `QDesignerCustomWidgetInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html>`_) - with Qt Designer. + `QDesignerCustomWidgetInterface`_) + with *Qt Widgets Designer*. :param QDesignerCustomWidgetInterface custom_widget: Custom widget instance + +.. _QDesignerCustomWidgetInterface: https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html diff --git a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerMemberSheetExtension.rst b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerMemberSheetExtension.rst index c52aafdf5..ef2356221 100644 --- a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerMemberSheetExtension.rst +++ b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerMemberSheetExtension.rst @@ -1,10 +1,9 @@ .. currentmodule:: PySide6.QtDesigner -.. _QPyDesignerMemberSheetExtension: - -QPyDesignerMemberSheetExtension -******************************* +.. py:class:: QPyDesignerMemberSheetExtension QPyDesignerMemberSheetExtension is the base class for implementing -`QDesignerMemberSheetExtension <https://doc.qt.io/qt-6/qdesignermembersheetextension.html>`_ -for a Qt Designer custom widget plugin in Python. +`QDesignerMemberSheetExtension class`_ +for a *Qt Widgets Designer* custom widget plugin in Python. It provides the required inheritance from **QObject**. + +.. _QDesignerMemberSheetExtension class: https://doc.qt.io/qt-6/qdesignermembersheetextension.html diff --git a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerTaskMenuExtension.rst b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerTaskMenuExtension.rst index 004c94693..e5e13122d 100644 --- a/sources/pyside6/doc/extras/QtDesigner.QPyDesignerTaskMenuExtension.rst +++ b/sources/pyside6/doc/extras/QtDesigner.QPyDesignerTaskMenuExtension.rst @@ -1,10 +1,9 @@ .. currentmodule:: PySide6.QtDesigner -.. _QPyDesignerTaskMenuExtension: - -QPyDesignerTaskMenuExtension -**************************** +.. py:class:: QPyDesignerTaskMenuExtension QPyDesignerTaskMenuExtension is the base class for implementing -`QDesignerTaskMenuExtension <https://doc.qt.io/qt-6/qdesignertaskmenuextension.html>`_ -for a Qt Designer custom widget plugin in Python. +`QDesignerTaskMenuExtension class`_ +for a *Qt Widgets Designer* custom widget plugin in Python. It provides the required inheritance from **QObject**. + +.. _QDesignerTaskMenuExtension class: https://doc.qt.io/qt-6/qdesignertaskmenuextension.html diff --git a/sources/pyside6/doc/extras/QtDesigner.rst b/sources/pyside6/doc/extras/QtDesigner.rst index c232128dd..844f25b7b 100644 --- a/sources/pyside6/doc/extras/QtDesigner.rst +++ b/sources/pyside6/doc/extras/QtDesigner.rst @@ -1,5 +1,6 @@ -Provides classes to create your own custom widget plugins for Qt Designer and -classes to access Qt Designer components. +Provides classes to create your own custom widget plugins for +*Qt Widgets Designer* and classes to access *Qt Widgets Designer* +components. In addition, the :class:`QFormBuilder<PySide6.QtDesigner.QFormBuilder>` class provides the possibility of constructing user interfaces from UI files at diff --git a/sources/pyside6/doc/extras/QtMultimedia.rst b/sources/pyside6/doc/extras/QtMultimedia.rst index f495ddc4e..527c2427b 100644 --- a/sources/pyside6/doc/extras/QtMultimedia.rst +++ b/sources/pyside6/doc/extras/QtMultimedia.rst @@ -29,7 +29,7 @@ directive: import PySide6.QtMultimedia -The module also provides `QML types <https://doc.qt.io/qt-6/qtmultimedia-qmlmodule.html>`_ . +The module also provides QML `types <https://doc.qt.io/qt-6/qtmultimedia-qmlmodule.html>`_ . Overviews and Important Topics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -46,27 +46,38 @@ QML Types The following table outlines some important QML types. - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |Type |Description | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`MediaPlayer <https://doc.qt.io/qt-6/qml-qtmultimedia-mediaplayer.html>`_ |Add audio/video playback functionality to a scene. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`CaptureSession <https://doc.qt.io/qt-6/qml-qtmultimedia-capturesession.html>`_|Create a session for capturing audio/video. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`Camera <https://doc.qt.io/qt-6/qml-qtmultimedia-camera.html>`_ |Access a camera connected to the system. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`AudioInput <https://doc.qt.io/qt-6/qml-qtmultimedia-audioinput.html>`_ |Access an audio input (microphone) connected to the system. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`AudioOutput <https://doc.qt.io/qt-6/qml-qtmultimedia-audiooutput.html>`_ |Access an audio output (speaker, headphone) connected to the system. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`VideoOutput <https://doc.qt.io/qt-6/qml-qtmultimedia-videooutput.html>`_ |Display video content. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`MediaRecorder <https://doc.qt.io/qt-6/qml-qtmultimedia-mediarecorder.html>`_ |Record audio/video from the `CaptureSession <https://doc.qt.io/qt-6/qml-qtmultimedia-capturesession.html>`_ . | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`ImageCapture <https://doc.qt.io/qt-6/qml-qtmultimedia-imagecapture.html>`_ |Capture still images from the Camera. | - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - |`Video <https://doc.qt.io/qt-6/qml-qtmultimedia-video.html>`_ |Add Video playback functionality to a scene. Uses `MediaPlayer <https://doc.qt.io/qt-6/qml-qtmultimedia-mediaplayer.html>`_ and `VideoOutput <https://doc.qt.io/qt-6/qml-qtmultimedia-videooutput.html>`_ types to provide video playback functionality.| - +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +------------------+---------------------------------------------------------------------+ + |Type |Description | + +------------------+---------------------------------------------------------------------+ + |`MediaPlayer`_ |Add audio/video playback functionality to a scene. | + +------------------+---------------------------------------------------------------------+ + |`CaptureSession`_ |Create a session for capturing audio/video. | + +------------------+---------------------------------------------------------------------+ + |`Camera`_ |Access a camera connected to the system. | + +------------------+---------------------------------------------------------------------+ + |`AudioInput`_ |Access an audio input (microphone) connected to the system. | + +------------------+---------------------------------------------------------------------+ + |`AudioOutput`_ |Access an audio output (speaker, headphone) connected to the system. | + +------------------+---------------------------------------------------------------------+ + |`VideoOutput`_ |Display video content. | + +------------------+---------------------------------------------------------------------+ + |`MediaRecorder`_ |Record audio/video from the `CaptureSession`_ . | + +------------------+---------------------------------------------------------------------+ + |`ImageCapture`_ |Capture still images from the Camera. | + +------------------+---------------------------------------------------------------------+ + |`Video`_ |Add Video playback functionality to a scene. Uses `MediaPlayer`_ and | + | |`VideoOutput`_ types to provide video playback functionality. | + +------------------+---------------------------------------------------------------------+ + +.. _MediaPlayer: https://doc.qt.io/qt-6/qml-qtmultimedia-mediaplayer.html +.. _CaptureSession: https://doc.qt.io/qt-6/qml-qtmultimedia-capturesession.html +.. _Camera: https://doc.qt.io/qt-6/qml-qtmultimedia-camera.html +.. _AudioInput: https://doc.qt.io/qt-6/qml-qtmultimedia-audioinput.html +.. _AudioOutput: https://doc.qt.io/qt-6/qml-qtmultimedia-audiooutput.html +.. _VideoOutput: https://doc.qt.io/qt-6/qml-qtmultimedia-videooutput.html +.. _MediaRecorder: https://doc.qt.io/qt-6/qml-qtmultimedia-mediarecorder.html +.. _ImageCapture: https://doc.qt.io/qt-6/qml-qtmultimedia-imagecapture.html +.. _Video: https://doc.qt.io/qt-6/qml-qtmultimedia-video.html C++ Classes ^^^^^^^^^^^ diff --git a/sources/pyside6/doc/extras/QtQml.ListProperty.rst b/sources/pyside6/doc/extras/QtQml.ListProperty.rst new file mode 100644 index 000000000..eaa580c68 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.ListProperty.rst @@ -0,0 +1,24 @@ +.. currentmodule:: PySide6.QtQml +.. py:class:: ListProperty + + The ``ListProperty`` class allows applications to expose list-like properties of + :class:`~PySide6.QtCore.QObject`-derived classes to QML. + The usage is shown in the :ref:`qml-object-and-list-property-types-example` + and the :ref:`qml-chapter5-listproperties` example. + + .. py:method:: __init__(type, append, count=None, at=None, clear=None, removeLast=None, doc="", notify=None, designable=True, scriptable=True, stored=True, user=False, constant=False, final=False) + + :param type type: Element type + :param callable append: A function to append an item + :param callable count: A function returning the list count + :param callable at: A function returning the item at an index + :param callable clear: A function to clear the list + :param removeLast: A function to remove the last item + :param str doc: Doc string + :param Signal notify: A signal emitted when a change occurs + :param bool designable: Not used in QML + :param bool scriptable: Not used in QML + :param bool stored: Whether the property is stored + :param bool user: Not used in QML + :param bool constant: Whether the property is constant + :param bool final: Whether the property is final diff --git a/sources/pyside6/doc/extras/QtQml.QPyQmlParserStatus.rst b/sources/pyside6/doc/extras/QtQml.QPyQmlParserStatus.rst index 58f609b03..10dde6b9a 100644 --- a/sources/pyside6/doc/extras/QtQml.QPyQmlParserStatus.rst +++ b/sources/pyside6/doc/extras/QtQml.QPyQmlParserStatus.rst @@ -1,10 +1,9 @@ .. currentmodule:: PySide6.QtQml -.. _QPyQmlParserStatus: - -QPyQmlParserStatus -****************** +.. py:class:: QPyQmlParserStatus QPyQmlParserStatus is the base class for implementing -`QQmlParserStatus <https://doc.qt.io/qt-6/qqmlparserstatus.html>`_ +`QQmlParserStatus class`_ . It provides the required inheritance from **QObject**. + +.. _QQmlParserStatus class: https://doc.qt.io/qt-6/qqmlparserstatus.html diff --git a/sources/pyside6/doc/extras/QtQml.QPyQmlPropertyValueSource.rst b/sources/pyside6/doc/extras/QtQml.QPyQmlPropertyValueSource.rst index 576b8baa0..bf7f8e98f 100644 --- a/sources/pyside6/doc/extras/QtQml.QPyQmlPropertyValueSource.rst +++ b/sources/pyside6/doc/extras/QtQml.QPyQmlPropertyValueSource.rst @@ -1,10 +1,9 @@ .. currentmodule:: PySide6.QtQml -.. _QPyQmlPropertyValueSource: - -QPyQmlPropertyValueSource -************************* +.. py:class:: QPyQmlPropertyValueSource QPyQmlPropertyValueSource is the base class for implementing -`QQmlPropertyValueSource <https://doc.qt.io/qt-6/qqmlpropertyvaluesource.html>`_ +`QQmlPropertyValueSource class`_ . It provides the required inheritance from **QObject**. + +.. _QQmlPropertyValueSource class: https://doc.qt.io/qt-6/qqmlpropertyvaluesource.html diff --git a/sources/pyside6/doc/extras/QtQml.QmlAnonymous.rst b/sources/pyside6/doc/extras/QtQml.QmlAnonymous.rst index a805b0763..44aa0ea21 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlAnonymous.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlAnonymous.rst @@ -1,22 +1,17 @@ .. currentmodule:: PySide6.QtQml -.. _QmlAnonymous: - -QmlAnonymous -************ - .. py:decorator:: QmlAnonymous - Declares the enclosing type to be available, but anonymous in QML. The type - cannot be created or used to declare properties in QML, but when passed from - C++, it is recognized. In QML, you can use properties of this type if they - are declared in C++. +Declares the enclosing type to be available, but anonymous in QML. The type +cannot be created or used to declare properties in QML, but when passed from +C++, it is recognized. In QML, you can use properties of this type if they +are declared in C++. - .. code-block:: python +.. code-block:: python - QML_IMPORT_NAME = "com.library.name" - QML_IMPORT_MAJOR_VERSION = 1 - QML_IMPORT_MINOR_VERSION = 0 # Optional + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional - @QmlAnonymous - class ClassForQml(QObject): - # ... + @QmlAnonymous + class ClassForQml(QObject): + # ... diff --git a/sources/pyside6/doc/extras/QtQml.QmlAttached.rst b/sources/pyside6/doc/extras/QtQml.QmlAttached.rst index e3fefb6b2..4331b03f9 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlAttached.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlAttached.rst @@ -1,9 +1,4 @@ .. currentmodule:: PySide6.QtQml -.. _QmlAttached: - -QmlAttached -*********** - .. py:decorator:: QmlAttached This decorator declares that the enclosing type attaches the type passed as diff --git a/sources/pyside6/doc/extras/QtQml.QmlElement.rst b/sources/pyside6/doc/extras/QtQml.QmlElement.rst index 2746fbc0b..66397b2d9 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlElement.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlElement.rst @@ -1,30 +1,25 @@ .. currentmodule:: PySide6.QtQml -.. _QmlElement: - -QmlElement -********** - .. py:decorator:: QmlElement - This decorator registers a class it is attached to for use in QML, using - global variables to specify the import name and version. +This decorator registers a class it is attached to for use in QML, using +global variables to specify the import name and version. - .. code-block:: python +.. code-block:: python - QML_IMPORT_NAME = "com.library.name" - QML_IMPORT_MAJOR_VERSION = 1 - QML_IMPORT_MINOR_VERSION = 0 # Optional + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional - @QmlElement - class ClassForQml(QObject): - # ... + @QmlElement + class ClassForQml(QObject): + # ... - Afterwards the class may be used in QML: +Afterwards the class may be used in QML: - .. code-block:: python +.. code-block:: python - import com.library.name 1.0 + import com.library.name 1.0 - ClassForQml { - // ... - } + ClassForQml { + // ... + } diff --git a/sources/pyside6/doc/extras/QtQml.QmlExtended.rst b/sources/pyside6/doc/extras/QtQml.QmlExtended.rst index f9ed5a106..af113a9c8 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlExtended.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlExtended.rst @@ -1,9 +1,4 @@ .. currentmodule:: PySide6.QtQml -.. _QmlExtended: - -QmlExtended -*********** - .. py:decorator:: QmlExtended Declares that the enclosing type uses the type passed as an extension to diff --git a/sources/pyside6/doc/extras/QtQml.QmlForeign.rst b/sources/pyside6/doc/extras/QtQml.QmlForeign.rst index c58be3cb9..90b821e9b 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlForeign.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlForeign.rst @@ -1,33 +1,28 @@ .. currentmodule:: PySide6.QtQml -.. _QmlForeign: - -QmlForeign -********** - .. py:decorator:: QmlForeign - This decorator can be used to change the type that is created by QML. +This decorator can be used to change the type that is created by QML. - This is useful for registering types that cannot be amended by adding the - QmlElement decorator, for example because they belong to 3rdparty libraries. +This is useful for registering types that cannot be amended by adding the +QmlElement decorator, for example because they belong to 3rdparty libraries. - .. code-block:: python +.. code-block:: python - QML_IMPORT_NAME = "com.library.name" - QML_IMPORT_MAJOR_VERSION = 1 - QML_IMPORT_MINOR_VERSION = 0 # Optional + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional - @QmlNamedElement("QWidget") - @QmlForeign(QWidget) - class ForeignWidgetHelperClass(QObject): + @QmlNamedElement("QWidget") + @QmlForeign(QWidget) + class ForeignWidgetHelperClass(QObject): ... - Afterwards the class may be used in QML: +Afterwards the class may be used in QML: - .. code-block:: javascript +.. code-block:: javascript - import com.library.name 1.0 + import com.library.name 1.0 - QWidget { - // ... - } + QWidget { + // ... + } diff --git a/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst b/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst index d603e2e83..79eb9d7ad 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst @@ -1,31 +1,26 @@ .. currentmodule:: PySide6.QtQml -.. _QmlNamedElement: - -QmlNamedElement -*************** - .. py:decorator:: QmlNamedElement - This decorator registers a class it is attached to for use in QML under - a name different from the class name, using global variables to specify - the import name and version. +This decorator registers a class it is attached to for use in QML under +a name different from the class name, using global variables to specify +the import name and version. - .. code-block:: python +.. code-block:: python - QML_IMPORT_NAME = "com.library.name" - QML_IMPORT_MAJOR_VERSION = 1 - QML_IMPORT_MINOR_VERSION = 0 # Optional + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional - @QmlNamedElement("ClassForQml") - class ClassWithSomeName(QObject): + @QmlNamedElement("ClassForQml") + class ClassWithSomeName(QObject): ... - Afterwards the class may be used in QML: +Afterwards the class may be used in QML: - .. code-block:: javascript +.. code-block:: javascript - import com.library.name 1.0 + import com.library.name 1.0 - ClassForQml { - // ... - } + ClassForQml { + // ... + } diff --git a/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst b/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst index d3d3bf4a7..402c18d55 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst @@ -1,13 +1,8 @@ .. currentmodule:: PySide6.QtQml -.. _QmlSingleton: - -QmlSingleton -************ - .. py:decorator:: QmlSingleton Declares the decorated type to be a singleton in QML. This only takes effect if -the type is a Q_OBJECT and is available in QML (by having a QmlElement decorator). +the type is a QObject and is available in QML (by having a QmlElement decorator). The QQmlEngine will try to create a singleton instance using the type's default constructor. @@ -20,6 +15,19 @@ constructor. @QmlElement @QmlSingleton class ClassForQml(QObject): - # ... + ... + +It is also possible to use a static ``create()`` method which receives +the engine as a parameter: + +.. code-block:: python + + @QmlElement + @QmlSingleton + class ClassForQml(QObject): + + @staticmethod + def create(engine): + ... .. note:: The order of the decorators matters; ``QmlSingleton`` needs to be preceded by ``QmlElement``. diff --git a/sources/pyside6/doc/extras/QtQml.QmlUncreatable.rst b/sources/pyside6/doc/extras/QtQml.QmlUncreatable.rst index 72fde741d..b7a28801f 100644 --- a/sources/pyside6/doc/extras/QtQml.QmlUncreatable.rst +++ b/sources/pyside6/doc/extras/QtQml.QmlUncreatable.rst @@ -1,9 +1,4 @@ .. currentmodule:: PySide6.QtQml -.. _QmlUncreatable: - -QmlUncreatable -************** - .. py:decorator:: QmlUncreatable Declares that the decorated type shall not be creatable from QML. This takes @@ -26,6 +21,6 @@ Passing None or no argument will cause a standard message to be used instead. @QmlElement @QmlUncreatable("BaseClassForQml is an abstract base class") class BaseClassForQml(QObject): - # ... + ... .. note:: The order of the decorators matters; ``QmlUncreatable`` needs to be preceded by ``QmlElement``. diff --git a/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonInstance.rst b/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonInstance.rst deleted file mode 100644 index 19d59893e..000000000 --- a/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonInstance.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. currentmodule:: PySide6.QtQml -.. _qmlRegisterSingletonInstance: - -qmlRegisterSingletonInstance -**************************** - -.. py:function:: qmlRegisterSingletonInstance(pytype: type,\ - uri: str,\ - versionMajor: int,\ - versionMinor: int,\ - typeName: str,\ - instanceObject: object) -> int - - :param type pytype: Python class - :param str uri: uri to use while importing the component in QML - :param int versionMajor: major version - :param int versionMinor: minor version - :param str typeName: name exposed to QML - :param object instanceObject: singleton object to be registered - :return: int (the QML type id) - - This function registers a singleton Python object *instanceObject*, with a particular *uri* and - *typeName*. Its version is a combination of *versionMajor* and *versionMinor*. - - Use this function to register an object of the given type *pytype* as a singleton type. diff --git a/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonType.rst b/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonType.rst deleted file mode 100644 index 32231a391..000000000 --- a/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonType.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. currentmodule:: PySide6.QtQml -.. _qmlRegisterSingletonType: - -qmlRegisterSingletonType -************************ - -.. py:function:: qmlRegisterSingletonType(pytype: type, uri: str, versionMajor: int, versionMinor: int, typeName: str) -> int - - :param type pytype: Python class - :param str uri: uri to use while importing the component in QML - :param int versionMajor: major version - :param int versionMinor: minor version - :param str typeName: name exposed to QML - :return: int (the QML type id) - - This function registers a Python type as a singleton in the QML system. - - Alternatively, the :ref:`QmlSingleton` decorator can be used. - -.. py:function:: qmlRegisterSingletonType(pytype: type, uri: str, versionMajor: int, versionMinor: int, typeName: str, callback: object) -> int - - :param type pytype: Python class - :param str uri: uri to use while importing the component in QML - :param int versionMajor: major version - :param int versionMinor: minor version - :param str typeName: name exposed to QML - :param object callback: Python callable (to handle Python type) - :return: int (the QML type id) - - This function registers a Python type as a singleton in the QML system using - the provided callback (which gets a QQmlEngine as a parameter) to generate - the singleton. - - -.. py:function:: qmlRegisterSingletonType(uri: str, versionMajor: int, versionMinor: int, typeName: str, callback: object) -> int - - :param str uri: uri to use while importing the component in QML - :param int versionMajor: major version - :param int versionMinor: minor version - :param str typeName: name exposed to QML - :param object callback: Python callable (to handle QJSValue) - :return: int (the QML type id) - - This function registers a QJSValue as a singleton in the QML system using - the provided callback (which gets a QQmlEngine as a parameter) to - generate the singleton. diff --git a/sources/pyside6/doc/extras/QtQml.qmlRegisterType.rst b/sources/pyside6/doc/extras/QtQml.qmlRegisterType.rst deleted file mode 100644 index 079e15bf1..000000000 --- a/sources/pyside6/doc/extras/QtQml.qmlRegisterType.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. currentmodule:: PySide6.QtQml -.. _qmlRegisterType: - -qmlRegisterType -*************** - -.. py:function:: qmlRegisterType(pytype: type, uri: str, versionMajor: int, versionMinor: int, qmlName: str) -> int - - :param type pytype: Python class - :param str uri: uri to use while importing the component in QML - :param int versionMajor: major version - :param int versionMinor: minor version - :param str qmlName: name exposed to QML - :return: int (the QML type id) - - This function registers the Python *type* in the QML system with the - name *qmlName*, in the library imported from *uri* having the - version number composed from *versionMajor* and *versionMinor*. - - For example, this registers a Python class 'MySliderItem' as a QML - type named 'Slider' for version '1.0' of a module called - 'com.mycompany.qmlcomponents': - - :: - - qmlRegisterType(MySliderItem, "com.mycompany.qmlcomponents", 1, 0, "Slider") - - Once this is registered, the type can be used in QML by importing - the specified module name and version number: - - :: - - import com.mycompany.qmlcomponents 1.0 - - Slider { ... } - - Note that it's perfectly reasonable for a library to register types - to older versions than the actual version of the library. - Indeed, it is normal for the new library to allow QML written to - previous versions to continue to work, even if more advanced - versions of some of its types are available. diff --git a/sources/pyside6/doc/extras/QtQml.qmlRegisterUncreatableType.rst b/sources/pyside6/doc/extras/QtQml.qmlRegisterUncreatableType.rst deleted file mode 100644 index be25f5f1e..000000000 --- a/sources/pyside6/doc/extras/QtQml.qmlRegisterUncreatableType.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. currentmodule:: PySide6.QtQml -.. _qmlRegisterUncreatableType: - - -qmlRegisterUncreatableType -************************** - - -.. py:function:: qmlRegisterUncreatableType(pytype: type, uri: str, versionMajor: int, versionMinor: int, qmlName: str, noCreationReason: str) -> int - - - :param type pytype: Python class - :param str uri: uri to use while importing the component in QML - :param int versionMajor: major version - :param int versionMinor: minor version - :param str qmlName: name exposed to QML - :param str noCreationReason: Error message shown when trying to create the QML type - :return: int (the QML type id) - - This function registers the Python *type* in the QML system as an uncreatable type with the - name *qmlName*, in the library imported from *uri* having the - version number composed from *versionMajor* and *versionMinor*, - showing *noCreationReason* as an error message when creating the type is attempted. - - For example, this registers a Python class 'MySliderItem' as a QML - type named 'Slider' for version '1.0' of a module called - 'com.mycompany.qmlcomponents': - - :: - qmlRegisterUncreatableType(MySliderItem, "com.mycompany.qmlcomponents", 1, 0, "Slider", "Slider cannot be created.") - - Note that it's perfectly reasonable for a library to register types - to older versions than the actual version of the library. - Indeed, it is normal for the new library to allow QML written to - previous versions to continue to work, even if more advanced - versions of some of its types are available. - - Alternatively, the :ref:`QmlUncreatable` decorator can be used. diff --git a/sources/pyside6/doc/extras/QtQuickTest.rst b/sources/pyside6/doc/extras/QtQuickTest.rst new file mode 100644 index 000000000..52f13590b --- /dev/null +++ b/sources/pyside6/doc/extras/QtQuickTest.rst @@ -0,0 +1,58 @@ + Qt Quick Test is a unit test framework for QML applications. Test cases are + written as JavaScript functions within a QML TestCase type: + +.. code-block:: JavaScript + + import QtQuick + import QtTest + + TestCase { + name: "MathTests" + + function test_math() { + compare(2 + 2, 4, "2 + 2 = 4") + } + + function test_fail() { + compare(2 + 2, 5, "2 + 2 = 5") + } + } + +Functions whose names start with ``test_`` are treated as test cases to be +executed. + +QML API +^^^^^^^ + +The `QML types <https://doc.qt.io/qt-6/qttest-qmlmodule.html>`_ +in Qt Quick Test are available through the ``QtTest`` import. +To use the types, add the following import statement to your ``.qml`` file: + +.. code-block:: JavaScript + + import QtTest + +Running Tests +^^^^^^^^^^^^^ + +Test cases are launched by a harness that consists of the following code: + +.. code-block:: Python + + import sys + from PySide6.QtQuickTest import QUICK_TEST_MAIN + + QUICK_TEST_MAIN("example", sys.argv) + +Where "example" is the identifier to use to uniquely identify this set of +tests. + +Test execution can be controlled by a number of command line options (pass +``-h`` for help). + +Executing Code Before QML Tests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To execute code before any of the QML tests are run, the +:py:func:`QUICK_TEST_MAIN_WITH_SETUP` function can be used. This can be useful +for setting context properties on the QML engine, amongst other things. diff --git a/sources/pyside6/doc/extras/QtUiTools.loadUiType.rst b/sources/pyside6/doc/extras/QtUiTools.loadUiType.rst deleted file mode 100644 index 8a8c4bef0..000000000 --- a/sources/pyside6/doc/extras/QtUiTools.loadUiType.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. currentmodule:: PySide6.QtUiTools -.. _loadUiType: - -loadUiType -*********** - -.. py:function:: loadUiType(uifile: str) -> tuple(object, object) - - :param str uifile: The name of the `.ui` file - :return: tuple(object, object) - - This function generates and loads a `.ui` file at runtime, and it returns - a `tuple` containing the reference to the Python class, and the base class. - - We recommend not to use this approach as the workflow should be to generate a Python file - from the `.ui` file, and then import and load it to use it, but we do understand that - there are some corner cases when such functionality is required. - - The internal process relies on `uic` being in the PATH. - The `pyside6-uic` wrapper uses a shipped `uic` that is located in the - `site-packages/PySide6/uic`, so PATH needs to be updated to use that if there - is no `uic` in the system. - - A simple use case is:: - - from PySide6.QtUiTools import loadUiType - - generated_class, base_class = loadUiType("themewidget.ui") - # the values will be: - # (<class '__main__.Ui_ThemeWidgetForm'>, <class 'PySide6.QtWidgets.QWidget'>) - - widget = base_class() - form = generated_class() - form.setupUi(widget) - # form.a_widget_member.a_method_of_member() - widget.show() diff --git a/sources/pyside6/doc/extras/QtUiTools.rst b/sources/pyside6/doc/extras/QtUiTools.rst index 6861605bb..e83aa0357 100644 --- a/sources/pyside6/doc/extras/QtUiTools.rst +++ b/sources/pyside6/doc/extras/QtUiTools.rst @@ -1,5 +1,5 @@ -Qt Designer forms are processed at run-time to produce -dynamically-generated user interfaces. In order to generate a form at +*Qt Widgets Designer* forms are processed at run-time to produce +dynamically-generated user interfaces. In order to generate a form at run-time, a resource file containing a UI file is needed. A form loader object, provided by the ``QUiLoader`` class, is used to diff --git a/sources/pyside6/doc/extras/QtWidgets.rst b/sources/pyside6/doc/extras/QtWidgets.rst index 8c91d3e31..784421aac 100644 --- a/sources/pyside6/doc/extras/QtWidgets.rst +++ b/sources/pyside6/doc/extras/QtWidgets.rst @@ -52,7 +52,7 @@ widget reports its size requirements to the layout through the :meth:`sizePolicy<PySide6.QtWidgets.QWidget.sizePolicy>` properties, and the layout distributes the available space accordingly. -:ref:`Qt Designer<using_ui_files>` is a powerful tool for interactively +:ref:`Qt Widgets Designer<using_ui_files>` is a powerful tool for interactively creating and arranging widgets in layouts. Model/View Classes |