Как получить подтверждение пользователя
=======================================

Библиотека ``ram.widgets`` предоставляет ряд функций-примитивов для отображения диалоговых окон.
Этот документ описывает использование функции ``AskViaButtons``, используемой для получения подтверждений пользователя.

При использовании псевдографического интерфейса на основе ``SnackUI``
пользователю выводится диалоговое окно с пояснительным текстом и две кнопки для выбора действия.

Если вопрос пользователю предполагает три и более вариантов ответа, следует воспользоваться функцией ``SingleChoice``.

.. py:function:: ram.process.AskViaButtons(header, text, yesButtonText=None, noButtonText=None)
    :noindex:

    Получение подтверждения пользователя. В случае согласия пользователя возвращает -- True, в ином случае False.

    :param header:              Строка, Заголовок диалогового окна.

    :param text:                Строка, Пояснительный текст вопроса.

    :param yesButtonText:       Строка, Надпись на кнопке согласия (кнопке по умолчанию).

    :param noButtonText:        Строка, Надпись на кнопке отказа (кнопка не по умолчанию).


Рекомендации по оформлению подтверждений
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Последним предложением пояснительного текста для пользователю следует поставить развернутый вопрос.
Если вопрос к пользователю связан с подтверждением изменения состояния или подтверждением данных введенных пользователем,
следует использовать форму вопроса предполагающую возможные ответы -- "Да" или "Нет".
В этом случае значения для параметров ``yesButtonText`` и ``noButtonText`` должны быть опущены,
будут использованы значение по умолчанию `"Yes"` и `"No"`:

.. sourcecode:: py

    if ram.widgets.AskViaButtons(
        "Select time zone",
        "Time zone will be set to `%s`\n\n"
        "Is that correct?" % timezone,
    ):
        ...

.. sourcecode:: py

    if ram.widgets.AskViaButtons(
        "Enable the feature",
        "Would you like to enable the feature?",
    ):
        ...

При форматировании кода вызова функции ``AskViaButtons`` рекомендуется имитировать диалоговое окно отображаемое пользователю.
Для этого задание аргументов вызова ``AskViaButtons`` вкладывается между строками с обрамляющими вызов скобками и 
дополнительно выделяются стандартным отступом.

Первая строка задает заголовок, последующие строки задают пояснительный текст.
При этом можно воспользоваться свойством интерпретатора конкатенировать строки разделенные пробелами и переносами строк.
На последней строке перечисляются варианты выбора пользователя:

.. sourcecode:: py

    if ram.widgets.AskViaButtons(
        "Set state",
        "Configurable object could be set to `running` and `stopped` states."
        "Depending on state object is able to process data or not.\n\n"
        "Whice state would you like to set for object?",
        "Running", "Stopped",
    ):
        ...

Если вопрос к пользователю связан с выполнением действия
следует использовать форму вопроса предполагающую возможные ответы -- "<Выполнить действие>" и "Отменить".
В этом случае значение параметра ``yesButtonText`` должно соотвествовать названию действия,
а значение параметра ``noButtonText`` должно быть опущено, будет использовано значение по умолчанию `"Cancel"`:

.. sourcecode:: py

    if ram.widgets.AskViaButtons(
        "Delete item from list?",
        "Would you like to delete item from list?",
        "Delete",
    ):
        ...

Помимо пояснительного текста для пользователя иногда бывает необходимо ясно подсказать пользователю,
что его выбор может быть изменен в другой момент или выбранное решение не критично по отношению к той или иной функциональности.
В этом случае следует перед завершающим вопросом добавить строку с подсказкой начинающейся со слова `"HINT:"`.

Если же необходимо подчеркнуть, что выбор пользователя несет критические и/или необратимые последствия,
то следует перед завершающим вопросом добавить строку с предупреждение начинающимся со слова `"WARNING:"`:

В рамках одного пояснительно текста может быть использовано несколько подсказок или предупреждений.
Отдельные подсказки и предупреждения следует выделять обрамляя их пустыми строками.

.. sourcecode:: py

    if ram.widgets.AskViaButtons(
        "Download bases?",
        "In order to provide security actual bases should be used.\n\n"
        "HINT: It's possible to download bases later.\n\n"
        "Do you want to download bases now?",
        "Download",
    ):
        ...

Если конфигурация установленная пользователем некорректна или неоптимальна следует предупредить пользователя об этом.
В этом случае в качестве значения параметра ``yesButtonText`` следует использовать -- `"Go back"`,
а в качестве значения параметра ``noButtonText`` -- `"Continue"`/`"Save and continue"`:

.. sourcecode:: py

    if ram.widgets.AskViaButtons(
        "Incorrect configution",
        "Database applications require fast disk throughput and low disk latency."
        "In order to meet these requirements databases should be placed onto separate disk drive.\n\n",
        "WARNING: It's strongly recommended to use separate disk drive for database!\n\n"
        "WARNING: It's not possible to change this setting later!\n\n"
        "Would you like to go back and select separate disk drive for database?",
        "Go back", "Continue",
    ):
        ...

Помимо вышеперечисленных рекомендаций по оформлению подтверждений пользователя,
следует учитывать общие рекомендации по использованию двойных кавычек для текста текста видимого пользователю.