diff options
Diffstat (limited to 'sources/pyside6/doc/tutorials/pretutorial')
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/distribution.rst | 69 | ||||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/hello_linux.png | bin | 5960 -> 0 bytes | |||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png | bin | 38777 -> 0 bytes | |||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg | bin | 5314 -> 0 bytes | |||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/tiobe.png | bin | 49961 -> 0 bytes | |||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst | 152 | ||||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/whatisqt.rst | 112 | ||||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/whatisshiboken.rst | 42 | ||||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/whichide.rst | 54 | ||||
-rw-r--r-- | sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst | 205 |
10 files changed, 0 insertions, 634 deletions
diff --git a/sources/pyside6/doc/tutorials/pretutorial/distribution.rst b/sources/pyside6/doc/tutorials/pretutorial/distribution.rst deleted file mode 100644 index fea588153..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/distribution.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _distribution: - -Distributing Your Application to Other Systems/Platforms -======================================================== - -After developing a couple of applications, you might want to distribute them to -other users. In case you do not have much experience with Python packages, you -might have even asked: *How do I create a Python executable?*. - -If you come from compiled programming languages, deployment is something -almost trivial, but for Python is a bit difficult. - -The deployment process for Python applications is called, "freezing", which is -distributing your virtual environment content to other users. - -.. important:: As Python does not support WebAssembly and mobile platforms, - such as Android and iOS, you cannot deploy applications to these platforms - directly, and you require advanced processes to do so. - -.. note:: For embedded systems, you currently need to build |project| for your - target platform, and deploy the installation alongside your application. - -Reproducible deployment ------------------------ - -A common approach is to only provide a ``requirements.txt`` file, where you -state your dependencies. Users would need to install them from there -to run your Application. - -For example, imagine I have a project with two dependencies, ``module_a`` and -``module_b``, which I use in my ``main.py`` file. So my structure is: - -.. code-block:: python - - # Content of the main.py file - from module_a import something - import module_b - - # ... - -So the ``requirements.txt`` for my application would look like this:: - - module_a - module_b - -Later, when a user want to execute your ``main.py``, the dependencies -must be installed using :command:`pip install -r requirements.txt` -in a new virtual environment. - -.. important:: You can notice that this approach includes sharing your code - so it fails if you want to hide the code of your application. - -Freezing Your Application -------------------------- - -This is the most common approach for users to distribute their applications -and even though the code is still available for the end user, it is a bit more -difficult to retrieve it. - -You can find a series of tutorials based on the most popular tools that -allow Python users to freeze and distribute applications in our -:ref:`deployment-guides` section. - -Compiling Python ----------------- - -Even though Python does not natively support to be compiled, there are -complementary tools that let you to achieve this. -You can check the `Nuitka <https://nuitka.net/>`_ project to learn more. diff --git a/sources/pyside6/doc/tutorials/pretutorial/hello_linux.png b/sources/pyside6/doc/tutorials/pretutorial/hello_linux.png Binary files differdeleted file mode 100644 index f335a234d..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/hello_linux.png +++ /dev/null diff --git a/sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png b/sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png Binary files differdeleted file mode 100644 index 863149399..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png +++ /dev/null diff --git a/sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg b/sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg Binary files differdeleted file mode 100644 index 78dcf8ab5..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg +++ /dev/null diff --git a/sources/pyside6/doc/tutorials/pretutorial/tiobe.png b/sources/pyside6/doc/tutorials/pretutorial/tiobe.png Binary files differdeleted file mode 100644 index 87647d1c2..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/tiobe.png +++ /dev/null diff --git a/sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst b/sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst deleted file mode 100644 index 71d38f809..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst +++ /dev/null @@ -1,152 +0,0 @@ -.. _typesoffiles: - -File Types -========== - -There are many different file types that you will encounter while -developing |project| applications, ui, qrc, qml, pyproject, etc. -Here you can find a simple explanation for -each of them. - -Python Files ``.py`` --------------------- - -Python files are the main format you will be dealing with, while developing -|project| projects. - -It is important to note that you can write applications **only** with Python -files, without the need of ``.ui``, ``.qrc``, or ``.qml`` files, however -using other formats will facilitate some processes, and enable new -functionality to your applications. - -.. code-block:: python - - class MyWidget(QWidget): - def __init__(self): - QWidget.__init__(self) - - self.hello = ["Hallo Welt", "你好,世界", "Hei maailma", - "Hola Mundo", "Привет мир"] - - self.button = QPushButton("Click me!") - self.text = QLabel("Hello World") - self.text.setAlignment(Qt.AlignCenter) - # ... - -User Interface Definition File ``.ui`` --------------------------------------- - -When using Qt Designer, you can create user interfaces using Qt Widgets with -the WYSIWYG form editor, this interface is represented as a widget tree using -XML. Here is an extract of the beginning of a ``.ui`` file: - -.. code-block:: xml - - <?xml version="1.0" encoding="UTF-8"?> - <ui version="4.0"> - <class>MainWindow</class> - <widget class="QMainWindow" name="MainWindow"> - <property name="geometry"> - <rect> - <x>0</x> - <y>0</y> - <width>400</width> - <height>300</height> - </rect> - </property> - <property name="windowTitle"> - <string>MainWindow</string> - </property> - <widget class="QWidget" name="centralWidget"> - ... - -The `pyside6-uic` tool generates Python code from these `.ui` files, -which you can import from your main files, so it is not necessary -for you to include the `.ui` files in your deployed application. - -For more details, see :ref:`using_ui_files`. - -Resource Collection Files ``.qrc`` ----------------------------------- - -List of binary files that will be used alongside your application. -As an XML-based file, its structure look like this: - -.. code-block:: xml - - <!DOCTYPE RCC><RCC version="1.0"> - <qresource> - <file>images/quit.png</file> - <file>font/myfont.ttf</file> - </qresource> - </RCC> - - -The `pyside6-rcc` tool generates Python code from these `.qrc` files, -so you are not required to include the listed files in your deployed -application. - -For more details, see :ref:`using_qrc_files`. - -Qt Modeling Language File ``.qml`` ----------------------------------- - -Graphical QML applications are not related to Qt Widgets applications, and -that is why the usual setup of QML project is a Python file that loads -the QML file, and optionally, elements defined in Python that are exposed -to QML to be used. - -You can write ``.qml`` files by hand, but also you can use tools like the -QML Designer that is embedded in Qt Creator. Additionally, there are commercial -tools like Qt Design Studio that allow you to load designs from other design -applications. - -Here you can find an example of how a ``.qml`` file looks like. -The code will display a lightgray rectangle, with the "Hello World!" -message on it. - -.. code-block:: javascript - - import QtQuick 2.0 - - Rectangle { - id: page - width: 320; - height: 480 - color: "lightgray" - - Text { - id: helloText - text: "Hello world!" - y: 30 - anchors.horizontalCenter: page.horizontalCenter - font.pointSize: 24; - font.bold: true - } - } - -Qt Creator Python Project File ``.pyproject`` ---------------------------------------------- - -For Qt Creator to load and handle Python based projects, a special file is -needed, because C++ based projects could be handle from ``.qmake`` or -``CMakeLists.txt`` file, which are not used with Python-based projects. - -Old versions of Qt Creator, provided a simple format with the ``.pyqtc`` -extension, which were plain-text files with one-file-per-line:: - - library/server.py - library/client.py - logger.py - ... - -There were limitations to this format, and further options that might be -added that would not be supported, which was the motivation to create a -``.pyproject`` file, which is a JSON-based file where more options could -be added. Here is an example of such file: - -.. code-block:: javascript - - { - "files": ["library/server.py", "library/client.py", "logger.py", ...] - } diff --git a/sources/pyside6/doc/tutorials/pretutorial/whatisqt.rst b/sources/pyside6/doc/tutorials/pretutorial/whatisqt.rst deleted file mode 100644 index 2dee661a7..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/whatisqt.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _whatisqt: - -Qt, QML, Widgets...What Is The Difference? -========================================== - -If you are new to Qt, there might be a chance that you are a bit confused about -all the concepts you have read so far. This section aims to provide a summary -of all the key components that are relevant to develop Qt applications. - -Keep in mind that Qt was designed and written in C++ as a C++ framework, you -will find many references, examples, and concepts that make sense in C++ -based applications, that might not be relevant in your Python applications, -but keep in mind that |project| aims to expose the Qt framework to Python -with many adaptations. You don't need to know C++ to use |project|, and you -can find all the possible combinations between these languages later on. - -Qt --- - -The Qt Project is an open collaboration that coordinates the development of the -Qt Framework. You might find situations where "Qt" refers to the project, or -to the framework. - -As a framework, Qt has many components, which are distributed by components -and modules, for example, `qtbase <https://code.qt.io/cgit/qt/qtbase.git/>`_ -is the base component that holds many modules, like: ``QtCore``, ``QtGui``, -``QtWidgets``, ``QtNetwork``, etc. -All those modules contains many classes that you can directly use, like the -case of the `Classes of QtCore <https://doc.qt.io/qt-6/qtcore-module.html>`_ -from which you can find classes like ``QFile``, ``QTime``, ``QByteArray``, etc. - -You can create applications without a User Interface, while using this classes -to create command line applications, handle files, network connections, -regular expressions, encoding of text, etc. - -On the other hand, you can create Graphical applications with classes -from the ``QtWidgets`` module, this is also referred as **Widgets**. - -There are many other Qt modules like ``QtMultimedia``, ``QtCharts``, ``Qt3D``, -among others. These modules has a specific functionality, and among this -modules, there is one called ``QtDeclarative``, in which you can find the -implementation of the ``QML`` declarative language. This language is similar -to CSS and JSON, and it was created to design UI applications declaratively, -allowing JavaScript to take care of some imperative sections, and enabling -other components to extend and connect the code with C++. - -Let us check the functionality of these different approaches separately. - -Widgets -------- - -As we mentioned before, ``QtWidgets`` is the module that provide predefined -Widgets that you can add into your graphical application, like Buttons, Labels, -Boxes, Menus, etc. - -Widget based applications will look like a native application, because the goal -is not to affect the user experience compared to other included applications. - -.. image:: hello_macOS.png - :width: 20% -.. image:: hello_win10.jpg - :width: 20% -.. image:: hello_linux.png - :width: 20% - -.. note:: You can adapt these applications to use your self-made style, but - you need to be aware that the goal of Widgets is to respect the system - style, be careful when changing colors. Check this `simple tutorial - <widgetstyling>`_ on how to do so. - -QML ---- - -QML offers an alternative approach to create User Interfaces, compared to -Widgets, and it was originally motivated from mobile applications development. -Together with the ``Qt Quick`` module, it provides access to interact with -mobile device using actions like taps, drag and drop, animations, states, -transitions, drawer menus, etc. - -The elements that you can find in QML/Quick applications are focused on -providing a more dynamic application infrastructure which different properties -based in certain behaviors. - -Even though QML has the motivation to provide interfaces with mobile devices, -you can use it for Desktop applications, too. - -Additionally, you can augment your application with standard JavaScript, which -in combination with C++ can become an attractive infrastructure. - -Python And C++ --------------- - -For |project| applications you **do not need to know C++**, but it is possible -to mix both languages in a couple of different use cases: - -1. If you have a Qt/C++ application, you can re-write it so it is a Qt/Python - application. This means that Python aims to be a full replacement for the - user level C++ code of Qt applications. -2. For custom Qt widgets written in C++, you can generate your own Python - bindings so people can use it directly from Python. -3. If you have a C++ based library that you use with your Qt/C++ applications - that is in charge of a specific task, like a performant process, you can - generate bindings for it, so people could be able to use it from Python. -4. For a Qt/C++ application, you can extend it with Python, by exposing the - main QApplication singleton as a python binding to a Python interpreter. - This can be understand as a "Python Plugin System" for your Qt/C++ - application, for example. - -For the the steps **2., 3., and 4.** you need the help of Shiboken, the -binding generation tool that is used to generate |project|. -You can find more information in the -`documentation page <https://doc.qt.io/qtforpython/shiboken6/index.html>`_. diff --git a/sources/pyside6/doc/tutorials/pretutorial/whatisshiboken.rst b/sources/pyside6/doc/tutorials/pretutorial/whatisshiboken.rst deleted file mode 100644 index 67aafc4f8..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/whatisshiboken.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _whatisshiboken: - -Binding Generation: What Is Shiboken? -===================================== - -When you install ``PySide6`` you might have notice that also ``Shiboken6`` -is installed as a dependency: - -.. code-block:: bash - - (env) [qt ~]$ pip install pyside6 - Collecting pyside6 - Downloading PySide6-6.0.0-6.0.0-cp36.cp37.cp38.cp39-abi3-manylinux1_x86_64.whl (170.5 MB) - |████████████████████████████████| 170.5 MB 42 kB/s - Collecting shiboken6==6.0.0 - Downloading shiboken6-6.0.0-6.0.0-cp36.cp37.cp38.cp39-abi3-manylinux1_x86_64.whl (964 kB) - |████████████████████████████████| 964 kB 29.3 MB/s - Installing collected packages: shiboken6, pyside6 - Successfully installed pyside6-6.0.0 shiboken6-6.0.0 - -That installed package is also called **Shiboken Module**, and it contains -some utilities for PySide to properly work. -You can find more information about it on its -`documentation page <https://doc.qt.io/qtforpython/shiboken6/shibokenmodule.html>`_ - -There is a third package that does not get installed when you install PySide, -because it is not required, and it is called **Shiboken Generator**. - -Most of the times you see mentions to use "Shiboken" or to do something -related to "binding generation", it is about this third package, and **not** -the dependency of the PySide package. - -Do I Need Shiboken Generator? ------------------------------ - -If your goal is to just write Qt applications in Python, -you do not need to worry about a Shiboken generator installation, -but on the other hand, if you want to work with your own bindings -or extend Qt/C++ applications with Python, you **need** it. - -You can find all the information related to Shiboken on its -`documentation page <https://doc.qt.io/qtforpython/shiboken6/>`_. diff --git a/sources/pyside6/doc/tutorials/pretutorial/whichide.rst b/sources/pyside6/doc/tutorials/pretutorial/whichide.rst deleted file mode 100644 index ec005a188..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/whichide.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _whichide: - -Which IDEs Are Compatible? -========================== - -|project|, as any other Python module, can be used in any Python-compatible -IDE, but not all of them will provide extra functionality like Qt Creator does. - -Besides writing files, there are some external steps you might want to perform -in order to help the development of your applications: - -From a terminal: - -* Generating a Python file from a ``.ui`` file: - :command:`pyside6-uic -i form.ui -o ui_form.py` -* Generating a Python file from a ``.qrc`` file: - :command:`pyside6-rcc -i resources.qrc -o rc_resources.py` -* Opening Qt Designer with the command :command:`pyside6-designer` to - edit/create ``.ui`` files. - -External add-ons/plugins from your favorite IDE might include configuration -steps to run these commands, or open external tools like Designer and -QtCreator. - -QtCreator ---------- - -You can create new projects based on some basic templates that are currently -available in QtCreator. After selecting one, you will pass through some steps -where you can specify the details of the template, like the project name, -base Qt class to use for your interface, among others. - -Here you can see an animation of the creation of a project: - -.. image:: https://qt-wiki-uploads.s3.amazonaws.com/images/7/7c/Qtcreator.gif - :alt: Qt Creator Animation - -Visual Studio Code ------------------- - -Besides editing the code of your application, you can use external plugins to -enable more functionality, like this unofficial -`plugin <https://marketplace.visualstudio.com/items?itemName=seanwu.vscode-qt-for-python>`_ -that you can install from VS Code while writing the following on the Quick Open Menu (``Ctrl+P``): -:command:`ext install seanwu.vscode-qt-for-python`. - -PyCharm -------- - -You can configure PyCharm to enable external tools, in |project| terms, Qt Designer, and -Qt Creator. Go to ``File > Settings > tools > PyCharm External Tools``, and include the following -information to add them to your project. -Later, you will be able to right click a ``.ui`` file, and select ``Qt Designer``, -``pyside6-uic``, or any tool that you configured this way. diff --git a/sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst b/sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst deleted file mode 100644 index ecb1873f4..000000000 --- a/sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _whyqtforpython: - -Why Qt for Python? -================== - -.. raw:: html - - <div style="float: right; padding-left: 20px; max-width: 30%; - background-color: #e9eff5; padding-top: 5px;"> - <img src="../../_images/tiobe.png" - style="width: 90%;" - alt="TIOBE index for Python" /> - <p style="font-size: 80%;"> - Screenshot from - <a href="https://www.tiobe.com/tiobe-index/python/">tiobe.com/tiobe-index/python</a>, - on 2021.09.06 - </p> - </div> - -To answer this question we need to take a step back, and talk a bit about -languages. - -Python has been around for almost the same amount of years that Qt has, -and similarly it has been growing, and transforming to become the most used, -loved, and demanded language for many programming areas. - -Currently (2021), it's rare to be aware of Machine Learning and Artificial -Intelligence, without having heard of Python. Similarly, when we hear about -Data Science/Analysis/Engineering we know that it is most probably related -to Python. - -One can validate this statements by public surveys that have been showing -the evolution and preference of the Python language, like the StackOverflow -Surveys of the lasts years: - -+----------------------+-----------+-----------+-----------+ -| | 2019_ | 2020_ | 2021_ | -+======================+===========+===========+===========+ -| Most Loved Language | 2nd place | 3rd place | 6th place | -+----------------------+-----------+-----------+-----------+ -| Most Wanted Language | 1st place | 1st place | 1st place | -+----------------------+-----------+-----------+-----------+ - -and the `TIOBE index`_ (image on the right). - -It's natural to think that this sources might not be enough to judge the -language in general terms, but it certainly highlights a trend among -developers around the world. - -Lowering the Qt Barrier ------------------------ - -Veteran C++ developers will have no problem with setting up a Qt -application from scratch, or even manage to understand a different -code base written with Qt. In addition, many teams are multidisciplinary, -and other project/company developers might not be fluent in C++. - -Python has been luring people into programming, and for the same reason -it's not uncommon that even people with a different background are able -to write code, meaning that different teams are enabled to speak -"the same language". - -Creating Qt applications in Python requires only a few lines of code, -and not much configuration is required to execute it. As an /unfair/ -example, let's check the code of a simple hello world application: - - -.. panels:: - :container: container-lg - - :column: col-lg-6 p-2 - - .. tabbed:: C++ Header - - .. code-block:: cpp - - #ifndef MAINWINDOW_H - #define MAINWINDOW_H - - #include <QMainWindow> - #include <QPushButton> - - class MainWindow : public QMainWindow - { - Q_OBJECT - public: - MainWindow(QWidget *parent = nullptr); - private slots: - void handleButton(); - private: - QPushButton *m_button; - }; - - #endif // MAINWINDOW_H - - .. tabbed:: C++ Implementation - - .. code-block:: cpp - - #include "mainwindow.h" - - MainWindow::MainWindow(QWidget *parent) - : QMainWindow(parent) - { - m_button = new QPushButton("My Button", this); - connect(m_button, SIGNAL(clicked()), this, - SLOT(handleButton())); - } - - void MainWindow::handleButton() - { - m_button->setText("Ready"); - } - - .. tabbed:: C++ Main - - .. code-block:: cpp - - #include <QApplication> - #include "mainwindow.h" - - int main(int argc, char *argv[]) - { - QApplication app(argc, argv); - MainWindow mainWindow; - mainWindow.show(); - return app.exec(d); - } - - --- - :column: col-lg-6 p-2 - - .. tabbed:: Python - - .. code-block:: python - - import sys - from pyside6.QtWidgets import (QApplication, QMainWindow, - QPushButton) - - class MainWindow(QMainWindow): - def __init__(self, parent=None): - QMainWindow.__init__(self, parent) - self.button = QPushButton("My Button", self) - self.button.clicked.connect(self.handleButton) - - def handleButton(self): - self.button.setText("Ready") - - if __name__ == "__main__": - app = QApplication([]) - mainWindow = MainWindow() - mainWindow.show() - sys.exit(app.exec()) - -It's fair to say that most of the boilerplate code is provided by many -good IDEs, like QtCreator, but using external tools certainly requires -some practice to use them and get familiarized. - -Unity Makes Strength --------------------- - -In our mission to enable more developers to enter the Qt World, it's -important to note that this doesn't imply C++ developers are forgotten. - -Together with the bindings, Qt for Python provides our binding generator, -Shiboken (Check :ref:`whatisshiboken`), whose functionality has -extensibly been shown by talks on events such as those from our -:ref:`video-gallery` section. - -Generating bindings between two languages it nothing new, but it has -always been a non-trivial task, mainly for being as-compatible-as-possible -when using external modules/libraries in your project. - -Shiboken's main use case is to extend Qt/C++ project's -functionality, making them **scriptable**. - -What does it mean for an application to be scriptable? - -* enables a interpreted language to interact directly with the Qt/C++ - application, -* provide the option to modify and create components/elements of the - application from Python, -* possibility to create a plugins/add-ons system for the application. -* complement a process with external Python functionality. - -Check out this `Shiboken Webinar`_ for a hands-on example. - -Shiboken excels at Qt-dependent binding generation, meaning that -any Qt/C++ project can be easily exposed to Python. -In addition, Shiboken has proven its support for C++ projects (without Qt), -as shown on event talks and `blog posts`. - -Adding Python support to well known solutions/projects is a pattern we keep -seeing in the industry, on a broad range of devices. -This is why we are working every day to improve the Qt for Python offering. - -We believe both Qt and Python will benefit from this interaction. - -.. _2019: https://insights.stackoverflow.com/survey/2019 -.. _2020: https://insights.stackoverflow.com/survey/2020 -.. _2021: https://insights.stackoverflow.com/survey/2021 -.. _`TIOBE index`: https://www.tiobe.com/tiobe-index/ -.. _`blog posts`: https://www.qt.io/blog/tag/qt-for-python -.. _`Shiboken Webinar`: https://www.youtube.com/watch?v=wOMlDutOWXI |