From a48009318a3420ad3a5b4ee9e2062ff2ab8faf94 Mon Sep 17 00:00:00 2001 From: Shyamnath Premnadh Date: Tue, 19 Mar 2024 12:36:19 +0100 Subject: Doc: Add pyside6-qml Change-Id: I5fa5397cf3f7e9c70e58adec7321f02ba7d38c9d Reviewed-by: Adrian Herrmann --- .../pyside6/doc/gettingstarted/package_details.rst | 8 +-- sources/pyside6/doc/tools/pyside-qml.rst | 84 ++++++++++++++++++++++ 2 files changed, 88 insertions(+), 4 deletions(-) create mode 100644 sources/pyside6/doc/tools/pyside-qml.rst diff --git a/sources/pyside6/doc/gettingstarted/package_details.rst b/sources/pyside6/doc/gettingstarted/package_details.rst index 986c6f00b..95c3e0c36 100644 --- a/sources/pyside6/doc/gettingstarted/package_details.rst +++ b/sources/pyside6/doc/gettingstarted/package_details.rst @@ -161,12 +161,12 @@ QML Development binary. .. grid-item-card:: ``pyside6-qml`` - :link: qml-chapter6-plugins-example + :link: pyside6-qml :link-type: ref - to enable quick prototyping with QML files. This tool mimics the capabilities of Qt's - ``qml`` runtime utility by directly invoking QQmlEngine/QQuickView. For usage, see - :ref:`qml-chapter6-plugins-example`. + 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 ~~~~~~~~~~~~ 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 `_ 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 `_ or +the `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 `_. 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 `_ 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 -- cgit v1.2.3