diff options
Diffstat (limited to 'sources/pyside6/doc/quickstart.rst')
| -rw-r--r-- | sources/pyside6/doc/quickstart.rst | 219 |
1 files changed, 193 insertions, 26 deletions
diff --git a/sources/pyside6/doc/quickstart.rst b/sources/pyside6/doc/quickstart.rst index babbab82e..7e1a210f2 100644 --- a/sources/pyside6/doc/quickstart.rst +++ b/sources/pyside6/doc/quickstart.rst @@ -1,44 +1,80 @@ -|project| Quick start -====================== +.. _quick-start: + +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.6+, - * 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 ------------ - -.. raw:: html - - <img src="https://qt-wiki-uploads.s3.amazonaws.com/images/8/8a/Pyside6_install.gif" - style="float: right; width: 35%; padding-left: 20px;" - alt="PySide6 installation animation" /> +.. 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: - * :command:`python -m venv env`, (Your Python executable might be called ``python3``) - * :command:`source env/bin/activate` for Linux and macOS - * :command:`env\\\Scripts\\\activate.bat` for Windows + * Create environment (Your Python executable might be called ``python3``):: + + python -m venv env -* **Installation** + * Activate the environment (Linux and macOS):: + + source env/bin/activate + + * Activate the environment (Windows):: + + env\Scripts\activate.bat + + 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 + +* **Installing PySide6** Now you are ready to install the |project| packages using ``pip``. From the terminal, run the following command: - * :command:`pip install pyside6`, for the latest version. - * :command:`pip install pyside6==6.0`, for the version ``6.0`` specifically. + * For the latest version:: + + pip install pyside6 + + * For a specific version, like 6.4.1:: + + pip install pyside6==6.4.1 + * 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** @@ -53,8 +89,11 @@ Installation # Prints the Qt version used to compile PySide6 print(PySide6.QtCore.__version__) -Create a Simple Application ---------------------------- +.. note:: For more information about what's included in the ``pyside6`` + package, check :ref:`package_details`. + +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 @@ -69,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): @@ -96,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** @@ -118,3 +158,130 @@ 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 +-------------------------- + +Here you can find a couple of common questions and situations that will +clarify questions before you start programming. + +.. 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: + + faq/whatisqt.rst + faq/whichide.rst + faq/whatisshiboken.rst + faq/typesoffiles.rst + faq/distribution.rst + faq/whyqtforpython.rst + |