diff options
| author | Cristián Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2021-07-07 10:47:13 +0200 |
|---|---|---|
| committer | Cristián Maureira-Fredes <cristian.maureira-fredes@qt.io> | 2021-09-09 15:47:06 +0200 |
| commit | db615e81615ee993cac69a3477351427d798e31e (patch) | |
| tree | 1f3974e29fe50e3ec6a7f98c6423256b4bbf6d84 /sources/pyside6/doc/tutorials | |
| parent | 6dcbbcc08895e3565f95570842f666050aef61a1 (diff) | |
doc: improve tutorials and styling
- Creating screenshots for tutorials.
- Add gallery style for tutorials.
- Add corporate Icons to the frontpage.
- tools: Reduce example long names in the gallery.
- videos: new order using panels
- Add tutorial about "Why Qt for Python"
Change-Id: I3ba50f74998399a47b4a34c1de029f3b746aa1e2
Reviewed-by: Christian Tismer <tismer@stackless.com>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
Diffstat (limited to 'sources/pyside6/doc/tutorials')
23 files changed, 350 insertions, 3 deletions
diff --git a/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.png b/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.png Binary files differnew file mode 100644 index 000000000..bfdc23fe0 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst b/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst index 894060e98..2221858bc 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst @@ -88,3 +88,8 @@ Here is the complete code for this example: button.show() # Run the main Qt loop app.exec() + +After a few clicks, you will get something like this on your terminal: + +.. image:: clickablebutton.png + :alt: Clickable Button Example diff --git a/sources/pyside6/doc/tutorials/basictutorial/dialog.png b/sources/pyside6/doc/tutorials/basictutorial/dialog.png Binary files differnew file mode 100644 index 000000000..ad5690927 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/dialog.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst index 577db27d9..bc06d6d9b 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst @@ -139,3 +139,10 @@ Here is the complete code for this tutorial: form.show() # Run the main Qt loop sys.exit(app.exec()) + + +When you execute the code, and write down your name, +the button will display messages on the terminal: + +.. image:: dialog.png + :alt: Simple Dialog Example diff --git a/sources/pyside6/doc/tutorials/basictutorial/icons.png b/sources/pyside6/doc/tutorials/basictutorial/icons.png Binary files differindex 0bcfd7d77..a5a554eba 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/icons.png +++ b/sources/pyside6/doc/tutorials/basictutorial/icons.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/player-new.png b/sources/pyside6/doc/tutorials/basictutorial/player-new.png Binary files differindex e1f660e5f..8e45c757d 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/player-new.png +++ b/sources/pyside6/doc/tutorials/basictutorial/player-new.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/player.png b/sources/pyside6/doc/tutorials/basictutorial/player.png Binary files differindex 3060a990d..0563d3223 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/player.png +++ b/sources/pyside6/doc/tutorials/basictutorial/player.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png b/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png Binary files differindex 8eb1398a7..e2549f7d0 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png +++ b/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/translations.png b/sources/pyside6/doc/tutorials/basictutorial/translations.png Binary files differnew file mode 100644 index 000000000..b9fc1ba17 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/translations.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/translations.rst b/sources/pyside6/doc/tutorials/basictutorial/translations.rst index 44280580c..544218553 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/translations.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/translations.rst @@ -3,6 +3,9 @@ Translating Applications ======================== +.. image:: translations.png + :alt: Translation Image + Qt Linguist ----------- diff --git a/sources/pyside6/doc/tutorials/basictutorial/treewidget.png b/sources/pyside6/doc/tutorials/basictutorial/treewidget.png Binary files differindex 077eb5830..990fe977b 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/treewidget.png +++ b/sources/pyside6/doc/tutorials/basictutorial/treewidget.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/uifiles.png b/sources/pyside6/doc/tutorials/basictutorial/uifiles.png Binary files differnew file mode 100644 index 000000000..918efec6d --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/uifiles.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst b/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst index adf5ec6d2..b3429ac1f 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst @@ -12,6 +12,9 @@ standalone binary (``pyside6-designer``) or embedded into the is described at `Using Qt Designer <http://doc.qt.io/qtcreator/creator-using-qt-designer.html>`_. +.. image:: uifiles.png + :alt: Designer and the equivalent code + The designs are stored in `.ui` files, which is an XML-based format. It will be converted to Python or C++ code populating a widget instance at project build time by the `pyside6-uic <https://doc.qt.io/qt-6/uic.html>`_ tool. diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgets.png b/sources/pyside6/doc/tutorials/basictutorial/widgets.png Binary files differnew file mode 100644 index 000000000..de7a969f9 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/widgets.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgets.rst b/sources/pyside6/doc/tutorials/basictutorial/widgets.rst index 89bd23f63..ef14c7e99 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgets.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/widgets.rst @@ -17,6 +17,12 @@ Here is a simple example of a Hello World application in PySide6: app.exec() +When you execute it the code, the application will look like: + +.. image:: widgets.png + :alt: Simple Widget + + For a widget application using PySide6, you must always start by importing the appropriate class from the `PySide6.QtWidgets` module. @@ -43,3 +49,4 @@ After the creation of the application object, we have created a Finally, we call `app.exec()` to enter the Qt main loop and start to execute the Qt code. In reality, it is only here where the label is shown, but this can be ignored for now. + diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-no.png b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-no.png Binary files differindex c30dd621b..f8346533f 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-no.png +++ b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-no.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-no.png b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-no.png Binary files differindex eb90e216d..d510a80cd 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-no.png +++ b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-no.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-yes.png b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-yes.png Binary files differindex 5a714977e..e7a0c0ef7 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-yes.png +++ b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-simple-yes.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-yes.png b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-yes.png Binary files differindex 8ba49bd26..9b83b8267 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-yes.png +++ b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling-yes.png diff --git a/sources/pyside6/doc/tutorials/index.rst b/sources/pyside6/doc/tutorials/index.rst index ae02153e4..628ab1fc3 100644 --- a/sources/pyside6/doc/tutorials/index.rst +++ b/sources/pyside6/doc/tutorials/index.rst @@ -11,17 +11,60 @@ application is put together. Before you start ---------------- +Here you can find a couple of common questions and situations that will +clarify questions before you start programming. If you have not installed PySide yet, remember to check the `Quick Start <../quickstart.html>`_ section. +.. panels:: + :container: container-lg pb-1 + :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2 + + .. link-button:: pretutorial/whatisqt + :type: ref + :text: Qt, QML, Widgets... What is the difference? + :classes: btn-link btn-block stretched-link + --- + + .. link-button:: pretutorial/whichide + :type: ref + :text: Which IDEs are compatible with PySide? + :classes: btn-link btn-block stretched-link + --- + + .. link-button:: pretutorial/whatisshiboken + :type: ref + :text: Binding Generation: What is Shiboken? + :classes: btn-link btn-block stretched-link + --- + + .. link-button:: pretutorial/typesoffiles + :type: ref + :text: File Types in PySide + :classes: btn-link btn-block stretched-link + --- + + .. link-button:: pretutorial/distribution + :type: ref + :text: Distributing your application to other systems and platforms + :classes: btn-link btn-block stretched-link + + --- + + .. link-button:: pretutorial/whyqtforpython + :type: ref + :text: As a Qt/C++ developer, why should I consider Qt for Python? + :classes: btn-link btn-block stretched-link + .. toctree:: - :maxdepth: 1 + :hidden: pretutorial/whatisqt.rst pretutorial/whichide.rst pretutorial/whatisshiboken.rst pretutorial/typesoffiles.rst pretutorial/distribution.rst + pretutorial/whyqtforpython.rst Qt Widgets: Basic tutorials --------------------------- @@ -30,8 +73,81 @@ If you want to see the available widgets in action, you can check the `Qt Widget Gallery <https://doc.qt.io/qt-6/gallery.html>`_ to learn their names and how they look like. +.. panels:: + :container: container-lg pb-1 + :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2 + :img-top-cls: d-flex align-self-center + + :img-top: basictutorial/widgets.png + + .. link-button:: basictutorial/widgets + :type: ref + :text: Your First QtWidgets Application + :classes: btn-link btn-block stretched-link + --- + :img-top: basictutorial/clickablebutton.png + + .. link-button:: basictutorial/clickablebutton + :type: ref + :text: Using a Simple Button + :classes: btn-link btn-block stretched-link + --- + :img-top: basictutorial/dialog.png + + .. link-button:: basictutorial/dialog + :type: ref + :text: Creating a Dialog Application + :classes: btn-link btn-block stretched-link + --- + :img-top: basictutorial/tablewidget.png + + .. link-button:: basictutorial/tablewidget + :type: ref + :text: Displaying Data Using a Table Widget + :classes: btn-link btn-block stretched-link + + --- + :img-top: basictutorial/treewidget.png + + .. link-button:: basictutorial/treewidget + :type: ref + :text: Displaying Data Using a Tree Widget + :classes: btn-link btn-block stretched-link + + --- + :img-top: basictutorial/uifiles.png + + .. link-button:: basictutorial/uifiles + :type: ref + :text: Using .ui files from Designer or QtCreator with QUiLoader and pyside6-uic + :classes: btn-link btn-block stretched-link + + --- + :img-top: basictutorial/player-new.png + + .. link-button:: basictutorial/qrcfiles + :type: ref + :text: Using .qrc Files (pyside6-rcc) + :classes: btn-link btn-block stretched-link + + --- + :img-top: basictutorial/translations.png + + .. link-button:: basictutorial/translations + :type: ref + :text: Translating Applications + :classes: btn-link btn-block stretched-link + + --- + :img-top: basictutorial/widgetstyling-yes.png + + .. link-button:: basictutorial/widgetstyling + :type: ref + :text: Styling the Widgets Application + :classes: btn-link btn-block stretched-link + .. toctree:: - :maxdepth: 1 + :hidden: basictutorial/widgets.rst basictutorial/clickablebutton.rst @@ -44,6 +160,7 @@ names and how they look like. basictutorial/widgetstyling.rst + Quick/QML: Basic tutorials -------------------------- diff --git a/sources/pyside6/doc/tutorials/pretutorial/distribution.rst b/sources/pyside6/doc/tutorials/pretutorial/distribution.rst index f55c3684a..fea588153 100644 --- a/sources/pyside6/doc/tutorials/pretutorial/distribution.rst +++ b/sources/pyside6/doc/tutorials/pretutorial/distribution.rst @@ -59,7 +59,7 @@ 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` section. +:ref:`deployment-guides` section. Compiling Python ---------------- diff --git a/sources/pyside6/doc/tutorials/pretutorial/tiobe.png b/sources/pyside6/doc/tutorials/pretutorial/tiobe.png Binary files differnew file mode 100644 index 000000000..87647d1c2 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/tiobe.png diff --git a/sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst b/sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst new file mode 100644 index 000000000..ecb1873f4 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/whyqtforpython.rst @@ -0,0 +1,205 @@ +.. _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 |
