Qt Designer: Document Qt for Python usage

Split up the chapters and add one about Python.

Change-Id: I58c5fe4ceeca5978c0dfbe73ab726a18080d21ea
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit 150c2fbad94ae99833da27be7ea9fa13412eeba7)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 94 insertions, 7 deletions

diff --git a/src/designer/src/designer/doc/src/designer-manual.qdoc b/src/designer/src/designer/doc/src/designer-manual.qdoc
index 5c6fd208a..b3f016f98 100644
--- a/src/designer/src/designer/doc/src/designer-manual.qdoc
+++ b/src/designer/src/designer/doc/src/designer-manual.qdoc
@@ -75,7 +75,8 @@
         \li  \l{Creating Main Windows in Qt Designer}
         \li  \l{Editing Resources with Qt Designer}
         \li  \l{Using Stylesheets with Qt Designer}
-        \li  \l{Using a Designer UI File in Your Application}
+        \li  \l{Using a Designer UI File in Your C++ Application}
+        \li  \l{Using a Designer UI File in Your Qt for Python Application}
     \li Advanced Use
     \list
         \li  \l{Customizing Qt Designer Forms}
@@ -1695,7 +1696,7 @@ pixmap property in the property editor.
 /*!
     \page designer-stylesheet.html
     \previouspage Editing Resources with Qt Designer
-    \nextpage Using a Designer UI File in Your Application
+    \nextpage Using a Designer UI File in Your C++ Application
 
     \title Using Stylesheets with Qt Designer
 
@@ -1719,11 +1720,11 @@ pixmap property in the property editor.
 
 
 /*!
-    \page designer-using-a-ui-file.html
+    \page designer-using-a-ui-file-cpp.html
     \previouspage Using Stylesheets with Qt Designer
-    \nextpage Using Custom Widgets with Qt Designer
+    \nextpage Using a Designer UI File in Your Qt for Python Application
 
-    \title Using a Designer UI File in Your Application
+    \title Using a Designer UI File in Your C++ Application
 
     Qt Designer UI files represent the widget tree of the form in XML format. The
     forms can be processed:
@@ -2111,10 +2112,96 @@ pixmap property in the property editor.
     write code themselves.
 */
 
+/*!
+    \page designer-using-a-ui-file-python.html
+    \previouspage Using a Designer UI File in Your C++ Application
+    \nextpage Using Custom Widgets with Qt Designer
+
+    \title Using a Designer UI File in Your Qt for Python Application
+
+    \section1 Converting the Form to Python Code
+
+    To demonstrate, we use the Qt Widgets animation easing example.
+
+    The application consists of one source file, \c easing.py, a UI
+    file \c form.ui, a resource file \c  easing.qrc and the project
+    file, \c{easing.pyproject} file in the YAML format:
+
+    \code
+    {
+        "files": ["easing.qrc", "ui_form.py", "easing.py", "easing_rc.py",
+                  "form.ui"]
+    }
+    \endcode
+
+    The UI file is converted to Python code building the form using the
+    \l{User Interface Compiler (uic)}:
+
+    \code
+    uic -g python form.ui > ui_form.py
+    \endcode
+
+    Since the top level widget is named \c Form, this results in a Python
+    class named \c Ui_Form being generated. It provides a function
+    \c setupUi(), taking the widget as parameter, which is called to
+    create the UI elements:
+
+    \code
+    from ui_form import Ui_Form
+    ...
+    class Window(QtWidgets.QWidget):
+        def __init__(self, parent=None):
+            super(Window, self).__init__(parent)
+
+            self.m_ui = Ui_Form()
+            self.m_ui.setupUi(self)
+    \endcode
+
+    Later on, the widgets can be accessed via the \c Ui_Form class:
+
+    \code
+    self.m_ui.graphicsView.setScene(self.m_scene)
+    \endcode
+
+    Besides \c setupUi(), \c Ui_Form provides another method
+    \c retranslateUi(), which can be called in reaction to
+    a QEvent of type QEvent.LanguageChange, which indicates
+    a change in the application language.
+
+    \section2 The UiTools Approach
+
+    The QUiLoader class provides a form loader object to construct the user
+    interface at runtime. This user interface can be retrieved from any
+    QIODevice, e.g., a QFile object. The QUiLoader::load() function
+    constructs the form widget using the user interface description
+    contained in the file.
+
+    It is demonstrated by the uiloader example:
+
+    \code
+    from PySide2.QtUiTools import QUiLoader
+
+    if __name__ == '__main__':
+        # Some code to obtain the form file name, ui_file_name
+        app = QApplication(sys.argv)
+        ui_file = QFile(ui_file_name)
+        if not ui_file.open(QIODevice.ReadOnly):
+            print("Cannot open {}: {}".format(ui_file_name, ui_file.errorString()))
+            sys.exit(-1)
+        loader = QUiLoader()
+        widget = loader.load(ui_file, None)
+        ui_file.close()
+        if not widget:
+            print(loader.errorString())
+            sys.exit(-1)
+        widget.show()
+        sys.exit(app.exec_())
+    \endcode
+*/
 
 /*!
     \page designer-customizing-forms.html
-    \previouspage Using Stylesheets with Qt Designer
+    \previouspage Using a Designer UI File in Your Qt for Python Application
     \nextpage Using Custom Widgets with Qt Designer
 
     \title Customizing Qt Designer Forms
@@ -2126,7 +2213,7 @@ pixmap property in the property editor.
     default layout, are stored along with the form's components. These settings
     are used when the \l uic generates the form's C++ code. For more
     information on how to use forms in your application, see the
-    \l{Using a Designer UI File in Your Application} section.
+    \l{Using a Designer UI File in Your C++ Application} section.
 
 
     \section1 Modifying the Form Settings