diff options
Diffstat (limited to 'sources/pyside6/doc/tools')
26 files changed, 1061 insertions, 0 deletions
diff --git a/sources/pyside6/doc/tools/index.rst b/sources/pyside6/doc/tools/index.rst new file mode 100644 index 000000000..b421a428f --- /dev/null +++ b/sources/pyside6/doc/tools/index.rst @@ -0,0 +1,211 @@ +.. _package_tools: + +Tools +===== + +Following the same idea from the modules, we also include in the packages +(wheels) Qt tools that are important for any Qt application development +workflow, like ``uic``, ``rcc``, etc. + +All the tools **must** be used from the PySide wrappers, and not directly. +For example, if exploring the ``site-packages/`` directory on your installation +you find ``uic.exe`` (on Windows), you should not click on that, and use +``pyside6-uic.exe`` instead. +The reason for this is the proper setup of PATHs, plugins, and more, +to properly work with the installed Python package. + +Here you can find all the tools we include in |project| starting +from 6.3.0, grouped by different topics: + +Project development +~~~~~~~~~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-project`` + :link: pyside6-project + :link-type: ref + + to build *Qt Widgets Designer* forms (``.ui`` files), + resource files (``.qrc``) and QML type files (``.qmltype``) + from a ``.pyproject`` file. + +Widget Development +~~~~~~~~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-designer`` + :link: pyside6-designer + :link-type: ref + + drag-and-drop tool for designing Widget UIs (generates ``.ui`` files, + see :ref:`using_ui_files`). + + .. grid-item-card:: ``pyside6-uic`` + :link: pyside6-uic + :link-type: ref + + to generate Python code from ``.ui`` form files. + + .. grid-item-card:: ``pyside6-rcc`` + :link: pyside6-rcc + :link-type: ref + + to generate serialized data from ``.qrc`` resources files. + Keep in mind these files can be used in other non-widget projects. + + +QML Development +~~~~~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-qmllint`` + :link: pyside6-qmllint + :link-type: ref + + that verifies the syntactic validity of QML files. + + .. grid-item-card:: ``pyside6-qmltyperegistrar`` + :link: pyside6-qmltyperegistrar + :link-type: ref + + to read metatypes files and generate files that contain the necessary + code to register all the types marked with relevant macros. + + .. grid-item-card:: ``pyside6-qmlimportscanner`` + :link: pyside6-qmlimportscanner + :link-type: ref + + to identify the QML modules imported from a + project/QML files and dump the result as a JSON array. + + .. grid-item-card:: ``pyside6-qmlcachegen`` + :link: pyside6-qmlcachegen + :link-type: ref + + to compile QML to bytecode at compile time for bundling inside the + binary. + + .. grid-item-card:: ``pyside6-qml`` + :link: pyside6-qml + :link-type: ref + + to enable quick prototyping with QML files. This tool mimics some of + the capabilities of Qt's ``QML`` runtime utility by + directly invoking QQmlEngine/QQuickView. + +Translations +~~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-linguist`` + :link: pyside6-linguist + :link-type: ref + + for translating text in applications. + + .. grid-item-card:: ``pyside6-lrelease`` + :link: pyside6-lrelease + :link-type: ref + + to create run-time translation files for the application. + + .. grid-item-card:: ``pyside6-lupdate`` + :link: pyside6-lupdate + :link-type: ref + + to synchronize source code and translations. + +Qt Help +~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-assistant`` + :link: pyside6-assistant + :link-type: ref + + for viewing online documentation in Qt Help file format. + Read more about the formats on the `QtHelp Framework`_ page. + +.. _`QtHelp Framework`: https://doc.qt.io/qt-6/qthelp-framework.html + +PySide Utilities +~~~~~~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-genpyi`` + :link: pyside6-genpyi + :link-type: ref + + to generate Python stubs (``.pyi`` files) for Qt modules. + + .. grid-item-card:: ``pyside6-metaobjectdump`` + :link: pyside6-metaobjectdump + :link-type: ref + + a tool to print out the metatype information in JSON to be used as + input for ``qmltyperegistrar``. + +Deployment +~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-deploy`` + :link: pyside6-deploy + :link-type: ref + + to deploy PySide6 applications to desktop platforms - Linux, Windows + and macOS. + + .. grid-item-card:: ``pyside6-android-deploy`` + :link: pyside6-android-deploy + :link-type: ref + + to deploy PySide6 application as an Android app targeting different + Android platforms - aarch64, armv7a, i686, x86_64. + +Shader Tools +~~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-qsb`` + :link: pyside6-qsb + :link-type: ref + + a command-line tool provided by the Qt Shader Tools modules to + generate and inspect .qsb files. + +Qt Quick 3D +~~~~~~~~~~~ + +.. grid:: 2 + :gutter: 3 3 4 5 + + .. grid-item-card:: ``pyside6-balsam`` + :link: pyside6-balsam + :link-type: ref + + a command line tool that takes assets created in digital content + creation tools like Maya, 3ds Max or Blender and converts them into an + efficient runtime format for use with Qt Quick 3D. + + .. grid-item-card:: ``pyside6-balsamui`` + :link: pyside6-balsamui + :link-type: ref + + a graphical user interface for the ``pyside6-balsam`` tool. diff --git a/sources/pyside6/doc/tools/pyside-assistant.rst b/sources/pyside6/doc/tools/pyside-assistant.rst new file mode 100644 index 000000000..c9b3470c3 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-assistant.rst @@ -0,0 +1,21 @@ +.. _pyside6-assistant: + +pyside6-assistant +================= + +``pyside6-assistant`` is a tool that wraps `Qt Assistant`_, the help +viewer of Qt for use with the Qt help file format (see `The Qt Help Framework`_). + +The version of assistant shipped with Qt for Python does not contain +any documentation. + +You can build the Qt for Python documentation in the Qt help file format +(see :ref:`building_documentation`) and register it for use in `Preferences` +dialog of ``pyside6-assistant`` (`Edit/Preferences`). + +.. image:: pyside6-assistant_screenshot.webp + :width: 381 + :alt: PySide6 Assistant Screenshot + +.. _`Qt Assistant`: https://doc.qt.io/qt-6/qtassistant-index.html +.. _`The Qt Help Framework`: https://doc.qt.io/qt-6/qthelp-framework.html diff --git a/sources/pyside6/doc/tools/pyside-designer.rst b/sources/pyside6/doc/tools/pyside-designer.rst new file mode 100644 index 000000000..4cde6b2bf --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-designer.rst @@ -0,0 +1,91 @@ +.. _pyside6-designer: + +pyside6-designer +================ + +``pyside6-designer`` is a tool that wraps the `Qt Widgets Designer`_, +to enable you to design Qt Widgets applications with a *drag-and-drop* +approach. + +.. image:: pyside6-designer_screenshot.webp + :width: 100% + :alt: PySide6 Designer Screenshot + +Usage +----- + +With ``pyside6-designer`` you can design your application in a simple way, +to later save the end result in a ``.ui`` file. When you start the tool, you +will see a dialog to select the base window: a QWidget, a QMainWindow, etc. + +.. image:: pyside6-designer_base_screenshot.webp + :width: 50% + :alt: PySide6 Designer Initial Screenshot + +Once you select one of those options, you can start placing widgets +into the interface, and have access to the whole structure, properties, +and more. + +.. image:: pyside6-designer_sections_screenshot.webp + :width: 100% + :alt: PySide6 Designer Initial Screenshot + +A simple distinction of the areas you might use is described in the +previous screenshot. In the section **1** you will find all the elements +you can use in your application, which is the area **2**. +The application designs follows a hierarchical configuration, +in **3** you can see the structure of the example which contains +only a ``QMainWindow`` and a ``QPushButton``. Lastly +you can access and modify the properties of the item in **4**, +where you could adjust dimensions, names, etc. + + +When your application is finished, you will save your design in a ``.ui`` +file. This ``.ui`` file can later be converted into a Python file, +with the help of the :ref:`pyside6-uic` tool. You can find +more details of this process in: :ref:`using_ui_files`. + +If you are interested in more functionality of the tool, you can check +the official `Qt Widgets Designer Manual`_. + + +Custom Widgets +-------------- + +One of the features that the `Qt Widgets Designer`_ provides is the possibility +of loading custom widgets, in order to facilitate the development with ad-hoc +widgets. + +On the following screenshot, you can see a new component on the left column +that is already added on the main widget, a tic-tac-toe custom widget. + +.. image:: pyside6-designer_customwidgets_screenshot.webp + :width: 100% + :alt: PySide6 Designer Custom Widgets Screenshot + +To achieve this, you need to register a custom widget by setting the environment +variable ``PYSIDE_DESIGNER_PLUGINS`` to the directory where your register file +is located. The registration file for the tic-tac-toe widget looks like this: + +.. code-block:: Python + + from tictactoe import TicTacToe + from tictactoeplugin import TicTacToePlugin + + from PySide6.QtDesigner import QPyDesignerCustomWidgetCollection + + + if __name__ == '__main__': + QPyDesignerCustomWidgetCollection.addCustomWidget(TicTacToePlugin()) + +As you can see in the previous code, ``TicTacToe`` is the custom widget, +imported from a different file, and the ``TicTacToePlugin`` is the interface +layer for `Qt Widgets Designer`_ to recognize it. +We provide a helper class, ``QPyDesignerCustomWidgetCollection``, to +simplify the registration process. + +If you are interested in all the details of this specific case, you can +check the :ref:`task-menu-extension-example`. + +.. _`Qt Widgets Designer`: https://doc.qt.io/qt-6/qtdesigner-manual.html +.. _`Qt Widgets Designer Manual`: https://doc.qt.io/qt-6/qtdesigner-manual.html diff --git a/sources/pyside6/doc/tools/pyside-genpyi.rst b/sources/pyside6/doc/tools/pyside-genpyi.rst new file mode 100644 index 000000000..0240c5005 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-genpyi.rst @@ -0,0 +1,52 @@ +.. _pyside6-genpyi: + +pyside6-genpyi +============== + +`pyside6-genpyi` is a command line tool to generate Python stub files +(.pyi) for PySide modules. Stub files define signatures of all classes, +methods (including overloads), constants and enums of the PySide +modules. Signatures also contain type hints. This helps PySide integrate +with Python type checkers and IDEs. For example, if you use any function +from the Qt API with PySide, your IDE's function lookup feature will +show you the function signature and its parameters and return value +including types. + +PySide6 already ships with stub files that were generated with +`pyside6-genpyi`. However, if you want to generate new stub files for +several (or all) modules, for example to toggle a few features, you can +run `pyside6-genpyi` manually. If you want to generate stub files for +your own custom module, refer to :ref:`shiboken6-genpyi`. + + +Usage +----- + +To generate stub files for a PySide module, run the following command: + +.. code-block:: bash + + pyside6-genpyi <module_names> [OPTIONS] + +where `<module_names>` is a space-separated list of module names (the +modules must be importable from the working directory) and where +`[OPTIONS]` can be one of the following: + +* **--quiet**: Run the tool quietly without output to stdout. +* **--outpath <output_dir>**: Specify the output directory for the + generated stub files. If not specified, the stub files are generated + in the location of the module binary. +* **--sys-path <paths>**: Prepend the system path (`sys.path`) with a + space-separated list of strings `<paths>`. This is useful if the + module is not installed in a default lookup location. +* **--feature <features>**: A space-separate list of optional PySide + features to enable (see :ref:`pysideapi2`). This option has no effect + when using PyPy. Currently, the following features are available: + + * **snake_case**: All methods in the module are switched from + ``camelCase`` to ``snake_case``. A single upper case letter is + replaced by an underscore and the lower case letter. + * **true_property**: All getter and setter functions in the module + which are marked as a property in the Qt6 docs are replaced by Python + property objects. Properties are also listed as such in the according + QMetaObject of a class. diff --git a/sources/pyside6/doc/tools/pyside-linguist.rst b/sources/pyside6/doc/tools/pyside-linguist.rst new file mode 100644 index 000000000..e13124a8e --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-linguist.rst @@ -0,0 +1,20 @@ +.. _pyside6-linguist: + +pyside6-linguist +================= + +``pyside6-linguist`` is a tool that wraps `Qt Linguist`_, Qt's tool to +translate user interfaces and manage application localizations. It +supports Qt's own TS file format as well as the XML Localization +Interchange File Format (XLIFF). There are no differences between the +version bundled with PySide and the one from Qt. + +For more information on how to use this tool, read Qt's documentation +here: `Qt Linguist`_. Read more about how to translate PySide +applications here: :ref:`translations`. + +.. image:: pyside6-linguist_screenshot.webp + :width: 500 + :alt: PySide6 Linguist Screenshot + +.. _`Qt Linguist`: https://doc.qt.io/qt-6/qtlinguist-index.html diff --git a/sources/pyside6/doc/tools/pyside-lrelease.rst b/sources/pyside6/doc/tools/pyside-lrelease.rst new file mode 100644 index 000000000..7c628f2aa --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-lrelease.rst @@ -0,0 +1,25 @@ +.. _pyside6-lrelease: + +pyside6-lrelease +================ + +.. note:: This tool is automatically called by :ref:`pyside6-project` + so you don't need to call it manually. *Qt Creator* will take care + of this step as well while executing a project. + +``pyside6-lrelease`` is a command line tool wrapping `lrelease`_. It produces +``.qm`` files out of ``.ts`` files. The ``.qm`` file format is a compact binary +format that the localized application uses. It provides extremely fast lookup +for translations (see :ref:`translations`). + +Usage +----- + +To convert a ``.ts`` file of the :ref:`qt-linguist-example` +into its binary representation, run: + +.. code-block:: bash + + pyside6-lrelease example_de.ts -qm example_de.qm + +.. _`lrelease`: https://doc.qt.io/qt-6/linguist-lrelease.html diff --git a/sources/pyside6/doc/tools/pyside-lupdate.rst b/sources/pyside6/doc/tools/pyside-lupdate.rst new file mode 100644 index 000000000..1c0d73c15 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-lupdate.rst @@ -0,0 +1,23 @@ +.. _pyside6-lupdate: + +pyside6-lupdate +=============== + +.. note:: This tool is automatically called by :ref:`pyside6-project` + so you don't need to call it manually. + +``pyside6-lupdate`` is a command line tool wrapping `lupdate`_. It finds +translatable strings in Python, ``.ui``, and ``.qml`` files and generates or +updates ``.ts`` files (see :ref:`translations`). + +Usage +----- + +To create or update the ``.ts`` file of the :ref:`qt-linguist-example`, +run: + +.. code-block:: bash + + pyside6-lupdate main.py main.qml form.ui -ts example_de.ts + +.. _`lupdate`: https://doc.qt.io/qt-6/linguist-lupdate.html diff --git a/sources/pyside6/doc/tools/pyside-metaobjectdump.rst b/sources/pyside6/doc/tools/pyside-metaobjectdump.rst new file mode 100644 index 000000000..1522b7ad5 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-metaobjectdump.rst @@ -0,0 +1,92 @@ +.. _pyside6-metaobjectdump: + +pyside6-metaobjectdump +====================== + +``pyside6-metaobjectdump`` is a command line tool. It scans Python source +files and dumps out information on classes to be registered with QML in +JSON-format. This serves as input for the :ref:`pyside6-qmltyperegistrar` tool. + +The tool is the equivalent of the `moc`_ tool in Qt / C++. + +It is automatically run by the :ref:`pyside6-project` tool +when passing the ``qmllint`` argument instructing it to check +the QML source files. + +Usage +----- + +Classes to be registered with QML are indicated by QML decorators +like :deco:`QmlElement`. Invoking: + +.. code-block:: bash + + pyside6-metaobjectdump birthdayparty.py + +produces the JSON data on stdout: + +.. code-block:: json + + [ + { + "classes": [ + { + "className": "BirthdayParty", + "qualifiedClassName": "BirthdayParty", + "object": true, + "superClasses": [ + { + "access": "public", + "name": "QObject" + } + ], + "classInfos": [ + { + "name": "QML.Element", + "value": "auto" + } + ], + "properties": [ + { + "name": "host", + "type": "Person", + "index": 0, + "read": "host", + "notify": "host_changed", + "write": "host" + }, + { + "name": "guests", + "type": "QQmlListProperty<Person>", + "index": 1 + } + ], + "signals": [ + { + "access": "public", + "name": "host_changed", + "arguments": [], + "returnType": "void" + }, + { + "access": "public", + "name": "guests_changed", + "arguments": [], + "returnType": "void" + } + ] + } + ], + "outputRevision": 68, + "QML_IMPORT_NAME": "People", + "QML_IMPORT_MAJOR_VERSION": 1, + "QML_IMPORT_MINOR_VERSION": 0, + "QT_MODULES": [ + "QtCore", + "QtQml" + ], + "inputFile": ".../examples/qml/tutorials/extending-qml-advanced/advanced1-Base-project/birthdayparty.py" + } + ] + +.. _`moc`: https://doc.qt.io/qt-6/moc.html diff --git a/sources/pyside6/doc/tools/pyside-project.rst b/sources/pyside6/doc/tools/pyside-project.rst new file mode 100644 index 000000000..0359e1b7d --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-project.rst @@ -0,0 +1,64 @@ +.. _pyside6-project: + +pyside6-project +=============== + +`pyside6-project` is a command line tool for creating, building and deploying +|project| applications. It operates on a project file which is also used by +`Qt Creator`_. + +Project file format +------------------- + +The project file format is a simple `JSON`_-based format with the suffix +``.pyproject`` listing all files of the project excluding generated files +(typically ``.py``, ``.qml``, ``.qrc``, ``.ts``, or ``.ui`` files): + +.. code-block:: json + + { + "files": ["main.py"] + } + + +Usage +----- + +The tool has several subcommands. New projects can be created using +the below commands, passing the project name (directory): + +*new-ui* + Creates a new QtWidgets project with a *Qt Widgets Designer*-based main + window. + +*new-widget* + Creates a new QtWidgets project with a main window. + +*new-quick* + Creates a new QtQuick project. + +The other commands take the project file as an argument. +It is also possible to specify a directory containing the project file. + +*build* + Builds the project, generating the required build artifacts + (see :ref:`using_ui_files`, :ref:`using_qrc_files`). + +*run* + Builds the project and runs the main. + +*deploy* + Deploys the application (see see :ref:`pyside6-deploy`). + +*lupdate* + Updates translation (.ts) files (see :ref:`translations`). + +*clean* + Cleans the build artifacts. + +*qmllint* + Runs the ``qmllint`` tool, checking the QML files. + + +.. _`Qt Creator`: https://www.qt.io/product/development-tools +.. _`JSON`: https://www.json.org/ diff --git a/sources/pyside6/doc/tools/pyside-qml.rst b/sources/pyside6/doc/tools/pyside-qml.rst new file mode 100644 index 000000000..0502dd94a --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-qml.rst @@ -0,0 +1,84 @@ +.. _pyside6-qml: + +pyside6-qml +=========== + +``pyside6-qml`` mimics some capabilities of Qt's `qml <qml_runtime>`_ runtime utility by directly +invoking QQmlEngine/QQuickView. It enables prototyping with QML/QtQuick without the need to write +any Python code that loads the QML files either through `QQmlApplicationEngine <qqmlappengine>`_ or +the `QQuickView <qquickview>`_ class. The tool also detects the QML classes implemented in Python +and registers them with the QML type system. + +Usage +----- + +Consider the example `Extending QML - Plugins Example <extending_qml_example>`_. This example does +not have a Python file with a ``main`` function that initializes a QmlEngine to load the QML file +``app.qml``. You can run the example by running + +.. code-block:: bash + + pyside6-qml examples/qml/tutorials/extending-qml/chapter6-plugins/app.qml -I examples/qml/tutorials/extending-qml/chapter6-plugins/Charts + +The ``-I`` flag is used to point ``pyside6-qml`` to the folder containing Python files that +implement QML classes. + +Command Line Options +-------------------- + +Here are all the command line options of ``pyside6-qml``: + +Arguments +^^^^^^^^^ + +* **file**: This option refers to the QML file to be loaded by ``pyside6-qml``. This option does not + have a name or a flag. Therefore, this option should be the first option supplied to + ``pyside6-qml``. For example, + +.. code-block:: bash + + pyside6-qml /path/to/test.qml + +Options +^^^^^^^ + +* **--module-paths/-I**: Specify space-separated folder/file paths which point to the Python files + that implement QML classes. By default, the parent directory of the QML file supplied to + ``pyside6-qml`` is searched recursively for all Python files and they are imported. Otherwise, + only the paths given in module paths are searched. + +* **--verbose/-v**: Run ``pyside6-qml`` in verbose mode. When run in this mode, pyside6-qml prints + log messages during various stages of processing. + +Options that align with `QML <qml_runtime>`_ runtime utility +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **--app-typ/-a**: Specifies which application class to use. It takes one of the three values - + ``core, gui, widget``. The default value is *gui*. + +* **--config/-c**: Load the given built-in configuration. It takes one of two values - ``default, + resizeToItem``. This option is only relevant for a QtQuick application. If ``default`` is used, + the view resizes to the size of the root item in the QML. If ``resizeToItem`` is used, the view + automatically resizes the root item to the size of the view. + +* **--list-conf**: List the built-in configurations. ``pyside6-qml`` has two built-in configurations + - ``default`` and ``resizeToItem``. See the option ``--config`` for more information. + +* **--rhi/-r**: Specifies the backend for the Qt graphics abstraction (RHI). It takes one of the + four values - ``vulkan, metal, d3dll, gl``. + +* **--verbose/-v**: List the built-in configurations. ``pyside6-qml`` has two built-in + configurations - *default* and *resizeToItem*. See the option ``--config`` for more information. + +* **--gles**: Force use of GLES (AA_UseOpenGLES). + +* **--desktop**: Force use of desktop OpenGL (AA_UseDesktopOpenGL). + +* **--software**: Force use of software rendering(AA_UseSoftwareOpenGL). + +* **--disable-context-sharing**: Disable the use of a shared GL context for QtQuick Windows". + +.. _`qml_runtime`: https://doc.qt.io/qt-6/qtquick-qml-runtime.html +.. _`qqmlappengine`: https://doc.qt.io/qt-6/qqmlapplicationengine.html +.. _`qquickview`: https://doc.qt.io/qt-6/qquickview.html +.. _`extending_qml_example`: https://doc.qt.io/qtforpython-6/examples/example_qml_tutorials_extending-qml_chapter6-plugins.html diff --git a/sources/pyside6/doc/tools/pyside-qmlcachegen.rst b/sources/pyside6/doc/tools/pyside-qmlcachegen.rst new file mode 100644 index 000000000..ecd8e6afd --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-qmlcachegen.rst @@ -0,0 +1,25 @@ +.. _pyside6-qmlcachegen: + +pyside6-qmlcachegen +=================== + +``pyside6-qmlcachegen`` is a command line tool that wraps `qmlcachegen`_. +This tool creates C++ code or `QML byte code` for ``.qml`` files. For +Qt for Python, only `QML byte code` is relevant. The file suffix is +``.qmlc`` and it works similar to compiled Python bytecode +(``.pyc`` files). + +Usage +----- + +The command line option ``--only-bytecode`` should be used to +create `QML byte code`. For example: + +.. code-block:: bash + + qmlcachegen --only-bytecode gallery.qml + +produces a file ``gallery.qmlc`` containing `QML byte code` which is +automatically loaded by the QML engine. + +.. _`qmlcachegen`: https://doc.qt.io/qt-6/qtqml-tool-qmlcachegen.html diff --git a/sources/pyside6/doc/tools/pyside-qmllint.rst b/sources/pyside6/doc/tools/pyside-qmllint.rst new file mode 100644 index 000000000..54a72470e --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-qmllint.rst @@ -0,0 +1,49 @@ +.. _pyside6-qmllint: + +pyside6-qmllint +=============== + +``pyside6-qmllint`` is a command line tool that wraps `qmllint`_. This tool +verifies the syntatic validity of QML files and warns about some QML +anti-patterns. + +It is automatically run by the :ref:`pyside6-project` tool +when passing the ``qmllint`` argument instructing it to check +the QML source files. + +Usage +----- + +The tool should normally not be invoked manually since it requires +a number of import paths and additional type information +generated by :ref:`pyside6-qmltyperegistrar` to function. + +For example, for a ``.qml`` file like: + +.. code-block:: javascript + + import QtQuick + import QtQuick.Controls + + Item { + Text { + id: name + text: qsTr("Hello World") + } + } + +when running: + +.. code-block:: bash + + pyside6-qmllint Main.qml + +it would warn about unused imports: + +.. code-block:: + + Info: Main.qml:2:1: Unused import [unused-imports] + import QtQuick.Controls + ^^^^^^ + +.. _`qmllint`: https://doc.qt.io/qt-6/qtquick-tool-qmllint.html diff --git a/sources/pyside6/doc/tools/pyside-qmltyperegistrar.rst b/sources/pyside6/doc/tools/pyside-qmltyperegistrar.rst new file mode 100644 index 000000000..0e8d66bd5 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-qmltyperegistrar.rst @@ -0,0 +1,17 @@ +.. _pyside6-qmltyperegistrar: + +pyside6-qmltyperegistrar +======================== + +``pyside6-qmltyperegistrar`` is a command line tool that wraps the +``qmltyperegistrar`` tool of Qt. + +It takes the file produced by :ref:`pyside6-metaobjectdump` +as input and generates C++ code to register C++ classes to QML +and a ``.qmltypes`` file containing a JSON description of the +classes. For Qt for Python, only the ``.qmltypes`` file +is of interest as input for :ref:`pyside6-qmllint`. + +The tool is automatically run by the :ref:`pyside6-project` tool +when passing the ``qmllint`` argument instructing it to check +the QML source files. diff --git a/sources/pyside6/doc/tools/pyside-rcc.rst b/sources/pyside6/doc/tools/pyside-rcc.rst new file mode 100644 index 000000000..e5688485e --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-rcc.rst @@ -0,0 +1,55 @@ +.. _pyside6-rcc: + +pyside6-rcc +=========== + +.. note:: This tool is automatically called by :ref:`pyside6-project` + so you don't need to call it manually. *Qt Creator* will take care + of this step as well while executing a project. + + +``pyside6-rcc`` is a command line tool for converting ``.qrc`` files into ``.py`` +files, so they can be used within your Python code. + +The tool is a wrapper around the `rcc`_ tool, which was originally +designed to generate C++ code, but it also has Python support. + +Even though the equivalent of ``pyside6-rcc`` is running ``rcc -g python`` +we strongly recommend you to rely on ``pyside6-rcc`` in order to avoid +mismatches between versions for the generated code. + +Usage +----- + +Once you have gathered your resources on a qrc file, +you can transform your ``.qrc`` file with the following command: + +.. code-block:: bash + + pyside6-rcc your_file.qrc -o rc_your_file.py + +It is important to use the ``-o`` option to generate the Python file with the +conversion, otherwise you will receive all the output as stdout in your terminal. + +To enable the usage of those resources in your program, you need to import +the file: + +.. code-block:: Python + + import rc_your_file + +then you can use a specific resource, for example an image, with the prefix ``:/``, +for example: + +.. code-block:: Python + + pixmap = QPixmap(":/icons/image.png") + + +For additional options, you can use ``pyside6-rcc -h`` in order to get +more information about additional options. + +Visit the tutorial :ref:`using_qrc_files` for a hands-on example. + +.. _`rcc`: https://doc.qt.io/qt-6/rcc.html + diff --git a/sources/pyside6/doc/tools/pyside-uic.rst b/sources/pyside6/doc/tools/pyside-uic.rst new file mode 100644 index 000000000..ba4e36b4e --- /dev/null +++ b/sources/pyside6/doc/tools/pyside-uic.rst @@ -0,0 +1,59 @@ +.. _pyside6-uic: + +pyside6-uic +=========== + +.. note:: This tool is automatically called by :ref:`pyside6-project` + so you don't need to call it manually. *Qt Creator* will take care + of this step as well while executing a project. + +``pyside6-uic`` is a command line tool for converting ``.ui`` files into ``.py`` +files, with the objective of using application designs as Python classes. + +The tool is a wrapper around the `uic`_ tool, which was originally +designed to generate C++ code, but it also has Python support. + +Even though the equivalent of ``pyside6-uic`` is running ``uic -g python`` +we strongly recommend you to rely on ``pyside6-uic`` in order to avoid +mismatches between versions for the generated code. + +Usage +----- + +Once you have designed your application with :ref:`pyside6-designer`, +you can transform your ``.ui`` file with the following command: + +.. code-block:: bash + + pyside6-uic your_file.ui -o ui_your_file.py + +It is important to use the ``-o`` option to generate the Python file with the +conversion, otherwise you will receive all the output as stdout in your terminal. + +The structure of the generated Python file will be similar in all cases, +and you will get one class called ``Ui_TheNameOfYourDesign(object)`` that +is in charge of positioning all the elements like your design. + +To use this Python file, you should follow our tutorial in +:ref:`using_ui_files`, but in summary, it is mainly importing the class +from the generated file and setting it up in your code: + +.. code-block:: Python + + self.ui = Ui_TheNameOfYourDesign() + self.ui.setupUi(self) + +For additional options, you can use ``pyside-uic -h`` in order to get +more information related to relative imports, absolute imports, using resources, +translations, etc. + +.. note:: Remember that you need to have a class corresponding to the base + form you selected in :ref:`pyside6-designer`, a ``QWidget``, or ``QDialog``, + or ``QMainWindow``, etc, in order for ``setupUi`` to work. Check + :ref:`using_ui_files` for more information. + +.. warning:: Do not modify the content of the generated Python file from your + ``.ui`` file, otherwise everything will be lost when you re-generate it. + +.. _`uic`: https://doc.qt.io/qt-6/uic.html + diff --git a/sources/pyside6/doc/tools/pyside6-assistant_screenshot.webp b/sources/pyside6/doc/tools/pyside6-assistant_screenshot.webp Binary files differnew file mode 100644 index 000000000..7d898d8e6 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-assistant_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-balsam.rst b/sources/pyside6/doc/tools/pyside6-balsam.rst new file mode 100644 index 000000000..c6677f6a3 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-balsam.rst @@ -0,0 +1,59 @@ +.. _pyside6-balsam: + +pyside6-balsam +============== + +``pyside6-qsb`` is a tool that wraps the `balsam <Balsam Asset Import Tool>`_ +tool provided with Qt Quick 3D. The Balsam tool is a command line application +that is part of Qt Quick 3D's asset conditioning pipeline. The purpose is to +take assets created in digital content creation tools like `Maya`_, `3ds Max`_ +or `Blender`_ and converts them into an efficient runtime format for use with Qt +Quick 3D. It is not possible, nor does it make sense to reference the +interchange formats directly in applications because a large amount of +resources are needed to parse and condition the content of the asset before it +is usable for real-time rendering. Instead, the interchange formats can be +converted via the Balsam tool into QML Components and resources like geometry +and textures. + + +For more information on how to use this tool, read Qt's documentation +here: `Balsam Asset Import Tool`_. + +Usage +----- + +.. code-block:: bash + + pyside6-balsam [options] sourceFileName + +To convert a 3D asset contained in the file ``testModel.fbx`` with +``pyside6-balsam`` the following command would be used: + +.. code-block:: bash + + pyside6-balsam testModel.fbx + +This would generate the following files: + +* meshes/testModel.mesh +* TestModel.qml + +Which can then be used in a Qt Quick 3D project by using that QML Component: + +.. code-block:: xml + + import QtQuick3D 1.0 + + Scene { + Model { + source: "TestModel.qml" + } + } + +For other modes of operation, refer to the `Balsam Asset Import Tool`_. + +.. _`Balsam Asset Import Tool`: https://doc.qt.io/qt-6/qtquick3d-tool-balsam.html +.. _Maya: https://www.autodesk.com/products/maya/overview +.. _3ds Max: https://www.autodesk.com/products/3ds-max/overview +.. _Blender: https://www.blender.org/ + diff --git a/sources/pyside6/doc/tools/pyside6-balsamui.rst b/sources/pyside6/doc/tools/pyside6-balsamui.rst new file mode 100644 index 000000000..f34cb6045 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-balsamui.rst @@ -0,0 +1,22 @@ +.. _pyside6-balsamui: + +pyside6-balsamui +================ + +``pyside6-balsamui`` is graphical user interface frontend to the command line +tool :ref:`pyside6-balsam`. The purpose of the tool is to take assets created +in digital content creation tools like `Maya`_, `3ds Max`_ or `Blender`_ and +converts them into an efficient runtime format for use with Qt Quick 3D. + +For more information on the further capabilities of the tool, read Qt's +documentation here: `Balsam Asset Import Tool`_. + +.. image:: pyside6-balsamui_screenshot.webp + :width: 500 + :alt: pyside6-balsamui screenshot + +.. _`Balsam Asset Import Tool`: https://doc.qt.io/qt-6/qtquick3d-tool-balsam.html +.. _Maya: https://www.autodesk.com/products/maya/overview +.. _3ds Max: https://www.autodesk.com/products/3ds-max/overview +.. _Blender: https://www.blender.org/ + diff --git a/sources/pyside6/doc/tools/pyside6-balsamui_screenshot.webp b/sources/pyside6/doc/tools/pyside6-balsamui_screenshot.webp Binary files differnew file mode 100644 index 000000000..5c194fdb6 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-balsamui_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-designer_base_screenshot.webp b/sources/pyside6/doc/tools/pyside6-designer_base_screenshot.webp Binary files differnew file mode 100644 index 000000000..88ff77786 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-designer_base_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-designer_customwidgets_screenshot.webp b/sources/pyside6/doc/tools/pyside6-designer_customwidgets_screenshot.webp Binary files differnew file mode 100644 index 000000000..c84436c1d --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-designer_customwidgets_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-designer_screenshot.webp b/sources/pyside6/doc/tools/pyside6-designer_screenshot.webp Binary files differnew file mode 100644 index 000000000..27f03652b --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-designer_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-designer_sections_screenshot.webp b/sources/pyside6/doc/tools/pyside6-designer_sections_screenshot.webp Binary files differnew file mode 100644 index 000000000..6ff025503 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-designer_sections_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-linguist_screenshot.webp b/sources/pyside6/doc/tools/pyside6-linguist_screenshot.webp Binary files differnew file mode 100644 index 000000000..cd91007ba --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-linguist_screenshot.webp diff --git a/sources/pyside6/doc/tools/pyside6-qmlimportscanner.rst b/sources/pyside6/doc/tools/pyside6-qmlimportscanner.rst new file mode 100644 index 000000000..ba27414d7 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-qmlimportscanner.rst @@ -0,0 +1,53 @@ +.. _pyside6-qmlimportscanner: + +pyside6-qmlimportscanner +======================== + +``pyside6-qmlimportscanner`` is a command line tool that wraps the +``qmlimportscanner`` tool of Qt. + + +The tool is automatically run by the :ref:`pyside6-project` tool +when passing the ``qmllint`` argument instructing it to check +the QML source files. + +Usage +----- + +Invoking the tool in the directory of the :ref:`filesystemexplorer_example` +example using: + +.. code-block:: bash + + pyside6-qmlimportscanner -rootPath . + +produces: + +.. code-block:: json + + [ + { + "name": "QtQuick", + "type": "module" + }, + { + "name": "QtQuick.Controls.Basic", + "type": "module" + }, + { + "name": "QtQuick.Layouts", + "type": "module" + }, + { + "name": "FileSystemModule", + "type": "module" + }, + { + "name": "QtQuick.Controls", + "type": "module" + }, + { + "name": "QtQuick.Effects", + "type": "module" + } + ] diff --git a/sources/pyside6/doc/tools/pyside6-qsb.rst b/sources/pyside6/doc/tools/pyside6-qsb.rst new file mode 100644 index 000000000..f6f1847d4 --- /dev/null +++ b/sources/pyside6/doc/tools/pyside6-qsb.rst @@ -0,0 +1,39 @@ +.. _pyside6-qsb: + +pyside6-qsb +=========== + +``pyside6-qsb`` is a tool that wraps the `qsb <QSB Manual>`_ tool. qsb is a +command line tool provided by the `Qt Shader Tools`_ module. It integrates +third-party libraries such as `glslang`_ and `SPIRV-Cross`_, optionally invokes +external tools, such as ``fxc`` or ``spirv-opt``, and generates .qsb files. +Additionally, it can be used to inspect the contents of a .qsb package. + +For more information on how to use this tool, read Qt's documentation +here: `QSB Manual`_. + +Usage +----- + +To create a qsb file from a shader file, e.g., ``shader.frag``, use the +following command: + +.. code-block:: bash + + pyside6-qsb -o shader.frag.qsb shader.frag + +To inspect the file produced, i.e., ``shader.frag.qsb``, use the following +command: + +.. code-block:: bash + + pyside6-qsb -d shader.frag.qsb + +This will print the reflection metadata (in JSON form) and the included shaders. + +For other modes of operation, refer to the `QSB Manual`_. + +.. _`glslang`: https://github.com/KhronosGroup/glslang +.. _`spirv-cross`: https://github.com/KhronosGroup/SPIRV-Cross +.. _`QSB Manual`: https://doc.qt.io/qt-6/qtshadertools-qsb.html +.. _`Qt Shader Tools`: https://doc.qt.io/qt-6/qtshadertools-index.html |
