diff options
Diffstat (limited to 'sources/pyside6/doc/tutorials')
18 files changed, 659 insertions, 30 deletions
diff --git a/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst b/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst index bd45f1f64..e81e4964a 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/clickablebutton.rst @@ -1,5 +1,5 @@ -A Simple Button Tutorial -************************ +Using a Simple Button +===================== In this tutorial, we'll show you how to handle **signals and slots** using Qt for Python. **Signals and slots** is a Qt feature that lets diff --git a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst index 04f6ffa5d..da3b336cd 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst @@ -1,5 +1,5 @@ -Creating a Simple PySide6 Dialog Application -********************************************* +Creating a Dialog Application +============================= This tutorial shows how to build a simple dialog with some basic widgets. The idea is to let users provide their name @@ -43,7 +43,7 @@ just sets the title of the dialog window. In `main()`, you can see that we are creating a *Form object* and showing it to the world. Create the Widgets -=================== +------------------ We are going to create two widgets: a `QLineEdit` where users can enter their name, and a `QPushButton` that prints the contents of @@ -59,7 +59,7 @@ It's obvious from the code that both widgets will show the corresponding texts. Create a layout to organize the Widgets -======================================== +--------------------------------------- Qt comes with layout-support that helps you organize the widgets in your application. In this case, let's use `QVBoxLayout` to lay out @@ -68,18 +68,14 @@ after creating the widgets: :: # Create layout and add widgets - layout = QVBoxLayout() + layout = QVBoxLayout(self) layout.addWidget(self.edit) layout.addWidget(self.button) - # Set dialog layout - self.setLayout(layout) -So, we create the layout, add the widgets with `addWidget()`, -and finally we say that our **Form** will have our `QVBoxLayout` -as its layout. +So, we create the layout, add the widgets with `addWidget()`. Create the function to greet and connect the Button -==================================================== +--------------------------------------------------- Finally, we just have to add a function to our custom **Form** and *connect* our button to it. Our function will be a part of @@ -106,7 +102,7 @@ Once executed, you can enter your name in the `QLineEdit` and watch the console for greetings. Complete code -============= +------------- Here is the complete code for this tutorial: :: diff --git a/sources/pyside6/doc/tutorials/basictutorial/qml.rst b/sources/pyside6/doc/tutorials/basictutorial/qml.rst index c972daa00..15fd1da75 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/qml.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/qml.rst @@ -1,5 +1,5 @@ -Your First Application Using PySide6 and QtQuick/QML -***************************************************** +Your First QtQuick/QML Application +********************************** QML is a declarative language that lets you develop applications faster than with traditional languages. It is ideal for designing the diff --git a/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png b/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png Binary files differnew file mode 100644 index 000000000..8eb1398a7 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/tablewidget.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/tablewidget.rst b/sources/pyside6/doc/tutorials/basictutorial/tablewidget.rst new file mode 100644 index 000000000..a041e4116 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/tablewidget.rst @@ -0,0 +1,97 @@ +Displaying Data Using a Table Widget +==================================== + +If you want to display data arranged in a table, use a ``QTableWidget`` to do +so, without dealing with much configuration. + +Notice that using a ``QTableWidget`` is not the only path to display +information in tables. You can also create a data model and display it using +a ``QTableView``, but that is not in the scope of this tutorial. + +.. note:: This Widget is a ready-to-use version of something you can customize + further on. To know more about the Model/View architecture in Qt, refer to + its `official documentation <https://doc.qt.io/qt-6/model-view-programming.html>`_. + +1. Import ``QTableWidget``, ``QTableWidgetItem``, and ``QColor`` to display + background colors: + + .. code-block:: python + + import sys + from PySide6.QtGui import QColor + from PySide6.QtWidgets import (QApplication, QTableWidget, + QTableWidgetItem) + +2. Create a simple data model containing the list of names and hex codes for + different colors: + + .. code-block:: python + + colors = [("Red", "#FF0000"), + ("Green", "#00FF00"), + ("Blue", "#0000FF"), + ("Black", "#000000"), + ("White", "#FFFFFF"), + ("Electric Green", "#41CD52"), + ("Dark Blue", "#222840"), + ("Yellow", "#F9E56d")] + +3. Define a function to translate the hex code into an RGB equivalent: + + .. code-block:: python + + def get_rgb_from_hex(code): + code_hex = code.replace("#", "") + rgb = tuple(int(code_hex[i:i+2], 16) for i in (0, 2, 4)) + return QColor.fromRgb(rgb[0], rgb[1], rgb[2]) + +4. Initialize the ``QApplication`` singleton: + + .. code-block:: python + + app = QApplication() + +5. Configure the ``QTableWidget`` to have a number of rows equivalent + to the amount of items from the ``colors`` structure, and a number of + columns with the members of one color entry, plus one. + You can set the column name using the ``setHorizontalHeaderLabels`` as + described below: + + .. code-block:: python + + table = QTableWidget() + table.setRowCount(len(colors)) + table.setColumnCount(len(colors[0]) + 1) + table.setHorizontalHeaderLabels(["Name", "Hex Code", "Color"]) + + .. note:: the reason of using ``+ 1`` is to include a new column where + we can display the color. + +6. Iterate the data structure, create the ``QTableWidgetItems`` instances, and + add them into the table using a ``x, y`` coordinate. Here the data is being + assigned row-per-row: + + .. code-block:: python + + for i, (name, code) in enumerate(colors): + item_name = QTableWidgetItem(name) + item_code = QTableWidgetItem(code) + item_color = QTableWidgetItem() + item_color.setBackground(get_rgb_from_hex(code)) + table.setItem(i, 0, item_name) + table.setItem(i, 1, item_code) + table.setItem(i, 2, item_color) + +7. Show the table and execute the ``QApplication``. + + .. code-block:: python + + table.show() + sys.exit(app.exec_()) + + +The final application will look like this: + +.. image:: tablewidget.png + :alt: QTableWidget example + :align: center diff --git a/sources/pyside6/doc/tutorials/basictutorial/treewidget.png b/sources/pyside6/doc/tutorials/basictutorial/treewidget.png Binary files differnew file mode 100644 index 000000000..077eb5830 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/treewidget.png diff --git a/sources/pyside6/doc/tutorials/basictutorial/treewidget.rst b/sources/pyside6/doc/tutorials/basictutorial/treewidget.rst new file mode 100644 index 000000000..26f29e1f0 --- /dev/null +++ b/sources/pyside6/doc/tutorials/basictutorial/treewidget.rst @@ -0,0 +1,79 @@ +Displaying Data Using a Tree Widget +=================================== + +If you want to display data arranged in a tree, use a ``QTreeWidget`` to do so. + +Notice that using a ``QTreeWidget`` is not the only path to display +information in trees. You can also create a data model and display it using a +``QTreeView``, but that is not in the scope of this tutorial. + +.. note:: This Widget is a ready-to-use version of something you can customize + further on. To know more about the Model/View architecture in Qt, refer to + its `official documentation <https://doc.qt.io/qt-6/model-view-programming.html>`_. + +1. Import ``QTreeWidget`` and ``QTreeWidgetItem`` for this application: + + .. code-block:: python + + import sys + from PySide6.QtWidgets import QApplication, QTreeWidget, QTreeWidgetItem + +2. Define a dictionary with project structures to display the information as a + tree, with files belonging to each project: + + .. code-block:: python + + data = {"Project A": ["file_a.py", "file_a.txt", "something.xls"], + "Project B": ["file_b.csv", "photo.jpg"], + "Project C": []} + +3. Initialize the ``QApplication`` singleton: + + .. code-block:: python + + app = QApplication() + +4. Configure the ``QTreeWidget`` to have two columns, one for the item name, + and the other for item type information of the files in the project + directories. + You can set the column name with the ``setHeaderLabels`` as described below: + + .. code-block:: python + + tree = QTreeWidget() + tree.setColumnCount(2) + tree.setHeaderLabels(["Name", "Type"]) + +5. Iterate the data structure, create the ``QTreeWidgetItem`` elements, and add + the corresponding children to each parent. + We also extract the extension name for only the files and add them + into the second column. + In the constructor, you can see that each element (``QTreeWidgetItem``) is + added to different columns of the tree (``QTreeWidget``). + + .. code-block:: python + + items = [] + for key, values in data.items(): + item = QTreeWidgetItem([key]) + for value in values: + ext = value.split(".")[-1].upper() + child = QTreeWidgetItem([value, ext]) + item.addChild(child) + items.append(item) + + tree.insertTopLevelItems(0, items) + +7. Show the tree and execute the ``QApplication``. + + .. code-block:: python + + tree.show() + sys.exit(app.exec_()) + + +The final application will look like this: + +.. image:: treewidget.png + :alt: QTreeWidget example + :align: center diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst index 8deef1d7f..6c83c1fbf 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst @@ -1,5 +1,7 @@ -Widget Styling -************** +.. _widgetstyling: + +Styling the Widgets Application +=============================== Qt Widgets application use a default theme depending on the platform. In some cases, there are system-wide configurations that modify the Qt theme, @@ -81,7 +83,7 @@ page. .. _`Qt Style Sheet Examples`: https://doc.qt.io/qt-5/stylesheet-examples.html Qt Style Sheets -=============== +--------------- .. warning:: diff --git a/sources/pyside6/doc/tutorials/index.rst b/sources/pyside6/doc/tutorials/index.rst index ca7ae4963..51ff02401 100644 --- a/sources/pyside6/doc/tutorials/index.rst +++ b/sources/pyside6/doc/tutorials/index.rst @@ -1,26 +1,57 @@ |project| Tutorials ==================== -A collection of tutorials with "walkthrough" guides are -provided with |project| to help new users get started. These -documents were ported from C++ to Python and cover a range of topics, -from basic use of widgets to step-by-step tutorials that show how an +A collection of tutorials with walkthrough guides are +provided with |project| to help new users get started. + +Some of these documents were ported from C++ to Python and cover a range of +topics, from basic use of widgets to step-by-step tutorials that show how an application is put together. -Basic tutorials ---------------- +Before you start +---------------- + +If you have not installed PySide yet, remember to check the +`Quick Start <../quickstart.html>`_ section. + +.. toctree:: + :maxdepth: 1 + + pretutorial/whatisqt.rst + pretutorial/whichide.rst + pretutorial/whatisshiboken.rst + pretutorial/typesoffiles.rst + pretutorial/distribution.rst + +Qt Widgets: Basic tutorials +--------------------------- + +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. .. toctree:: :maxdepth: 1 basictutorial/widgets.rst - basictutorial/qml.rst basictutorial/clickablebutton.rst basictutorial/dialog.rst + basictutorial/tablewidget.rst + basictutorial/treewidget.rst basictutorial/uifiles.rst basictutorial/qrcfiles.rst basictutorial/widgetstyling.rst + +Quick/QML: Basic tutorials +-------------------------- + +.. toctree:: + :maxdepth: 1 + + basictutorial/qml.rst + qmlintegration/qmlintegration.rst + Real use-cases applications --------------------------- @@ -28,7 +59,6 @@ Real use-cases applications :maxdepth: 1 qmlapp/qmlapplication.rst - qmlintegration/qmlintegration.rst qmlsqlintegration/qmlsqlintegration.rst .. datavisualize/index.rst diff --git a/sources/pyside6/doc/tutorials/pretutorial/distribution.rst b/sources/pyside6/doc/tutorials/pretutorial/distribution.rst new file mode 100644 index 000000000..f55c3684a --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/distribution.rst @@ -0,0 +1,69 @@ +.. _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` 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 differnew file mode 100644 index 000000000..f335a234d --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/hello_linux.png diff --git a/sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png b/sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png Binary files differnew file mode 100644 index 000000000..863149399 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/hello_macOS.png diff --git a/sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg b/sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg Binary files differnew file mode 100644 index 000000000..78dcf8ab5 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/hello_win10.jpg diff --git a/sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst b/sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst new file mode 100644 index 000000000..f606c2784 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/typesoffiles.rst @@ -0,0 +1,149 @@ +.. _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 interfaces 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. + +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. + + +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 new file mode 100644 index 000000000..2dee661a7 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/whatisqt.rst @@ -0,0 +1,112 @@ +.. _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 new file mode 100644 index 000000000..67aafc4f8 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/whatisshiboken.rst @@ -0,0 +1,42 @@ +.. _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 new file mode 100644 index 000000000..ec005a188 --- /dev/null +++ b/sources/pyside6/doc/tutorials/pretutorial/whichide.rst @@ -0,0 +1,54 @@ +.. _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/qmlintegration/qmlintegration.rst b/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst index 5bbb89609..46b055e13 100644 --- a/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst +++ b/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst @@ -1,6 +1,5 @@ -######################## -QML Integration Tutorial -######################## +Python-based context properties +=============================== This tutorial provides a quick walk-through of a python application that loads, and interacts with a QML file. QML is a declarative language that lets you design UIs faster than a traditional |