diff options
| author | Cristián Maureira-Fredes <[email protected]> | 2023-04-04 17:19:23 +0200 |
|---|---|---|
| committer | Cristián Maureira-Fredes <[email protected]> | 2023-04-05 09:26:43 +0200 |
| commit | 900c050c66119454585ec83cf31149f6d64dd3ea (patch) | |
| tree | c9db45471d33aaf9ca6ad7de191d73eed2cbec24 /sources/pyside6/doc | |
| parent | d35b650fe4369952a44c3891fedb6d8ee1417df5 (diff) | |
doc: fix issues with pyside rst files
Fixing extra indentation, syntax issues, and formatting.
Adapting too some snippet line highlights, and many other
details.
Pick-to: 6.5
Change-Id: Ife4eb5cec03577b2902d409b4007ae6d12141747
Reviewed-by: Friedemann Kleint <[email protected]>
Diffstat (limited to 'sources/pyside6/doc')
30 files changed, 543 insertions, 567 deletions
diff --git a/sources/pyside6/doc/considerations.rst b/sources/pyside6/doc/considerations.rst index 680d70340..58c95a112 100644 --- a/sources/pyside6/doc/considerations.rst +++ b/sources/pyside6/doc/considerations.rst @@ -254,7 +254,7 @@ Activating the New Enums The new approach to enum will be the default in ``PySide 6.4``, but a preview is already built into ``PySide 6.3`` with the environment variable: -`PYSIDE63_OPTION_PYTHON_ENUM=1 python3 <myscript>` enables the new enums. +``PYSIDE63_OPTION_PYTHON_ENUM=1 python3 <myscript>`` enables the new enums. In ``PySide 6.4``, this flag is by default on, but it can be switched to the old Shiboken enums by setting the variable to 0. @@ -268,13 +268,10 @@ The Differences between old and new Enums Python enums and Shiboken enums are more or less compatible with each other. Tiny differences are in restrictions: - * Python enums cannot inherit from each other, whereas Shiboken enums can - - * Python enums don't allow undefined values, Shiboken enums do - - * Python enums always need exactly one argument, Shiboken enums have a default zero value - - * Python enums rarely inherit from int, Shiboken enums always do +* Python enums cannot inherit from each other, whereas Shiboken enums can +* Python enums don't allow undefined values, Shiboken enums do +* Python enums always need exactly one argument, Shiboken enums have a default zero value +* Python enums rarely inherit from int, Shiboken enums always do More visible are the differences between flags, as shown in the following: @@ -348,9 +345,8 @@ and never propose the old ones. The reason to implement ``forgiveness mode`` this way was - * to make the transition as smooth as possible, but - - * to encourage people to use the new enums whenever new code is written. +* to make the transition as smooth as possible, but +* to encourage people to use the new enums whenever new code is written. So you can continue to write: diff --git a/sources/pyside6/doc/deployment/deployment-briefcase.rst b/sources/pyside6/doc/deployment/deployment-briefcase.rst index 95aee1432..e85e618a7 100644 --- a/sources/pyside6/doc/deployment/deployment-briefcase.rst +++ b/sources/pyside6/doc/deployment/deployment-briefcase.rst @@ -1,13 +1,16 @@ |project| & Briefcase ####################### -`Briefcase <https://briefcase.readthedocs.io>`_ is a packaging tool that lets you create a standalone package for a Python application. It supports the following installer formats: +`Briefcase <https://briefcase.readthedocs.io>`_ is a packaging tool that lets +you create a standalone package for a Python application. It supports the +following installer formats: - * .app application bundle for macOS - * MSI installer for Windows - * AppImage for Linux +* ``.app`` application bundle for macOS +* MSI installer for Windows +* AppImage for Linux -For more details, see the `official documentation <https://briefcase.readthedocs.io/en/latest/index.html>`_. +For more details, see the `official documentation +<https://briefcase.readthedocs.io/en/latest/index.html>`_. Status of Qt 6 Support ====================== @@ -17,15 +20,15 @@ As of March 2021, Qt 6 is not supported yet. Preparation =========== -Install `Briefcase` using the following **pip** command:: +Install ``Briefcase`` using the following **pip** command:: pip install briefcase You also need : docker on linux, `WixToolset`_ on windows, -If you're using a virtual environment, remember to activate it before installing `Briefcase`. +If you're using a virtual environment, remember to activate it before installing ``Briefcase``. -After installation, the `briefcase` binary is located in your virtual environment's `bin/` +After installation, the ``briefcase`` binary is located in your virtual environment's ``bin/`` directory, or where your Python executable is located. You can either create a brand new project using the briefcase assistant or setup your own. @@ -39,8 +42,8 @@ Run the following command and answer the questions to get started:: briefcase new -Ensure that `PySide6` is chosen as the `GUI toolkit choice`. -Your PySide6 application is now configured. You can jump to `Build the package`_. +Ensure that |pymodname| is chosen as the **GUI toolkit choice**. +Your |pymodname| application is now configured. You can jump to `Build the package`_. Set up your project @@ -49,7 +52,7 @@ Set up your project Create a pyproject.toml ----------------------- -At the root level of your project, create a `pyproject.toml` file:: +At the root level of your project, create a ``pyproject.toml`` file:: [tool.briefcase] project_name = "MyPySideApp" @@ -85,7 +88,7 @@ At the root level of your project, create a `pyproject.toml` file:: Write some code ----------------- +--------------- Let's say your project tree is like this:: @@ -103,7 +106,7 @@ Let's say your project tree is like this:: app.py -Content of `__main__.py`:: +Content of ``__main__.py``:: import sys from PySide6.QtWidgets import QApplication @@ -119,7 +122,7 @@ Content of `__main__.py`:: sys.exit(app.exec()) -Content of `app.py`:: +Content of ``app.py``:: import random from PySide6.QtWidgets import (QLabel, QPushButton, @@ -151,10 +154,10 @@ Content of `app.py`:: Build the package -================== +================= Initialize the package ------------------------- +---------------------- Just run:: @@ -162,7 +165,8 @@ Just run:: Run the following command to initialize the building the packages for Windows, Linux, and macOS. It creates a subdirectory each for the different platforms. -This step takes longer as it adds the packages listed in `requires` sections in the `pyproject.toml` file. +This step takes longer as it adds the packages listed in ``requires`` sections in the +``pyproject.toml`` file. Build the application --------------------- @@ -185,20 +189,23 @@ Run the application briefcase run -.. note:: You can run your project in `dev` mode (your source code not packaged) with `briefcase dev` +.. note:: You can run your project in ``dev`` mode (your source code not packaged) with + ``briefcase dev`` Build the installer (only Windows and macOS) ---------------------------------------------- +-------------------------------------------- macOS:: briefcase package --no-sign -It's possible to sign, see the `documentation <https://briefcase.readthedocs.io/en/latest/how-to/code-signing/index.html>`_. You get `macOS/A Cool App-0.0.1.dmg` +It's possible to sign, see the +`documentation <https://briefcase.readthedocs.io/en/latest/how-to/code-signing/index.html>`_. +You get ``macOS/A Cool App-0.0.1.dmg`` Windows:: briefcase package -You get `windows\A_Cool_App-0.0.1.msi` +You get ``windows\A_Cool_App-0.0.1.msi`` diff --git a/sources/pyside6/doc/deployment/deployment-cxfreeze.rst b/sources/pyside6/doc/deployment/deployment-cxfreeze.rst index 612ca5a32..46cbb142e 100644 --- a/sources/pyside6/doc/deployment/deployment-cxfreeze.rst +++ b/sources/pyside6/doc/deployment/deployment-cxfreeze.rst @@ -15,31 +15,31 @@ if you find any, or contributing to `their development <https://github.com/marce Preparation =========== -Installing `cx_Freeze` can be done using **pip**:: +Installing ``cx_Freeze`` can be done using **pip**:: pip install cx_freeze If you are using a virtual environment, remember to activate it before -installing `cx_Freeze` into it. +installing ``cx_Freeze`` into it. -After the installation, you will have the `cxfreeze` binary to deploy +After the installation, you will have the ``cxfreeze`` binary to deploy your application. Freezing an application ======================= -There are three options to work with `cx_Freeze`: +There are three options to work with ``cx_Freeze``: - 1. Using the `cxfreeze` script. - 2. Creating `setup.py` script to build the project. - 3. Using the module classes directly (for advanced purposes). +1. Using the ``cxfreeze`` script. +2. Creating ``setup.py`` script to build the project. +3. Using the module classes directly (for advanced purposes). The following sections cover the first two use cases. Creating an example ------------------- -Now, consider the following simple script, named `hello.py`:: +Now, consider the following simple script, named ``hello.py``:: import sys import random @@ -80,28 +80,28 @@ Now, consider the following simple script, named `hello.py`:: sys.exit(app.exec()) -Using `cxfreeze` executable ---------------------------- +Using ``cxfreeze`` executable +----------------------------- Now that we have an application, try freezing it with the following command:: cxfreeze hello.py -This command creates a `dist/` directory containing the executable. -and a `lib/` directory containing all the shared libraries. +This command creates a ``dist/`` directory containing the executable. +and a ``lib/`` directory containing all the shared libraries. -To launch the application, go to the `dist/` directory and execute +To launch the application, go to the ``dist/`` directory and execute the file:: cd dist/ ./main -Using a setuptools script -------------------------- +Using a ``setuptools`` script +----------------------------- -For this process, you need an additional script called `setup.py`:: +For this process, you need an additional script called ``setup.py``:: import sys from cx_Freeze import setup, Executable @@ -115,15 +115,15 @@ Now, build the project using it:: python setup.py build -This step creates a `build/` directory with the following structure:: +This step creates a ``build/`` directory with the following structure:: build └── exe.linux-x86_64-3.7 └── lib └── main -The first directory inside `build/` depends on the platform -you are using, in this case a `x86_64` Linux using Python 3.7. +The first directory inside ``build/`` depends on the platform +you are using, in this case a ``x86_64`` Linux using Python 3.7. The structure is the same as previously described, and you can simply enter the directory and execute the file:: diff --git a/sources/pyside6/doc/deployment/deployment-fbs.rst b/sources/pyside6/doc/deployment/deployment-fbs.rst index 1098ccd4e..459a225bf 100644 --- a/sources/pyside6/doc/deployment/deployment-fbs.rst +++ b/sources/pyside6/doc/deployment/deployment-fbs.rst @@ -2,7 +2,7 @@ #################### `fbs`_ provides a powerful environment for packaging, creating installers, and signing your -application. It also lets you manage updates to your application. Since `fbs` is based on +application. It also lets you manage updates to your application. Since `fbs`_ is based on PyInstaller, it supports Linux, macOS, and Windows. For more details, see the `fbs tutorial`_ and the `fbs manual`_. @@ -32,12 +32,12 @@ command:: This command prompts you to answer a few questions to configure the details of your project, like: - * Application name - * Author name - * Qt bindings (PySide6 or PyQt5) - * Bundle indentified (for macOS) +* Application name +* Author name +* Qt bindings (PySide6) +* Bundle indentified (for macOS) -Afterwards, you have a `src/` directory that contains the following structure:: +Afterwards, you have a ``src/`` directory that contains the following structure:: └── src ├── build @@ -49,10 +49,10 @@ Afterwards, you have a `src/` directory that contains the following structure:: │ └── mac └── python -Inside the `settings` directory, there are a few JSON files that can be edited to include more +Inside the ``settings`` directory, there are a few JSON files that can be edited to include more information about your project. -The `main` file is in the `python` directory, and its default content is:: +The ``main`` file is in the ``python`` directory, and its default content is:: from fbs_runtime.application_context import ApplicationContext from PySide6.QtWidgets import QMainWindow @@ -67,7 +67,7 @@ The `main` file is in the `python` directory, and its default content is:: exit_code = appctxt.app.exec() # 2. Invoke appctxt.app.exec() sys.exit(exit_code) -This example shows an empty `QMainWindow`. You can run it using the following command:: +This example shows an empty ``QMainWindow``. You can run it using the following command:: fbs run @@ -87,11 +87,11 @@ example:: Now, you can try to run the application. The result is the same window as the one you saw with the -`fbs run` command:: +``fbs run`` command:: cd target/MyApp/ ./MyApp .. note:: This is the case for Linux. For other platforms like macOS, you need to enter the - directory: `target/MyApp.app/Contents/macOS`. For Windows, you need to find the `MyApp.exe` + directory: ``target/MyApp.app/Contents/macOS``. For Windows, you need to find the ``MyApp.exe`` executable. diff --git a/sources/pyside6/doc/deployment/deployment-nuitka.rst b/sources/pyside6/doc/deployment/deployment-nuitka.rst index 9be982a4c..8b0afa56c 100644 --- a/sources/pyside6/doc/deployment/deployment-nuitka.rst +++ b/sources/pyside6/doc/deployment/deployment-nuitka.rst @@ -11,11 +11,11 @@ For more details, see the `official documentation <https://nuitka.net/pages/over Preparation =========== -Install `Nuitka` via **pip** with the following command:: +Install ``Nuitka`` via **pip** with the following command:: - pip3 install nuitka + pip install nuitka -After installation, the `nuitka3` binary is located in your virtual environment's `bin/` +After installation, the ``nuitka3`` binary is located in your virtual environment's ``bin/`` directory, or where your Python executable is located. Alternatively, you can also run:: @@ -26,7 +26,7 @@ to achieve the same effect. Freeze an application ===================== -`Nuitka` has many options that you can use. To list them all, run `nuitka3 -h`. +``Nuitka`` has many options that you can use. To list them all, run ``nuitka3 -h``. To simply compile a project, you can run:: @@ -34,17 +34,17 @@ To simply compile a project, you can run:: There are two main features: - * the option to place it in a directory containing the libraries - (`--standalone`) - * the option to package the whole project (including shared libraries) into one executable file - (`--onefile`) +* the option to place it in a directory containing the libraries + (``--standalone``) +* the option to package the whole project (including shared libraries) into one executable file + (``--onefile``) -If you use these options, you need to specify `--plugin-enable=pyside6`. +If you use these options, you need to specify ``--plugin-enable=pyside6``. Run an example -------------- -Now, consider the following script, named `hello.py`:: +Now, consider the following script, named ``hello.py``:: import sys import random @@ -84,13 +84,13 @@ Now, consider the following script, named `hello.py`:: sys.exit(app.exec()) -You don't have to copy this script. You find it as `examples/installer_test/hello.py`. +You don't have to copy this script. You find it as ``examples/installer_test/hello.py``. The command line to proceed looks like this:: nuitka3 examples/installer_test/hello.py -This process creates an executable `hello.bin` and a directory hello.build that you +This process creates an executable ``hello.bin`` and a directory hello.build that you don't need. You can execute the binary directly. In order to create a bundle which can be copied onto a machine without any pre-existing @@ -98,23 +98,23 @@ installation, run:: nuitka3 --standalone --plugin-enable=pyside6 examples/installer_test/hello.py -This creates an application `hello.dist/hello` that contains everything needed to run. +This creates an application ``hello.dist/hello`` that contains everything needed to run. -To run the application, go to `hello.dist/` and run the program:: +To run the application, go to ``hello.dist/`` and run the program:: cd hello.dist ./hello -Use the `--onefile` option if you prefer to have everything bundled into one executable, without +Use the ``--onefile`` option if you prefer to have everything bundled into one executable, without the shared libraries next to it. First you need to install:: - pip3 install zstandard + pip install zstandard -for data compression. Then you can run +for data compression. Then you can run:: nuitka3 --onefile --plugin-enable=pyside6 examples/installer_test/hello.py -This process takes a bit longer, but in the end you have one executable `hello.bin`:: +This process takes a bit longer, but in the end you have one executable ``hello.bin``:: ./hello.bin @@ -127,6 +127,6 @@ Nuitka issue on macOS --------------------- Nuitka currently has a problem with the macOS bundle files on current macOS versions. -That has the effect that `--standalone` and `--onefile` create a crashing application. +That has the effect that ``--standalone`` and ``--onefile`` create a crashing application. Older versions which don't have the recent macOS API changes from 2020 will work. We are currently trying to fix that problem. diff --git a/sources/pyside6/doc/deployment/deployment-py2exe.rst b/sources/pyside6/doc/deployment/deployment-py2exe.rst index 24d260d71..6ca09a826 100644 --- a/sources/pyside6/doc/deployment/deployment-py2exe.rst +++ b/sources/pyside6/doc/deployment/deployment-py2exe.rst @@ -1,16 +1,16 @@ |project| & py2exe ################## -Deploying an application using py2exe requires writing a small `setup.py` file. +Deploying an application using py2exe requires writing a small ``setup.py`` file. It is explained in the `Tutorial <http://www.py2exe.org/index.cgi/Tutorial>`_. py2exe is not generally aware of Qt. It merely copies the dependent libraries -of the application to the `dist` directory, so, the plugins, QML imports +of the application to the ``dist`` directory, so, the plugins, QML imports and translations of Qt are missing. The latter need to be copied manually after running py2exe. -This can be achieved by running the `windeployqt` tool -from the Qt SDK on the Qt libraries present in the `dist` directory, -for example: +This can be achieved by running the ``windeployqt`` tool +from the Qt SDK on the Qt libraries present in the ``dist`` directory, +for example:: windeployqt dist\\Qt6Widgets.dll diff --git a/sources/pyside6/doc/deployment/deployment-pyinstaller.rst b/sources/pyside6/doc/deployment/deployment-pyinstaller.rst index 8d78ddba0..feb257162 100644 --- a/sources/pyside6/doc/deployment/deployment-pyinstaller.rst +++ b/sources/pyside6/doc/deployment/deployment-pyinstaller.rst @@ -11,15 +11,15 @@ Status of Qt 6 Support ====================== As of March 2021, Qt 6 is not supported yet. PyInstaller is unable to properly -deploy Qt; the Qt plugins are not copied. With that, using `--onefile` is not +deploy Qt; the Qt plugins are not copied. With that, using ``--onefile`` is not possible. -It is possible to use PyInstaller for the non `--onefile` case though by +It is possible to use PyInstaller for the non ``--onefile`` case though by manually copying the Qt plugins, QML imports and translations into the dist directory after running PyInstaller. -On Windows, this can be achieved by running the `windeployqt` tool -from the Qt SDK on the Qt libraries present in the `dist` directory, for +On Windows, this can be achieved by running the ``windeployqt`` tool +from the Qt SDK on the Qt libraries present in the ``dist`` directory, for example: windeployqt dist\\app\\Qt6Widgets.dll @@ -28,15 +28,15 @@ example: Preparation =========== -Install the `PyInstaller` via **pip** with the following command:: +Install the ``PyInstaller`` via **pip** with the following command:: pip install pyinstaller -If you're using a virtual environment, remember to activate it before installing `PyInstaller`. +If you're using a virtual environment, remember to activate it before installing ``PyInstaller``. -After installation, the `pyinstaller` binary is located in your virtual environment's `bin/` -directory, or where your Python executable is located. If that directory isn't in your `PATH`, -include the whole path when you run `pyinstaller`. +After installation, the ``pyinstaller`` binary is located in your virtual environment's ``bin/`` +directory, or where your Python executable is located. If that directory isn't in your ``PATH``, +include the whole path when you run ``pyinstaller``. .. warning:: If you already have a PySide6 or Shiboken6 version installed in your system path, PyInstaller uses them instead of your virtual environment version. @@ -44,24 +44,24 @@ include the whole path when you run `pyinstaller`. Freeze an application ======================= -`PyInstaller` has many options that you can use. To list them all, run `pyinstaller -h`. +``PyInstaller`` has many options that you can use. To list them all, run ``pyinstaller -h``. There are two main features: * the option to package the whole project (including shared libraries) into one executable file - (`--onefile`) + (``--onefile``) * the option to place it in a directory containing the libraries -Additionally, on Windows when the command is running, you can open a console with the `-c` option -(or `--console` or `--nowindowed` equivalent). +Additionally, on Windows when the command is running, you can open a console with the ``-c`` option +(or ``--console`` or ``--nowindowed`` equivalent). -Otherwise, you can specify to not open such a console window on macOS and Windows with the `-w` -option (or `--windowed` or `--noconsole` equivalent). +Otherwise, you can specify to not open such a console window on macOS and Windows with the ``-w`` +option (or ``--windowed`` or ``--noconsole`` equivalent). Create an example ----------------- -Now, consider the following script, named `hello.py`:: +Now, consider the following script, named ``hello.py``:: import sys import random @@ -102,28 +102,29 @@ Now, consider the following script, named `hello.py`:: sys.exit(app.exec()) -Since it has a UI, you use the `--windowed` option. +Since it has a UI, you use the ``--windowed`` option. The command line to proceed looks like this:: pyinstaller --name="MyApplication" --windowed hello.py -This process creates two directories: `dist/` and `build/`. The application executable and the -required shared libraries are placed in `dist/MyApplication`. +This process creates two directories: ``dist/`` and ``build/``. The application executable and the +required shared libraries are placed in ``dist/MyApplication``. -To run the application, go to `dist/MyApplication` and run the program:: +To run the application, go to ``dist/MyApplication`` and run the program:: cd dist/MyApplication/ ./MyApplication -.. note:: The directory inside `dist/` and the executable have the same name. +.. note:: The directory inside ``dist/`` and the executable have the same name. -Use the `--onefile` option if you prefer to have everything bundled into one executable, without +Use the ``--onefile`` option if you prefer to have everything bundled into one executable, without the shared libraries next to it:: pyinstaller --name="MyApplication" --windowed --onefile hello.py -This process takes a bit longer, but in the end you have one executable in the `dist/` directory:: +This process takes a bit longer, but in the end you have one executable in the +``dist/`` directory:: cd dist/ ./MyApplication @@ -136,26 +137,26 @@ Some Caveats PyInstaller Issue ----------------- -As mentioned before, if available, `PyInstaller` picks a system installation of PySide6 or -Shiboken6 instead of your `virtualenv` version without notice. This is negligible if those +As mentioned before, if available, ``PyInstaller`` picks a system installation of |pymodname| or +Shiboken6 instead of your ``virtualenv`` version without notice. This is negligible if those two versions are the same. If you're working with different versions, this can result in frustrating debugging sessions -when you think you are testing the latest version, but `PyInstaller` is working with an older +when you think you are testing the latest version, but ``PyInstaller`` is working with an older version. Safety Instructions ------------------- -- When using `PyInstaller` with `virtualenv`, make sure that there is no system +- When using ``PyInstaller`` with ``virtualenv``, make sure that there is no system installation of PySide6 or shiboken6. -- Before compiling, use `pip -uninstall pyside6 shiboken6 -y` multiple times, until - none of the programs are found anymore. +- Before compiling, use ``pip -uninstall pyside6 pyside6_essentials pyside6_addons shiboken6 -y`` + multiple times, until none of the programs are found anymore. - Pip is usually a good tool. But to be 100 % sure, you should directly remove - the PySide6 and shiboken6 folders from site-packages. + the PySide6 and shiboken6 folders from ``site-packages``. - Be sure to use the right version of pip. The safest way to really run the right pip, is to use the Python that you mean: Instead of the pip command, better use:: diff --git a/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst b/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst index 1fde3104f..417a1f65f 100644 --- a/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst +++ b/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst @@ -3,48 +3,51 @@ pyside6-deploy: the deployment tool for Qt for Python ##################################################### -`pyside6-deploy` is an easy to use tool for deploying PySide6 applications to different platforms. -It is a wrapper around `Nuitka <https://nuitka.net/>`_, a Python compiler that compiles your Python -code to C code, and links with libpython to produce the final executable. +``pyside6-deploy`` is an easy to use tool for deploying PySide6 applications to different +platforms. It is a wrapper around `Nuitka <https://nuitka.net/>`_, a Python compiler that +compiles your Python code to C code, and links with libpython to produce the final executable. -The final executable produced has a `.exe` suffix on Windows. For Linux and macOS, they have a `.bin` -suffix. +The final executable produced has a ``.exe`` suffix on Windows. For Linux and macOS, they have a +``.bin`` suffix. How to use it? ============== -There are 2 different ways with which you can deploy your PySide6 application using `pyside6-deploy` +There are 2 different ways with which you can deploy your PySide6 application using +``pyside6-deploy``: Approach 1: Using the main python entry point file -------------------------------------------------- -In this approach, you point `pyside6-deploy` to the file containing the main Python entry point file -of the project i.e. the file containing `if __name__ == "__main__":`. The command looks like this:: +In this approach, you point ``pyside6-deploy`` to the file containing the main Python entry point +file of the project i.e. the file containing ``if __name__ == "__main__":``. +The command looks like this:: pyside6-deploy /path/to/main_file.py -On running the command, `pyside6-deploy` installs all the dependencies required for deployment +On running the command, ``pyside6-deploy`` installs all the dependencies required for deployment into the Python environment. -If your main Python entry point file is named `main.py`, then you don't have to point it to the -filename. You can run `pyside6-deploy` without any options, and it will work. +If your main Python entry point file is named ``main.py``, then you don't have to point it to the +filename. You can run ``pyside6-deploy`` without any options, and it will work. -.. note:: If your project contains a `pysidedeploy.spec` file, which is generated on the first run - of `pyside6-deploy` on the project directory, then for any subsequent runs of `pyside6-deploy` - you can run `pyside6-deploy` without specifying the main Python entry point file. It would take - the path to the main file from the `pysidedeploy.spec` file. To know more about what deployment - parameters are controlled by `pysidedeploy.spec` file, read `pysidedeploy`_. +.. note:: If your project contains a ``pysidedeploy.spec`` file, which is generated on the first + run of ``pyside6-deploy`` on the project directory, then for any subsequent runs of + ``pyside6-deploy`` you can run ``pyside6-deploy`` without specifying the main Python entry + point file. It would take the path to the main file from the ``pysidedeploy.spec`` file. + To know more about what deployment parameters are controlled by ``pysidedeploy.spec`` file, + read `pysidedeploy`_. .. _approach_two: Approach 2: Using pysidedeploy.spec config file ------------------------------------------------ -When you run `pyside6-deploy` for the first time, it creates a file called `pysidedeploy.spec` in -the project directory. This file controls various :ref:`parameters <pysidedeploy>` that influence -the deployment process. Any subsequent runs of `pyside6-deploy` on the project directory, would not -require additional parameters like the main Python entry point file. You can also point -`pyside6-deploy` to the path of the `pysidedeploy.spec` file (in case it is not in the same +When you run ``pyside6-deploy`` for the first time, it creates a file called ``pysidedeploy.spec`` +in the project directory. This file controls various :ref:`parameters <pysidedeploy>` that influence +the deployment process. Any subsequent runs of ``pyside6-deploy`` on the project directory, would +not require additional parameters like the main Python entry point file. You can also point +``pyside6-deploy`` to the path of the ``pysidedeploy.spec`` file (in case it is not in the same directory), to take the parameters from that file. This can be done with the following command:: pyside6-deploy -c /path/to/pysidedeploy.spec @@ -69,88 +72,80 @@ two folds: The various parameters controlled by this file are: -* `app` - - * `title`: The name of the application - - * `project_dir`: Project directory. The general assumption made is that the project directory - is the parent directory of the main Python entry point file - - * `input_file`: Path to the main Python entry point file - - * `project_file`: If it exists, this points to the path to the `Qt Creator Python Project File - .pyproject <https://doc.qt.io/qtforpython/tutorials/pretutorial/typesoffiles.html - #qt-creator-python-project-file-pyproject>`_ file. Such a file makes sure that the deployment - process never considers unnecessary files when bundling the executable. - -* `python` - - * `python_path`: Path to the Python executable. It is recommended to run the deployment process - inside a virtual environment as certain python packages will be installed onto the Python - environment. - - * `packages`: The Python packages installed into the Python environment for deployment to work. - By default, the Python packages `nuitka <https://pypi.org/project/Nuitka/>`__, - `ordered_set <https://pypi.org/project/ordered-set/>`_ and `zstandard - <https://pypi.org/project/zstandard/>`_ are installed. If the deployment platform is - Linux-based, then `patchelf <https://pypi.org/project/patchelf/>`_ is also installed - -* `qt` - - * `qml_files`: Comma-separated paths to all the QML files bundled with the executable - - * `excluded_qml_plugins`: The problem with using Nuitka for QML deployment is that all the QML - plugins are also bundled with the executable. When the plugins are bundled, the binaries of - the plugin's Qt module are also packaged. For example, size heavy module like QtWebEngine - also gets added to your executable, even when you do not use it in your code. The - `excluded_qml_plugins` parameter helps you to explicitly specify which all QML plugins are - excluded. `pyside6-deploy` automatically checks the QML files against the various QML plugins - and excludes the following Qt modules if they don't exist:: - - QtQuick, QtQuick3D, QtCharts, QtWebEngine, QtTest, QtSensors - - The reason why only the presence of the above 6 Qt modules is searched for is because they - have the most size heavy binaries among all the Qt modules. With this, you can drastically - reduce the size of your executables. - -* `nuitka` - - * `extra_args`: Any extra Nuitka arguments specified. It is specified as space-separated - command line arguments i.e. just like how you would specify it when you use Nuitka through - the command line. By default, it contains the following arguments:: - - --quiet --noinclude-qt-translations=True +**app** + * ``title``: The name of the application + * ``project_dir``: Project directory. The general assumption made is that the project directory + is the parent directory of the main Python entry point file + * ``input_file``: Path to the main Python entry point file + * ``project_file``: If it exists, this points to the path to the `Qt Creator Python Project File + .pyproject <https://doc.qt.io/qtforpython/tutorials/pretutorial/typesoffiles.html + #qt-creator-python-project-file-pyproject>`_ file. Such a file makes sure that the deployment + process never considers unnecessary files when bundling the executable. + +**python** + * ``python_path``: Path to the Python executable. It is recommended to run the deployment + process inside a virtual environment as certain python packages will be installed onto the + Python environment. + * ``packages``: The Python packages installed into the Python environment for deployment to + work. By default, the Python packages `nuitka <https://pypi.org/project/Nuitka/>`__, + `ordered_set <https://pypi.org/project/ordered-set/>`_ and `zstandard + <https://pypi.org/project/zstandard/>`_ are installed. If the deployment platform is + Linux-based, then `patchelf <https://pypi.org/project/patchelf/>`_ is also installed + +**qt** + * ``qml_files``: Comma-separated paths to all the QML files bundled with the executable + * ``excluded_qml_plugins``: The problem with using Nuitka for QML deployment is that all the QML + plugins are also bundled with the executable. When the plugins are bundled, the binaries of + the plugin's Qt module are also packaged. For example, size heavy module like QtWebEngine + also gets added to your executable, even when you do not use it in your code. The + ``excluded_qml_plugins`` parameter helps you to explicitly specify which all QML plugins are + excluded. ``pyside6-deploy`` automatically checks the QML files against the various QML + plugins and excludes the following Qt modules if they don't exist:: + + QtQuick, QtQuick3D, QtCharts, QtWebEngine, QtTest, QtSensors + + The reason why only the presence of the above 6 Qt modules is searched for is because they + have the most size heavy binaries among all the Qt modules. With this, you can drastically + reduce the size of your executables. + +**nuitka** + * ``extra_args``: Any extra Nuitka arguments specified. It is specified as space-separated + command line arguments i.e. just like how you would specify it when you use Nuitka through + the command line. By default, it contains the following arguments:: + + --quiet --noinclude-qt-translations=True Command Line Options ==================== The most important command line options are the path to the main Python entry point file and the -pysidedeploy.spec file. If neither of these files exists or their command line options are given, -then `pyside6-deploy` assumes that your current working directory does not contain a PySide6 project. +``pysidedeploy.spec`` file. If neither of these files exists or their command line options are +given, then ``pyside6-deploy`` assumes that your current working directory does not contain a +PySide6 project. -Here are all the command line options of `pyside6-deploy`: +Here are all the command line options of ``pyside6-deploy``: * **main entry point file**: This option does not have a name or a flag and is not restricted by it. - This enables `pyside6-deploy` to be used like:: + This enables ``pyside6-deploy`` to be used like:: pyside6-deploy /path/to/main_file.py -* **-c/--config-file**: This option is used to specify the path to `pysidedeploy.spec` explicitly +* **-c/--config-file**: This option is used to specify the path to ``pysidedeploy.spec`` explicitly -* **--init**: Used to only create the `pysidedeploy.spec` file +* **--init**: Used to only create the ``pysidedeploy.spec`` file Usage:: pyside6-deploy /path/to/main --init -* **-v/--verbose**: Runs `pyside6-deploy` in verbose mode +* **-v/--verbose**: Runs ``pyside6-deploy`` in verbose mode * **--dry-run**: Displays the final Nuitka command being run * **--keep-deployment-files**: When this option is added, it retains the build folders created by Nuitka during the deployment process. -* **-f/--force**: When this option is used, it forces through all the input prompts. `pyside6-deploy` - prompts the user to create a Python virtual environment, if not already in one. With this option, - the current Python environment is used irrespective of whether the current Python environment is a - virtual environment or not. +* **-f/--force**: When this option is used, it forces through all the input prompts. + ``pyside6-deploy`` prompts the user to create a Python virtual environment, if not already in one. + With this option, the current Python environment is used irrespective of whether the current + Python environment is a virtual environment or not. diff --git a/sources/pyside6/doc/deployment/index.rst b/sources/pyside6/doc/deployment/index.rst index 9785b82d1..6f4c2d44a 100644 --- a/sources/pyside6/doc/deployment/index.rst +++ b/sources/pyside6/doc/deployment/index.rst @@ -20,12 +20,12 @@ that deploys your PySide6 application to all desktop platforms - Windows, Linux, more about how to use the tool see :ref:`pyside6-deploy`. Additionally, you can also use other popular deployment tools shown below: - * `fbs`_ - * `PyInstaller`_ - * `cx_Freeze`_ - * `py2exe`_ - * `py2app`_ - * `briefcase`_ +* `fbs`_ +* `PyInstaller`_ +* `cx_Freeze`_ +* `py2exe`_ +* `py2app`_ +* `briefcase`_ .. _fbs: https://build-system.fman.io/ .. _PyInstaller: https://www.pyinstaller.org/ diff --git a/sources/pyside6/doc/developer/add_port_example.rst b/sources/pyside6/doc/developer/add_port_example.rst index 1188b8c4c..6ddd1f0f2 100644 --- a/sources/pyside6/doc/developer/add_port_example.rst +++ b/sources/pyside6/doc/developer/add_port_example.rst @@ -33,7 +33,7 @@ Port a Qt example - Add a ``.pyproject`` file (verify later on that docs build). - Add a ``doc`` directory and descriptive ``.rst`` file, and a screenshot if suitable (use ``optipng`` to reduce file size). -- Add the """Port of the ... example from Qt 6""" doc string. +- Add the ``"""Port of the ... example from Qt 6"""`` doc string. - Try to port variable and function names to snake case convention. - Verify that a flake check is mostly silent. - Remove C++ documentation from ``sources/pyside6/doc/additionaldocs.lst``. diff --git a/sources/pyside6/doc/developer/add_tool.rst b/sources/pyside6/doc/developer/add_tool.rst index 31a6e773f..bceccbdce 100644 --- a/sources/pyside6/doc/developer/add_tool.rst +++ b/sources/pyside6/doc/developer/add_tool.rst @@ -26,16 +26,16 @@ Add a Qt tool wrapper - Install the files (``sources/pyside-tools/CMakeLists.txt``). - Include the tool in the deprecated 'setup.py bdist_wheel' process: - - Add the tool in ``build_scripts/__init__.py``. + - Add the tool in ``build_scripts/__init__.py``. - - Copy the files to the wheels in ``build_scripts/platforms/*.py``. + - Copy the files to the wheels in ``build_scripts/platforms/*.py``. - - Add an entry to ``sources/pyside6/doc/gettingstarted/package_details.rst``. + - Add an entry to ``sources/pyside6/doc/gettingstarted/package_details.rst``. - Include the tool in the new wheel creation process: - - Add an entry to ``create_wheels.py``. + - Add an entry to ``create_wheels.py``. - - Include the Qt binaries explicitly on ``build_scripts/wheel_files.py`` + - Include the Qt binaries explicitly on ``build_scripts/wheel_files.py`` - Build with ``--standalone``, verify it is working. diff --git a/sources/pyside6/doc/developer/feature-motivation.rst b/sources/pyside6/doc/developer/feature-motivation.rst index 9249e034e..43bbb86b6 100644 --- a/sources/pyside6/doc/developer/feature-motivation.rst +++ b/sources/pyside6/doc/developer/feature-motivation.rst @@ -84,12 +84,11 @@ all methods of all classes used in this module are changing their name. The algorithm to change names is this: - * if the name has less than 3 chars, or - * if two upper chars are adjacent, or - * if the name starts with ``gl`` (which marks OpenGL), - * the name is returned unchanged. Otherwise - - * a single upper char ``C`` is replaced by ``_c`` +* if the name has less than 3 chars, or +* if two upper chars are adjacent, or +* if the name starts with ``gl`` (which marks OpenGL), +* the name is returned unchanged. Otherwise +* a single upper char ``C`` is replaced by ``_c`` The true_property feature diff --git a/sources/pyside6/doc/developer/signature_doc.rst b/sources/pyside6/doc/developer/signature_doc.rst index 3bd28ad68..c81e9a559 100644 --- a/sources/pyside6/doc/developer/signature_doc.rst +++ b/sources/pyside6/doc/developer/signature_doc.rst @@ -136,71 +136,52 @@ Really important are the **parser**, **mapping**, **errorhandler**, **enum_sig** or be compatible with embedding and installers. -loader.py -+++++++++ +**loader.py** + This module assembles and imports the ``inspect`` module, and then exports the + ``create_signature`` function. This function takes a fake function and some + attributes and builds a ``__signature__`` object with the inspect module. -This module assembles and imports the ``inspect`` module, and then exports the -``create_signature`` function. This function takes a fake function and some -attributes and builds a ``__signature__`` object with the inspect module. +**parser.py** + This module takes a class signatures string from C++ and parses it into the + needed properties for the ``create_signature`` function. Its entry point is the + ``pyside_type_init`` function, which is called from the C module via ``loader.py``. -parser.py -+++++++++ -This module takes a class signatures string from C++ and parses it into the -needed properties for the ``create_signature`` function. Its entry point is the -``pyside_type_init`` function, which is called from the C module via ``loader.py``. +**mapping.py** + The purpose of the mapping module is maintaining a list of replacement strings + that map from the *signature text* in C to the property strings that Python + needs. A lot of mappings are resolved by rather complex expressions in ``parser.py``, + but a few hundred cases are better to spell explicitly, here. +**errorhandler.py** + Since ``Qt For Python 5.12``, we no longer use the builtin type error messages from C++. + Instead, we get much better results with the signature module. At the same time, + this enforced supporting shiboken as well, and the signature module was no longer + optional. -mapping.py -++++++++++ +**enum_sig.py** + The diverse applications of the signature module all needed to iterate over modules, + classes and functions. In order to centralize this enumeration, the process has + been factored out as a context manager. The user has only to supply functions + that do the actual formatting. -The purpose of the mapping module is maintaining a list of replacement strings -that map from the *signature text* in C to the property strings that Python -needs. A lot of mappings are resolved by rather complex expressions in ``parser.py``, -but a few hundred cases are better to spell explicitly, here. + See for example the .pyi generator ``pyside6/PySide6/support/generate_pyi.py``. +**layout.py** + As more applications used the signature module, different formatting of signatures + was needed. To support that, we created the function ``create_signature``, which + has a parameter to choose from some predefined layouts. -errorhandler.py -+++++++++++++++ -Since ``Qt For Python 5.12``, we no longer use the builtin type error messages from C++. -Instead, we get much better results with the signature module. At the same time, -this enforced supporting shiboken as well, and the signature module was no longer -optional. +**typing27.py** + Python 2 has no typing module at all. This is a backport of the minimum that is needed. -enum_sig.py -+++++++++++ - -The diverse applications of the signature module all needed to iterate over modules, -classes and functions. In order to centralize this enumeration, the process has -been factored out as a context manager. The user has only to supply functions -that do the actual formatting. - -See for example the .pyi generator ``pyside6/PySide6/support/generate_pyi.py``. - - -layout.py -+++++++++ - -As more applications used the signature module, different formatting of signatures -was needed. To support that, we created the function ``create_signature``, which -has a parameter to choose from some predefined layouts. - - -*typing27.py* -+++++++++++++ - -Python 2 has no typing module at all. This is a backport of the minimum that is needed. - - -*backport_inspect.py* -+++++++++++++++++++++ - -Python 2 has an inspect module, but lacks the signature functions, completely. -This module adds the missing functionality, which is merged at runtime into -the inspect module. +**backport_inspect.py** + Python 2 has an inspect module, but lacks the signature functions, completely. + This module adds the missing functionality, which is merged at runtime into + the inspect module. Multiple Arities @@ -372,11 +353,9 @@ This was implemented in ``Qt For Python 5.12.1``. Literature ---------- - `PEP 362 – Function Signature Object <https://www.python.org/dev/peps/pep-0362/>`__ - - `PEP 484 – Type Hints <https://www.python.org/dev/peps/pep-0484/>`__ - - `PEP 3107 – Function Annotations <https://www.python.org/dev/peps/pep-3107/>`__ +* `PEP 362 – Function Signature Object <https://www.python.org/dev/peps/pep-0362/>`__ +* `PEP 484 – Type Hints <https://www.python.org/dev/peps/pep-0484/>`__ +* `PEP 3107 – Function Annotations <https://www.python.org/dev/peps/pep-3107/>`__ *Personal Remark: This module is dedicated to our lovebird "Püppi", who died on 2017-09-15.* diff --git a/sources/pyside6/doc/faq.rst b/sources/pyside6/doc/faq.rst index c1a27b3c2..4171df947 100644 --- a/sources/pyside6/doc/faq.rst +++ b/sources/pyside6/doc/faq.rst @@ -23,14 +23,14 @@ Frequently Asked Questions Before the official release, everything was in one big wheel, so it made sense to split these into separate wheels, each for the major projects currently in development: - * **pyside6**: contains all the PySide6 modules to use the Qt framework; also depends on the - shiboken6 module. - * **shiboken6**: contains the shiboken6 module with helper functions for PySide6. - * **shiboken6_generator**: contains the generator binary that can work with a C++ project and a - typesystem to generate Python bindings. - If you want to generate bindings for a Qt/C++ project, there won't be any linking to the Qt - shared libraries; you need to do this by hand. We recommend building PySide6 from scratch - to have everything properly linked. + * **pyside6**: contains all the PySide6 modules to use the Qt framework; also depends on the + shiboken6 module. + * **shiboken6**: contains the shiboken6 module with helper functions for PySide6. + * **shiboken6_generator**: contains the generator binary that can work with a C++ project and a + typesystem to generate Python bindings. + If you want to generate bindings for a Qt/C++ project, there won't be any linking to the Qt + shared libraries; you need to do this by hand. We recommend building PySide6 from scratch + to have everything properly linked. **Why is the shiboken6_generator not installed automatically?** It's not necessary to install the shiboken6_generator to use PySide6. The package is a result of diff --git a/sources/pyside6/doc/gettingstarted/index.rst b/sources/pyside6/doc/gettingstarted/index.rst index 9de7587c4..f24f9dd4f 100644 --- a/sources/pyside6/doc/gettingstarted/index.rst +++ b/sources/pyside6/doc/gettingstarted/index.rst @@ -17,12 +17,12 @@ On **Linux** you might get them with your operating system package manager, on * you might get them with ``brew``, and on **Windows** you can download the installer from each website. - * **Python**: 3.7+ `[official Python website] <https://www.python.org/downloads/>`_ - * **Qt:** 6.4+ `[online installer] <https://download.qt.io/official_releases/online_installers/>`_ - * **CMake:** 3.18+ `[official CMake website] <https://cmake.org/download/>`_ - * **Git:** 2.0+. `[official Git website] <https://git-scm.com/downloads>`_ - * **libclang:** The libclang library, recommended: version 10 for 6.0+. - Prebuilt versions for each OS can be `downloaded here`_. +* **Python**: 3.7+ `[official Python website] <https://www.python.org/downloads/>`_ +* **Qt:** 6.4+ `[online installer] <https://download.qt.io/official_releases/online_installers/>`_ +* **CMake:** 3.18+ `[official CMake website] <https://cmake.org/download/>`_ +* **Git:** 2.0+. `[official Git website] <https://git-scm.com/downloads>`_ +* **libclang:** The libclang library, recommended: version 10 for 6.0+. + Prebuilt versions for each OS can be `downloaded here`_. .. _downloaded here: https://download.qt.io/development_releases/prebuilt/libclang/ diff --git a/sources/pyside6/doc/gettingstarted/linux.rst b/sources/pyside6/doc/gettingstarted/linux.rst index f5ef71bae..f3ea5f7b0 100644 --- a/sources/pyside6/doc/gettingstarted/linux.rst +++ b/sources/pyside6/doc/gettingstarted/linux.rst @@ -4,11 +4,11 @@ Getting Started on Linux Requirements ------------ - * GCC - * ``sphinx`` package for the documentation (optional). - * Depending on your linux distribution, the following dependencies might also be required: +* GCC +* ``sphinx`` package for the documentation (optional). +* Depending on your linux distribution, the following dependencies might also be required: - * ``libgl-dev``, ``python-dev``, ``python-distutils``, and ``python-setuptools``. + * ``libgl-dev``, ``python-dev``, ``python-distutils``, and ``python-setuptools``. Building from source -------------------- @@ -59,7 +59,7 @@ Install the general dependencies:: Building and Installing (setuptools) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `setuptools` approach uses the `setup.py` file to execute the build, +The ``setuptools`` approach uses the ``setup.py`` file to execute the build, install, and packaging steps. Check your Qt installation path, to specifically use that version of qtpaths to build PySide. @@ -76,7 +76,7 @@ To install on the current directory, just run:: Building and Installing (cmake) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `setuptools` approach includes internal `CMake` calls when +The ``setuptools`` approach includes internal ``CMake`` calls when building and installing the project, but a CMake-only approach is only recommended for packaging the project for distribution builds. diff --git a/sources/pyside6/doc/gettingstarted/macOS.rst b/sources/pyside6/doc/gettingstarted/macOS.rst index 9d57c7ceb..ea173b9ed 100644 --- a/sources/pyside6/doc/gettingstarted/macOS.rst +++ b/sources/pyside6/doc/gettingstarted/macOS.rst @@ -4,11 +4,11 @@ Getting Started on macOS Requirements ------------ - * `XCode`_ 8.2 (macOS 10.11), 8.3.3 (macOS 10.12), 9 (macOS 10.13), 10.1 (macOS 10.14) - * ``sphinx`` package for the documentation (optional). - * Depending on your OS, the following dependencies might also be required: +* `XCode`_ 8.2 (macOS 10.11), 8.3.3 (macOS 10.12), 9 (macOS 10.13), 10.1 (macOS 10.14) +* ``sphinx`` package for the documentation (optional). +* Depending on your OS, the following dependencies might also be required: - * ``libgl-dev``, ``python-dev``, ``python-distutils``, and ``python-setuptools``. + * ``libgl-dev``, ``python-dev``, ``python-distutils``, and ``python-setuptools``. .. _XCode: https://developer.apple.com/xcode/ diff --git a/sources/pyside6/doc/gettingstarted/porting_from2.rst b/sources/pyside6/doc/gettingstarted/porting_from2.rst index 2d5c8414f..07f5b48c6 100644 --- a/sources/pyside6/doc/gettingstarted/porting_from2.rst +++ b/sources/pyside6/doc/gettingstarted/porting_from2.rst @@ -66,28 +66,28 @@ Class/Function Deprecations Then, the code base needs to be checked for usage of deprecated API and adapted accordingly. For example: - * The High DPI scaling attributes ``Qt.AA_EnableHighDpiScaling``, - ``Qt.AA_DisableHighDpiScaling`` and ``Qt.AA_UseHighDpiPixmaps`` are - deprecated. High DPI is by default enabled in Qt 6 and cannot be turned off. - * ``QDesktopWidget`` has been removed. ``QScreen`` should be used instead, - which can be retrieved using ``QWidget.screen()``, - ``QGuiApplication.primaryScreen()`` or ``QGuiApplication.screens()``. - * ``QFontMetrics.width()`` has been renamed to ``horizontalAdvance()``. - * ``QMouseEvent.pos()`` and ``QMouseEvent.globalPos()`` returning a ``QPoint`` - as well as ``QMouseEvent.x()`` and ``QMouseEvent.y()`` returning ``int`` - are now deprecated. ``QMouseEvent.position()`` and - ``QMouseEvent.globalPosition()`` returning a ``QPointF`` should be used - instead. - * ``Qt.MidButton`` has been renamed to ``Qt.MiddleButton``. - * ``QOpenGLVersionFunctionsFactory.get()`` instead of - ``QOpenGLContext.versionFunctions()`` should be used to obtain - *Open GL* functions. - * ``QRegExp`` has been replaced by ``QRegularExpression``. - * ``QWidget.mapToGlobal()`` and ``QWidget.mapFromGlobal()`` now also accept - and return ``QPointF``. - * Functions named ``exec_`` (classes ``QCoreApplication``, ``QDialog``, - ``QEventLoop``) have been renamed to ``exec`` which became possible - in Python 3. +* The High DPI scaling attributes ``Qt.AA_EnableHighDpiScaling``, + ``Qt.AA_DisableHighDpiScaling`` and ``Qt.AA_UseHighDpiPixmaps`` are + deprecated. High DPI is by default enabled in Qt 6 and cannot be turned off. +* ``QDesktopWidget`` has been removed. ``QScreen`` should be used instead, + which can be retrieved using ``QWidget.screen()``, + ``QGuiApplication.primaryScreen()`` or ``QGuiApplication.screens()``. +* ``QFontMetrics.width()`` has been renamed to ``horizontalAdvance()``. +* ``QMouseEvent.pos()`` and ``QMouseEvent.globalPos()`` returning a ``QPoint`` + as well as ``QMouseEvent.x()`` and ``QMouseEvent.y()`` returning ``int`` + are now deprecated. ``QMouseEvent.position()`` and + ``QMouseEvent.globalPosition()`` returning a ``QPointF`` should be used + instead. +* ``Qt.MidButton`` has been renamed to ``Qt.MiddleButton``. +* ``QOpenGLVersionFunctionsFactory.get()`` instead of + ``QOpenGLContext.versionFunctions()`` should be used to obtain + *Open GL* functions. +* ``QRegExp`` has been replaced by ``QRegularExpression``. +* ``QWidget.mapToGlobal()`` and ``QWidget.mapFromGlobal()`` now also accept + and return ``QPointF``. +* Functions named ``exec_`` (classes ``QCoreApplication``, ``QDialog``, + ``QEventLoop``) have been renamed to ``exec`` which became possible + in Python 3. More information can be found in the `Porting to Qt 6 <https://doc.qt.io/qt-6/portingguide.html>`_ Guide diff --git a/sources/pyside6/doc/gettingstarted/windows.rst b/sources/pyside6/doc/gettingstarted/windows.rst index dd266c8f4..f94421d24 100644 --- a/sources/pyside6/doc/gettingstarted/windows.rst +++ b/sources/pyside6/doc/gettingstarted/windows.rst @@ -7,9 +7,9 @@ selected when using the online installer. Requirements ------------ - * `MSVC2022`_ or (MSVC2019) for Python 3 on Windows, - * `OpenSSL`_ (optional for SSL support, Qt must have been configured using the same SSL library). - * ``sphinx`` package for the documentation (optional). +* `MSVC2022`_ or (MSVC2019) for Python 3 on Windows, +* `OpenSSL`_ (optional for SSL support, Qt must have been configured using the same SSL library). +* ``sphinx`` package for the documentation (optional). .. note:: Python 3.8.0 was missing some API required for PySide/Shiboken so it's not possible to use it for a Windows build. @@ -83,7 +83,7 @@ Creating Debug Builds * Choose *Custom Installation* when installing Python and tick the options for debug binaries and libraries -* Use ``venv`` to create a virtual environment and pass the debug binary: +* Use ``venv`` to create a virtual environment and pass the debug binary:: python_d.exe -m venv testenv_d diff --git a/sources/pyside6/doc/quickstart.rst b/sources/pyside6/doc/quickstart.rst index 83268589c..64a185be2 100644 --- a/sources/pyside6/doc/quickstart.rst +++ b/sources/pyside6/doc/quickstart.rst @@ -10,10 +10,10 @@ 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 recommend using a virtual environment, such as + `venv <https://docs.python.org/3/library/venv.html>`_ or + `virtualenv <https://virtualenv.pypa.io/en/latest>`_ Installation ------------ diff --git a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst index bc06d6d9b..e2512f9db 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst @@ -3,8 +3,8 @@ 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 -in a `QLineEdit`, and the dialog greets them on click of a -`QPushButton`. +in a ``QLineEdit``, and the dialog greets them on click of a +``QPushButton``. Let us just start with a simple stub that creates and shows a dialog. This stub is updated during the course of this @@ -31,24 +31,24 @@ tutorial, but you can use this stub as is if you need to: sys.exit(app.exec()) The imports aren't new to you, the same for the creation of the -`QApplication` and the execution of the Qt main loop. +``QApplication`` and the execution of the Qt main loop. The only novelty here is the **class definition**. You can create any class that subclasses PySide6 widgets. -In this case, we are subclassing `QDialog` to define a custom +In this case, we are subclassing ``QDialog`` to define a custom dialog, which we name as **Form**. We have also implemented the -`init()` method that calls the `QDialog`'s init method with the -parent widget, if any. Also, the new `setWindowTitle()` method -just sets the title of the dialog window. In `main()`, you can see +``init()`` method that calls the ``QDialog``'s init method with the +parent widget, if any. Also, the new ``setWindowTitle()`` method +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 -the `QLineEdit`. -So, let's add the following code to the `init()` method of our Form: +We are going to create two widgets: a ``QLineEdit`` where users can +enter their name, and a ``QPushButton`` that prints the contents of +the ``QLineEdit``. +So, let's add the following code to the ``init()`` method of our Form: :: # Create widgets @@ -62,8 +62,8 @@ 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 -the widgets vertically. Add the following code to the `init()` method, +in your application. In this case, let's use ``QVBoxLayout`` to lay out +the widgets vertically. Add the following code to the ``init()`` method, after creating the widgets: :: @@ -72,33 +72,33 @@ after creating the widgets: layout.addWidget(self.edit) layout.addWidget(self.button) -So, we create the layout, add the widgets with `addWidget()`. +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 -the Form, so you have to add it after the `init()` function: +the Form, so you have to add it after the ``init()`` function: :: # Greets the user def greetings(self): print(f"Hello {self.edit.text()}") -Our function just prints the contents of the `QLineEdit` to the +Our function just prints the contents of the ``QLineEdit`` to the python console. We have access to the text by means of the -`QLineEdit.text()` method. +``QLineEdit.text()`` method. Now that we have everything, we just need to *connect* the -`QPushButton` to the `Form.greetings()` method. To do so, add the -following line to the `init()` method: +``QPushButton`` to the ``Form.greetings()`` method. To do so, add the +following line to the ``init()`` method: :: # Add button signal to greetings slot self.button.clicked.connect(self.greetings) -Once executed, you can enter your name in the `QLineEdit` and watch +Once executed, you can enter your name in the ``QLineEdit`` and watch the console for greetings. Complete code diff --git a/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst b/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst index 5b397bd0b..907afc726 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/qrcfiles.rst @@ -1,7 +1,7 @@ .. _using_qrc_files: -Using `.qrc` Files (`pyside6-rcc`) -********************************** +Using ``.qrc`` Files (``pyside6-rcc``) +************************************** The `Qt Resource System`_ is a mechanism for storing binary files in an application. @@ -17,7 +17,7 @@ In this tutorial you will learn how to load custom images as button icons. For inspiration, we will try to adapt the multimedia player example from Qt. -As you can see on the following image, the `QPushButton` that are used +As you can see on the following image, the ``QPushButton`` that are used for the media actions (play, pause, stop, and so on) are using the default icons meant for such actions. @@ -31,19 +31,19 @@ and use them. .. image:: icons.png :alt: New Multimedia icons -You can find more information about the `rcc` command, and `.qrc` file +You can find more information about the ``rcc`` command, and ``.qrc`` file format, and the resource system in general in the `Qt Resource System`_ site. .. _`download the following set`: icons/ -The `.qrc` file -================ +The ``.qrc`` file +================= -Before running any command, add information about the resources to a `.qrc` +Before running any command, add information about the resources to a ``.qrc`` file. -In the following example, notice how the resources are listed in `icons.qrc` +In the following example, notice how the resources are listed in ``icons.qrc`` :: @@ -62,15 +62,15 @@ In the following example, notice how the resources are listed in `icons.qrc` Generating a Python file ========================= -Now that the `icons.qrc` file is ready, use the `pyside6-rcc` tool to generate +Now that the ``icons.qrc`` file is ready, use the ``pyside6-rcc`` tool to generate a Python class containing the binary information about the resources To do this, we need to run:: pyside6-rcc icons.qrc -o rc_icons.py -The `-o` option lets you specify the output filename, -which is `rc_icons.py` in this case. +The ``-o`` option lets you specify the output filename, +which is ``rc_icons.py`` in this case. To use the generated file, add the following import at the top of your main Python file:: @@ -167,7 +167,7 @@ Now, the constructor of your class should look like this: Executing the example ===================== -Run the application by calling `python main.py` to checkout the new icon-set: +Run the application by calling ``python main.py`` to checkout the new icon-set: .. image:: player-new.png :alt: New Multimedia Player Qt Example diff --git a/sources/pyside6/doc/tutorials/basictutorial/signals_and_slots.rst b/sources/pyside6/doc/tutorials/basictutorial/signals_and_slots.rst index 695f431e1..57e55f5aa 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/signals_and_slots.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/signals_and_slots.rst @@ -43,21 +43,21 @@ a signal directly to another signal. (This will emit the second signal immediately whenever the first is emitted.) Qt's widgets have many predefined signals and slots. For example, -`QAbstractButton` (base class of buttons in Qt) has a `clicked()` -signal and `QLineEdit` (single line input field) has a slot named -'clear()`. So, a text input field with a button to clear the text -could be implemented by placing a `QToolButton` to the right of the -`QLineEdit` and connecting its `clicked()` signal to the slot -'clear()`. This is done using the `connect()` method of the signal: +``QAbstractButton`` (base class of buttons in Qt) has a ``clicked()`` +signal and ``QLineEdit`` (single line input field) has a slot named +``clear()``. So, a text input field with a button to clear the text +could be implemented by placing a ``QToolButton`` to the right of the +``QLineEdit`` and connecting its ``clicked()`` signal to the slot +``clear()``. This is done using the ``connect()`` method of the signal: - .. code-block:: python +.. code-block:: python - button = QToolButton() - line_edit = QLineEdit() - button.clicked.connect(line_edit.clear) + button = QToolButton() + line_edit = QLineEdit() + button.clicked.connect(line_edit.clear) -`connect()` returns a `QMetaObject.Connection` object, which can be -used with the `disconnect()` method to sever the connection. +``connect()`` returns a ``QMetaObject.Connection`` object, which can be +used with the ``disconnect()`` method to sever the connection. Signals can also be connected to free functions: @@ -86,7 +86,7 @@ The Signal Class When writing classes in Python, signals are declared as class level variables of the class ``QtCore.Signal()``. A QWidget-based button -that emits a `clicked()` signal could look as +that emits a ``clicked()`` signal could look as follows: .. code-block:: python @@ -215,7 +215,7 @@ Specifying Signals and Slots by Method Signature Strings Signals and slots can also be specified as C++ method signature -strings passed through the `SIGNAL()` and/or `SLOT()` functions: +strings passed through the ``SIGNAL()`` and/or ``SLOT()`` functions: .. code-block:: python @@ -225,7 +225,7 @@ strings passed through the `SIGNAL()` and/or `SLOT()` functions: action_handler, SLOT("action1(Qt::MouseButton)")) This is not recommended for connecting signals, it is mostly -used to specify signals for methods like `QWizardPage::registerField()`: +used to specify signals for methods like ``QWizardPage::registerField()``: .. code-block:: python diff --git a/sources/pyside6/doc/tutorials/basictutorial/translations.rst b/sources/pyside6/doc/tutorials/basictutorial/translations.rst index 31cd004a3..98a5d94dc 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/translations.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/translations.rst @@ -28,18 +28,18 @@ The linguist example has a number of messages enclosed in ``self.tr()``. The status bar message shown in response to a selection change uses a plural form depending on a count: - .. code-block:: python +.. code-block:: python - count = len(self._list_widget.selectionModel().selectedRows()) - message = self.tr("%n language(s) selected", "", count) + count = len(self._list_widget.selectionModel().selectedRows()) + message = self.tr("%n language(s) selected", "", count) The translation workflow for the example is as follows: The translated messages are extracted using the ``lupdate`` tool, producing XML-based ``.ts`` files: - .. code-block:: bash +.. code-block:: bash - pyside6-lupdate main.py -ts example_de.ts + pyside6-lupdate main.py -ts example_de.ts If ``example_de.ts`` already exists, it will be updated with the new messages added to the code in-between. @@ -52,15 +52,15 @@ they should be passed to the ``pyside6-lupdate`` tool as well: pyside6-lupdate main.py main.qml form.ui -ts example_de.ts The source files generated by ``pyside6-uic`` from the form files -should `not` be passed. +should **not** be passed. ``.ts`` files are translated using *Qt Linguist*. Once this is complete, the files are converted to a binary form (``.qm`` files): - .. code-block:: bash +.. code-block:: bash - mkdir translations - pyside6-lrelease example_de.ts -qm translations/example_de.qm + mkdir translations + pyside6-lrelease example_de.ts -qm translations/example_de.qm To avoid having to ship the ``.qm`` files, it is recommend to put them into a Qt resource file along with icons and other @@ -68,35 +68,35 @@ applications resources (see :ref:`using_qrc_files`). The resource file ``linguist.qrc`` provides the ``example_de.qm`` under ``:/translations``: - .. code-block:: xml +.. code-block:: xml - <!DOCTYPE RCC><RCC version="1.0"> - <qresource> - <file>translations/example_de.qm</file> - </qresource> - </RCC> + <!DOCTYPE RCC><RCC version="1.0"> + <qresource> + <file>translations/example_de.qm</file> + </qresource> + </RCC> At runtime, the translations need to be loaded using the ``QTranslator`` class: - .. code-block:: python +.. code-block:: python - path = QLibraryInfo.location(QLibraryInfo.TranslationsPath) - translator = QTranslator(app) - if translator.load(QLocale.system(), 'qtbase', '_', path): - app.installTranslator(translator) - translator = QTranslator(app) - path = ':/translations' - if translator.load(QLocale.system(), 'example', '_', path): - app.installTranslator(translator) + path = QLibraryInfo.location(QLibraryInfo.TranslationsPath) + translator = QTranslator(app) + if translator.load(QLocale.system(), 'qtbase', '_', path): + app.installTranslator(translator) + translator = QTranslator(app) + path = ':/translations' + if translator.load(QLocale.system(), 'example', '_', path): + app.installTranslator(translator) The code first loads the translations shipped for Qt and then the translations of the applications loaded from resources. The example can then be run in German: - .. code-block:: bash +.. code-block:: bash - LANG=de python main.py + LANG=de python main.py GNU gettext ----------- @@ -116,29 +116,29 @@ aliased to ``ngettext``. Those functions are defined at the top: - .. code-block:: python +.. code-block:: python - import gettext - ... - _ = None - ngettext = None + import gettext + ... + _ = None + ngettext = None and later assigned as follows: - .. code-block:: python - - src_dir = Path(__file__).resolve().parent - try: - translation = gettext.translation('example', localedir=src_dir / 'locales') - if translation: - translation.install() - _ = translation.gettext - ngettext = translation.ngettext - except FileNotFoundError: - pass - if not _: - _ = gettext.gettext - ngettext = gettext.ngettext +.. code-block:: python + + src_dir = Path(__file__).resolve().parent + try: + translation = gettext.translation('example', localedir=src_dir / 'locales') + if translation: + translation.install() + _ = translation.gettext + ngettext = translation.ngettext + except FileNotFoundError: + pass + if not _: + _ = gettext.gettext + ngettext = gettext.ngettext This specifies that our translation file has the base name ``example`` and will be found in the source tree under ``locales``. The code will try @@ -146,18 +146,18 @@ to load a translation matching the current language. Messages to be translated look like: - .. code-block:: python +.. code-block:: python - file_menu = self.menuBar().addMenu(_("&File")) + file_menu = self.menuBar().addMenu(_("&File")) The status bar message shown in response to a selection change uses a plural form depending on a count: - .. code-block:: python +.. code-block:: python - count = len(self._list_widget.selectionModel().selectedRows()) - message = ngettext("{0} language selected", - "{0} languages selected", count).format(count) + count = len(self._list_widget.selectionModel().selectedRows()) + message = ngettext("{0} language selected", + "{0} languages selected", count).format(count) The ``ngettext()`` function takes the singular form, plural form and the count. The returned string still contains the formatting placeholder, so it needs @@ -174,41 +174,41 @@ is first created: This file has a few generic placeholders which can be replaced by the appropriate values. It is then copied to the ``de_DE/LC_MESSAGES`` directory. - .. code-block:: bash +.. code-block:: bash - cd locales/de_DE/LC_MESSAGES/ - cp ../../example.pot . + cd locales/de_DE/LC_MESSAGES/ + cp ../../example.pot . Further adaptions need to be made to account for the German plural form and encoding: - .. code-block:: +.. code-block:: - "Project-Id-Version: PySide6 gettext example\n" - "POT-Creation-Date: 2021-07-05 14:16+0200\n" - "Language: de_DE\n" - "MIME-Version: 1.0\n" - "Content-Type: text/plain; charset=UTF-8\n" - "Content-Transfer-Encoding: 8bit\n" - "Plural-Forms: nplurals=2; plural=n != 1;\n" + "Project-Id-Version: PySide6 gettext example\n" + "POT-Creation-Date: 2021-07-05 14:16+0200\n" + "Language: de_DE\n" + "MIME-Version: 1.0\n" + "Content-Type: text/plain; charset=UTF-8\n" + "Content-Transfer-Encoding: 8bit\n" + "Plural-Forms: nplurals=2; plural=n != 1;\n" Below, the translated messages can be given: - .. code-block:: +.. code-block:: - #: main.py:57 - msgid "&File" - msgstr "&Datei" + #: main.py:57 + msgid "&File" + msgstr "&Datei" Finally, the ``.pot`` is converted to its binary form (machine object file, ``.mo``), which needs to be deployed: - .. code-block:: bash +.. code-block:: bash - msgfmt -o example.mo example.pot + msgfmt -o example.mo example.pot The example can then be run in German: - .. code-block:: bash +.. code-block:: bash - LANG=de python main.py + LANG=de python main.py diff --git a/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst b/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst index cd1057c97..4f2fa1ba5 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst @@ -1,7 +1,7 @@ .. _using_ui_files: -Using `.ui` files from Designer or QtCreator with `QUiLoader` and `pyside6-uic` -******************************************************************************* +Using ``.ui`` files from Designer or QtCreator with ``QUiLoader`` and ``pyside6-uic`` +************************************************************************************* This page describes the use of `Qt Designer <https://doc.qt.io/qt-6/qtdesigner-manual.html>`_ to create @@ -15,13 +15,13 @@ is described at .. image:: uifiles.png :alt: Designer and the equivalent code -The designs are stored in `.ui` files, which is an XML-based format. It will +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. To create a new Qt Design Form in **Qt Creator**, choose -`File/New File Or Project` and "Main Window" for template. Save it as -`mainwindow.ui`. Add a `QPushButton` to the center of the centralwidget. +``File/New File Or Project`` and "Main Window" for template. Save it as +``mainwindow.ui``. Add a ``QPushButton`` to the center of the centralwidget. Your file ``mainwindow.ui`` should look something like this: @@ -88,12 +88,12 @@ Option A: Generating a Python class =================================== The standard way to interact with a **UI file** is to generate a Python -class from it. This is possible thanks to the `pyside6-uic` tool. +class from it. This is possible thanks to the ``pyside6-uic`` tool. To use this tool, you need to run the following command on a console:: - pyside6-uic mainwindow.ui > ui_mainwindow.py + pyside6-uic mainwindow.ui -o ui_mainwindow.py -We redirect all the output of the command to a file called `ui_mainwindow.py`, +We redirect all the output of the command to a file called ``ui_mainwindow.py``, which will be imported directly:: from ui_mainwindow import Ui_MainWindow @@ -136,7 +136,7 @@ file: .. note:: - You must run `pyside6-uic` again every time you make changes + You must run ``pyside6-uic`` again every time you make changes to the **UI file**. Option B: Loading it directly @@ -149,7 +149,7 @@ module: from PySide6.QtUiTools import QUiLoader -The `QUiLoader` lets us load the **ui file** dynamically +The ``QUiLoader`` lets us load the **ui file** dynamically and use it right away: .. code-block:: python @@ -198,9 +198,9 @@ command prompt: .. note:: - `QUiLoader` uses connect() calls taking the function signatures as string + ``QUiLoader`` uses ``connect()`` calls taking the function signatures as string arguments for signal/slot connections. - It is thus unable to handle Python types like `str` or `list` from + It is thus unable to handle Python types like ``str`` or ``list`` from custom widgets written in Python since these types are internally mapped to different C++ types. @@ -270,7 +270,7 @@ for registering types or adding instances of The function :meth:`registerCustomWidget()<PySide6.QtDesigner.QPyDesignerCustomWidgetCollection.registerCustomWidget>` is used to register a widget type with **Qt Designer**. In the simple case, it -can be used like `QUiLoader.registerCustomWidget()`. It takes the custom widget +can be used like ``QUiLoader.registerCustomWidget()``. It takes the custom widget type and some optional keyword arguments passing values that correspond to the getters of `QDesignerCustomWidgetInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html>`_ : diff --git a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst index e1af8b8a9..2fa51c0a8 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/widgetstyling.rst @@ -23,7 +23,7 @@ to each component. As an example, look at the following simple snippet: w.show() sys.exit(app.exec()) -When you execute this code, you will see a simple `QLabel` aligned at the +When you execute this code, you will see a simple ``QLabel`` aligned at the center, and with a placeholder text. .. image:: widgetstyling-simple-no.png @@ -32,8 +32,8 @@ center, and with a placeholder text. You can style your application using the CSS-like syntax. For more information, see `Qt Style Sheets Reference`_. -A `QLabel` can be styled differently by setting some of its CSS -properties, such as `background-color` and `font-family`, +A ``QLabel`` can be styled differently by setting some of its CSS +properties, such as ``background-color`` and ``font-family``, so let's see how does the code look like with these changes: .. code-block:: python @@ -55,7 +55,7 @@ so let's see how does the code look like with these changes: w.show() sys.exit(app.exec()) -Now when you run the code, notice that the `QLabel` looks different with your +Now when you run the code, notice that the ``QLabel`` looks different with your custom style: .. image:: widgetstyling-simple-yes.png @@ -64,15 +64,15 @@ custom style: .. note:: - If you don't have the font `Titillium` installed, you can try with any + If you don't have the font ``Titillium`` installed, you can try with any other you prefer. - Remember you can list your installed fonts using `QFontDatabase`, - specifically the `families()` method. + Remember you can list your installed fonts using ``QFontDatabase``, + specifically the ``families()`` method. Styling each UI element separately like you did in the previous snippet is a lot of work. The easier alternative for this is to use Qt Style Sheets, -which is one or more `.qss` files defining the style for the UI elements in +which is one or more ``.qss`` files defining the style for the UI elements in your application. More examples can be found in the `Qt Style Sheet Examples`_ documentation @@ -94,7 +94,7 @@ Qt Style Sheets It's recommended to create a full new Qt style to cover all the possible corner cases. -A `qss` file is quite similar to a CSS file, but you need to specify the Widget +A ``qss`` file is quite similar to a CSS file, but you need to specify the Widget component and optionally the name of the object:: QLabel { @@ -105,8 +105,8 @@ component and optionally the name of the object:: font-size: 20px; } -The first style defines a `background-color` for all `QLabel` objects in your -application, whereas the later one styles the `title` object only. +The first style defines a ``background-color`` for all ``QLabel`` objects in your +application, whereas the later one styles the ``title`` object only. .. note:: @@ -115,8 +115,8 @@ application, whereas the later one styles the `title` object only. `label.setObjectName("title")` -Once you have a `qss` file for your application, you can apply it by reading -the file and using the `QApplication.setStyleSheet(str)` function: +Once you have a ``qss`` file for your application, you can apply it by reading +the file and using the ``QApplication.setStyleSheet(str)`` function: .. code-block:: python @@ -132,7 +132,7 @@ the file and using the `QApplication.setStyleSheet(str)` function: sys.exit(app.exec()) -Having a general `qss` file allows you to decouple the styling aspects of +Having a general ``qss`` file allows you to decouple the styling aspects of the code, without mixing it in the middle of the general functionality, and you can simply enable it or disable it. @@ -142,14 +142,14 @@ Look at this new example, with more widgets components: :linenos: :lines: 22-44 -This displays a two column widget, with a `QListWidget` on the left and a -`QLabel` and a `QPushButton` on the right. It looks like this when you run the +This displays a two column widget, with a ``QListWidget`` on the left and a +``QLabel`` and a ``QPushButton`` on the right. It looks like this when you run the code: .. image:: widgetstyling-no.png :alt: Widget with no style -If you add content to the previously described `style.qss` file, you can modify +If you add content to the previously described ``style.qss`` file, you can modify the look-n-feel of the previous example: .. literalinclude:: style.qss @@ -161,7 +161,7 @@ You can also use state-based styling on the QListWidget *items* for example, to style them differently depending on whether they are *selected* or not. After applying all the styling alternatives you explored in this topic, notice -that the `QLabel` example looks a lot different now. +that the ``QLabel`` example looks a lot different now. Try running the code to check its new look: .. image:: widgetstyling-yes.png diff --git a/sources/pyside6/doc/tutorials/debugging/qtcreator/qtcreator.rst b/sources/pyside6/doc/tutorials/debugging/qtcreator/qtcreator.rst index c8c9fb8ae..a35020fd1 100644 --- a/sources/pyside6/doc/tutorials/debugging/qtcreator/qtcreator.rst +++ b/sources/pyside6/doc/tutorials/debugging/qtcreator/qtcreator.rst @@ -14,26 +14,26 @@ Here are the steps: 2. Go to Projects -> Run -> Run Configuration -> Add. This is going to open a new window shown below. - .. image:: custom_executable_create.png - :alt: creation of custom executable - :align: center + .. image:: custom_executable_create.png + :alt: creation of custom executable + :align: center 3. Click on Custom Executable and `Create` a new configuration. Feed in the -details like shown below. + details like shown below. - .. image:: custom_executable_run_config.png - :alt: run configuration of custom executable - :align: center + .. image:: custom_executable_run_config.png + :alt: run configuration of custom executable + :align: center 4. Debug -> Start Debugging -> Start Debugging Without Deployment. - .. image:: start_debugging_without_deployment.png - :alt: start debugging without deployment - :align: center + .. image:: start_debugging_without_deployment.png + :alt: start debugging without deployment + :align: center You will now hit you breakpoint and can start debugging your code. - .. image:: breakpoint_cpp.png - :alt: breakpoint cpp - :align: center +.. image:: breakpoint_cpp.png + :alt: breakpoint cpp + :align: center diff --git a/sources/pyside6/doc/tutorials/debugging/vscode/vscode.rst b/sources/pyside6/doc/tutorials/debugging/vscode/vscode.rst index 806035299..b2a527b0e 100644 --- a/sources/pyside6/doc/tutorials/debugging/vscode/vscode.rst +++ b/sources/pyside6/doc/tutorials/debugging/vscode/vscode.rst @@ -36,7 +36,7 @@ search for "Python: Select Interpreter". Creating Configurations in launch.json -------------------------------------- -Run -> Add Configuration -> Python -> Python File +``Run -> Add Configuration -> Python -> Python File`` This should create a launch.json file which looks like this: @@ -145,7 +145,7 @@ Debug The Process 1. Set a breakpoint in the Python code. -2. Go to `Run And Debug` (Ctrl + Shift + D) and run the "Python: Current File" +2. Go to ``Run And Debug`` (Ctrl + Shift + D) and run the "Python: Current File" by clicking the run symbol (green right-arrow). This will hit the breakpoint and will halt the Python debugger. @@ -153,40 +153,40 @@ Debug The Process Current File" to "(gdb) Attach" or "(Windows) Attach". Your setup should now look like this. - .. image:: breakpoint_gdb.png - :alt: breakpoint before attach gdb - :align: center + .. image:: breakpoint_gdb.png + :alt: breakpoint before attach gdb + :align: center 4. Run "(gdb) Attach" or "(Windows) Attach" and this should ask you for the processId of the Python process to which you want to attach the C++ debugger. VSCode also lets you search for the process by its name. - .. tip:: You can find the processId by running `ps aux | grep python` + .. tip:: You can find the processId by running ``ps aux | grep python`` - .. image:: find_process_gdb.png - :alt: find process vscode - :align: center + .. image:: find_process_gdb.png + :alt: find process vscode + :align: center 5. VSCode might now ask you for superuser permissions. In that case, type 'y' and enter your password. - .. code-block:: bash + .. code-block:: bash - Superuser access is required to attach to a process. Attaching as - superuser can potentially harm your computer. Do you want to continue? - [y/N]_ + Superuser access is required to attach to a process. Attaching as + superuser can potentially harm your computer. Do you want to continue? + [y/N]_ 6. That is it. You should now be able to hit the breakpoints that you have set on the C++ counterparts. - .. figure:: audioformat_wrapper.png - :alt: Breakpoint set on the shiboken wrapper class - :align: left + .. figure:: audioformat_wrapper.png + :alt: Breakpoint set on the shiboken wrapper class + :align: left - Breakpoint set on the shiboken wrapper class + Breakpoint set on the shiboken wrapper class - .. figure:: audioformat_cpp.png - :alt: Breakpoint set on C++ implementation - :align: left + .. figure:: audioformat_cpp.png + :alt: Breakpoint set on C++ implementation + :align: left - Breakpoint set on C++ implementation + Breakpoint set on C++ implementation diff --git a/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst b/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst index 9520f0b5d..c60566fd5 100644 --- a/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst +++ b/sources/pyside6/doc/tutorials/qmlintegration/qmlintegration.rst @@ -35,7 +35,7 @@ application and PySide6 integration: Notice that we only need a :code:`QQmlApplicationEngine` to :code:`load` the QML file. -#. Define the `Bridge` class, containing all the logic for the element +#. Define the ``Bridge`` class, containing all the logic for the element that will be register in QML: .. literalinclude:: main.py @@ -48,7 +48,7 @@ application and PySide6 integration: class and the variables :code:`QML_IMPORT_NAME` and :code:`QML_IMPORT_MAJOR_VERSION`. -#. Now, go back to the QML file and connect the signals to the slots defined in the `Bridge` class: +#. Now, go back to the QML file and connect the signals to the slots defined in the ``Bridge`` class: .. code:: js @@ -95,22 +95,22 @@ application and PySide6 integration: #. Now, for changing the look of our application, you have two options: - 1. Use the command line: execute the python file adding the option, `--style`:: + 1. Use the command line: execute the python file adding the option, ``--style``:: python main.py --style material - 2. Use a `qtquickcontrols2.conf` file: + 2. Use a ``qtquickcontrols2.conf`` file: .. literalinclude:: qtquickcontrols2.conf :linenos: - Then add it to your `.qrc` file: + Then add it to your ``.qrc`` file: .. literalinclude:: style.qrc :linenos: - Generate the *rc* file running, `pyside6-rcc style.qrc -o style_rc.py` - And finally import it from your `main.py` script. + Generate the *rc* file running, ``pyside6-rcc style.qrc -o style_rc.py`` + And finally import it from your ``main.py`` script. .. literalinclude:: main.py :linenos: diff --git a/sources/pyside6/doc/tutorials/qmlsqlintegration/qmlsqlintegration.rst b/sources/pyside6/doc/tutorials/qmlsqlintegration/qmlsqlintegration.rst index 4c0131f32..c664f2e46 100644 --- a/sources/pyside6/doc/tutorials/qmlsqlintegration/qmlsqlintegration.rst +++ b/sources/pyside6/doc/tutorials/qmlsqlintegration/qmlsqlintegration.rst @@ -14,9 +14,9 @@ name of our table, and define the global function ``createTable()`` that creates doesn't already exist. The database contains a single line to mock the beginning of a conversation. - .. literalinclude:: sqlDialog.py - :linenos: - :lines: 3-42 +.. literalinclude:: sqlDialog.py + :linenos: + :lines: 4-43 The ``SqlConversationModel`` class offers the read-only data model required for the non-editable contacts list. It derives from the :ref:`QSqlQueryModel` class, which is the logical choice for @@ -26,25 +26,25 @@ Then, we proceed to create the table, set its name to the one defined previously We add the necessary attributes to the table, to have a program that reflects the idea of a chat application. - .. literalinclude:: sqlDialog.py - :linenos: - :lines: 46-58 +.. literalinclude:: sqlDialog.py + :linenos: + :lines: 47-59 In ``setRecipient()``, you set a filter over the returned results from the database, and emit a signal every time the recipient of the message changes. - .. literalinclude:: sqlDialog.py - :linenos: - :lines: 60-69 +.. literalinclude:: sqlDialog.py + :linenos: + :lines: 61-70 The ``data()`` function falls back to ``QSqlTableModel``'s implementation if the role is not a custom user role. If you get a user role, we can subtract :meth:`~.QtCore.Qt.UserRole` from it to get the index of that field, and then use that index to find the value to be returned. - .. literalinclude:: sqlDialog.py - :linenos: - :lines: 71-78 +.. literalinclude:: sqlDialog.py + :linenos: + :lines: 72-79 In ``roleNames()``, we return a Python dictionary with our custom role and role names as key-values @@ -53,27 +53,27 @@ Alternatively, it can be useful to declare an Enum to hold all of the role value Note that ``names`` has to be a hash to be used as a dictionary key, and that's why we're using the ``hash`` function. - .. literalinclude:: sqlDialog.py - :linenos: - :lines: 80-94 +.. literalinclude:: sqlDialog.py + :linenos: + :lines: 81-95 The ``send_message()`` function uses the given recipient and message to insert a new record into the database. Using :meth:`~.QSqlTableModel.OnManualSubmit` requires you to also call ``submitAll()``, since all the changes will be cached in the model until you do so. - .. literalinclude:: sqlDialog.py - :linenos: - :lines: 96-115 +.. literalinclude:: sqlDialog.py + :linenos: + :lines: 97-116 chat.qml -------- Let's look at the ``chat.qml`` file. - .. literalinclude:: chat.qml - :linenos: - :lines: 3-5 +.. literalinclude:: chat.qml + :linenos: + :lines: 4-6 First, import the Qt Quick module. This gives us access to graphical primitives such as Item, Rectangle, Text, and so on. @@ -86,9 +86,9 @@ root type, Window: Let's step through the ``chat.qml`` file. - .. literalinclude:: chat.qml - :linenos: - :lines: 8-13 +.. literalinclude:: chat.qml + :linenos: + :lines: 9-14 ``ApplicationWindow`` is a Window with some added convenience for creating a header and a footer. It also provides the foundation for popups and supports some basic styling, such as the background @@ -101,9 +101,9 @@ Once we've set these, we have a properly sized, empty window ready to be filled Because we are exposing the :code:`SqlConversationModel` class to QML, we will declare a component to access it: - .. literalinclude:: chat.qml - :linenos: - :lines: 15-17 +.. literalinclude:: chat.qml + :linenos: + :lines: 16-18 There are two ways of laying out items in QML: `Item Positioners`_ and `Qt Quick Layouts`_. @@ -113,13 +113,13 @@ There are two ways of laying out items in QML: `Item Positioners`_ and `Qt Quick resizable user interfaces. Below, we use `ColumnLayout`_ to vertically lay out a `ListView`_ and a `Pane`_. - .. literalinclude:: chat.qml - :linenos: - :lines: 19-22 + .. literalinclude:: chat.qml + :linenos: + :lines: 20-23 - .. literalinclude:: chat.qml - :linenos: - :lines: 71-73 + .. literalinclude:: chat.qml + :linenos: + :lines: 72-74 Pane is basically a rectangle whose color comes from the application's style. It's similar to `Frame`_, but it has no stroke around its border. @@ -149,13 +149,12 @@ remaining space that is left after accommodating the Pane. Let's look at the ``Listview`` in detail: - .. literalinclude:: chat.qml - :linenos: - :lines: 22-69 +.. literalinclude:: chat.qml + :linenos: + :lines: 23-70 After filling the ``width`` and ``height`` of its parent, we also set some margins on the view. - Next, we set `displayMarginBeginning`_ and `displayMarginEnd`_. These properties ensure that the delegates outside the view don't disappear when you scroll at the edges of the view. @@ -179,9 +178,9 @@ At the bottom of the screen, we place a `TextArea`_ item to allow multi-line tex button to send the message. We use Pane to cover the area under these two items: - .. literalinclude:: chat.qml - :linenos: - :lines: 71-95 +.. literalinclude:: chat.qml + :linenos: + :lines: 72-96 The `TextArea`_ should fill the available width of the screen. We assign some placeholder text to provide a visual cue to the contact as to where they should begin @@ -203,16 +202,16 @@ main.py We use ``logging`` instead of Python's ``print()``, because it provides a better way to control the messages levels that our application will generate (errors, warnings, and information messages). - .. literalinclude:: main.py - :linenos: - :lines: 3-15 +.. literalinclude:: main.py + :linenos: + :lines: 4-16 ``connectToDatabase()`` creates a connection with the SQLite database, creating the actual file if it doesn't already exist. - .. literalinclude:: main.py - :linenos: - :lines: 18-38 +.. literalinclude:: main.py + :linenos: + :lines: 19-39 A few interesting things happen in the ``main`` function: @@ -227,8 +226,8 @@ A few interesting things happen in the ``main`` function: Finally, the Qt application runs, and your program starts. - .. literalinclude:: main.py - :linenos: - :lines: 41-51 +.. literalinclude:: main.py + :linenos: + :lines: 42-52 .. image:: example_list_view.png |