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

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

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

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

ram.process.AskViaButtons(header, text, yesButtonText=None, noButtonText=None)

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

Parameters:

• header – Строка, Заголовок диалогового окна.
• text – Строка, Пояснительный текст вопроса.
• yesButtonText – Строка, Надпись на кнопке согласия (кнопке по умолчанию).
• noButtonText – Строка, Надпись на кнопке отказа (кнопка не по умолчанию).

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

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

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

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

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

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

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”:

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

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

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

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

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”:

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",
):
    ...

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