Creating Modal and Modeless Dialogs
=====================================

Modal Dialogs
-------------

- The user cannot interact with the main window until the dialog is closed.
  
- Typically used for critical information or decisions that require the user's focus.

Modeless Dialogs
----------------

- Even if the dialog is open, the user can interact with the main window simultaneously.



.. code-block:: python
    :caption: scripts/PYQT2/03_toggle_screens/main.py
    :linenos:

    # -*- coding: utf-8 -*-

    import sys
    from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton, QDialog, QVBoxLayout, QLabel, QWidget

    class MainWindow(QMainWindow):
        def __init__(self):
            super(MainWindow, self).__init__()

            self.init_ui()

        def init_ui(self):
            self.button_modal = QPushButton("Open Modal Dialog", self)
            self.button_modal.clicked.connect(self.show_modal)
            self.button_modal.move(10, 10)
            self.button_modal.resize(150, 40)

            self.button_modeless = QPushButton("Open Modeless Dialog", self)
            self.button_modeless.clicked.connect(self.show_modeless)
            self.button_modeless.move(10, 60)
            self.button_modeless.resize(150, 40)

        def show_modal(self):
            self.modal_dialog = QDialog(self)
            self.modal_dialog.setWindowTitle("Modal Dialog")

            layout = QVBoxLayout()
            label = QLabel("This is a Modal Dialog. You can't interact with the main window until you close this.")
            layout.addWidget(label)

            self.modal_dialog.setLayout(layout)
            self.modal_dialog.exec_()

        def show_modeless(self):
            self.modeless_dialog = QDialog(self)
            self.modeless_dialog.setWindowTitle("Modeless Dialog")

            layout = QVBoxLayout()
            label = QLabel("This is a Modeless Dialog. You can still interact with the main window.")
            layout.addWidget(label)

            self.modeless_dialog.setLayout(layout)
            self.modeless_dialog.show()

    if __name__ == '__main__':
        app = QApplication(sys.argv)
        mainWin = MainWindow()
        mainWin.show()
        sys.exit(app.exec_())


Difference between exec_() and show()
------------------------------------

``exec_()`` and ``show()`` are two main methods in PyQt used for displaying dialogs or widgets. Their primary differences are as follows:

Block vs Non-Block
^^^^^^^^^^^^^^^^^^

- ``exec_()``: 
  - This method is ``blocking``.
  - This means when the ``exec_()`` method is called, the execution of the code pauses until that dialog is closed.
  - It's mainly used in modal dialogs.
  - It restricts the user from interacting with other parts of the application until they respond to the dialog.
  
- ``show()``: 
  - This method is ``non-blocking``.
  - When the ``show()`` method is called, the dialog is displayed and the code continues to run.
  - It's mainly used in modeless dialogs.
  - It allows the user to interact with other parts of the application alongside the dialog.

Return Value
^^^^^^^^^^^^

- ``exec_()``: 
  - Has a return value.
  - Typically, it returns one of the values ``QDialog.Accepted`` or ``QDialog.Rejected``.
  - This can indicate whether the user clicked the '``OK``' or '``Cancel``' button in the dialog.
  
- ``show()``: 
  - Does not have a return value.

Use Cases
^^^^^^^^^

- ``exec_()``: 
  - Mainly used when waiting for a user's response is necessary, like when needing to wait for user choices in a popup that asks for information input.

- ``show()``: 
  - Mainly used when just providing information or when not necessarily awaiting a user's decision.

In conclusion, the method to use depends on the purpose of the dialog and the desired interaction with the user.