1 files changed, 149 insertions, 0 deletions
diff --git a/sources/pyside6/doc/tutorials/basictutorial/dialog.rst b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst
new file mode 100644
index 000000000..b7712672b
--- /dev/null
+++ b/sources/pyside6/doc/tutorials/basictutorial/dialog.rst
@@ -0,0 +1,149 @@
+Creating a Dialog Application
+=============================
+
+This tutorial shows how to build a simple dialog with some
+basic widgets. The idea is to let users provide their name
+in a ``QLineEdit``, and the dialog greets them on click of a
+``QPushButton``.
+
+Let us just start with a simple stub that creates and shows
+a dialog. This stub is updated during the course of this
+tutorial, but you can use this stub as is if you need to:
+::
+
+    import sys
+    from PySide6.QtWidgets import QApplication, QDialog, QLineEdit, QPushButton
+
+    class Form(QDialog):
+
+        def __init__(self, parent=None):
+            super(Form, self).__init__(parent)
+            self.setWindowTitle("My Form")
+
+
+    if __name__ == '__main__':
+        # Create the Qt Application
+        app = QApplication(sys.argv)
+        # Create and show the form
+        form = Form()
+        form.show()
+        # Run the main Qt loop
+        sys.exit(app.exec())
+
+The imports aren't new to you, the same for the creation of the
+``QApplication`` and the execution of the Qt main loop.
+The only novelty here is the **class definition**.
+
+You can create any class that subclasses PySide6 widgets.
+In this case, we are subclassing ``QDialog`` to define a custom
+dialog, which we name as **Form**. We have also implemented the
+``init()`` method that calls the ``QDialog``'s init method with the
+parent widget, if any. Also, the new ``setWindowTitle()`` method
+just sets the title of the dialog window. In ``main()``, you can see
+that we are creating a *Form object* and showing it to the world.
+
+Create the Widgets
+------------------
+
+We are going to create two widgets: a ``QLineEdit`` where users can
+enter their name, and a ``QPushButton`` that prints the contents of
+the ``QLineEdit``.
+So, let's add the following code to the ``init()`` method of our Form:
+::
+
+    # Create widgets
+    self.edit = QLineEdit("Write my name here..")
+    self.button = QPushButton("Show Greetings")
+
+It's obvious from the code that both widgets will show the corresponding
+texts.
+
+Create a layout to organize the Widgets
+---------------------------------------
+
+Qt comes with layout-support that helps you organize the widgets
+in your application. In this case, let's use ``QVBoxLayout`` to lay out
+the widgets vertically. Add the following code to the ``init()`` method,
+after creating the widgets:
+::
+
+    # Create layout and add widgets
+    layout = QVBoxLayout(self)
+    layout.addWidget(self.edit)
+    layout.addWidget(self.button)
+
+So, we create the layout, add the widgets with ``addWidget()``.
+
+Create the function to greet and connect the Button
+---------------------------------------------------
+
+Finally, we just have to add a function to our custom **Form**
+and *connect* our button to it. Our function will be a part of
+the Form, so you have to add it after the ``init()`` function:
+::
+
+    # Greets the user
+    def greetings(self):
+        print(f"Hello {self.edit.text()}")
+
+Our function just prints the contents of the ``QLineEdit`` to the
+python console. We have access to the text by means of the
+``QLineEdit.text()`` method.
+
+Now that we have everything, we just need to *connect* the
+``QPushButton`` to the ``Form.greetings()`` method. To do so, add the
+following line to the ``init()`` method:
+::
+
+    # Add button signal to greetings slot
+    self.button.clicked.connect(self.greetings)
+
+Once executed, you can enter your name in the ``QLineEdit`` and watch
+the console for greetings.
+
+Complete code
+-------------
+
+Here is the complete code for this tutorial:
+
+.. code-block:: python
+
+    import sys
+    from PySide6.QtWidgets import (QLineEdit, QPushButton, QApplication,
+        QVBoxLayout, QDialog)
+
+    class Form(QDialog):
+
+        def __init__(self, parent=None):
+            super(Form, self).__init__(parent)
+            # Create widgets
+            self.edit = QLineEdit("Write my name here")
+            self.button = QPushButton("Show Greetings")
+            # Create layout and add widgets
+            layout = QVBoxLayout()
+            layout.addWidget(self.edit)
+            layout.addWidget(self.button)
+            # Set dialog layout
+            self.setLayout(layout)
+            # Add button signal to greetings slot
+            self.button.clicked.connect(self.greetings)
+
+        # Greets the user
+        def greetings(self):
+            print(f"Hello {self.edit.text()}")
+
+    if __name__ == '__main__':
+        # Create the Qt Application
+        app = QApplication(sys.argv)
+        # Create and show the form
+        form = Form()
+        form.show()
+        # Run the main Qt loop
+        sys.exit(app.exec())
+
+
+When you execute the code, and write down your name,
+the button will display messages on the terminal:
+
+.. image:: dialog.png
+   :alt: Simple Dialog Example