diff options
| author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2022-03-15 08:14:51 +0100 |
|---|---|---|
| committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2022-03-16 07:59:29 +0100 |
| commit | 8fb276b5d8436e2ec84e1b9d3f24a77fb2863017 (patch) | |
| tree | 2edd6065bf1685ee28830ceccccd1feaf78ead83 | |
| parent | 8b79b1ce2cb0353c85919600a1ff269e56a537e6 (diff) | |
PySide6/Documentation: Add module descriptions
Add module descriptions and a README.md on how to create them.
Pick-to: 6.2
Change-Id: I627205843bedd74e625d14da718e42faac0a2c68
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
30 files changed, 1358 insertions, 11 deletions
diff --git a/sources/pyside6/doc/README.md b/sources/pyside6/doc/README.md new file mode 100644 index 000000000..b43effd2d --- /dev/null +++ b/sources/pyside6/doc/README.md @@ -0,0 +1,12 @@ +# Recreating the module descriptions after a Qt major version change + +The source tree contains .rst files containing the module description in +doc/extras (named for example "QtCore.rst"). They are extracted/adapted from +the C++ module descriptions. If there is no module description file, shiboken +will extract the module description from the webxml files generated by qdoc. +This ends up in the build directory under doc/rst/PySide6/<module>/index.rst. +It can be used as a starting point for a module description file. C++ +specific information like build instructions should be removed. + +The descriptions may link to tutorials which can be added to additionaldocs.lst +for webxml extraction. diff --git a/sources/pyside6/doc/extras/QtBluetooth.rst b/sources/pyside6/doc/extras/QtBluetooth.rst new file mode 100644 index 000000000..dda05f20b --- /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 <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ 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 <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ module +exports the following :class:`logging categories<~.Configuring Categories>` : + + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |Logging Category |Description | + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |qt.bluetooth |Enables logging of cross platform code path in `QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_| + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |qt.bluetooth.android|Enables logging of the Android implementation | + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |qt.bluetooth.bluez |Enables logging of the BLuez/Linux implementation | + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |qt.bluetooth.ios |Enables logging of the iOS implementation | + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |qt.bluetooth.osx |Enables logging of the macOS implementation | + +--------------------+--------------------------------------------------------------------------------------------------------------+ + |qt.bluetooth.windows|Enables logging of the Qt for Windows implementation | + +--------------------+--------------------------------------------------------------------------------------------------------------+ + +Logging categories can be used to enable additional warning and debug output +for `QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ . More +detailed information about logging can be found in +:class:`QLoggingCategory<~.QLoggingCategory>` . A quick way to enable all +`QtBluetooth <https://doc.qt.io/qt-6/qtbluetooth-module.html>`_ logging is to +add the following line to the ``main()`` function: + + :: + + QLoggingCategory.setFilterRules("qt.bluetooth* = true") diff --git a/sources/pyside6/doc/extras/QtCharts.rst b/sources/pyside6/doc/extras/QtCharts.rst new file mode 100644 index 000000000..894a8ce02 --- /dev/null +++ b/sources/pyside6/doc/extras/QtCharts.rst @@ -0,0 +1,17 @@ +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 <http://doc.qt.io/qt-6/qtcharts-qmlmodule.html>`_ . 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.rst b/sources/pyside6/doc/extras/QtCore.rst index a0b524976..ac72bc487 100644 --- a/sources/pyside6/doc/extras/QtCore.rst +++ b/sources/pyside6/doc/extras/QtCore.rst @@ -1,6 +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..4bd6ef9f3 --- /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 <http://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.rst b/sources/pyside6/doc/extras/QtDesigner.rst new file mode 100644 index 000000000..c232128dd --- /dev/null +++ b/sources/pyside6/doc/extras/QtDesigner.rst @@ -0,0 +1,17 @@ +Provides classes to create your own custom widget plugins for Qt Designer and +classes to access Qt 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..65ab066ee 100644 --- a/sources/pyside6/doc/extras/QtMultimedia.rst +++ b/sources/pyside6/doc/extras/QtMultimedia.rst @@ -1,7 +1,105 @@ -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 <http://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 <https://doc.qt.io/qt-6/qml-qtmultimedia-mediaplayer.html>`_ |Add audio/video playback functionality to a scene. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`CaptureSession <https://doc.qt.io/qt-6/qml-qtmultimedia-capturesession.html>`_|Create a session for capturing audio/video. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`Camera <https://doc.qt.io/qt-6/qml-qtmultimedia-camera.html>`_ |Access a camera connected to the system. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`AudioInput <https://doc.qt.io/qt-6/qml-qtmultimedia-audioinput.html>`_ |Access an audio input (microphone) connected to the system. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`AudioOutput <https://doc.qt.io/qt-6/qml-qtmultimedia-audiooutput.html>`_ |Access an audio output (speaker, headphone) connected to the system. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`VideoOutput <https://doc.qt.io/qt-6/qml-qtmultimedia-videooutput.html>`_ |Display video content. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`MediaRecorder <https://doc.qt.io/qt-6/qml-qtmultimedia-mediarecorder.html>`_ |Record audio/video from the `CaptureSession <https://doc.qt.io/qt-6/qml-qtmultimedia-capturesession.html>`_ . | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`ImageCapture <https://doc.qt.io/qt-6/qml-qtmultimedia-imagecapture.html>`_ |Capture still images from the Camera. | + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + |`Video <https://doc.qt.io/qt-6/qml-qtmultimedia-video.html>`_ |Add Video playback functionality to a scene. Uses `MediaPlayer <https://doc.qt.io/qt-6/qml-qtmultimedia-mediaplayer.html>`_ and `VideoOutput <https://doc.qt.io/qt-6/qml-qtmultimedia-videooutput.html>`_ types to provide video playback functionality.| + +-------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +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/QtPositioning.rst b/sources/pyside6/doc/extras/QtPositioning.rst new file mode 100644 index 000000000..cc0d051eb --- /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 <http://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.rst b/sources/pyside6/doc/extras/QtQml.rst new file mode 100644 index 000000000..4e6231495 --- /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 <http://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/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/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..e6cc8874e --- /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 <http://doc.qt.io/qt-6/qtsensors-qmlmodule.html>`_ . 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/QtWebChannel.rst b/sources/pyside6/doc/extras/QtWebChannel.rst new file mode 100644 index 000000000..5c2fbdd4a --- /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 <http://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..05b003ea6 --- /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 <http://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..8c91d3e31 --- /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 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: :: |