diff options
author | Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io> | 2019-03-22 15:22:49 +0100 |
---|---|---|
committer | Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io> | 2019-03-27 15:19:29 +0000 |
commit | ee9ead9f4ca85804f6cab977a0881458714aee3b (patch) | |
tree | d8be599d8ba5f47e7a734413b50495e833573c9f /sources | |
parent | 066dfadf24b64628fabe25097a86a41f62e73526 (diff) |
Doc: Add descriptions, pages, and moving modules
Having all the Qt modules on the main page is too verbose.
I created four sections with a couple of them and added
more context to clarify when to use them.
All the modules are still listed in a new page called `modules`.
I included an `overview` page with some general information from
our wiki: compatibility among platforms, an example and the FAQ.
Task-number: PYSIDE-691
Change-Id: Ic9e2519aa2caa9c8a645633c2c1772e4844b5ec5
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Diffstat (limited to 'sources')
-rw-r--r-- | sources/pyside2/doc/contents.rst | 2 | ||||
-rw-r--r-- | sources/pyside2/doc/faq.rst | 49 | ||||
-rw-r--r-- | sources/pyside2/doc/index.rst | 160 | ||||
-rw-r--r-- | sources/pyside2/doc/modules.rst | 94 | ||||
-rw-r--r-- | sources/pyside2/doc/overview.rst | 42 |
5 files changed, 255 insertions, 92 deletions
diff --git a/sources/pyside2/doc/contents.rst b/sources/pyside2/doc/contents.rst index d58dc9716..645f461e5 100644 --- a/sources/pyside2/doc/contents.rst +++ b/sources/pyside2/doc/contents.rst @@ -4,6 +4,8 @@ .. toctree:: :maxdepth: 2 + overview.rst + faq.rst gettingstarted.rst tutorials/index.rst pysideapi2.rst diff --git a/sources/pyside2/doc/faq.rst b/sources/pyside2/doc/faq.rst new file mode 100644 index 000000000..e09d98999 --- /dev/null +++ b/sources/pyside2/doc/faq.rst @@ -0,0 +1,49 @@ +Frequently Asked Questions +========================== + +**When was PySide2 adopted by The Qt Company?** + During April 2016 `The Qt Company <https://qt.io>`_ decided to properly support the port + (`see details <https://groups.google.com/forum/#!topic/pyside-dev/pqwzngAGLWE>`_). + +**PySide? Qt for Python? what is the name?** + The name of the project is Qt for Python and the name of the module is PySide2. + +**Why PySide2 and not just PySide?** + Since PySide was developed for Qt4, when the port was made to support Qt5, + the name is changed to PySide2 to imply that it was a newer version. + +**Where I can find information about the old PySide project?** + The old wiki page of the project is available on PySide, but the project is deprecated + and there is no official support for it. We highly recommend not to use it. + +**My project is using PySide, how hard would it be to adapt it to PySide2?** + The changes are the same as between Qt4 and Qt5, and for PySide users it mostly means + adapting the import statements since many classes were moved from QtGui to QtWidgets. + Qt 5 is highly compatible with Qt 4. It is possible for developers of Qt 4 applications to + seamlessly move to Qt 5 with their current functionality and gradually develop new things, + leveraging all the great items Qt 5 makes possible. + +**Does PySide2 support Android and iOS development / deployment?** + At the moment there is no support for mobile platforms. + +**Does PySide2 have support for embedded Linux (Raspberry Pi, i.MX6 etc)?** + Not at the moment. + +**There are three wheels (pyside2, shiboken2, and shiboken2_generator) + what is the different between them?** + + Before the official release, everything was in one big wheel, but it made sense to split + the projects in three different wheels: + * **pyside2**: contains all the PySide2 modules to use the Qt framework. + Also depends on the shiboken2 module. + * **shiboken2**: contains the shiboken2 module with helper functions for PySide2. + * **shiboken2_generator**: contains the generator binary that can work with a C++ project + and a typesystem to generate Python bindings. + Take into account that if you want to generate bindings for a Qt/C++ project, + the linking to the Qt shared libraries will be missing, and you will need to do this by hand. + We recommend to build PySide2 from scratch to have everything properly linked. + +**Why shiboken2_generator is not installed automatically?** + It's not necessary to install it to use PySide2. + The package is the result of the wheel splitting process. + To use the generator, it's recommended to build it from scratch to have the proper Qt-linking. diff --git a/sources/pyside2/doc/index.rst b/sources/pyside2/doc/index.rst index 7f3b8e4a7..b0bb1d19c 100644 --- a/sources/pyside2/doc/index.rst +++ b/sources/pyside2/doc/index.rst @@ -3,7 +3,9 @@ |project| offers Python bindings for Qt, enabling the use of Qt5 APIs in Python applications. It lets Python developers utilize the full potential of Qt, using -the |pymodname| module. The |pymodname| module provides access to the individual +the |pymodname| module. + +The |pymodname| module provides access to the individual Qt modules such as QtCore, QtGui, and so on. |project| also comes with the :doc:`Shiboken2 <shiboken2:index>` CPython binding code generator, which can be used to generate Python bindings for your C or C++ code. @@ -18,94 +20,68 @@ used to generate Python bindings for your C or C++ code. Qt Modules =========== -.. list-table:: - :widths: 150, 150 - :align: left - - * - `Qt Core <PySide2/QtCore/index.html>`_ - Provides core non-GUI functionality. - - `Qt 3D Animation <PySide2/Qt3DAnimation/index.html>`_ - Provides basic elements required to animate 3D objects. - * - `Qt Gui <PySide2/QtGui/index.html>`_ - Extends QtCore with GUI functionality. - - `Qt Help <PySide2/QtHelp/index.html>`_ - Provides classes for integrating online documentation in applications. - * - `Qt Network <PySide2/QtNetwork/index.html>`_ - Offers classes that lets you to write TCP/IP clients and servers. - - `Qt OpenGL <PySide2/QtOpenGL/index.html>`_ - Offers classes that make it easy to use OpenGL in Qt applications. - * - `Qt PrintSupport <PySide2/QtPrintSupport/index.html>`_ - Provides extensive cross-platform support for printing. - - `Qt Qml <PySide2/QtQml/index.html>`_ - Python API for Qt QML. - * - `Qt Charts <PySide2/QtCharts/index.html>`_ - Provides a set of easy to use chart components. - - `Qt Quick <PySide2/QtQuick/index.html>`_ - Provides classes for embedding Qt Quick in Qt applications. - * - `Qt DataVisualization <PySide2/QtDataVisualization/index.html>`_ - Provides a way to visualize data in 3D as bar, scatter, and surface graphs. - - `Qt QuickWidgets <PySide2/QtQuickWidgets/index.html>`_ - Provides the QQuickWidget class for embedding Qt Quick in widget-based applications. - * - `Qt TextToSpeech <PySide2/QtTextToSpeech/index.html>`_ - Provides API to access text-to-speech engines. - - `Qt Sql <PySide2/QtSql/index.html>`_ - Helps you provide seamless database integration to your Qt applications. - * - `Qt Multimedia <PySide2/QtMultimedia/index.html>`_ - Provides low-level multimedia functionality. - - `Qt MultimediaWidgets <PySide2/QtMultimediaWidgets/index.html>`_ - Provides the widget-based multimedia API. - * - `Qt MacExtras <PySide2/QtMacExtras/index.html>`_ - Provides classes and functions specific to - macOS and iOS operating systems. - - `Qt Svg <PySide2/QtSvg/index.html>`_ - Provides classes for displaying the contents of SVG files. - * - `Qt UiTools <PySide2/QtUiTools/index.html>`_ - Provides classes to handle forms created with Qt Designer. - - `Qt Test <PySide2/QtTest/index.html>`_ - Provides classes for unit testing Qt applications and libraries. - * - `Qt Concurrent <PySide2/QtConcurrent/index.html>`_ - 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. - - `Qt AxContainer <PySide2/QtAxContainer/index.html>`_ - Provides QAxObject and QAxWidget which act as - containers for COM objects and ActiveX controls. - * - `Qt WebEngineCore <PySide2/QtWebEngineCore/index.html>`_ - Provides the core functionality to integrate web content - - `Qt WebEngineWidgets <PySide2/QtWebEngineWidgets/index.html>`_ - Provides widgets that can handle web content - * - `Qt WebChannel <PySide2/QtWebChannel/index.html>`_ - Enables peer-to-peer communication between a server and a client - (HTML/JavaScript or QML application). - - `Qt WebSockets <PySide2/QtWebSockets/index.html>`_ - Provides 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. - * - `Qt Widgets <PySide2/QtWidgets/index.html>`_ - Extends Qt GUI with C++ widget functionality. - - `Qt WinExtras <PySide2/QtWinExtras/index.html>`_ - Provides classes and functions for using some Windows APIs in a Qt way. - * - `Qt X11Extras <PySide2/QtX11Extras/index.html>`_ - Provides information about the X display configuration. - - `Qt Xml <PySide2/QtXml/index.html>`_ - Provides C++ implementations of SAX and DOM. - * - `Qt XmlPatterns <PySide2/QtXmlPatterns/index.html>`_ - Provides support for XPath, XQuery, XSLTi, and XML Schema validation. - - `Qt 3D Core <PySide2/Qt3DCore/index.html>`_ - Contains functionality to support near-realtime simulation systems. - * - `Qt 3D Extras <PySide2/Qt3DExtras/index.html>`_ - Provides a set of prebuilt elements to help you get started with Qt 3D. - - `Qt 3D Input <PySide2/Qt3DInput/index.html>`_ - Provides classes for handling user input in applications using Qt 3D. - * - `Qt 3D Logic <PySide2/Qt3DLogic/index.html>`_ - Enables synchronizing frames with the Qt 3D backend. - - `Qt 3D Render <PySide2/Qt3DRender/index.html>`_ - Contains functionality to support 2D and 3D rendering using Qt 3D. - * - `Qt Positioning <PySide2/QtPositioning/index.html>`_ - Provides positioning information via QML and Python interfaces. - - `Qt Location <PySide2/QtLocation/index.html>`_ - Helps you create viable mapping solutions using the data available from some of the popular location services. - * - `Qt Sensors <PySide2/QtSensors/index.html>`_ - Provides access to sensor hardware via QML and Python interfaces and a motion gesture recognition API for devices. - - `Qt Scxml <PySide2/QtScxml/index.html>`_ - Provides classes to create and use state machines from SCXML files. +Basic modules +------------- + These are the main modules that will help you build a Widget based UI. + + `Qt Core <PySide2/QtCore/index.html>`_ + Provides core non-GUI functionality, like signal and slots, properties, base classes of item models, serialization, etc. + `Qt Gui <PySide2/QtGui/index.html>`_ + Extends QtCore with GUI functionality: Events, windows and screens, OpenGL and raster-based 2D painting, images. + `Qt Widgets <PySide2/QtWidgets/index.html>`_ + Ready to use Widgets for your application, including also graphical elements for your UI. + +QML and Qt Quick +---------------- + If you want to use the `Qml Language <https://doc.qt.io/qt-5/qmlapplications.html>`, these + modules will help you interact with it from Python. + + `Qt Qml <PySide2/QtQml/index.html>`_ + Base Python API to interact with the QML module. + `Qt Quick <PySide2/QtQuick/index.html>`_ + Provides classes for embedding Qt Quick in Qt applications. + `Qt QuickWidgets <PySide2/QtQuickWidgets/index.html>`_ + Provides the QQuickWidget class for embedding Qt Quick in widget-based applications. + +Data visualization +------------------ + + Charts, diagrams, animations: these modules provide a large amount + of classes that can help you include these elements in your UI. + + `Qt Charts <PySide2/QtCharts/index.html>`_ + Provides a set of easy to use chart components. + `Qt DataVisualization <PySide2/QtDataVisualization/index.html>`_ + Provides a way to visualize data in 3D as bar, scatter, and surface graphs. + +Multimedia +----------- + + Audio, video, and hardware interaction: check these modules if you are + looking for multimedia solutions. + + `Qt Multimedia <PySide2/QtMultimedia/index.html>`_ + Provides low-level multimedia functionality. + `Qt MultimediaWidgets <PySide2/QtMultimediaWidgets/index.html>`_ + Provides the widget-based multimedia API. + +WebEngine +--------- + + If your project is based on a browser or the features around web + based applications, these modules will help you to interact with them. + + `Qt WebEngineWidgets <PySide2/QtWebEngineWidgets/index.html>`_ + Provides widgets that can handle web content. + `Qt WebChannel <PySide2/QtWebChannel/index.html>`_ + Enables peer-to-peer communication between a server and a client + (HTML/JavaScript or QML application). + +All the modules +--------------- + + There are many other modules currently supported by |pymodname|, + here you can find a complete list of them. + + `Check all the modules <modules.html>`_ + Display a table with all the currently supported Qt modules. diff --git a/sources/pyside2/doc/modules.rst b/sources/pyside2/doc/modules.rst new file mode 100644 index 000000000..1d6564300 --- /dev/null +++ b/sources/pyside2/doc/modules.rst @@ -0,0 +1,94 @@ +Qt Modules +=========== + +.. list-table:: + :widths: 150, 150 + :align: left + + * - `Qt Core <PySide2/QtCore/index.html>`_ + Provides core non-GUI functionality. + - `Qt 3D Animation <PySide2/Qt3DAnimation/index.html>`_ + Provides basic elements required to animate 3D objects. + * - `Qt Gui <PySide2/QtGui/index.html>`_ + Extends QtCore with GUI functionality. + - `Qt Help <PySide2/QtHelp/index.html>`_ + Provides classes for integrating online documentation in applications. + * - `Qt Network <PySide2/QtNetwork/index.html>`_ + Offers classes that let you to write TCP/IP clients and servers. + - `Qt OpenGL <PySide2/QtOpenGL/index.html>`_ + Offers classes that make it easy to use OpenGL in Qt applications. + * - `Qt PrintSupport <PySide2/QtPrintSupport/index.html>`_ + Provides extensive cross-platform support for printing. + - `Qt Qml <PySide2/QtQml/index.html>`_ + Python API for Qt QML. + * - `Qt Charts <PySide2/QtCharts/index.html>`_ + Provides a set of easy to use chart components. + - `Qt Quick <PySide2/QtQuick/index.html>`_ + Provides classes for embedding Qt Quick in Qt applications. + * - `Qt DataVisualization <PySide2/QtDataVisualization/index.html>`_ + Provides a way to visualize data in 3D as bar, scatter, and surface graphs. + - `Qt QuickWidgets <PySide2/QtQuickWidgets/index.html>`_ + Provides the QQuickWidget class for embedding Qt Quick in widget-based applications. + * - `Qt TextToSpeech <PySide2/QtTextToSpeech/index.html>`_ + Provides API to access text-to-speech engines. + - `Qt Sql <PySide2/QtSql/index.html>`_ + Helps you provide seamless database integration to your Qt applications. + * - `Qt Multimedia <PySide2/QtMultimedia/index.html>`_ + Provides low-level multimedia functionality. + - `Qt MultimediaWidgets <PySide2/QtMultimediaWidgets/index.html>`_ + Provides the widget-based multimedia API. + * - `Qt MacExtras <PySide2/QtMacExtras/index.html>`_ + Provides classes and functions specific to + macOS and iOS operating systems. + - `Qt Svg <PySide2/QtSvg/index.html>`_ + Provides classes for displaying the contents of SVG files. + * - `Qt UiTools <PySide2/QtUiTools/index.html>`_ + Provides classes to handle forms created with Qt Designer. + - `Qt Test <PySide2/QtTest/index.html>`_ + Provides classes for unit testing Qt applications and libraries. + * - `Qt Concurrent <PySide2/QtConcurrent/index.html>`_ + 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. + - `Qt AxContainer <PySide2/QtAxContainer/index.html>`_ + Provides QAxObject and QAxWidget which act as + containers for COM objects and ActiveX controls. + * - `Qt WebEngineCore <PySide2/QtWebEngineCore/index.html>`_ + Provides the core functionality to integrate web content. + - `Qt WebEngineWidgets <PySide2/QtWebEngineWidgets/index.html>`_ + Provides widgets that can handle web content. + * - `Qt WebChannel <PySide2/QtWebChannel/index.html>`_ + Enables peer-to-peer communication between a server and a client + (HTML/JavaScript or QML application). + - `Qt WebSockets <PySide2/QtWebSockets/index.html>`_ + Provides 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. + * - `Qt Widgets <PySide2/QtWidgets/index.html>`_ + Extends Qt GUI with C++ widget functionality. + - `Qt WinExtras <PySide2/QtWinExtras/index.html>`_ + Provides classes and functions for using some Windows APIs in a Qt way. + * - `Qt X11Extras <PySide2/QtX11Extras/index.html>`_ + Provides information about the X display configuration. + - `Qt Xml <PySide2/QtXml/index.html>`_ + Provides C++ implementations of SAX and DOM. + * - `Qt XmlPatterns <PySide2/QtXmlPatterns/index.html>`_ + Provides support for XPath, XQuery, XSLTi, and XML Schema validation. + - `Qt 3D Core <PySide2/Qt3DCore/index.html>`_ + Contains functionality to support near-realtime simulation systems. + * - `Qt 3D Extras <PySide2/Qt3DExtras/index.html>`_ + Provides a set of prebuilt elements to help you get started with Qt 3D. + - `Qt 3D Input <PySide2/Qt3DInput/index.html>`_ + Provides classes for handling user input in applications using Qt 3D. + * - `Qt 3D Logic <PySide2/Qt3DLogic/index.html>`_ + Enables synchronizing frames with the Qt 3D backend. + - `Qt 3D Render <PySide2/Qt3DRender/index.html>`_ + Contains functionality to support 2D and 3D rendering using Qt 3D. + * - `Qt Positioning <PySide2/QtPositioning/index.html>`_ + Provides positioning information via QML and Python interfaces. + - `Qt Location <PySide2/QtLocation/index.html>`_ + Helps you create viable mapping solutions using the data available from some of the popular location services. + * - `Qt Sensors <PySide2/QtSensors/index.html>`_ + Provides access to sensor hardware via QML and Python interfaces and a motion gesture recognition API for devices. + - `Qt Scxml <PySide2/QtScxml/index.html>`_ + Provides classes to create and use state machines from SCXML files. diff --git a/sources/pyside2/doc/overview.rst b/sources/pyside2/doc/overview.rst new file mode 100644 index 000000000..e8a8ace00 --- /dev/null +++ b/sources/pyside2/doc/overview.rst @@ -0,0 +1,42 @@ +Overview +========= + +The |project| project aims to provide a complete port of the PySide module to Qt 5. +The development started on GitHub in May 2015. The project managed to port Pyside to +Qt 5.3, 5. 4 & 5.5. + +The `PySide2` module was released mid June 2018 as a Technical Preview (supporting Qt 5.11), +and it has been fully supported since Qt 5.12. + +|project| is available under LGPLv3/GPLv2 and commercial license for the following platforms: + ++-------------+--------+--------+--------+--------+---------+---------+ +| | Linux | macOS | Windows | ++=============+========+========+========+========+=========+=========+ +| | 32bit | 64bit | 32bit | 64bit | 32bit | 64bit | ++-------------+--------+--------+--------+--------+---------+---------+ +| Python 2.7 | No (*) | Yes | No (*) | Yes | No (**) | No (**) | ++-------------+--------+--------+--------+--------+---------+---------+ +| Python 3.5+ | No (*) | Yes | No (*) | Yes | Yes | Yes | ++-------------+--------+--------+--------+--------+---------+---------+ + + * (*): `No Qt release <https://wiki.qt.io/Qt_5.12_Tools_and_Versions#Software_configurations_for_Qt_5.12.0>`_ + * (**): `MSVC issue with Python 2.7 and Qt <https://wiki.qt.io/Qt_for_Python/Considerations#Missing_Windows_.2F_Python_2.7_release>`_ + + +What does PySide2 look like? +---------------------------- + +A simple Hello World example in PySide2 looks like this: + +:: + + import sys + from PySide2.QtWidgets import QApplication, QLabel + + + if __name__ == "__main__": + app = QApplication(sys.argv) + label = QLabel("Hello World") + label.show() + sys.exit(app.exec_()) |