.. meta::
    :description: Extensions How to develop GUI User Interface

.. _howtodevelopui:

How to develop a User Interface
===============================

For the extensions using a User Interface (UI), the application rely on the library `Qt <https://www.qt.io/>`_
and on the associated Python wrapper.

To design the UI, we recommend using `Qt Designer <http://doc.qt.io/qt-5/qtdesigner-manual.html>`_.
This section describes how to do the setup and the different development procedures.

.. _howtodevelopui_videotutorial:

.. includevideo:: DemoDevelopmentUI

The source code of the plugin developed in this tutorial can be downloaded
:download:`here </Documentation/Zipped/MyDemo_4924010623d611e88ff4448a5b5d70c0.zip>`.

Setup to start Qt Designer
--------------------------

In a file browser, go to the folder where Dragonfly is installed (usually *C:\\Program Files\\Dragonfly*;
see :ref:`setupForDevelopmentWithPyCharm`).
Copy the file *setEVarsForPythonIDE.bat* in a folder with writing permission (example, the Desktop).
Edit that copied file with a text editor, like Notepad.
Add the path to the Qt Designer executable at the end of the file.
Save and close the file.
Rename the file with a more relevant name, like *startQtDesigner.bat*.

.. image:: EditSetEVarsForPythonIDEQtDesigner.jpg

Starting Qt Designer
--------------------

Execute the file created at the previous step (renamed *startQtDesigner.bat*).

.. note::
    Starting Qt Designer through this batch file is mandatory.
    It may simply not start by executing directly *designer.exe* since it requires the proper setting
    of environment variables.

Design of the UI
----------------

A UI is a window composed of *widgets*.
Each widget has properties that can be set in the code and modified by the user to interact with the
running application.
Widgets are used as:

- containers (to organize the disposition of children widgets);
- buttons (push buttons, radio buttons, checkboxes, ...);
- inputs and outputs (strings, numbers, sliders, ...);
- interactive lists, tables and graphs;
- ...

When developing extensions using a user interface, the associated generator
creates a UI file having a .ui file extension to be opened and edited with Qt Designer.

See the `Qt Designer manual <http://doc.qt.io/qt-5/qtdesigner-manual.html>`_ for more information on
how to edit the UI file.

Promoting widgets
-----------------

The promotion of widgets is sometimes required to specialize a behavior of such a widget.
To do so, open the Qt Designer window *Promoted Widgets* from the widget to promote and set these values:

- Promoted class name: Python class name overloading the base class. For example: ``MyLineEdit``;
- Header file: file name containing the Python class, starting with a ``.`` and no extension. For example: ``.mylineedit``.

.. image:: PromotedWidgets.jpg

Click on the *Add* button to add this class to the list of promoted classes, then click on *Promote*.

Create the file ``mylineedit.py`` in the same folder where the .ui file is,
open that Python file and define the ``MyLineEdit`` class with all the required overloaded methods.

.. image:: MyLineEditPromotedClass.jpg

.. _sourcecodeexample_plugin_DemoPromotingWidgets_7e725328bf2b11e7afbc448a5b5d70c0:

Source code example:

#. Download the :download:`compressed file </Documentation/Zipped/DemoPromotingWidgets_7e725328bf2b11e7afbc448a5b5d70c0.zip>`;
#. Extract these files into a :ref:`plugin extension folder <filesLocationPluginExtension>`;
#. Start the application;
#. Open the top level menu *Demos* to see the menu item named *Demo: open the plugin DemoPromotingWidgets*;
#. By clicking on the menu item, an instance of the plugin will be created
   and his mainform will be displayed;
#. Bring the cursor over the LineEdit widget to see that the cursor changes to a pointing hand.

Using resources
---------------

Resources are different kinds of images to be used with a UI.
They can be used to put images on buttons, or to define cursors icons.
They are optional to the development of a UI.

Resources editing is done also in Qt Designer.

When developing extensions using a user interface, the associated generator
creates a resource file having a .qrc file extension to be opened and edited with Qt Designer.

See `Editing Resources with Qt Designer <http://doc.qt.io/qt-5/designer-resources.html>`_.

Updating Python files
---------------------

Once the modifications are saved in the .qrc and .ui files, the Python equivalent files
(those to be used by the application) must be generated.
This is done by executing batch files created by the extension generator
and contained in the same folder as the extension:

- *pyrcc.bat* (or any other .bat file starting by *pyrcc*). This file should be executed if a .qrc file
  is included in the design. This will generate a .py file having the name of the extension with the suffix *_rc*,
  like *DemoPlugin_rc.py*;
- *pyuic.bat*. This will generate a .py file having the name of the form prefixed by *ui_*, like *ui_mainform.py*.

To execute these files, start Dragonfly, open a command prompt from the menu *Tools/Start Command Prompt*,
set the current directory as the folder where the batch files are located, then run the batch files.

.. image:: ExecuteBatchFilesPyrccPyuic.jpg