diff options
Diffstat (limited to 'sources/pyside6/doc/tutorials/basictutorial/uifiles.rst')
| -rw-r--r-- | sources/pyside6/doc/tutorials/basictutorial/uifiles.rst | 114 |
1 files changed, 74 insertions, 40 deletions
diff --git a/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst b/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst index 2a7582ec9..cb945908d 100644 --- a/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst +++ b/sources/pyside6/doc/tutorials/basictutorial/uifiles.rst @@ -1,17 +1,27 @@ -Using `.ui` files from Designer or QtCreator with `QUiLoader` and `pyside6-uic` -******************************************************************************* +.. _using_ui_files: -This page describes the use of Qt Creator to create graphical -interfaces for your Qt for Python project. -You will need **Qt Creator** to design and modify your interface (UI file). +Using ``.ui`` files from Designer or QtCreator with ``QUiLoader`` and ``pyside6-uic`` +************************************************************************************* -If you don't know how to use Qt Creator, refer to the -`Using Qt Designer <http://doc.qt.io/qtcreator/creator-using-qt-designer.html>`_ -documentation page. +This page describes the use of +`Qt Widgets Designer <https://doc.qt.io/qt-6/qtdesigner-manual.html>`_ to create +graphical interfaces based on Qt Widgets for your Qt for Python project. +*Qt Widgets Designer* is a graphical UI design tool which is available as a +standalone binary (``pyside6-designer``) or embedded into the +`Qt Creator IDE <https://doc.qt.io/qtcreator>`_. Its use within *Qt Creator* +is described at +`Using Qt Widgets Designer <https://doc.qt.io/qtcreator/creator-using-qt-designer.html>`_. -At Qt Creator, create a new Qt Design Form, choose "Main Window" for template. -And save as `mainwindow.ui`. -Add a `QPushButton` to the center of the centralwidget. +.. image:: uifiles.png + :alt: Designer and the equivalent code + +The designs are stored in ``.ui`` files, which is an XML-based format. It will +be converted to Python or C++ code populating a widget instance at project build +time by the `pyside6-uic <https://doc.qt.io/qt-6/uic.html>`_ tool. + +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. Your file ``mainwindow.ui`` should look something like this: @@ -77,13 +87,13 @@ Now we are ready to decide how to use the **UI file** from Python. Option A: Generating a Python class =================================== -Another option to interact with a **UI file** is to generate a Python -class from it. This is possible thanks to the `pyside6-uic` tool. +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. 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 @@ -112,7 +122,7 @@ To understand the idea, let's take a look at the whole code: window = MainWindow() window.show() - sys.exit(app.exec_()) + sys.exit(app.exec()) What is inside the *if* statement is already known from the previous examples, and our new basic class contains only two new lines @@ -126,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 @@ -139,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 @@ -177,38 +187,46 @@ The complete code of this example looks like this: sys.exit(-1) window.show() - sys.exit(app.exec_()) + sys.exit(app.exec()) Then to execute it we just need to run the following on a command prompt: -.. code-block:: python +.. code-block:: bash python main.py +.. note:: + + ``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 + custom widgets written in Python since these types are internally mapped + to different C++ types. .. _designer_custom_widgets: -Custom Widgets in Qt Designer -============================= +Custom Widgets in Qt Widgets Designer +===================================== -**Qt Designer** is able to use user-provided (custom) widgets. They are shown -in the widget box and can be dragged onto the form just like Qt's widgets (see -`Using Custom Widgets with Qt Designer <https://doc.qt.io/qt-6/designer-using-custom-widgets.html>`_ -). Normally, this requires implementing the widget as a plugin to Qt Designer -written in C++ implementing its -`QDesignerCustomWidgetInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html>`_ . +*Qt Widgets Designer* is able to use user-provided (custom) widgets. +They are shown in the widget box and can be dragged onto the form just like +Qt's widgets (see +`Using Custom Widgets with Qt Widgets Designer <https://doc.qt.io/qt-6/designer-using-custom-widgets.html>`_ +). Normally, this requires implementing the widget as a plugin to +*Qt Widgets Designer* written in C++ implementing its +`QDesignerCustomWidgetInterface`_ . Qt for Python provides a simple interface for this which is similar to :meth:`registerCustomWidget()<PySide6.QtUiTools.QUiLoader.registerCustomWidget>`. The widget needs to be provided as a Python module, as shown by -the widgetbinding example (file ``wigglywidget.py``) or -the taskmenuextension example (file ``tictactoe.py``). +the :ref:`widgetbinding-example` (file ``wigglywidget.py``) or +the :ref:`task-menu-extension-example` (file ``tictactoe.py``). -Registering this with Qt Designer is done by providing +Registering this with *Qt Widgets Designer* is done by providing a registration script named ``register*.py`` and pointing -the path-type environment variable ``PYSIDE_DESIGNER_PLUGINS`` +the path-type environment variable ``PYSIDE_DESIGNER_PLUGINS`` to the directory. The code of the registration script looks as follows: @@ -245,20 +263,20 @@ The code of the registration script looks as follows: QPyDesignerCustomWidgetCollection provides an implementation of -`QDesignerCustomWidgetCollectionInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetcollectioninterface.html>`_ -exposing custom widgets to **Qt Designer** with static convenience functions -for registering types or adding instances of -`QDesignerCustomWidgetInterface <https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html>`_ . +`QDesignerCustomWidgetCollectionInterface`_ +exposing custom widgets to *Qt Widgets Designer* with static convenience +functions for registering types or adding instances of +`QDesignerCustomWidgetInterface`_ . 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 +is used to register a widget type with *Qt Widgets Designer*. In the simple case, it +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>`_ : +`QDesignerCustomWidgetInterface`_ : -When launching **Qt Designer** via its launcher ``pyside6-designer``, +When launching *Qt Widgets Designer* via its launcher ``pyside6-designer``, the custom widget should be visible in the widget box. For advanced usage, it is also possible to pass the function an implementation @@ -268,3 +286,19 @@ This is shown in taskmenuextension example, where a custom context menu is registered for the custom widget. The example is a port of the corresponding C++ `Task Menu Extension Example <https://doc.qt.io/qt-6/qtdesigner-taskmenuextension-example.html>`_ . + +.. _QDesignerCustomWidgetCollectionInterface: https://doc.qt.io/qt-6/qdesignercustomwidgetcollectioninterface.html +.. _QDesignerCustomWidgetInterface: https://doc.qt.io/qt-6/qdesignercustomwidgetinterface.html + +Troubleshooting the Qt Widgets Designer Plugin +++++++++++++++++++++++++++++++++++++++++++++++ + +- The launcher ``pyside6-designer`` must be used. The standalone + *Qt Widgets Designer* will not load the plugin. +- The menu item **Help/About Plugin** brings up a dialog showing the plugins + found and potential load error messages. +- Check the console or Windows Debug view for further error messages. +- Due to the buffering of output by Python, error messages may appear + only after *Qt Widgets Designer* has terminated. +- When building Qt for Python, be sure to set the ``--standalone`` option + for the plugin to be properly installed. |