diff options
Diffstat (limited to 'sources/pyside6/doc/extras')
64 files changed, 2008 insertions, 416 deletions
diff --git a/sources/pyside6/doc/extras/QtBluetooth.rst b/sources/pyside6/doc/extras/QtBluetooth.rst new file mode 100644 index 000000000..965896752 --- /dev/null +++ b/sources/pyside6/doc/extras/QtBluetooth.rst @@ -0,0 +1,102 @@ +Qt Bluetooth enables connectivity between Bluetooth enabled devices. + +The Bluetooth API provides connectivity between Bluetooth enabled devices. + +Currently, the API is supported on the following platforms: + + +-------------------------------------+-------+---+-----------------+-----------------------------------------+--------------+ + |API Feature |Android|iOS|Linux (BlueZ 5.x)|:ref:`macOS<Qt-WebEngine-Platform-Notes>`|Qt for Windows| + +-------------------------------------+-------+---+-----------------+-----------------------------------------+--------------+ + |Classic Bluetooth |x | |x |x |x | + +-------------------------------------+-------+---+-----------------+-----------------------------------------+--------------+ + |Bluetooth LE Central |x |x |x |x |x | + +-------------------------------------+-------+---+-----------------+-----------------------------------------+--------------+ + |Bluetooth LE Peripheral |x |x |x |x | | + +-------------------------------------+-------+---+-----------------+-----------------------------------------+--------------+ + |Bluetooth LE Advertisement & Scanning| | | | | | + +-------------------------------------+-------+---+-----------------+-----------------------------------------+--------------+ + +Qt 5.14 adds a native Win32 port supporting Classic Bluetooth on Windows 7 or +newer, and Bluetooth LE on Windows 8 or newer. It must be enabled at build time +by configuration option -native-win32-bluetooth. The UWP backend is used by +default if this option is not set and the Win32 target platform supports the +required UWP APIs (minimal requirement is Windows 10 version 1507, with +slightly improved service discovery since Windows 10 version 1607). + +Overview +^^^^^^^^ + +Bluetooth is a short-range (less than 100 meters) wireless technology. It has a +reasonably high data transfer rate of 2.1 Mbit/s, which makes it ideal for +transferring data between devices. Bluetooth connectivity is based on basic +device management, such as scanning for devices, gathering information about +them, and exchanging data between them. + +Qt Bluetooth supports Bluetooth Low Energy development for client/central role +use cases. Further details can be found in the :ref:`Bluetooth Low Energy +Overview<Bluetooth-Low-Energy-Overview>` section. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtBluetooth + +macOS Specific +^^^^^^^^^^^^^^ + +The Bluetooth API on macOS requires a certain type of event dispatcher that in +Qt causes a dependency to +:class:`QGuiApplication<PySide6.QtGui.QGuiApplication>` . However, you can set +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`_ is available, +as CoreBluetooth (Bluetooth LE) do not require either of +:class:`QApplication<PySide6.QtWidgets.QApplication>` or +:class:`QGuiApplication<PySide6.QtGui.QGuiApplication>` . + +Guides +^^^^^^ + + * :ref:`Classic Bluetooth Overview<Qt-Bluetooth-Overview>` + * :ref:`Bluetooth Low Energy Overview<Bluetooth-Low-Energy-Overview>` + + +Logging Categories +^^^^^^^^^^^^^^^^^^ + +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`_| + +--------------------+-------------------------------------------------------------+ + |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`_ . More detailed information about logging can be found in +:class:`QLoggingCategory<~.QLoggingCategory>` . A quick way to enable all +`QtBluetooth`_ logging is to add the following line to the ``main()`` +function:: + + 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 new file mode 100644 index 000000000..8f2d768bf --- /dev/null +++ b/sources/pyside6/doc/extras/QtCharts.rst @@ -0,0 +1,21 @@ +The Qt Charts module provides a set of easy-to-use chart components. It uses +the Qt Graphics View Framework to integrate charts with modern user interfaces. +Qt Charts can be used as QWidgets, +:class:`QGraphicsWidget<PySide6.QtWidgets.QGraphicsWidget>` , or QML types. +Users can easily create impressive charts by selecting one of the themes. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +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/QtConcurrent.rst b/sources/pyside6/doc/extras/QtConcurrent.rst new file mode 100644 index 000000000..33c5b3bfb --- /dev/null +++ b/sources/pyside6/doc/extras/QtConcurrent.rst @@ -0,0 +1,37 @@ +The Qt Concurrent module contains functionality to support concurrent execution +of program code. + +The Qt Concurrent module provides high-level APIs that make it possible to +write multi-threaded programs without using low-level threading primitives such +as mutexes, read-write locks, wait conditions, or semaphores. Programs written +with Qt Concurrent automatically adjust the number of threads used according to +the number of processor cores available. This means that applications written +today will continue to scale when deployed on multi-core systems in the future. + +Qt Concurrent includes functional programming style APIs for parallel list +processing, including a MapReduce and FilterReduce implementation for +shared-memory (non-distributed) systems, and classes for managing asynchronous +computations in GUI applications: + + * :class:`QFuture<PySide6.QtCore.QFuture>` represents the result of an + asynchronous computation. + * :class:`QFutureIterator<~.QFutureIterator>` allows iterating through results + available via :class:`QFuture<PySide6.QtCore.QFuture>` . + * :class:`QFutureWatcher<PySide6.QtCore.QFutureWatcher>` allows monitoring a + :class:`QFuture<PySide6.QtCore.QFuture>` using signals-and-slots. + * :class:`QFutureSynchronizer<~.QFutureSynchronizer>` is a convenience class + that automatically synchronizes several QFutures. + * :class:`QPromise<~.QPromise>` provides a way to report progress and results + of the asynchronous computation to :class:`QFuture<PySide6.QtCore.QFuture>` . + Allows suspending or canceling the task when requested by + :class:`QFuture<PySide6.QtCore.QFuture>` . + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtConcurrent diff --git a/sources/pyside6/doc/extras/QtCore.ClassInfo.rst b/sources/pyside6/doc/extras/QtCore.ClassInfo.rst index b767ae153..75445e1fc 100644 --- a/sources/pyside6/doc/extras/QtCore.ClassInfo.rst +++ b/sources/pyside6/doc/extras/QtCore.ClassInfo.rst @@ -1,23 +1,34 @@ .. currentmodule:: PySide6.QtCore -.. _ClassInfo: +.. py:decorator:: ClassInfo -ClassInfo -********* - -This class is used to associates 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. -.. note:: This Class is a implementation of Q_CLASSINFO macro. - +The recommended usage is to provide the key/value using python keyword syntax, where the +keyword becomes the key, and the provided string becomes the value. + +If the key needs to contain special characters (spaces, commas, '::', start with a number, etc), +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 decorator is a implementation of the Q_CLASSINFO macro. + Example ------- -:: +.. code-block:: python + # Recommended syntax @ClassInfo(Author='PySide Team', URL='http://www.pyside.org') class MyObject(QObject): ... + + # Provided to support keys not supported by Python's keyword syntax + @ClassInfo({'Some key text $': 'This syntax supports special characters in keys'}) + class MyObject(QObject): + ... diff --git a/sources/pyside6/doc/extras/QtCore.Property.rst b/sources/pyside6/doc/extras/QtCore.Property.rst index 5eb299f67..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,17 +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. @@ -65,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 @@ -107,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 @@ -120,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 d33134264..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,68 +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): - ... - -We are considering to map all builtin enums and flags to Python enums as well -in a later release. +See :deco:`QFlag` for registering Python Flag 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.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 60c611482..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,30 +7,52 @@ 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=[]]]) + + :param name: str + :param arguments: list + +``Signal`` takes a list of Python types of the arguments. + + It is possible to use the same signal name with different types by + passing a list of tuples representing the signatures, but this is a legacy + technique recommended against in new code (see + :ref:`overloading-signals-and-slots`). + +The optional named argument ``name`` defines the signal name. If nothing is +passed, the new signal will have the same name as the variable that it is +being assigned to. - PySide adopt PyQt's new signal and slot syntax as-is. The PySide implementation is functionally compatible with the PyQt 4.5 one, with the exceptions listed bellow. +The optional named argument ``arguments`` receives a list of strings +denoting the argument names. This is useful for QML applications which +may refer to the emitted values by name. .. method:: Signal.connect(receiver[, type=Qt.AutoConnection]) - Create a connection between this signal and a `receiver`, the `receiver` can be a Python callable, a :class:`Slot` or a :class:`Signal`. + Create a connection between this signal and a `receiver`, the `receiver` + can be a Python callable, a :class:`Slot` or a :class:`Signal`. .. method:: Signal.disconnect(receiver) - Disconnect this signal from a `receiver`, the `receiver` can be a Python callable, a :class:`Slot` or a :class:`Signal`. + Disconnect this signal from a `receiver`, the `receiver` can be a Python + callable, a :class:`Slot` or a :class:`Signal`. .. method:: Signal.emit(*args) `args` is the arguments to pass to any connected slots, if any. +.. seealso:: :ref:`signals-and-slots` diff --git a/sources/pyside6/doc/extras/QtCore.Slot.rst b/sources/pyside6/doc/extras/QtCore.Slot.rst index 268cfa4ad..98a1d465b 100644 --- a/sources/pyside6/doc/extras/QtCore.Slot.rst +++ b/sources/pyside6/doc/extras/QtCore.Slot.rst @@ -1,39 +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()``. + +This implementation is functionally compatible with the PyQt one. + +======= =========== ====== +Module PyQt PySide +======= =========== ====== +QtCore pyqtSignal Signal +QtCore pyqtSlot Slot +======= =========== ====== + +.. 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/QtCore.rst b/sources/pyside6/doc/extras/QtCore.rst index 694fb84e9..ac72bc487 100644 --- a/sources/pyside6/doc/extras/QtCore.rst +++ b/sources/pyside6/doc/extras/QtCore.rst @@ -1,5 +1,61 @@ -All other Qt modules rely on this module. To include the definitions of the module's classes, use the following directive: +The Qt Core module is part of Qt's essential modules. + +The Qt Core module adds these features to C++: + + * a very powerful mechanism for seamless object communication called signals and slots + * queryable and designable object properties + * hierarchical and queryable object trees + +The following pages provide more information about Qt's core features: + + * :ref:`The Meta-Object System<The-Meta-Object-System>` + * :ref:`The Property System<The-Property-System>` + * :ref:`Object Model<Object-Model>` + * :ref:`Object Trees & Ownership<Object-Trees---Ownership>` + * :ref:`Signals & Slots<Signals---Slots>` + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: import PySide6.QtCore + +Threading and Concurrent Programming +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Qt provides thread support in the form of platform-independent +threading classes, a thread-safe way of posting events, and +signal-slot connections across threads. Multithreaded programming is +also a useful paradigm for performing time-consuming operations +without freezing the user interface of an application. + +The Thread Support in Qt page contains information on implementing +threads in applications. Additional concurrent classes are provided by +the :ref:`Qt Concurrent<Qt-Concurrent>` module. + +Input/Output and Resources +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Qt provides a resource system for organizing application files and +assets, a set of containers, and classes for receiving input and +printing output. + + * :ref:`Serializing Qt Data Types<Serializing-Qt-Data-Types>` + +In addition, Qt Core provides a platform-independent mechanism for +storing binary files in the application's executable. + + * :ref:`The Qt Resource System<using_qrc_files>` + +Additional Frameworks +^^^^^^^^^^^^^^^^^^^^^ + +Qt Core also provides some of Qt's key frameworks. + + * :ref:`The Animation Framework<The-Animation-Framework>` + * `JSON Support in Qt <https://doc.qt.io/qt-6/json.html>`_ + * :ref:`The Event System<The-Event-System>` diff --git a/sources/pyside6/doc/extras/QtDBus.rst b/sources/pyside6/doc/extras/QtDBus.rst new file mode 100644 index 000000000..3b9cd775a --- /dev/null +++ b/sources/pyside6/doc/extras/QtDBus.rst @@ -0,0 +1,193 @@ +An introduction to Inter-Process Communication and Remote Procedure +Calling with D-Bus. + +Introduction +^^^^^^^^^^^^ + +D-Bus is an Inter-Process Communication (IPC) and Remote Procedure +Calling (RPC) mechanism originally developed for Linux to replace +existing and competing IPC solutions with one unified protocol. It has +also been designed to allow communication between system-level +processes (such as printer and hardware driver services) and normal +user processes. + +It uses a fast, binary message-passing protocol, which is suitable for +same-machine communication due to its low latency and low overhead. +Its specification is currently defined by the ``freedesktop.org`` +project, and is available to all parties. + +Communication in general happens through a central server application, +called the "bus" (hence the name), but direct +application-to-application communication is also possible. When +communicating on a bus, applications can query which other +applications and services are available, as well as activate one on +demand. + +The Buses +^^^^^^^^^ + +D-Bus buses are used when many-to-many communication is desired. In +order to achieve that, a central server is launched before any +applications can connect to the bus: this server is responsible for +keeping track of the applications that are connected and for properly +routing messages from their source to their destination. + +In addition, D-Bus defines two well-known buses, called the system bus +and the session bus. These buses are special in the sense that they +have well-defined semantics: some services are defined to be found in +one or both of these buses. + +For example, an application wishing to query the list of hardware +devices attached to the computer will probably communicate to a +service available on the system bus, while the service providing +opening of the user's web browser will probably be found on the +session bus. + +On the system bus, one can also expect to find restrictions on what +services each application is allowed to offer. Therefore, one can be +reasonably certain that, if a certain service is present, it is being +offered by a trusted application. + +Messages +^^^^^^^^ + +On the low level, applications communicate over D-Bus by sending +messages to one another. Messages are used to relay the remote +procedure calls as well as the replies and errors associated with +them. When used over a bus, messages have a destination, which means +they are routed only to the interested parties, avoiding congestion +due to "swarming" or broadcasting. + +A special kind of message called a "signal message" (a concept based +on Qt's :ref:`Signals and Slots<Signals---Slots>` mechanism), however, +does not have a pre-defined destination. Since its purpose is to be +used in a one-to-many context, signal messages are designed to work +over an "opt-in" mechanism. + +The Qt D-Bus module fully encapsulates the low-level concept of +messages into a simpler, object-oriented approach familiar to Qt +developers. In most cases, the developer need not worry about sending +or receiving messages. + +Service Names +^^^^^^^^^^^^^ + +When communicating over a bus, applications obtain what is called a +"service name": it is how that application chooses to be known by +other applications on the same bus. The service names are brokered by +the D-Bus bus daemon and are used to route messages from one +application to another. An analogous concept to service names are IP +addresses and hostnames: a computer normally has one IP address and +may have one or more hostnames associated with it, according to the +services that it provides to the network. + +On the other hand, if a bus is not used, service names are also not +used. If we compare this to a computer network again, this would +equate to a point-to-point network: since the peer is known, there is +no need to use hostnames to find it or its IP address. + +The format of a D-Bus service name is in fact very similar to a host +name: it is a dot-separated sequence of letters and digits. The common +practice is even to name one's service name according to the domain +name of the organization that defined that service. + +For example, the D-Bus service is defined by ``freedesktop.org`` and +can be found on the bus under the service name: + + :: + + org.freedesktop.DBus + +Object Paths +^^^^^^^^^^^^ + +Like network hosts, applications provide specific services to other +applications by exporting objects. Those objects are hierarchically +organized, much like the parent-child relationship that classes +derived from :class:`QObject<PySide6.QtCore.QObject>` possess. One +difference, however, is that there is the concept of "root object", +which all objects have as the ultimate parent. + +If we continue our analogy with Web services, object paths equate to +the path part of a URL. + +Like them, object paths in D-Bus are formed resembling path names on +the filesystem: they are slash-separated labels, each consisting of +letters, digits and the underscore character ("\_"). They must always +start with a slash and must not end with one. + +Interfaces +^^^^^^^^^^ + +Interfaces are similar to C++ abstract classes and Java's +``interface`` keyword and declare the "contract" that is established +between caller and callee. That is, they establish the names of the +methods, signals, and properties that are available as well as the +behavior that is expected from either side when communication is +established. + +Qt uses a very similar mechanism in its Plugin system: Base classes in +C++ are associated with a unique identifier by way of the +:meth:`Q\_DECLARE\_INTERFACE()<~QtDBus.Q_DECLARE_INTERFACE>` macro. + +D-Bus interface names are, in fact, named in a manner similar to what +is suggested by the Qt Plugin System: an identifier usually +constructed from the domain name of the entity that defined that +interface. + +Cheat Sheet +^^^^^^^^^^^ + +To facilitate remembering of the naming formats and their purposes, +the following table can be used: + + +-------------+------------------+---------------------------------------+ + |D-Bus Concept|Analogy |Name format | + +-------------+------------------+---------------------------------------+ + |Service name |Network hostnames |Dot-separated ("looks like a hostname")| + +-------------+------------------+---------------------------------------+ + |Object path |URL path component|Slash-separated ("looks like a path") | + +-------------+------------------+---------------------------------------+ + |Interface |Plugin identifier |Dot-separated | + +-------------+------------------+---------------------------------------+ + +Debugging +^^^^^^^^^ + +When developing applications that use D-Bus, it is sometimes useful to +be able to see information about the messages that are sent and +received across the bus by each application. + +This feature can be enabled on a per-application basis by setting the +``QDBUS_DEBUG`` environment variable before running each application. +For example, we can enable debugging only for the car in the +:ref:`D-Bus Remote Controlled Car +Example<D-Bus-Remote-Controlled-Car-Example>` by running the +controller and the car in the following way: + + :: + + QDBUS_DEBUG=1 python examples/dbus/pingpong/pong.py + +Information about the messages will be written to the console the +application was launched from. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtDBus + +Further Reading +^^^^^^^^^^^^^^^ + +The following documents contain information about Qt's D-Bus integration features, and provide details about the mechanisms used to send and receive type information over the bus: + + * `Using Qt D-Bus Adaptors <https://doc.qt.io/qt-6/usingadaptors.html>`_ + * `The Qt D-Bus Type System <https://doc.qt.io/qt-6/qdbustypesystem.html>`_ + * `Qt D-Bus XML compiler (qdbusxml2cpp) <https://doc.qt.io/qt-6/qdbusxml2cpp.html>`_ + * `D-Bus Viewer <https://doc.qt.io/qt-6/qdbusviewer.html>`_ diff --git a/sources/pyside6/doc/extras/QtDataVisualization.rst b/sources/pyside6/doc/extras/QtDataVisualization.rst new file mode 100644 index 000000000..66e2d9523 --- /dev/null +++ b/sources/pyside6/doc/extras/QtDataVisualization.rst @@ -0,0 +1,30 @@ +Provides functionality for 3D visualization. + +The Qt Data Visualization module enables you to visualize data in 3D as bar, +scatter, and surface graphs. It's especially useful for visualizing depth maps +and large quantities of rapidly changing data, such as data received from +multiple sensors. The look and feel of graphs can be customized by using themes +or by adding custom items and labels. + +Qt Data Visualization is built on Qt 6 and OpenGL to take advantage of hardware +acceleration and Qt Quick 2. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtDataVisualization + +The module also provides `QML types <https://doc.qt.io/qt-6/qtdatavisualization-qmlmodule.html>`_ . + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * :ref:`Overview<Qt-Data-Visualization-Overview>` + * :ref:`Data Handling<Qt-Data-Visualization-Data-Handling>` + * :ref:`Interacting with Data<Qt-Data-Visualization-Interacting-with-Data>` + * :ref:`Known Issues<Qt-Data-Visualization-Known-Issues>` 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 new file mode 100644 index 000000000..844f25b7b --- /dev/null +++ b/sources/pyside6/doc/extras/QtDesigner.rst @@ -0,0 +1,18 @@ +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 +run-time. + + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtDesigner diff --git a/sources/pyside6/doc/extras/QtGui.rst b/sources/pyside6/doc/extras/QtGui.rst index d55212bdf..8341ff453 100644 --- a/sources/pyside6/doc/extras/QtGui.rst +++ b/sources/pyside6/doc/extras/QtGui.rst @@ -1,7 +1,142 @@ -To include the definitions of modules classes, use the following directive: +The Qt GUI module provides classes for windowing system integration, +event handling, OpenGL and OpenGL ES integration, 2D graphics, basic +imaging, fonts, and text. These classes are used internally by Qt's +user interface technologies and can also be used directly, for +instance to write applications using low-level OpenGL ES graphics +APIs. + +For application developers writing user interfaces, Qt provides higher +level APIs, like Qt Quick, that are much more suitable than the +enablers found in the Qt GUI module. + +Application Windows +^^^^^^^^^^^^^^^^^^^ + +The most important classes in the Qt GUI module are +:class:`QGuiApplication<PySide6.QtGui.QGuiApplication>` and +:class:`QWindow<PySide6.QtGui.QWindow>` . A Qt application that wants +to show content on screen will need to make use of these. +:class:`QGuiApplication<PySide6.QtGui.QGuiApplication>` contains the +main event loop, where all events from the window system and other +sources are processed and dispatched. It also handles the +application's initialization and finalization. + +The :class:`QWindow<PySide6.QtGui.QWindow>` class represents a window +in the underlying windowing system. It provides a number of virtual +functions to handle events ( :class:`QEvent<PySide6.QtCore.QEvent>` ) +from the windowing system, such as touch-input, exposure, focus, key +strokes, and geometry changes. + +2D Graphics +^^^^^^^^^^^ + +The Qt GUI module contains classes for 2D graphics, imaging, fonts, +and advanced typography. + +A :class:`QWindow<PySide6.QtGui.QWindow>` created with the surface +type :attr:`RasterSurface<QSurface.SurfaceType>` can be used in +combination with :class:`QBackingStore<PySide6.QtGui.QBackingStore>` +and :class:`QPainter<PySide6.QtGui.QPainter>` , Qt's highly optimized +2D vector graphics API. :class:`QPainter<PySide6.QtGui.QPainter>` +supports drawing lines, polygons, vector paths, images, and text. For +more information, see :ref:`Paint System<Paint-System>` and +:ref:`Raster Window Example<Raster-Window-Example>` . + +Qt can load and save images using the +:class:`QImage<PySide6.QtGui.QImage>` and +:class:`QPixmap<PySide6.QtGui.QPixmap>` classes. By default, Qt +supports the most common image formats including JPEG and PNG among +others. Users can add support for additional formats via the +:class:`QImageIOPlugin<~.QImageIOPlugin>` class. For more information, +see :ref:`Reading and Writing Image +Files<Reading-and-Writing-Image-Files>` . + +Typography in Qt is done with +:class:`QTextDocument<PySide6.QtGui.QTextDocument>` , which uses the +:class:`QPainter<PySide6.QtGui.QPainter>` API in combination with Qt's +font classes, primarily :class:`QFont<PySide6.QtGui.QFont>` . +Applications that prefer more low-level APIs to text and font handling +can use classes like :class:`QRawFont<PySide6.QtGui.QRawFont>` and +:class:`QGlyphRun<PySide6.QtGui.QGlyphRun>` . + +OpenGL and OpenGL ES Integration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:class:`QWindow<PySide6.QtGui.QWindow>` supports rendering using +OpenGL and OpenGL ES, depending on what the platform supports. OpenGL +rendering is enabled by setting the +:class:`QWindow<PySide6.QtGui.QWindow>` 's surface type to +:attr:`OpenGLSurface<QSurface.SurfaceType>` , choosing the format +attributes with :class:`QSurfaceFormat<PySide6.QtGui.QSurfaceFormat>` +, and then creating a +:class:`QOpenGLContext<PySide6.QtGui.QOpenGLContext>` to manage the +native OpenGL context. In addition, Qt has +:class:`QOpenGLPaintDevice<PySide6.QtOpenGL.QOpenGLPaintDevice>` , +which enables the use of OpenGL accelerated +:class:`QPainter<PySide6.QtGui.QPainter>` rendering, as well as +convenience classes that simplify the writing of OpenGL code and hides +the complexities of extension handling and the differences between +OpenGL ES 2 and desktop OpenGL. The convenience classes include +:class:`QOpenGLFunctions<PySide6.QtGui.QOpenGLFunctions>` that lets an +application use all the OpenGL ES 2 functions on desktop OpenGL +without having to manually resolve the OpenGL function pointers. This +enables cross-platform development of applications targeting mobile or +embedded devices, and provides classes that wrap native OpenGL +functionality in a simpler Qt API. + +For more information, see the :ref:`OpenGL Window Example<OpenGL-Window-Example>` . + +The Qt GUI module also contains a few math classes to aid with the +most common mathematical operations related to 3D graphics. These +classes include :class:`QMatrix4x4<PySide6.QtGui.QMatrix4x4>` , +:class:`QVector4D<PySide6.QtGui.QVector4D>` , and +:class:`QQuaternion<PySide6.QtGui.QQuaternion>` . + +A :class:`QWindow<PySide6.QtGui.QWindow>` created with the +:attr:`OpenGLSurface<QSurface.SurfaceType>` can be used in combination +with :class:`QPainter<PySide6.QtGui.QPainter>` and +:class:`QOpenGLPaintDevice<PySide6.QtOpenGL.QOpenGLPaintDevice>` to +have OpenGL hardware-accelerated 2D graphics by sacrificing some of +the visual quality. + +Vulkan Integration +^^^^^^^^^^^^^^^^^^ + +Qt GUI has support for the `Vulkan <https://www.khronos.org/vulkan/>`_ +API. Qt applications require the presence of the `LunarG Vulkan SDK +<https://www.lunarg.com/vulkan-sdk/>`_ . + +On Windows, the SDK sets the environment variable ``VULKAN_SDK``\, +which will be detected by the ``configure`` script. + +On Android, Vulkan headers were added in API level 24 of the NDK. + +Relevant classes: + +* QVulkanDeviceFunctions + * :class:`QVulkanExtension<~.QVulkanExtension>` + * QVulkanFunctions + * :class:`QVulkanInfoVector<~.QVulkanInfoVector>` + * :class:`QVulkanInstance<~.QVulkanInstance>` + * :class:`QVulkanWindow<~.QVulkanWindow>` + * :class:`QVulkanWindowRenderer<~.QVulkanWindowRenderer>` + +For more information, see the +:ref:`Hello Vulkan Widget Example<Hello-Vulkan-Widget-Example>` and the +:ref:`Hello Vulkan Window Example<Hello-Vulkan-Window-Example>` . + +Drag and Drop +^^^^^^^^^^^^^ + +Qt GUI includes support for drag and drop. The +:ref:`Drag and Drop<Drag-and-Drop>` overview has more information. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: import PySide6.QtGui - -.. seealso:: :mod:`PySide6.QtCore` diff --git a/sources/pyside6/doc/extras/QtHelp.rst b/sources/pyside6/doc/extras/QtHelp.rst index 845d1f968..f6013486e 100644 --- a/sources/pyside6/doc/extras/QtHelp.rst +++ b/sources/pyside6/doc/extras/QtHelp.rst @@ -1,5 +1,19 @@ -To include the definitions of the module's classes, use the following directive: +The QtHelp module provides classes for integrating online documentation +in applications. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: import PySide6.QtHelp + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + +The classes and tools supplied with Qt to enable developers to include online +help and documentation in their applications are described in more detail in +:ref:`The Qt Help Framework<The-Qt-Help-Framework>` . diff --git a/sources/pyside6/doc/extras/QtMultimedia.rst b/sources/pyside6/doc/extras/QtMultimedia.rst index 9b6b702ce..527c2427b 100644 --- a/sources/pyside6/doc/extras/QtMultimedia.rst +++ b/sources/pyside6/doc/extras/QtMultimedia.rst @@ -1,7 +1,116 @@ -To include the definitions of the module's classes, use the following directive: + .. image:: images/noun_Media_166644.svg + +The Qt Multimedia module provides APIs for playing back and recording audiovisual content + +Qt Multimedia is an add-on module that provides a rich set of QML types and C++ +classes to handle multimedia content. It contains an easy to use API for +playing back audio and video files and rendering those on screen, as well as a +comprehensive API for recording audio and video from the systems cameras and +microphones. + +The functionality of this module is divided into the following submodules: + + + +---------------------------------------------------+-----------------------------------------------+ + |:ref:`Qt Multimedia<Multimedia-Overview>` |Provides API for multimedia-specific use cases.| + +---------------------------------------------------+-----------------------------------------------+ + |:ref:`Qt Multimedia Widgets<Qt-Multimedia-Widgets>`|Provides the widget-based multimedia API. | + +---------------------------------------------------+-----------------------------------------------+ + +Getting started +^^^^^^^^^^^^^^^ + +If you are porting from Qt 5 to Qt 6 see :ref:`Changes to Qt Multimedia<Changes-to-Qt-Multimedia>` . + +To include the definitions of modules classes, use the following +directive: :: import PySide6.QtMultimedia +The module also provides QML `types <https://doc.qt.io/qt-6/qtmultimedia-qmlmodule.html>`_ . + +Overviews and Important Topics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * :ref:`Changes in Qt 6<Changes-to-Qt-Multimedia>` + * :ref:`Multimedia Overview<Multimedia-Overview>` + * :ref:`Audio Overview<Audio-Overview>` + * :ref:`Video Overview<Video-Overview>` + * :ref:`Camera Overview<Camera-Overview>` + * :ref:`Supported Media Formats<Video-Overview>` + +QML Types +^^^^^^^^^ + +The following table outlines some important QML types. + + +------------------+---------------------------------------------------------------------+ + |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 +^^^^^^^^^^^ + +The following table outlines some important C++ Classes + + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |Class |Description | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QMediaPlayer<PySide6.QtMultimedia.QMediaPlayer>` |Playback media from a source. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QVideoWidget<PySide6.QtMultimediaWidgets.QVideoWidget>` |Display video from a media player or a capture session. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QMediaCaptureSession<PySide6.QtMultimedia.QMediaCaptureSession>`|Capture audio and video. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QCamera<PySide6.QtMultimedia.QCamera>` |Access a camera connected to the system | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QAudioInput<PySide6.QtMultimedia.QAudioInput>` |Access an audio input (microphone) connected to the system. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QAudioOutput<PySide6.QtMultimedia.QAudioOutput>` |Access an audio output (speaker, headphone) connected to the system.| + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QImageCapture<PySide6.QtMultimedia.QImageCapture>` |Capture still images with a camera. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QMediaRecorder<PySide6.QtMultimedia.QMediaRecorder>` |Record media content from a capture session. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QVideoSink<PySide6.QtMultimedia.QVideoSink>` |Access and render individual video frames. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ + |:class:`QAudioSink<PySide6.QtMultimedia.QAudioSink>` |Sends raw audio data to an audio output device. | + +------------------------------------------------------------------------+--------------------------------------------------------------------+ +For playback :class:`QMediaPlayer<PySide6.QtMultimedia.QMediaPlayer>` , +:class:`QAudioOutput<PySide6.QtMultimedia.QAudioOutput>` and QVideoOutput +contain all the required functionality. The other classes are used for +capturing audio and video content, where the +:class:`QMediaCaptureSession<PySide6.QtMultimedia.QMediaCaptureSession>` is the +central class managing the whole capture/recording process. diff --git a/sources/pyside6/doc/extras/QtMultimediaWidgets.rst b/sources/pyside6/doc/extras/QtMultimediaWidgets.rst new file mode 100644 index 000000000..510114907 --- /dev/null +++ b/sources/pyside6/doc/extras/QtMultimediaWidgets.rst @@ -0,0 +1,15 @@ +An add-on module which provides multimedia-related widgets. + +Qt Multimedia Widgets provides additional multimedia-related widgets and +controls. The classes expand the capabilities of the +:ref:`Qt Multimedia<Qt-Multimedia>` and :ref:`Qt Widgets<Qt-Widgets>` modules. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtMultimediaWidgets diff --git a/sources/pyside6/doc/extras/QtNetwork.rst b/sources/pyside6/doc/extras/QtNetwork.rst index 070ab77f7..18d8b3db2 100644 --- a/sources/pyside6/doc/extras/QtNetwork.rst +++ b/sources/pyside6/doc/extras/QtNetwork.rst @@ -1,5 +1,30 @@ -To include the definitions of the module's classes, use the following directive: +Provides networking capabilities + +The Qt Network module provides a set of APIs for programming applications that +use TCP/IP. Operations such as requests, cookies, and sending data over HTTP +are handled by various Python classes. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: import PySide6.QtNetwork + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + +These articles contain information about Qt Network setup and about applications with networking capabilities. + + + * :ref:`Network Programming with Qt<Network-Programming-with-Qt>` - Programming applications + with networking capabilities + * :ref:`Secure Sockets Layer (SSL) Classes<Secure-Sockets-Layer--SSL--Classes>` - Classes + for secure communication over network sockets + +Also note shipping OpenSSL might cause +`Import and Export Restrictions <https://doc.qt.io/qt-6/ssl.html#import-and-export-restrictions>`_ +to apply. diff --git a/sources/pyside6/doc/extras/QtNetworkAuth.rst b/sources/pyside6/doc/extras/QtNetworkAuth.rst new file mode 100644 index 000000000..1947d5ba4 --- /dev/null +++ b/sources/pyside6/doc/extras/QtNetworkAuth.rst @@ -0,0 +1,37 @@ +Provides network authorization capabilities (OAuth). + +Qt Network Authorization provides a set of APIs that enable Qt applications to +obtain limited access to online accounts and HTTP services without exposing +users' passwords. + +Currently, the supported authorization protocol is `OAuth <https://oauth.net>`_ +, versions 1 and 2. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtNetworkAuth + +Overview +^^^^^^^^ + +The goal of this module is to provide a way to handle different authentication +methods present on the Internet. + +There are several authentication systems, including: + + * `OAuth 1 <https://datatracker.ietf.org/doc/html/rfc5849>`_ + * `OAuth 2 <https://datatracker.ietf.org/doc/html/rfc6749>`_ + * `OpenID <http://openid.net>`_ + * `OpenID Connect <http://openid.net/connect/>`_ + +These systems allow the application developers to create applications which use +external authentication servers provided by an *Authorization Server*\. Users +of these services need not worry about passing their credentials to suspicious +applications. Instead, the credentials are entered in a known and trusted web +interface. diff --git a/sources/pyside6/doc/extras/QtNfc.rst b/sources/pyside6/doc/extras/QtNfc.rst new file mode 100644 index 000000000..9cd0181f0 --- /dev/null +++ b/sources/pyside6/doc/extras/QtNfc.rst @@ -0,0 +1,31 @@ +Enables connectivity between NFC enabled devices. + +The NFC API provides connectivity between NFC enabled devices. + +Overview +^^^^^^^^ + +NFC is an extremely short-range (less than 20 centimeters) wireless technology +and has a maximum transfer rate of 424 kbit/s. NFC is ideal for transferring +small packets of data when two devices are touched together. + +The NFC API provides APIs for interacting with NFC Forum Tags and NFC Forum +Devices, including target detection and loss, registering NDEF message +handlers, reading and writing NDEF messages on NFC Forum Tags and sending tag +specific commands. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtNfc + +Guides +^^^^^^ + + * `Qt NFC Overview <https://doc.qt.io/qt-6/qtnfc-overview.html>`_ + * `Qt NFC on Android <https://doc.qt.io/qt-6/nfc-android.html>`_ diff --git a/sources/pyside6/doc/extras/QtOpenGL.rst b/sources/pyside6/doc/extras/QtOpenGL.rst index 9979f9f03..aa699a7d7 100644 --- a/sources/pyside6/doc/extras/QtOpenGL.rst +++ b/sources/pyside6/doc/extras/QtOpenGL.rst @@ -1,14 +1,26 @@ -OpenGL is a standard API for rendering 3D graphics. OpenGL only deals with 3D rendering and provides little or no support for GUI programming issues. The user interface for an OpenGL application must be created with another toolkit, such as Motif on the X platform, Microsoft Foundation Classes (MFC) under Windows, or Qt on both platforms. +OpenGL is a standard API for rendering 3D graphics. OpenGL only deals +with 3D rendering and provides little or no support for GUI +programming issues. The user interface for an OpenGL application must +be created with another toolkit, such as XCB on the X platform, +Microsoft Foundation Classes (MFC) under Windows, or Qt on both +platforms. .. note:: OpenGL is a trademark of Silicon Graphics, Inc. in the United States and other countries. -The Qt OpenGL module makes it easy to use OpenGL in Qt applications. It provides an OpenGL widget class that can be used just like any other Qt widget, except that it opens an OpenGL display buffer where you can use the OpenGL API to render the contents. -To include the definitions of the module's classes, use the following directive: +The Qt OpenGL module makes it easy to use OpenGL in Qt applications. +To include the definitions of the module's classes, use the following +directive: :: import PySide6.QtOpenGL -The Qt OpenGL module is implemented as a platform-independent wrapper around the platform-dependent GLX (version 1.3 or later), WGL, or AGL C APIs. Although the basic functionality provided is very similar to Mark Kilgard's GLUT library, applications using the Qt OpenGL module can take advantage of the whole Qt API for non-OpenGL-specific GUI functionality. +The Qt OpenGL module is implemented as a platform-independent wrapper +around the platform-dependent GLX (version 1.3 or later), WGL, or AGL +C APIs. Applications using the Qt OpenGL module can take advantage of +the whole Qt API for non-OpenGL-specific GUI functionality. + +The QtOpenGL module is available on Windows, X11 and Mac OS X. Qt for +Embedded Linux and OpenGL supports OpenGL ES (OpenGL for Embedded +Systems). -The QtOpenGL module is available on Windows, X11 and Mac OS X. Qt for Embedded Linux and OpenGL supports OpenGL ES (OpenGL for Embedded Systems).
\ No newline at end of file diff --git a/sources/pyside6/doc/extras/QtOpenGLWidgets.rst b/sources/pyside6/doc/extras/QtOpenGLWidgets.rst new file mode 100644 index 000000000..d40b89d71 --- /dev/null +++ b/sources/pyside6/doc/extras/QtOpenGLWidgets.rst @@ -0,0 +1,8 @@ +The Qt OpenGL provides the OpenGL widget class that can be used just like any +other Qt widget, except that it opens an OpenGL display buffer where you can +use the OpenGL API to render the contents. To include the definitions of +the module's classes, use the following directive: + +:: + + import PySide6.QtOpenGLWidgets diff --git a/sources/pyside6/doc/extras/QtPositioning.rst b/sources/pyside6/doc/extras/QtPositioning.rst new file mode 100644 index 000000000..800e369fa --- /dev/null +++ b/sources/pyside6/doc/extras/QtPositioning.rst @@ -0,0 +1,40 @@ +The Qt Positioning API provides positioning information via QML and Python interfaces. + +Currently the API is supported on Android, iOS, macOS, Linux, and Windows (with +GPS receivers exposed as a serial port providing NMEA sentences or using +``Windows.Devices.Geolocation``\). + +Overview +^^^^^^^^ + +The Qt Positioning API gives developers the ability to determine a position by +using a variety of possible sources, including satellite, or wifi, or text +file, and so on. That information can then be used to for example determine a +position on a map. In addition satellite information can be retrieved and area +based monitoring can be performed. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtPositioning + +The module also provides `QML types <https://doc.qt.io/qt-6/qtpositioning-qmlmodule.html>`_ . + +To load the Qt Positioning module, add the following statement to your .qml files + + :: + + import QtPositioning + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * :ref:`Positioning introduction for C++<Positioning--C--->` + * :ref:`Positioning introduction for QML<Positioning--QML->` + * :ref:`Qt Positioning Plugins<Qt-Positioning-Plugins>` + * :ref:`Interfaces between C++ and QML Code in Qt Positioning<Interfaces-between-C---and-QML-Code-in-Qt-Positioning>` diff --git a/sources/pyside6/doc/extras/QtPrintSupport.rst b/sources/pyside6/doc/extras/QtPrintSupport.rst new file mode 100644 index 000000000..146ef6a9f --- /dev/null +++ b/sources/pyside6/doc/extras/QtPrintSupport.rst @@ -0,0 +1,15 @@ +The Qt Print Support module provides extensive cross-platform support for +printing. Using the printing systems on each platform, Qt applications can +print to attached printers and across networks to remote printers. The printing +system also supports PDF file generation, providing the foundation for basic +report generation facilities. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtPrintSupport 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 new file mode 100644 index 000000000..10dde6b9a --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QPyQmlParserStatus.rst @@ -0,0 +1,9 @@ +.. currentmodule:: PySide6.QtQml +.. py:class:: QPyQmlParserStatus + +QPyQmlParserStatus is the base class for implementing +`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 new file mode 100644 index 000000000..bf7f8e98f --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QPyQmlPropertyValueSource.rst @@ -0,0 +1,9 @@ +.. currentmodule:: PySide6.QtQml +.. py:class:: QPyQmlPropertyValueSource + +QPyQmlPropertyValueSource is the base class for implementing +`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 new file mode 100644 index 000000000..44aa0ea21 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlAnonymous.rst @@ -0,0 +1,17 @@ +.. currentmodule:: PySide6.QtQml +.. 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++. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + @QmlAnonymous + class ClassForQml(QObject): + # ... diff --git a/sources/pyside6/doc/extras/QtQml.QmlAttached.rst b/sources/pyside6/doc/extras/QtQml.QmlAttached.rst new file mode 100644 index 000000000..4331b03f9 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlAttached.rst @@ -0,0 +1,35 @@ +.. currentmodule:: PySide6.QtQml +.. py:decorator:: QmlAttached + +This decorator declares that the enclosing type attaches the type passed as +an attached property to other types. This takes effect if the type is exposed +to QML using a ``QmlElement()`` or ``@QmlNamedElement()`` decorator. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + @QmlAnonymous + class LayoutAttached(QObject): + @Property(QMargins) + def margins(self): + ... + + @QmlElement() + @QmlAttached(LayoutAttached) + class Layout(QObject): + ... + +Afterwards the class may be used in QML: + +.. code-block:: javascript + + import com.library.name 1.0 + + Layout { + Widget { + Layout.margins: [2, 2, 2, 2] + } + } 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 new file mode 100644 index 000000000..af113a9c8 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlExtended.rst @@ -0,0 +1,32 @@ +.. currentmodule:: PySide6.QtQml +.. py:decorator:: QmlExtended + +Declares that the enclosing type uses the type passed as an extension to +provide further properties, methods, and enumerations in QML. This takes effect +if the type is exposed to QML using a ``QmlElement()`` or ``QmlNamedElement()`` +decorator. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + class LineEditExtension(QObject): + pass + + @QmlNamedElement("QLineEdit") + @QmlExtended(LineEditExtension) + @QmlForeign(QLineEdit) + class LineEditForeign(QObject): + ... + +Afterwards the class may be used in QML: + +.. code-block:: javascript + + import com.library.name 1.0 + + QLineEdit { + left_margin: 10 + } diff --git a/sources/pyside6/doc/extras/QtQml.QmlForeign.rst b/sources/pyside6/doc/extras/QtQml.QmlForeign.rst new file mode 100644 index 000000000..90b821e9b --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlForeign.rst @@ -0,0 +1,28 @@ +.. currentmodule:: PySide6.QtQml +.. py:decorator:: QmlForeign + +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. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + @QmlNamedElement("QWidget") + @QmlForeign(QWidget) + class ForeignWidgetHelperClass(QObject): + ... + +Afterwards the class may be used in QML: + +.. code-block:: javascript + + import com.library.name 1.0 + + QWidget { + // ... + } diff --git a/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst b/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst new file mode 100644 index 000000000..79eb9d7ad --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlNamedElement.rst @@ -0,0 +1,26 @@ +.. currentmodule:: PySide6.QtQml +.. 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. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + @QmlNamedElement("ClassForQml") + class ClassWithSomeName(QObject): + ... + +Afterwards the class may be used in QML: + +.. code-block:: javascript + + import com.library.name 1.0 + + ClassForQml { + // ... + } diff --git a/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst b/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst new file mode 100644 index 000000000..402c18d55 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlSingleton.rst @@ -0,0 +1,33 @@ +.. currentmodule:: PySide6.QtQml +.. py:decorator:: QmlSingleton + +Declares the decorated type to be a singleton in QML. This only takes effect if +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. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + @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 new file mode 100644 index 000000000..b7a28801f --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.QmlUncreatable.rst @@ -0,0 +1,26 @@ +.. currentmodule:: PySide6.QtQml +.. py:decorator:: QmlUncreatable + +Declares that the decorated type shall not be creatable from QML. This takes +effect if the type is available in QML, by a preceding ``QmlElement`` +decorator. The reason will be emitted as error message if an attempt to create +the type from QML is detected. + +Some QML types are implicitly uncreatable, in particular types exposed with +``QmlAnonymous``. + +Passing None or no argument will cause a standard message to be used instead. + +.. code-block:: python + + QML_IMPORT_NAME = "com.library.name" + QML_IMPORT_MAJOR_VERSION = 1 + QML_IMPORT_MINOR_VERSION = 0 # Optional + + + @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.qmlRegisterSingletonType.rst b/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonType.rst deleted file mode 100644 index 83102bf86..000000000 --- a/sources/pyside6/doc/extras/QtQml.qmlRegisterSingletonType.rst +++ /dev/null @@ -1,44 +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. - -.. 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 2f34cd987..000000000 --- a/sources/pyside6/doc/extras/QtQml.qmlRegisterUncreatableType.rst +++ /dev/null @@ -1,36 +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. diff --git a/sources/pyside6/doc/extras/QtQml.rst b/sources/pyside6/doc/extras/QtQml.rst new file mode 100644 index 000000000..66f736f02 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQml.rst @@ -0,0 +1,75 @@ +The Qt QML module defines and implements the QML language + +The Qt QML module provides a framework for developing applications and +libraries with the QML language. It defines and implements the language and +engine infrastructure, and provides an API to enable application developers to +extend the QML language with custom types and integrate QML code with +JavaScript and C++. The Qt QML module provides both a `QML API +<https://doc.qt.io/qt-6/qtqml-qmlmodule.html>`_ and a `C++ API +<https://doc.qt.io/qt-6/qtqml-module.html>`_ . + +Note that while the Qt QML module provides the language and infrastructure for +QML applications, the :ref:`Qt Quick<Qt-Quick>` module provides many visual +components, model-view support, an animation framework, and much more for +building user interfaces. + +For those new to QML and Qt Quick, please see QML Applications for an +introduction to writing QML applications. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtQml + +The module also provides `QML types <https://doc.qt.io/qt-6/qtqml-qmlmodule.html>`_ . + +QML and QML Types +^^^^^^^^^^^^^^^^^ + +The Qt QML module contains the QML framework and important QML types used in +applications. The constructs of QML are described in the +:ref:`The QML Reference<The-QML-Reference>` . + +In addition to the :ref:`QML Basic Types<QML-Basic-Types>` , the module comes +with the following QML object types: + + * `Component <https://doc.qt.io/qt-6/qml-qtqml-component.html>`_ + * `QtObject <https://doc.qt.io/qt-6/qml-qtqml-qtobject.html>`_ + * `Binding <https://doc.qt.io/qt-6/qml-qtqml-binding.html>`_ + * `Connections <https://doc.qt.io/qt-6/qml-qtqml-connections.html>`_ + * `Timer <https://doc.qt.io/qt-6/qml-qtqml-timer.html>`_ + +The `Qt <https://doc.qt.io/qt-6/qml-qtqml-qt.html>`_ global object provides +useful enums and functions for various QML types. + +Lists and Models +^^^^^^^^^^^^^^^^ + +New in Qt 5.1, the model types are moved to a submodule, ``QtQml.Models``\. The +Qt QML Models page has more information. + + * DelegateModel + * DelegateModelGroup + * ListElement + * ListModel + * ObjectModel + +JavaScript Environment for QML Applications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +JavaScript expressions allow QML code to contain application logic. Qt QML +provides the framework for running JavaScript expressions in QML and from C++. + +These sections are from :ref:`The QML Reference<The-QML-Reference>` . + + * `Integrating QML and JavaScript <https://doc.qt.io/qt-6/qtqml-javascript-topic.html>`_ + * `Using JavaScript Expressions with QML <https://doc.qt.io/qt-6/qtqml-javascript-expressions.html>`_ + * `Dynamic QML Object Creation from JavaScript <https://doc.qt.io/qt-6/qtqml-javascript-dynamicobjectcreation.html>`_ + * `Defining JavaScript Resources In QML <https://doc.qt.io/qt-6/qtqml-javascript-resources.html>`_ + * `Importing JavaScript Resources In QML <https://doc.qt.io/qt-6/qtqml-javascript-imports.html>`_ + * `JavaScript Host Environment <https://doc.qt.io/qt-6/qtqml-javascript-hostenvironment.html>`_ diff --git a/sources/pyside6/doc/extras/QtQuickControls2.rst b/sources/pyside6/doc/extras/QtQuickControls2.rst new file mode 100644 index 000000000..dba542045 --- /dev/null +++ b/sources/pyside6/doc/extras/QtQuickControls2.rst @@ -0,0 +1,45 @@ +Provides a set of UI controls for Qt Quick. + +Qt Quick Controls provides a set of controls that can be used to build complete +interfaces in Qt Quick. The module was introduced in Qt 5.7. + + .. image:: images/qtquickcontrols2-styles.png + +Qt Quick Controls comes with a selection customizable styles. See +:ref:`Styling Qt Quick Controls<Styling-Qt-Quick-Controls>` for more details. + + .. _QtQuickControls2_using-the-module: + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtQuickControls2 + +Versions +^^^^^^^^ + +Qt Quick Controls 2.0 was introduced in Qt 5.7. Subsequent minor Qt releases +increment the import version of the Qt Quick Controls modules by one, until Qt +5.12, where the import versions match Qt's minor version. + +In Qt 6, both the major and minor versions match, and version numbers may be +omitted from imports in QML. If the version is omitted, the latest version will +be used. + +Topics +^^^^^^ + + * `Getting Started <https://doc.qt.io/qt-6/qtquickcontrols2-gettingstarted.html>`_ + * `Guidelines <https://doc.qt.io/qt-6/qtquickcontrols2-guidelines.html>`_ + * `Styling <https://doc.qt.io/qt-6/qtquickcontrols2-styles.html>`_ + * `Icons <https://doc.qt.io/qt-6/qtquickcontrols2-icons.html>`_ + * `Customization <https://doc.qt.io/qt-6/qtquickcontrols2-customize.html>`_ + * `Using File Selectors <https://doc.qt.io/qt-6/qtquickcontrols2-fileselectors.html>`_ + * `Deployment <https://doc.qt.io/qt-6/qtquickcontrols2-deployment.html>`_ + * `Configuration File <https://doc.qt.io/qt-6/qtquickcontrols2-configuration.html>`_ + * `Environment Variables <https://doc.qt.io/qt-6/qtquickcontrols2-environment.html>`_ 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/QtRemoteObjects.rst b/sources/pyside6/doc/extras/QtRemoteObjects.rst new file mode 100644 index 000000000..7a8eb76a3 --- /dev/null +++ b/sources/pyside6/doc/extras/QtRemoteObjects.rst @@ -0,0 +1,101 @@ +Provides APIs for inter-process communication. + +Remote Object Concepts +^^^^^^^^^^^^^^^^^^^^^^ + +Qt Remote Objects (QtRO) is an Inter-Process Communication (IPC) module +developed for Qt. This module extends Qt's existing functionalities to enable +information exchange between processes or computers, easily. + +One of Qt's key features, to enable this information exchange, is the +distinction between an object's API (defined by its properties, signals, and +slots) and the implementation of that API. QtRO's purpose is to meet that +expected API, even if the true :class:`QObject<PySide6.QtCore.QObject>` is in a +different process. A slot called on a copy of an object (the +:ref:`Replica<Qt-Remote-Objects-Replica>` in QtRO) is forwarded to the true +object (the :ref:`Source<Qt-Remote-Objects-Source>` in QtRO) for handling. +Every Replica receives updates to the Source, either property changes or +emitted signals. + +A :ref:`Replica<Qt-Remote-Objects-Replica>` is a light-weight proxy for the +:ref:`Source<Qt-Remote-Objects-Source>` object, but a Replica supports the same +connections and behavior of QObjects, which makes it usable in the same way as +any other :class:`QObject<PySide6.QtCore.QObject>` that Qt provides. Behind the +scenes, QtRO handles everything that's necessary for the Replica to look like +its Source. + +Note that Remote Objects behave differently from traditional Remote Procedure +Call (RPC) implementations, for example: + + * In RPC, the client makes a request and waits for the response. + * In RPC, the server doesn't push anything to the client unless it's in response to a request. + * Often, the design of RPC is such that different clients are independent of each other: + for instance, two clients can ask a mapping service for directions and get + different results. + +While it is possible to implement this RPC-style behavior in QtRO, as Sources +without properties, and slots that have return values, QtRO hides the fact that +the processing is really remote. You let a node give you the Replica instead of +creating it yourself, possibly use the status signals ( +:meth:`isReplicaValid()<PySide6.QtRemoteObjects.QRemoteObjectReplica.isReplicaValid>` +), but then interact with the object like you would with any other +:class:`QObject<PySide6.QtCore.QObject>` -based type. + +Use Case: GPS +^^^^^^^^^^^^^ + +Consider a sensor such as a Global Positioning System (GPS) receiver. In QtRO terms: + + * The :ref:`Source<Qt-Remote-Objects-Source>` would be the process that directly + interacts with the GPS hardware and derives your current location. + * The location would be exposed as :class:`QObject<PySide6.QtCore.QObject>` properties; + the periodic updates to the location would update these properties and emit property + changed signals. + * :ref:`Replicas<Qt-Remote-Objects-Replica>` would be created in other processes + and would always know your current location, but wouldn't need any of the logic + to compute the location from the sensor data. + * Connecting to the location changed signal on the Replica would work as + expected: the signal emitted from the Source would trigger the signal + emission on every Replica. + +Use Case: Printer Access +^^^^^^^^^^^^^^^^^^^^^^^^ + +Consider a service that provides access to a printer. In QtRO terms: + + * The :ref:`Source<Qt-Remote-Objects-Source>` would be the process + controlling the printer directly. + * The ink levels and printer status would be monitored by + :class:`QObject<PySide6.QtCore.QObject>` properties. Updates to these + properties would emit property changed signals. + * The key feature -- being able to print something -- needs to be passed + back to the printer. Incidentally, this aligns with the Qt slot mechanism, + which QtRO uses as the way for :ref:`Replicas<Qt-Remote-Objects-Replica>` + to make calls on the Source. In effect, properties and signals go from Source + to Replicas; slots go from Replica to Source. + * When a print request is accepted, the printer status would change, + triggering a change in the status property. This would then be reported + to all Replicas. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtRemoteObjects + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * `Getting Started with Qt Remote Objects <https://doc.qt.io/qt-6/qtremoteobjects-gettingstarted.html>`_ + * `Nodes <https://doc.qt.io/qt-6/qtremoteobjects-node.html>`_ + * `Sources <https://doc.qt.io/qt-6/qtremoteobjects-source.html>`_ + * `Replicas <https://doc.qt.io/qt-6/qtremoteobjects-replica.html>`_ + * `Registry <https://doc.qt.io/qt-6/qtremoteobjects-registry.html>`_ + * `Compiler <https://doc.qt.io/qt-6/qtremoteobjects-repc.html>`_ + * `Remote Object Interaction <https://doc.qt.io/qt-6/qtremoteobjects-interaction.html>`__ + * `Troubleshooting <https://doc.qt.io/qt-6/qtremoteobjects-troubleshooting.html>`_ + * `Protocol Versioning <https://doc.qt.io/qt-6/qtremoteobjects-compatibility.html>`_ diff --git a/sources/pyside6/doc/extras/QtScript.rst b/sources/pyside6/doc/extras/QtScript.rst deleted file mode 100644 index 1d2a1bd04..000000000 --- a/sources/pyside6/doc/extras/QtScript.rst +++ /dev/null @@ -1,21 +0,0 @@ -The QtScript module only provides core scripting facilities; the QtScriptTools module provides additional Qt Script-related components that application developers may find useful. - -To include the definitions of the module's classes, use the following directive: - -:: - - import PySide6.QtScript - -License Information -------------------- - -Qt Commercial Edition licensees that wish to distribute applications that use the QtScript module need to be aware of their obligations under the GNU Library General Public License (LGPL). - -Developers using the Open Source Edition can choose to redistribute the module under the appropriate version of the GNU LGPL. -QtScript is licensed under the GNU Library General Public License. Individual contributor names and copyright dates can be found inline in the code. - -This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - -This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. - -You should have received a copy of the GNU Library General Public License along with this library; see the file COPYING.LIB. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. diff --git a/sources/pyside6/doc/extras/QtScriptTools.rst b/sources/pyside6/doc/extras/QtScriptTools.rst deleted file mode 100644 index 8f0c7e12b..000000000 --- a/sources/pyside6/doc/extras/QtScriptTools.rst +++ /dev/null @@ -1,5 +0,0 @@ -Applications that use the Qt Script Tools classes need to be configured to be built against the QtScriptTools module. To include the definitions of the module's classes, use the following directive: - -:: - - import PySide6.QtScriptTools diff --git a/sources/pyside6/doc/extras/QtScxml.rst b/sources/pyside6/doc/extras/QtScxml.rst new file mode 100644 index 000000000..e757bfd58 --- /dev/null +++ b/sources/pyside6/doc/extras/QtScxml.rst @@ -0,0 +1,25 @@ +Provides functionality to create state machines from SCXML files. + +The Qt SCXML module provides functionality to create state machines from +`SCXML <http://www.w3.org/TR/scxml/>`_ files. This includes both dynamically +creating state machines (loading the SCXML file and instantiating states and +transitions) and generating a C++ file that has a class implementing the state +machine. It also contains functionality to support data models and executable +content. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtScxml + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * `Qt SCXML Overview <https://doc.qt.io/qt-6/qtscxml-overview.html>`_ + * `Instantiating State Machines <https://doc.qt.io/qt-6/qtscxml-instantiating-state-machines.html>`_ + * `SCXML Compliance <https://doc.qt.io/qt-6/qtscxml-scxml-compliance.html>`_ diff --git a/sources/pyside6/doc/extras/QtSensors.rst b/sources/pyside6/doc/extras/QtSensors.rst new file mode 100644 index 000000000..03a4d5477 --- /dev/null +++ b/sources/pyside6/doc/extras/QtSensors.rst @@ -0,0 +1,19 @@ + +The Qt Sensors API provides access to sensor hardware via QML and Python +interfaces. + +Currently the API is supported on Android, iOS, and Windows (MSVC). + +Information for Application Writers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Applications can access Qt Sensors using QML or Python. + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtSensors + +The module also provides `QML types <https://doc.qt.io/qt-6/qtsensors-qmlmodule.html>`_ . diff --git a/sources/pyside6/doc/extras/QtSerialBus.rst b/sources/pyside6/doc/extras/QtSerialBus.rst new file mode 100644 index 000000000..a6493a2ae --- /dev/null +++ b/sources/pyside6/doc/extras/QtSerialBus.rst @@ -0,0 +1,46 @@ +The Qt Serial Bus API provides classes and functions to access the various +industrial serial buses and protocols, such as CAN, ModBus, and others. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtSerialBus + +Supported Buses and Protocols +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * Qt CAN Bus + * Qt Modbus + +Logging Categories +^^^^^^^^^^^^^^^^^^ + +The QtSerialBus module exports the following logging categories: + +.. list-table:: + :header-rows: 1 + + * - Logging Category + - Description + * - qt.canbus + - Enables standard logging inside the Qt CAN Bus classes + * - qt.canbus.plugins + - Enables low level logging inside the Qt CAN Bus plugin classes. To set logging for a specific plugin, use ``qt.canbus.plugins.pluginname``, e.g. ``qt.canbus.plugins.socketcan``. ``qt.canbus.plugins*`` affects all plugins. + * - qt.modbus + - Enables standard logging inside the Qt Modbus classes + * - qt.modbus.lowlevel + - Enables low level logging including individual packet content inside the Qt Modbus classes + +Logging categories can be used to enable additional warning and debug output +for QtSerialBus. + +A quick way to enable all Qt Modbus logging is to add the following line: + +.. code-block:: python + + QLoggingCategory.setFilterRules("qt.modbus* = true") diff --git a/sources/pyside6/doc/extras/QtSerialPort.rst b/sources/pyside6/doc/extras/QtSerialPort.rst new file mode 100644 index 000000000..1b20039c3 --- /dev/null +++ b/sources/pyside6/doc/extras/QtSerialPort.rst @@ -0,0 +1,18 @@ +Provides an API to make serial programming simple and portable. + +Qt Serial Port provides the basic functionality, which includes configuring, +I/O operations, getting and setting the control signals of the RS-232 pinouts. + +The following items are not supported by this module: + + * Terminal features, such as echo, control CR/LF, and so on. + * Text mode. + * Configuring timeouts and delays while reading or writing. + * Pinout signal change notification. + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtSerialPort diff --git a/sources/pyside6/doc/extras/QtSql.rst b/sources/pyside6/doc/extras/QtSql.rst index fb62f887c..f3374edc8 100644 --- a/sources/pyside6/doc/extras/QtSql.rst +++ b/sources/pyside6/doc/extras/QtSql.rst @@ -1,4 +1,20 @@ -To include the definitions of the module's classes, use the following directive: +Provides a driver layer, SQL API layer, and a user interface layer for SQL databases + +The Qt SQL module provides support for SQL databases. Qt SQL's APIs are divided +into different layers: + + * Driver layer + * SQL API layer + * User interface layer + +The :ref:`SQL Programming<SQL-Programming>` guide contains information about +development using Qt SQL. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: diff --git a/sources/pyside6/doc/extras/QtSvg.rst b/sources/pyside6/doc/extras/QtSvg.rst index eae02c41e..d652841a6 100644 --- a/sources/pyside6/doc/extras/QtSvg.rst +++ b/sources/pyside6/doc/extras/QtSvg.rst @@ -1,5 +1,21 @@ -To include the definitions of the module's classes, use the following directive: +Qt SVG provides functionality for handling SVG images. + +Scalable Vector Graphics (SVG) is an XML-based language for describing +two-dimensional vector graphics. Qt provides classes for rendering and +displaying SVG drawings in widgets and on other paint devices. + + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: import PySide6.QtSvg + +Articles +^^^^^^^^ + + * :ref:`Rendering SVG Files<Rendering-SVG-Files>` contains information about how to render SVG files diff --git a/sources/pyside6/doc/extras/QtTest.rst b/sources/pyside6/doc/extras/QtTest.rst index 1b3f98940..cebd5a053 100644 --- a/sources/pyside6/doc/extras/QtTest.rst +++ b/sources/pyside6/doc/extras/QtTest.rst @@ -4,4 +4,4 @@ To include the definitions of the module's classes, use the following directive: import PySide6.QtTest -.. note:: All macros in the C++ version of QtTest were not binded in PySide, this module is useful only for GUI testing and benchmarking, for ordinary unit testing you should use the ``unittest`` Python module. +.. note:: Not all macros in the C++ version of QtTest were exposed in PySide. This module is useful only for GUI testing and benchmarking; for ordinary unit testing you should use the ``pytest`` Python module. 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 2769da4d6..e83aa0357 100644 --- a/sources/pyside6/doc/extras/QtUiTools.rst +++ b/sources/pyside6/doc/extras/QtUiTools.rst @@ -1,6 +1,14 @@ -These 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. +*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 construct the user interface. This user interface can be retrieved from any QIODevice; for example, a QFile object can be used to obtain a form stored in a project's resources. The :meth:`PySide6.QtUiTools.QUiLoader.load` function takes the user interface description contained in the file and constructs the form widget. +A form loader object, provided by the ``QUiLoader`` class, is used to +construct the user interface. This user interface can be retrieved +from any ``QIODevice``; for example, a ``QFile`` object can be used to obtain +a form stored in a project's resources. The +:meth:`PySide6.QtUiTools.QUiLoader.load` function takes the user +interface description contained in the file and constructs the form +widget. To include the definitions of the module's classes, use the following directive: diff --git a/sources/pyside6/doc/extras/QtWebChannel.rst b/sources/pyside6/doc/extras/QtWebChannel.rst new file mode 100644 index 000000000..5207a3486 --- /dev/null +++ b/sources/pyside6/doc/extras/QtWebChannel.rst @@ -0,0 +1,30 @@ +Bridges the gap between Qt applications and HTML/JavaScript. + +Qt WebChannel enables peer-to-peer communication between a server (QML/Python +application) and a client (HTML/JavaScript or QML application). It is supported +out of the box by :ref:`Qt WebEngine<Qt-WebEngine>` . In addition it can work +on all browsers that support :ref:`WebSockets<Qt-WebSockets>` , enabling Qt +WebChannel clients to run in any JavaScript environment (including QML). This +requires the implementation of a custom transport based on Qt WebSockets. + +The module provides a JavaScript library for seamless integration of Python and +QML applications with HTML/JavaScript and QML clients. The clients must use the +JavaScript library to access the serialized QObjects published by the host +applications. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtWebChannel + +API Reference +^^^^^^^^^^^^^ + + * `JavaScript API <https://doc.qt.io/qt-6/qtwebchannel-javascript.html>`_ + +The module also provides `QML types <https://doc.qt.io/qt-6/qtwebchannel-qmlmodule.html>`_ . diff --git a/sources/pyside6/doc/extras/QtWebEngineCore.rst b/sources/pyside6/doc/extras/QtWebEngineCore.rst new file mode 100644 index 000000000..ff8dd5c23 --- /dev/null +++ b/sources/pyside6/doc/extras/QtWebEngineCore.rst @@ -0,0 +1,19 @@ +Provides common API shared by Qt WebEngine and Qt WebEngine Widgets. + +Qt WebEngine Core provides API shared by :ref:`Qt WebEngine<Qt-WebEngine>` +and :ref:`Qt WebEngine Widgets<Qt-WebEngine-Widgets>` . + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtWebEngineCore + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * `Qt WebEngine Overview <https://doc.qt.io/qt-6/qtwebengine-overview.html>`_ diff --git a/sources/pyside6/doc/extras/QtWebEngineWidgets.rst b/sources/pyside6/doc/extras/QtWebEngineWidgets.rst new file mode 100644 index 000000000..8d3f6e126 --- /dev/null +++ b/sources/pyside6/doc/extras/QtWebEngineWidgets.rst @@ -0,0 +1,18 @@ +Provides a web browser engine as well as C++ classes to render web content and +interact with it. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtWebEngineWidgets + + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * `Qt WebEngine Overview <https://doc.qt.io/qt-6/qtwebengine-overview.html>`_ diff --git a/sources/pyside6/doc/extras/QtWebSockets.rst b/sources/pyside6/doc/extras/QtWebSockets.rst new file mode 100644 index 000000000..f15264699 --- /dev/null +++ b/sources/pyside6/doc/extras/QtWebSockets.rst @@ -0,0 +1,29 @@ +Provides an implementation of the WebSocket protocol. + +WebSocket is a web-based protocol designed to enable two-way communication +between a client application and a remote host. It enables the two entities to +send data back and forth if the initial handshake succeeds. WebSocket is the +solution for applications that struggle to get real-time data feeds with less +network latency and minimum data exchange. + +The Qt WebSockets module provides C++ and QML interfaces that enable Qt +applications to act as a server that can process WebSocket requests, or a +client that can consume data received from the server, or both. + +Getting Started +^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtWebSockets + +The module also provides `QML types <https://doc.qt.io/qt-6/qtwebsockets-qmlmodule.html>`_ . + +Articles and Guides +^^^^^^^^^^^^^^^^^^^ + + * `Overview <https://doc.qt.io/qt-6/websockets-overview.html>`_ + * `Testing Qt WebSockets <https://doc.qt.io/qt-6/qtwebsockets-testing.html>`_ diff --git a/sources/pyside6/doc/extras/QtWidgets.rst b/sources/pyside6/doc/extras/QtWidgets.rst new file mode 100644 index 000000000..784421aac --- /dev/null +++ b/sources/pyside6/doc/extras/QtWidgets.rst @@ -0,0 +1,86 @@ +A module which provides a set of C++ technologies for building user +interfaces + +The QtWidgets module provides a set of UI elements to create classic +desktop-style user interfaces. + +Widgets +^^^^^^^ + +Widgets are the primary elements for creating user interfaces in Qt. They can +display data and status information, receive user input, and provide a +container for other widgets that should be grouped together. A widget that is +not embedded in a parent widget is called a window. + + .. image:: images/parent-child-widgets.png + +The :class:`QWidget<PySide6.QtWidgets.QWidget>` class provides the +basic capability to render to the screen, and to handle user input +events. All UI elements that Qt provides are either subclasses of +:class:`QWidget<PySide6.QtWidgets.QWidget>` , or are used in +connection with a :class:`QWidget<PySide6.QtWidgets.QWidget>` +subclass. Creating custom widgets is done by subclassing +:class:`QWidget<PySide6.QtWidgets.QWidget>` or a suitable subclass and +reimplementing the virtual event handlers. + + * :ref:`Window and Dialog Widgets<Window-and-Dialog-Widgets>` + * :ref:`Application Main Window<Application-Main-Window>` + * :ref:`Dialog Windows<Dialog-Windows>` + * :ref:`Keyboard Focus in Widgets<Keyboard-Focus-in-Widgets>` + +Styles +^^^^^^ + +:ref:`Styles<Styles-and-Style-Aware-Widgets>` draw on behalf of +widgets and encapsulate the look and feel of a GUI. Qt's built-in +widgets use the :class:`QStyle<PySide6.QtWidgets.QStyle>` class to +perform nearly all of their drawing, ensuring that they look exactly +like the equivalent native widgets. + +:ref:`Qt Style Sheets<Qt-Style-Sheets>` are a powerful mechanism that +allows you to customize the appearance of widgets, in addition to what +is already possible by subclassing +:class:`QStyle<PySide6.QtWidgets.QStyle>` . + +Layouts +^^^^^^^ + +:ref:`Layouts<Layout-Management>` are an elegant and flexible way to +automatically arrange child widgets within their container. Each +widget reports its size requirements to the layout through the +:meth:`sizeHint<PySide6.QtWidgets.QWidget.sizeHint>` and +:meth:`sizePolicy<PySide6.QtWidgets.QWidget.sizePolicy>` properties, +and the layout distributes the available space accordingly. + +:ref:`Qt Widgets Designer<using_ui_files>` is a powerful tool for interactively +creating and arranging widgets in layouts. + +Model/View Classes +^^^^^^^^^^^^^^^^^^ + +The :ref:`model/view<Model-View-Programming>` architecture provides +classes that manage the way data is presented to the user. Data-driven +applications which use lists and tables are structured to separate the +data and view using models, views, and delegates. + + .. image:: images/windows-treeview.png + +Graphics View +^^^^^^^^^^^^^ + +The :ref:`Graphics View Framework<Graphics-View-Framework>` is for +managing and interacting with a large number of custom-made 2D +graphical items, and a view widget for visualizing the items, with +support for zooming and rotation. + + .. image:: images/graphicsview-items.png + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: + +:: + + import PySide6.QtWidgets diff --git a/sources/pyside6/doc/extras/QtXml.rst b/sources/pyside6/doc/extras/QtXml.rst index 39c384e77..33d821baa 100644 --- a/sources/pyside6/doc/extras/QtXml.rst +++ b/sources/pyside6/doc/extras/QtXml.rst @@ -1,4 +1,12 @@ -To include the definitions of the module's classes, use the following directive: +The Qt XML module provides implementations of the SAX and DOM standards for XML. + +.. note:: Qt XML will no longer receive additional features. For reading or writing XML documents iteratively (SAX), use the :class:`QXmlStreamReader<PySide6.QtCore.QXmlStreamReader>` and :class:`QXmlStreamWriter<PySide6.QtCore.QXmlStreamWriter>` classes. The classes are both easier to use and more compliant with the XML standard. + +Using the Module +^^^^^^^^^^^^^^^^ + +To include the definitions of modules classes, use the following +directive: :: diff --git a/sources/pyside6/doc/extras/QtXmlPatterns.rst b/sources/pyside6/doc/extras/QtXmlPatterns.rst deleted file mode 100644 index 258fdf28d..000000000 --- a/sources/pyside6/doc/extras/QtXmlPatterns.rst +++ /dev/null @@ -1,12 +0,0 @@ -To include the definitions of the module's classes, use the following directive: - -:: - - import PySide6.QtXmlPatterns - -Further Reading ---------------- - -General overviews of XQuery and XSchema can be found in the XQuery document. - -An introduction to the XQuery language can be found in A Short Path to XQuery. |