EasyDialogs — Базовые диалоговые окна Macintosh

Модуль EasyDialogs содержит несколько простых диалоговых окон для Macintosh. Диалоговые окна запускаются в отдельном приложении, которое отображается в доке и должно быть щелкнуто для отображения диалоговых окон. Все процедуры принимают необязательный параметр идентификатора ресурса id, с помощью которого можно переопределить используемый ресурс DLOG для диалогового окна, при условии, что элементы диалогового окна соответствуют (по типу и номеру элемента) элементам в стандартном ресурсе DLOG. Подробности см. в исходном коде.

Модуль EasyDialogs определяет следующие функции:

EasyDialogs.Message(str[, id[, ok]])

Отображает модальное диалоговое окно с текстом сообщения str, длина которого должна быть не более 255 символов. Текст кнопки по умолчанию — «ОК», но устанавливается в строковый аргумент ok, если он предоставлен. Управление возвращается, когда пользователь нажимает кнопку «ОК».

EasyDialogs.AskString(prompt[, default[, id[, ok[, cancel]]]])

Запрашивает у пользователя строковое значение через модальное диалоговое окно. prompt — сообщение запроса, а необязательный default предоставляет начальное значение для строки (в противном случае используется ""). Текст кнопок «ОК» и «Отмена» можно изменить с помощью аргументов ok и cancel. Все строки могут иметь длину не более 255 байтов. AskString() возвращает введённую строку или None в случае отмены пользователем.

EasyDialogs.AskPassword(prompt[, default[, id[, ok[, cancel]]]])

Запрашивает у пользователя строковое значение через модальное диалоговое окно. Аналогично AskString(), но текст отображается в виде точек. Аргументы имеют то же значение, что и для AskString().

EasyDialogs.AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])

Отображает диалоговое окно с запросом question и тремя кнопками: «Да», «Нет» и «Отмена». Возвращает 1 для «Да», 0 для «Нет» и -1 для «Отмена». Значение default (или 0 если default не указан) возвращается при нажатии клавиши RETURN. Текст кнопок можно изменить с помощью аргументов yes, no и cancel; чтобы предотвратить отображение кнопки, укажите "" для соответствующего аргумента.

EasyDialogs.ProgressBar([title[, maxval[, label[, id]]]])

Отображает диалоговое окно с полосой прогресса в безмодальном режиме. Это конструктор класса ProgressBar, описанного ниже. title — отображаемый текст (по умолчанию «Работаем…»), maxval — значение, при достижении которого процесс завершён (по умолчанию 0, что указывает на то, что предстоит выполнить неопределённое количество работы), а label — текст, отображаемый над самой полосой прогресса.

EasyDialogs.GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])

Отображает диалоговое окно, которое помогает пользователю составить список аргументов командной строки. Возвращает список в формате sys.argv, подходящем для передачи в качестве аргумента функции getopt.getopt(). addoldfile, addnewfile и addfolder — булевы аргументы. При ненулевом значении они позволяют пользователю вставить в командную строку пути к существующему файлу, (возможно) ещё не существующему файлу и папке соответственно. (Примечание: Аргументы опций должны предшествовать файлам и папкам в командной строке, чтобы быть распознанными функцией getopt.getopt().) Аргументы, содержащие пробелы, можно указать, заключив их в одинарные или двойные кавычки. Исключение SystemExit генерируется, если пользователь нажмёт кнопку «Отмена».

optionlist — список, определяющий выпадающее меню разрешённых опций. Его элементы могут иметь одну из двух форм: optstr или (optstr, descr) . Если присутствует descr, это короткое описательное сообщение, которое отображается в диалоговом окне во время выбора этой опции в выпадающем меню. Соответствие между optstr и аргументами командной строки:

Формат optstr	Формат командной строки
x	-x (короткая опция)
x: или x=	-x (короткая опция со значением)
xyz	--xyz (длинная опция)
xyz: или xyz=	--xyz (длинная опция со значением)

