hamyar_paygah.utils.qt_utils
============================

.. py:module:: hamyar_paygah.utils.qt_utils

.. autoapi-nested-parse::

   Utility functions related to Qt UI.



Attributes
----------

.. autoapisummary::

   hamyar_paygah.utils.qt_utils.NOT_REGISTERED_PERSIAN_TEXT
   hamyar_paygah.utils.qt_utils.F


Functions
---------

.. autoapisummary::

   hamyar_paygah.utils.qt_utils.set_checkbox
   hamyar_paygah.utils.qt_utils.set_textfield
   hamyar_paygah.utils.qt_utils.set_enum_textfield
   hamyar_paygah.utils.qt_utils.typed_async_slot
   hamyar_paygah.utils.qt_utils.show_error_dialog


Module Contents
---------------

.. py:data:: NOT_REGISTERED_PERSIAN_TEXT
   :type:  str
   :value: 'ثبت نشده'


   Text to show when an information is not yet registered by EMS

.. py:function:: set_checkbox(checkbox, *, value)

   Set a checkbox state and enabled status.

   The checkbox is checked and enabled if ``value`` is ``True``.
   If ``value`` is ``False``, the checkbox is unchecked and disabled.

   :param checkbox: The QCheckBox instance to modify.
   :param value: Determines both the checked state and whether the checkbox is enabled.


.. py:function:: set_textfield(textfield, value)

   Set a text field with a value or disable it if empty/zero.

   This function updates the text of a QLineEdit or QPlainTextEdit widget.
   - If `value` is None or zero (for integers), the field is disabled and
   filled with a placeholder text (`NOT_REGISTERED_PERSIAN_TEXT`).
   - Otherwise, the field is updated with `str(value)` and will be enabled.

   :param textfield: A QLineEdit or QPlainTextEdit widget to update.
   :param value: The value to set. Can be int, str, timedelta, time, jdatetime.date,
                 or None. Integers equal to zero are treated as empty.

   :returns: None

   .. rubric:: Notes

   - This function is designed to handle various types safely.
   - `NOT_REGISTERED_PERSIAN_TEXT` is used as a placeholder for missing values.


.. py:function:: set_enum_textfield(textfield, enum_value)

   Set a QLineEdit with the Persian label of a domain enum.

   If `enum_value` is None, the text field is populated with
   `NOT_REGISTERED_PERSIAN_TEXT` and disabled.

   If a valid enum value is provided, its `persian_label`
   attribute is displayed and the field is enabled.

   :param textfield: The QLineEdit widget to update.
   :param enum_value: A supported domain enum instance or None.

   :returns: None


.. py:data:: F

.. py:function:: typed_async_slot(*args, **kwargs)

   Typed wrapper around qasync.asyncSlot.

   Provides proper type hints for the untyped ``asyncSlot`` decorator
   from the ``qasync`` module. This allows static type checkers such
   as mypy or Pyright to correctly infer the signature of decorated
   async functions.

   :param \*args: Positional arguments forwarded to ``asyncSlot``.
   :param \*\*kwargs: Keyword arguments forwarded to ``asyncSlot``.

   :returns: A decorator that preserves the type signature of the async
             function it decorates.


.. py:function:: show_error_dialog(parent, title, message)

   Display an error dialog with a critical icon.

   This function creates a modal error dialog attached to the given parent
   widget. The dialog displays a title and a message to inform the user of
   an error. Execution is blocked until the user closes the dialog.

   :param parent: The parent widget for the dialog. The dialog will
                  be centered on this widget.
   :type parent: PySide6.QtWidgets.QWidget
   :param title: The title displayed in the window's title bar.
   :type title: str
   :param message: The error message to display in the dialog body.
   :type message: str

   :returns: None

   .. rubric:: Notes

   - This function uses a modal dialog; it will block interaction with
     other windows until closed.
   - For non-blocking dialogs, consider using `dialog.show()` instead
     of `dialog.exec()`.