diff options
Diffstat (limited to 'sources/pyside6/doc/quickstart.rst')
| -rw-r--r-- | sources/pyside6/doc/quickstart.rst | 194 |
1 files changed, 141 insertions, 53 deletions
diff --git a/sources/pyside6/doc/quickstart.rst b/sources/pyside6/doc/quickstart.rst index 141edf94c..7e1a210f2 100644 --- a/sources/pyside6/doc/quickstart.rst +++ b/sources/pyside6/doc/quickstart.rst @@ -4,20 +4,32 @@ Quick start =========== New to Qt? Check also the :ref:`faq-section` section at the end of this page. +In case you own a Qt License, please refer to :ref:`commercial-page`. + +.. note:: Having Qt installed in your system will not interfere with your + PySide6 installation if you do it via ``pip install``, because the Python + packages (wheels) include already Qt binaries. Most notably, style plugins + from the system won't have any effect on PySide applications. Requirements ------------ Before you can install |project|, first you must install the following software: - * Python 3.7+, - * We recommend using a virtual environment, such as - `venv <https://docs.python.org/3/library/venv.html>`_ or - `virtualenv <https://virtualenv.pypa.io/en/latest>`_ +* Python 3.7+, +* We **highly** recommend using a virtual environment, such as + `venv <https://docs.python.org/3/library/venv.html>`_ or + `virtualenv <https://virtualenv.pypa.io/en/latest>`_ + and avoid installing PySide6 via ``pip`` in your system. + +.. note:: For Windows users, please use the interpreter from https://python.org/download + rather than the one installed from the Microsoft Store. Installation ------------ +.. note:: For a commercial installation, refer to :ref:`commercial-page`. + * **Creating and activating an environment** You can do this by running the following on a terminal: @@ -36,7 +48,7 @@ Installation Check this animation on how to do it: .. image:: https://qt-wiki-uploads.s3.amazonaws.com/images/8/8a/Pyside6_install.gif - :alt: Installation gif + :alt: Installation GIF * **Installing PySide6** @@ -54,7 +66,15 @@ Installation * It is also possible to install a specific snapshot from our servers. To do so, you can use the following command:: - pip install --index-url=https://download.qt.io/snapshots/ci/pyside/6.0.0/latest pyside6 --trusted-host download.qt.io + pip install --index-url=https://download.qt.io/snapshots/ci/pyside/6.4/latest pyside6 --trusted-host download.qt.io + + .. note:: Starting with 6.4.3, PySide6 can be used from inside a + `conda <https://conda.io>`_ environment, but any manual changes you make to + the ``qt.conf`` file will be ignored. If you want to set custom values to + the Qt configuration, set them in a ``qt6.conf`` file instead. + Read more about `qt.conf`_. + +.. _`qt.conf`: https://doc.qt.io/qt-6/qt-conf.html * **Test your installation** @@ -72,8 +92,8 @@ Installation .. note:: For more information about what's included in the ``pyside6`` package, check :ref:`package_details`. -Create a Simple Application ---------------------------- +Create a Simple Qt Widgets Application +-------------------------------------- Your |project| setup is ready. You can explore it further by developing a simple application that prints "Hello World" in several languages. The following instructions will @@ -88,12 +108,12 @@ guide you through the development process: from PySide6 import QtCore, QtWidgets, QtGui The |pymodname| Python module provides access to the Qt APIs as its submodule. - In this case, you are importing the :code:`QtCore`, :code:`QtWidgets`, and :code:`QtGui` submodules. + In this case, you are importing the :ref:`QtCore`, :ref:`QtWidgets`, and :ref:`QtGui` submodules. * **Main Class** - Define a class named :code:`MyWidget`, which extends QWidget and includes a QPushButton and - QLabel.:: + Define a class named :code:`MyWidget`, which extends :ref:`QWidget` and + includes a :ref:`QPushButton` and :ref:`QLabel`.:: class MyWidget(QtWidgets.QWidget): def __init__(self): @@ -115,8 +135,9 @@ guide you through the development process: def magic(self): self.text.setText(random.choice(self.hello)) - The MyWidget class has the :code:`magic` member function that randomly chooses an item from the - :code:`hello` list. When you click the button, the :code:`magic` function is called. + The ``MyWidget`` class has the :code:`magic` member function that randomly + chooses an item from the :code:`hello` list. When you click the button, the + :code:`magic` function is called. * **Application execution** @@ -138,6 +159,81 @@ guide you through the development process: .. image:: images/screenshot_hello.png :alt: Hello World application +Create a Simple Quick Application +--------------------------------- + +To do the same using Qt Quick: + +* **Imports** + + Create a new file named :code:`hello_world_quick.py`, and add the following imports to it.:: + + import sys + from PySide6.QtGui import QGuiApplication + from PySide6.QtQml import QQmlApplicationEngine + +* **Declarative UI** + + The UI can be described in the QML language (assigned to a Python variable):: + + QML = """ + import QtQuick + import QtQuick.Controls + import QtQuick.Layouts + + Window { + width: 300 + height: 200 + visible: true + title: "Hello World" + + readonly property list<string> texts: ["Hallo Welt", "Hei maailma", + "Hola Mundo", "Привет мир"] + + function setText() { + var i = Math.round(Math.random() * 3) + text.text = texts[i] + } + + ColumnLayout { + anchors.fill: parent + + Text { + id: text + text: "Hello World" + Layout.alignment: Qt.AlignHCenter + } + Button { + text: "Click me" + Layout.alignment: Qt.AlignHCenter + onClicked: setText() + } + } + } + """ + + .. note:: Keep in mind ideally this content should go into + a ``qml`` file, but for simplicity, we are using a string variable. + +* **Application execution** + + Now, add a main function where you instantiate a :ref:`QQmlApplicationEngine` and + load the QML:: + + if __name__ == "__main__": + app = QGuiApplication(sys.argv) + engine = QQmlApplicationEngine() + engine.loadData(QML.encode('utf-8')) + if not engine.rootObjects(): + sys.exit(-1) + exit_code = app.exec() + del engine + sys.exit(exit_code) + + + .. note:: This is a simplified example. Normally, the QML code should be in a separate + :code:`.qml` file, which can be edited by design tools. + .. _faq-section: Frequently Asked Questions @@ -146,45 +242,38 @@ Frequently Asked Questions Here you can find a couple of common questions and situations that will clarify questions before you start programming. -.. panels:: - :container: container-lg pb-1 - :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2 - - .. link-button:: faq/whatisqt - :type: ref - :text: Qt, QML, Widgets... What is the difference? - :classes: btn-link btn-block stretched-link - --- - - .. link-button:: faq/whichide - :type: ref - :text: Which IDEs are compatible with PySide? - :classes: btn-link btn-block stretched-link - --- - - .. link-button:: faq/whatisshiboken - :type: ref - :text: Binding Generation: What is Shiboken? - :classes: btn-link btn-block stretched-link - --- - - .. link-button:: faq/typesoffiles - :type: ref - :text: File Types in PySide - :classes: btn-link btn-block stretched-link - --- - - .. link-button:: faq/distribution - :type: ref - :text: Distributing your application to other systems and platforms - :classes: btn-link btn-block stretched-link - - --- - - .. link-button:: faq/whyqtforpython - :type: ref - :text: As a Qt/C++ developer, why should I consider Qt for Python? - :classes: btn-link btn-block stretched-link +.. grid:: 1 3 3 3 + :gutter: 2 + + .. grid-item-card:: What is Qt + :link: faq/whatisqt.html + + Qt, QML, Widgets... What is the difference? + + .. grid-item-card:: Compatible IDEs + :link: faq/whichide.html + + Which IDEs are compatible with PySide? + + .. grid-item-card:: Binding Generation + :link: faq/whatisshiboken.html + + What is Shiboken? + + .. grid-item-card:: File types + :link: faq/typesoffiles.html + + File Types in PySide + + .. grid-item-card:: App distribution + :link: faq/distribution.html + + Distributing your application to other systems and platforms + + .. grid-item-card:: Why Qt for Python? + :link: faq/whyqtforpython.html + + As a Qt/C++ developer, why should I consider Qt for Python? .. toctree:: :hidden: @@ -196,4 +285,3 @@ clarify questions before you start programming. faq/distribution.rst faq/whyqtforpython.rst - |