commandlist — список элементов вида cmdstr или (cmdstr, descr), где descr, как и выше. cmdstr отобразятся в выпадающем меню. При выборе текст cmdstr будет добавлен в командную строку как есть, за исключением того, что заключительные ':' или '=' (если присутствуют) будут удалены.

Добавлена в версии 2.0.

EasyDialogs.AskFileForOpen([message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )

Отображает диалоговое окно, запрашивающее у пользователя файл для открытия, и возвращает выбранный файл или None в случае отмены. message — сообщение, которое должно отображаться, typeList — список допустимых типов файлов (4 символа), defaultLocation — путь к папке, FSSpec или FSRef папки, которая будет отображена первоначально, location — (x, y) положение на экране, где отображается диалоговое окно, actionButtonLabel — строка, которая отображается вместо «Открыть» на кнопке «ОК», cancelButtonLabel — строка, которая отображается вместо «Отмена» на кнопке отмены, wanted — тип требуемого значения: str, unicode, FSSpec, FSRef и их подтипы допустимы.

Для описания других аргументов см. документацию Apple по сервисам навигации и исходный код модуля EasyDialogs.

EasyDialogs.AskFileForSave([message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )

Отображает диалоговое окно, запрашивающее у пользователя файл для сохранения, и возвращает выбранный файл или None в случае отмены. savedFileName — значение по умолчанию для имени файла для сохранения (значение возврата). См. AskFileForOpen() для описания других аргументов.

EasyDialogs.AskFolder([message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )

Отображает диалоговое окно, запрашивающее у пользователя папку, и возвращает выбранную папку или None в случае отмены. См. AskFileForOpen() для описания аргументов.

1. Объекты ProgressBar

ProgressBar объекты предоставляют поддержку безмодальных диалоговых окон с полосой прогресса. Поддерживаются как детерминированные (типа «термометр»), так и недетерминированные (типа «волчок») полосы прогресса. Полоса будет детерминированной, если её максимальное значение больше нуля; в противном случае она будет недетерминированной.

Диалоговое окно отображается сразу после создания. Если пользователь нажмёт кнопку «Отмена» в диалоговом окне, или если напечатаны Cmd-. или ESC, диалоговое окно скрывается, и генерируется исключение KeyboardInterrupt (но обратите внимание, что этот ответ не произойдёт до следующего обновления полосы прогресса, обычно с помощью вызова inc() или set()). В противном случае полоса остаётся видимой до тех пор, пока объект ProgressBar не будет удалён.

ProgressBar объекты обладают следующими атрибутами и методами:

ProgressBar.curval

Текущее значение (целое или длинное целое) полосы прогресса. Стандартные методы доступа принудительно приводят curval к значению между 0 и maxval. Этот атрибут не следует изменять напрямую.

ProgressBar.maxval

Максимальное значение (целое или длинное целое) полосы прогресса; полоса прогресса (в стиле термометра) полностью заполняется, когда curval равно maxval. Если maxval равно 0, полоса будет неопределённой (в стиле «барбершопа»). Этот атрибут не следует изменять напрямую.

ProgressBar.title([newstr])

Устанавливает текст в строке заголовка диалогового окна прогресса на newstr.

ProgressBar.label([newstr])

Устанавливает текст в поле прогресса диалогового окна прогресса на newstr.

ProgressBar.set(value[, max])

Устанавливает curval полосы прогресса на value, а также maxval на max, если последний задан. value сначала приводится к значению от 0 до maxval. Полоса термометра обновляется для отражения изменений, включая изменение от неопределённого к определённому и наоборот.

ProgressBar.inc([n])

Увеличивает curval полосы прогресса на n или на 1, если n не задано. (Обратите внимание, что n может быть отрицательным, в этом случае происходит уменьшение.) Полоса прогресса обновляется для отражения изменения. Если полоса неопределённа, это вызывает один «оборот» «барбершопной» полосы. Результирующее curval приводится к значению между 0 и maxval, если увеличение приводит к тому, что оно выходит за этот диапазон.