curses — Обработка терминала для дисплеев с ячейками символов

Модуль curses предоставляет интерфейс к библиотеке curses, фактическому стандарту для переносимой обработки продвинутых терминалов.

Хотя curses наиболее широко используется в среде Unix, версии доступны для Windows, DOS и, возможно, для других систем. Этот модуль расширения разработан для соответствия API ncurses, открытой библиотеки curses, размещенной в Linux и BSD-вариантах Unix.

import locale
locale.setlocale(locale.LC_ALL, '')
code = locale.getpreferredencoding()

16.10.1. Функции

Модуль curses определяет следующее исключение:

exception curses.error

Исключение, возбуждаемое, когда функция библиотеки curses возвращает ошибку.

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

curses.baudrate()

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

curses.beep()

Издаёт короткий звуковой сигнал.

curses.can_change_color()

Возвращает True или False, в зависимости от того, может ли программист изменить цвета, отображаемые терминалом.

curses.cbreak()

Переход в режим cbreak. В режиме cbreak (иногда называемом режимом «редко») обычная буферизация строки tty отключается, и символы доступны для чтения по одному. Однако, в отличие от режима raw, специальные символы (прерывание, выход, приостановка и управление потоком) сохраняют своё влияние на драйвер tty и программу вызова. Если сначала вызвать raw(), а затем cbreak(), терминал переходит в режим cbreak.

curses.color_content(color_number)

Возвращает интенсивность красной, зеленой и синей (RGB) составляющих в цвете color_number, который должен быть между 0 и COLORS. Возвращает кортеж из 3 элементов, содержащий значения R,G,B для заданного цвета, которые будут между 0 (нет компоненты) и 1000 (максимальное значение компоненты).

curses.color_pair(color_number)

Возвращает значение атрибута для отображения текста в указанном цвете. Это значение атрибута может быть комбинировано с A_STANDOUT, A_REVERSE, и другими A_* атрибутами. pair_number() является аналогом этой функции.

curses.curs_set(visibility)

Устанавливает состояние курсора. visibility может быть 0, 1, или 2, для невидимого, нормального или очень видимого. Если терминал поддерживает запрашиваемое состояние видимости, возвращает предыдущее состояние курсора; в противном случае возбуждает исключение. На многих терминалах режим «видимый» — это курсор с подчёркиванием, а режим «очень видимый» — это курсор в виде блока.

curses.def_prog_mode()

Сохраняет текущий режим терминала как режим «программы», режим, когда работающая программа использует curses. (Его аналогом является режим «оболочки», когда программа не использует curses.) Последующие вызовы reset_prog_mode() восстанавливают этот режим.

curses.def_shell_mode()

Сохраняет текущий режим терминала как режим «оболочки», режим, когда работающая программа не использует curses. (Его аналогом является режим «программы», когда программа использует возможности curses.) Последующие вызовы reset_shell_mode() восстанавливают этот режим.

curses.delay_output(ms)

Вставляет паузу в ms миллисекунд в выходных данных.

curses.doupdate()

Обновляет физический экран. Библиотека curses поддерживает две структуры данных: одну, представляющую текущее содержимое физического экрана, и виртуальный экран, представляющий желаемое следующее состояние. Вызов doupdate() обновляет физический экран для соответствия виртуальному экрану.

Виртуальный экран можно обновить с помощью вызова noutrefresh() после выполнения операций записи, таких как addstr(), в окне. Обычный вызов refresh() просто noutrefresh() за которым следует doupdate(); если вам нужно обновить несколько окон, вы можете ускорить производительность и, возможно, уменьшить мерцание экрана, вызвав вызовы noutrefresh() для всех окон, за которым следует один вызов doupdate().

curses.echo()

Перейти в режим отображения ввода. В режиме отображения ввода каждый символ ввода отображается на экране по мере его ввода.

curses.endwin()

Деинициализирует библиотеку и возвращает терминал в нормальное состояние.

curses.erasechar()

Возвращает текущий символ стирания пользователя в виде объекта bytes из одного байта. В операционных системах Unix это свойство управляющего tty программы curses, и оно не устанавливается самой библиотекой curses.

curses.filter()

Функция filter(), если она используется, должна вызываться перед initscr(). В результате, во время этих вызовов LINES устанавливается в 1; возможности clear, cup, cud, cud1, cuu1, cuu, vpa отключаются; и строка home устанавливается в значение cr.

curses.flash()

Мгновенно мигнуть экраном. То есть, поменять его на обратный видеорежим и затем вернуть его обратно в короткий промежуток времени. Некоторые предпочитают такое «видимое звонок» вместо звукового сигнала внимания, который генерируется beep().

curses.flushinp()

Очистить все буферы ввода. Это отбрасывает все предварительно введённые символы, которые были введены пользователем, но ещё не обработаны программой.

curses.getmouse()

После того, как getch() возвращает KEY_MOUSE для сигнализации о событии мыши, этот метод должен быть вызван для получения очереди события мыши, представленного в виде 5-кортежа (id, x, y, z, bstate). id — значение идентификатора, используемое для различения нескольких устройств, а x, y, z — координаты события. (z в настоящее время не используется.) bstate — целое значение, биты которого будут установлены для указания типа события и будет являться побитовым ИЛИ одного или нескольких из следующих констант, где n — номер кнопки от 1 до 4: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

curses.getsyx()

Возвращает текущие координаты виртуального курсора экрана в виде кортежа (y, x). Если leaveok в настоящее время True, то возвращает (-1, -1).

curses.getwin(file)

Считывает данные, связанные с окном, сохраненные в файле после предыдущего вызова putwin(). Затем процедура создает и инициализирует новое окно, возвращая новый объект окна.

curses.has_colors()

Возвращает True если терминал может отображать цвета; в противном случае возвращает False.

curses.has_ic()

Возвращает True если терминал имеет возможности вставки и удаления символов. Эта функция включена только по историческим причинам, так как все современные эмуляторы терминалов имеют такие возможности.

curses.has_il()

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

curses.has_key(ch)

Принимает значение клавиши ch и возвращает True если текущий тип терминала распознает клавишу с этим значением.

curses.halfdelay(tenths)

Используется для режима половинной задержки, который похож на режим cbreak тем, что набранные пользователем символы немедленно становятся доступны программе. Однако после блокирования на tenths десятых долей секунды, генерируется исключение, если ничего не было введено. Значение tenths должно быть числом от 1 до 255. Используйте nocbreak() для выхода из режима половинной задержки.

curses.init_color(color_number, r, g, b)

Изменяет определение цвета, принимая номер изменяемого цвета и три значения RGB (для количества компонентов красного, зеленого и синего). Значение color_number должно быть от 0 до COLORS. Каждое из значений r, g, b должно быть значением от 0 до 1000. Когда используется init_color(), все вхождения этого цвета на экране немедленно изменяются на новое определение. Эта функция является no-op на большинстве терминалов; она активна только если can_change_color() возвращает True.

curses.init_pair(pair_number, fg, bg)

Изменяет определение пары цветов. Принимает три аргумента: номер изменяемой пары цветов, номер цвета переднего плана и номер цвета фона. Значение pair_number должно быть от 1 до COLOR_PAIRS - 1 (пара цвета 0 подключена к белому на черном и не может быть изменена). Значения аргументов fg и bg должны быть от 0 до COLORS. Если пара цветов была ранее инициализирована, экран обновляется, и все вхождения этой пары цветов изменяются на новое определение.

curses.initscr()

Инициализирует библиотеку. Возвращает объект окно, представляющий весь экран.

Примечание

Если произошла ошибка при открытии терминала, подлежащая библиотека curses может привести к завершению интерпретатора.

curses.is_term_resized(nlines, ncols)

Возвращает True если resize_term() изменит структуру окна; False в противном случае.

curses.isendwin()

Возвращает True если был вызван endwin() (то есть, библиотека curses была деинициализирована).

curses.keyname(k)

Возвращает имя клавиши с номером k в виде объекта bytes. Имя клавиши, генерирующей печатаемый символ ASCII, — это символ клавиши. Имя комбинации клавиш управления — это объект bytes из двух байтов, состоящий из знака «^» (b'^') и соответствующего печатаемого символа ASCII. Имя комбинации клавиш Alt (128–255) — это объект bytes, состоящий из префикса b'M-' и имени соответствующего символа ASCII.

curses.killchar()

Возвращает текущий символ удаления строки пользователя в виде объекта bytes длиной один байт. В системах Unix это свойство управляющего tty программы curses и не устанавливается самой библиотекой curses.

curses.longname()

Возвращает объект bytes, содержащий поле terminfo «длинного имени», описывающее текущий терминал. Максимальная длина подробного описания — 128 символов. Он определяется только после вызова initscr().

curses.meta(flag)

Если flag — True, разрешить ввод 8-битных символов. Если flag — False, разрешить только 7-битные символы.

curses.mouseinterval(interval)

Устанавливает максимальное время в миллисекундах, которое может пройти между нажатием и отпусканием событий, чтобы они распознавались как щелчок, и возвращает предыдущее значение интервала. Значение по умолчанию составляет 200 мс, или одна пятая секунды.

curses.mousemask(mousemask)

Устанавливает события мыши, которые должны отслеживаться, и возвращает кортеж (availmask, oldmask). availmask указывает, какие из указанных событий мыши могут быть отслеживаются; при полной неудаче возвращает 0. oldmask — предыдущее значение маски событий мыши данного окна. Если эта функция никогда не вызывается, события мыши никогда не отслеживаются.

curses.napms(ms)

Подождать ms миллисекунд.

curses.newpad(nlines, ncols)

Создает и возвращает указатель на новую структуру данных pad с заданным количеством строк и столбцов. Возвращает pad как объект окна.

Pad похож на окно, за исключением того, что он не ограничен размером экрана и не обязательно связан с какой-либо конкретной частью экрана. Pads могут быть использованы, когда требуется большое окно, и только часть окна будет отображаться на экране в одно время. Автоматические обновления pad (например, при прокрутке или эхо-отображении ввода) не происходят. Методы refresh() и noutrefresh() pad требуют 6 аргументов для указания части pad, которая должна быть отображена, и местоположения на экране, которое должно быть использовано для отображения. Аргументы — pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; аргументы p относятся к верхнему левому углу области pad, подлежащей отображению, а аргументы s определяют ограничивающую рамку на экране, в пределах которой область pad должна быть отображена.

curses.newwin(nlines, ncols)

curses.newwin(nlines, ncols, begin_y, begin_x)

Возвращает новое окно, верхний левый угол которого находится в (begin_y, begin_x), а высота/ширина — nlines/ncols.

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

curses.nl()

Переход в режим новой строки. Этот режим преобразует клавишу ввода в новую строку при вводе и преобразует новую строку в возвращение и перевод строки при выводе. Режим новой строки по умолчанию включен.

curses.nocbreak()

Выход из режима cbreak. Возврат в обычный «обработанный» режим с буферизацией строк.

curses.noecho()

Выход из режима отображения. Вывод введенных символов отключается.

curses.nonl()

Выход из режима новой строки. Отключение преобразования клавиши ввода в новую строку на входе и отключение низкоуровневого преобразования новой строки в новую строку/возврат на выходе (но это не изменяет поведение addch('\n'), которое всегда выполняет эквивалент возврата и перевода строки на виртуальном экране). При отключенном преобразовании curses иногда немного ускоряет вертикальное перемещение; также оно сможет обнаружить клавишу ввода на входе.

curses.noqiflush()

При использовании процедуры noqiflush() обычная очистка очередей ввода и вывода, связанных с символами INTR, QUIT и SUSP, не выполняется. Возможно, вам потребуется вызвать noqiflush() в обработчике сигнала, если вы хотите, чтобы вывод продолжался так, как будто прерывания не произошло, после выхода из обработчика.

curses.noraw()

Выход из сырого режима. Возврат в обычный «обработанный» режим с буферизацией строк.

curses.pair_content(pair_number)

Возвращает кортеж (fg, bg) содержащий цвета для запрошенной пары цветов. Значение pair_number должно быть между 1 и COLOR_PAIRS - 1.

curses.pair_number(attr)

Возвращает номер набора пар цветов, установленного значением атрибута attr. color_pair() является обратной функцией для этой функции.

curses.putp(str)

Эквивалентно tputs(str, 1, putchar); выводит значение указанной возможности terminfo для текущего терминала. Обратите внимание, что вывод putp() всегда направлен в стандартный вывод.

curses.qiflush([flag])

Если flag равно False, эффект такой же, как вызов noqiflush(). Если flag равно True, или аргумент не указан, очереди будут очищены при чтении этих управляющих символов.

curses.raw()

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

curses.reset_prog_mode()

Восстанавливает терминал в «программный» режим, как ранее сохранил def_prog_mode().

curses.reset_shell_mode()

Восстанавливает терминал в «оболочный» режим, как ранее сохранил def_shell_mode().

curses.resetty()

Восстанавливает состояние режимов терминала до того, что оно было при последнем вызове savetty().

curses.resize_term(nlines, ncols)

Вспомогательная функция, используемая resizeterm(), выполняющая большую часть работы; при изменении размеров окон resize_term() заполняет расширенные области пустым значением. Приложение должно заполнить эти области соответствующими данными. Функция resize_term() пытается изменить размер всех окон. Однако из-за соглашения о вызове для областей это невозможно сделать без дополнительного взаимодействия с приложением.

curses.resizeterm(nlines, ncols)

Изменяет размеры стандартных и текущих окон до указанных размеров и корректирует другие служебные данные, используемые библиотекой curses, которые записывают размеры окон (в частности, обработчик SIGWINCH).

curses.savetty()

Сохраняет текущее состояние режимов терминала в буфере, пригодном для использования функцией resetty().

curses.setsyx(y, x)

Устанавливает виртуальный курсор экрана в координаты y, x. Если y и x оба -1, тогда leaveok устанавливается True.

curses.setupterm(term=None, fd=-1)

Инициализирует терминал. term — это строка, задающая имя терминала, или None; если опущена или None, будет использовано значение переменной окружения TERM. fd — это дескриптор файла, в который будут отправлены любые начальные последовательности; если не указан или -1, будет использован дескриптор файла для sys.stdout.

curses.start_color()

Необходимо вызвать, если программист хочет использовать цвета, и до вызова любой другой процедуры управления цветом. Хорошей практикой является вызов этой процедуры сразу после initscr().

start_color() инициализирует восемь основных цветов (чёрный, красный, зелёный, жёлтый, синий, пурпурный, голубой и белый), и две глобальные переменные в модуле curses, COLORS и COLOR_PAIRS, содержащие максимальное количество цветов и пар цветов, которые поддерживает терминал. Также она восстанавливает цвета на терминале до значений, которые были у него при включении.

curses.termattrs()

Возвращает логическое ИЛИ всех видеоатрибутов, поддерживаемых терминалом. Эта информация полезна, когда программе curses требуется полный контроль над внешним видом экрана.

curses.termname()

Возвращает значение переменной среды TERM, как объект bytes, усечённый до 14 символов.

curses.tigetflag(capname)

Возвращает значение булевой возможности, соответствующей имени возможности terminfo capname как целое число. Возвращает значение -1 если capname не является булевой возможностью, или 0 если она отменена или отсутствует в описании терминала.

curses.tigetnum(capname)

Возвращает значение числовой возможности, соответствующей имени возможности terminfo capname как целое число. Возвращает значение -2 если capname не является числовой возможностью, или -1 если она отменена или отсутствует в описании терминала.

curses.tigetstr(capname)

Возвращает значение строковой возможности, соответствующей имени возможности terminfo capname как объект bytes. Возвращает None если capname не является «строковой возможностью» terminfo, или она отменена или отсутствует в описании терминала.

curses.tparm(str[, ...])

Инициализирует объект bytes str с предоставленными параметрами, где str должна быть параметризованная строка, полученная из базы данных terminfo. Например, tparm(tigetstr("cup"), 5, 3) может привести к b'\033[6;4H', точный результат зависит от типа терминала.

curses.typeahead(fd)

Указывает, что дескриптор файла fd используется для проверки наличия ввода. Если fd равно -1, то проверка ввода не выполняется.

Библиотека curses выполняет «оптимизацию разрыва строк» путём периодического поиска ввода в очереди, во время обновления экрана. Если ввод найден и он поступает с устройства tty, текущее обновление откладывается до вызова refresh или doupdate, что позволяет быстрее реагировать на команды, набранные заранее. Эта функция позволяет указать другой дескриптор файла для проверки ввода.

curses.unctrl(ch)

Возвращает объект bytes, который является удобочитаемым представлением символа ch. Управляющие символы представлены как символ ^, за которым следует символ, например, b'^C'. Печатные символы остаются без изменений.

curses.ungetch(ch)

Возвращает ch, чтобы следующий вызов getch() вернул его.

Примечание

Можно добавить только один ch, прежде чем вызвать getch().

curses.update_lines_cols()

Обновить LINES и COLS. Полезно для обнаружения ручного изменения размера экрана.

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

curses.unget_wch(ch)

Возвращает ch, чтобы следующий вызов get_wch() вернул его.

Примечание

Можно добавить только один ch, прежде чем вызвать get_wch().

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

curses.ungetmouse(id, x, y, z, bstate)

Добавляет событие KEY_MOUSE в очередь ввода, сопоставляя с ним заданные данные состояния.

curses.use_env(flag)

Если используется, эта функция должна вызываться перед initscr() или newterm. Когда flag равно False, будут использоваться значения строк и столбцов, указанные в базе данных terminfo, даже если переменные среды LINES и COLUMNS (используемые по умолчанию) установлены или если curses работает в окне (в этом случае по умолчанию используется размер окна, если LINES и COLUMNS не установлены).

curses.use_default_colors()

Разрешить использование значений по умолчанию для цветов на терминалах, поддерживающих эту функцию. Используйте это для поддержки прозрачности в вашем приложении. Цвет по умолчанию назначается номеру цвета -1. После вызова этой функции init_pair(x, curses.COLOR_RED, -1) инициализирует, например, пару цветов x красным цветом переднего плана на фоновом цвете по умолчанию.

curses.wrapper(func, ...)

Инициализировать curses и вызвать другой вызываемый объект func, который должен быть остальной частью вашего приложения, использующего curses. Если приложение вызывает исключение, эта функция восстановит терминал в нормальное состояние перед повторным возбуждением исключения и генерацией трассировки стека. Вызываемый объект func затем получает главное окно ‘stdscr’ в качестве первого аргумента, за которым следуют любые другие аргументы, переданные в wrapper(). Перед вызовом func, wrapper() включает режим cbreak, отключает эхо, включает клавиши терминала и инициализирует цвета, если терминал поддерживает цвет. При выходе (в нормальном режиме или при исключении) он восстанавливает режим cooked, включает эхо и отключает клавиши терминала.

16.10.2. Объекты окон

Объекты окон, возвращаемые initscr() и newwin() выше, имеют следующие методы и атрибуты:

window.addch(ch[, attr])

window.addch(y, x, ch[, attr])

Отобразить символ ch в позиции (y, x) с атрибутами attr, перезаписывая любой ранее нарисованный символ в этом месте. По умолчанию позиция символа и атрибуты — это текущие настройки для объекта окна.

Примечание

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

window.addnstr(str, n[, attr])

window.addnstr(y, x, str, n[, attr])

Отобразить не более n символов строки символов str в позиции (y, x) с атрибутами attr, перезаписывая все ранее отображенное на экране.

window.addstr(str[, attr])

window.addstr(y, x, str[, attr])

Отобразить строку символов str в позиции (y, x) с атрибутами attr, перезаписывая все ранее отображенное на экране.

Примечание

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

window.attroff(attr)

Удалить атрибут attr из набора «фоновые» атрибутов, применяемых ко всем записям в текущем окне.

window.attron(attr)

Добавить атрибут attr в набор «фоновые» атрибутов, применяемых ко всем записям в текущем окне.

window.attrset(attr)

Установить набор «фоновые» атрибуты на attr. Изначально этот набор 0 (без атрибутов).

window.bkgd(ch[, attr])

Установить фоновый цвет окна на символ ch с атрибутами attr. Изменение затем применяется к каждой позиции символа в этом окне:

• Атрибут каждого символа в окне изменяется на новый фоновый атрибут.
• В местах, где раньше был фоновый символ, он изменяется на новый фоновый символ.

window.bkgdset(ch[, attr])

Установить фон окна. Фон окна состоит из символа и любого сочетания атрибутов. Часть атрибутов фона объединяется (OR'ится) со всеми непустыми символами, которые записываются в окно. И символ, и атрибуты фона объединяются с пустыми символами. Фон становится свойством символа и перемещается вместе с ним при прокрутке и операциях вставки/удаления строк/символов.

window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

Нарисовать рамку вокруг краев окна. Каждый параметр задает символ, который используется для конкретной части рамки; подробности см. в таблице ниже.

Примечание

Значение 0 для любого параметра приведет к использованию символа по умолчанию для этого параметра. Использование ключевых параметров невозможно. Значения по умолчанию указаны в этой таблице:

Параметр	Описание	Значение по умолчанию
ls	Левая сторона	ACS_VLINE
rs	Правая сторона	ACS_VLINE
ts	Верх	ACS_HLINE
bs	Низ	ACS_HLINE
tl	Левый верхний угол	ACS_ULCORNER
tr	Правый верхний угол	ACS_URCORNER
bl	Левый нижний угол	ACS_LLCORNER
br	Правый нижний угол	ACS_LRCORNER

window.box([vertch, horch])

Аналогично border(), но как ls и rs — vertch, так и ts и bs — horch. Символы углов по умолчанию всегда используются этой функцией.

window.chgat(attr)

window.chgat(num, attr)

window.chgat(y, x, attr)

window.chgat(y, x, num, attr)

Установить атрибуты num символов в текущей позиции курсора или в позиции (y, x), если указана. Если num не указано или равно -1, атрибут будет установлен для всех символов до конца строки. Эта функция перемещает курсор в позицию (y, x), если указана. Измененная строка будет затронута с помощью метода touchline(), чтобы содержимое было перерисовано при следующем обновлении окна.

window.clear()

Как и erase(), но также вызывает перерисовку всего окна при следующем вызове refresh().

window.clearok(flag)

Если flag равно True, следующий вызов refresh() очистит окно полностью.

window.clrtobot()

Очистить от курсора до конца окна: все строки ниже курсора удаляются, а затем выполняется эквивалент clrtoeol().

window.clrtoeol()

Очистить от курсора до конца строки.

window.cursyncup()

Обновить текущую позицию курсора всех предков окна, чтобы отразить текущую позицию курсора окна.

window.delch([y, x])

Удалить символ в позиции (y, x).

window.deleteln()

Удалить строку под курсором. Все последующие строки сдвигаются вверх на одну строку.

window.derwin(begin_y, begin_x)

window.derwin(nlines, ncols, begin_y, begin_x)

Аббревиатура «производное окно», derwin() — то же самое, что и вызов subwin(), за исключением того, что begin_y и begin_x относятся к началу окна, а не к всему экрану. Возвращает объект окна для производного окна.

window.echochar(ch[, attr])

Добавить символ ch с атрибутом attr и немедленно вызвать refresh() для окна.

window.enclose(y, x)

Проверить, находятся ли заданные координаты символов (относительно экрана) внутри данного окна, возвращая True или False. Это полезно для определения подмножества окон экрана, которые охватывают местоположение события мыши.

window.encoding

Кодировка, используемая для кодирования аргументов метода (строки и символы Юникода). Атрибут кодировки наследуется от родительского окна при создании дочернего окна, например, с помощью window.subwin(). По умолчанию используется кодировка локали (см. locale.getpreferredencoding()).

Введено в версии 3.3.

window.erase()

Очистить окно.

window.getbegyx()

Возвращает кортеж (y, x) координат верхнего левого угла.

window.getbkgd()

Возвращает текущую пару символа/атрибута фона данного окна.

window.getch([y, x])

Получить символ. Обратите внимание, что возвращаемое целое число не обязательно должно находиться в диапазоне ASCII: клавиши функций, клавиши клавиатуры и т. д. представлены числами больше 255. В режиме без задержки, возвращает -1 если нет входных данных, в противном случае ожидает нажатия клавиши.

window.get_wch([y, x])

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

Введено в версии 3.3.

window.getkey([y, x])

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

window.getmaxyx()

Возвращает кортеж (y, x) высоты и ширины окна.

window.getparyx()

Возвращает начальные координаты этого окна относительно его родительского окна в виде кортежа (y, x). Возвращает (-1, -1) если у этого окна нет родителя.

window.getstr()

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

Считывает объект байтов от пользователя с примитивными возможностями редактирования строк.

window.getyx()

Возвращает кортеж (y, x) текущего положения курсора относительно верхнего левого угла окна.

window.hline(ch, n)

window.hline(y, x, ch, n)

Отображает горизонтальную линию, начинающуюся с (y, x) длиной n, состоящую из символа ch.

window.idcok(flag)

Если flag равен False, curses больше не учитывает использование аппаратной функции вставки/удаления символов терминала; если flag равен True, использование вставки и удаления символов включено. Когда curses впервые инициализируется, использование вставки/удаления символов включено по умолчанию.

window.idlok(flag)

Если flag равен True, curses будет пытаться использовать аппаратные средства редактирования строк. В противном случае, вставка/удаление строк отключены.

window.immedok(flag)

Если flag равен True, любое изменение изображения окна автоматически приводит к обновлению окна; вам больше не нужно вызывать refresh() самостоятельно. Однако это может значительно ухудшить производительность из-за многократных вызовов wrefresh. Этот параметр отключен по умолчанию.

window.inch([y, x])

Возвращает символ в заданной позиции в окне. Нижние 8 битов — сам символ, а старшие биты — атрибуты.

window.insch(ch[, attr])

window.insch(y, x, ch[, attr])

Отображает символ ch в (y, x) с атрибутами attr, сдвигая строку в позиции x вправо на один символ.

window.insdelln(nlines)

Вставляет nlines строк в указанное окно над текущей строкой. Последние nlines строк теряются. Для отрицательных nlines удаляются nlines строк, начиная с той, что находится под курсором, и остальные строки перемещаются вверх. Последние nlines строк очищаются. Текущее положение курсора остается неизменным.

window.insertln()

Вставляет пустую строку под курсором. Все последующие строки перемещаются вниз на одну строку.

window.insnstr(str, n[, attr])

window.insnstr(y, x, str, n[, attr])

Вставляет строку символов (столько символов, сколько поместится в строке) перед символом под курсором, до n символов. Если n равно нулю или меньше нуля, вставляется вся строка. Все символы справа от курсора сдвигаются вправо, а самые правые символы в строке теряются. Позиция курсора не меняется (после перемещения в y, x, если указано).

window.insstr(str[, attr])

window.insstr(y, x, str[, attr])

Вставляет строку символов (столько символов, сколько поместится в строке) перед символом под курсором. Все символы справа от курсора сдвигаются вправо, а самые правые символы в строке теряются. Позиция курсора не меняется (после перемещения в y, x, если указано).

window.instr([n])

window.instr(y, x[, n])

Возвращает объект байтов символов, извлечённых из окна, начиная с текущей позиции курсора или с y, x, если указано. Атрибуты удаляются из символов. Если n задано, instr() возвращает строку не более n символов (за исключением завершающего NUL).

window.is_linetouched(line)

Возвращает True если указанная строка была изменена с момента последнего вызова refresh(); в противном случае возвращает False. Генерирует исключение curses.error, если line не является допустимым для данного окна.

window.is_wintouched()

Возвращает True если указанное окно было изменено с момента последнего вызова refresh(); в противном случае возвращает False.

window.keypad(flag)

Если flag равен True, последовательности escape, сгенерированные некоторыми клавишами (клавиатуры, клавиши функций), будут интерпретироваться curses. Если flag равен False, последовательности escape будут оставлены в потоке ввода как есть.

window.leaveok(flag)

Если flag равен True, курсор останется на месте при обновлении вместо того, чтобы находиться в «положение курсора». Это уменьшает перемещение курсора, где это возможно. Если возможно, курсор будет сделан невидимым. Если flag равен False, курсор всегда будет в «положении курсора» после обновления.

window.move(new_y, new_x)

Переместить курсор в (new_y, new_x).

window.mvderwin(y, x)

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

window.mvwin(new_y, new_x)

Переместить окно так, чтобы его верхний левый угол находился в (new_y, new_x).

window.nodelay(flag)

Если flag равен True, getch() будет неблокирующим.

window.notimeout(flag)

Если flag равен True, последовательности escape не будут приостановлены по таймауту. Если flag равен False, после нескольких миллисекунд последовательность escape не будет интерпретирована и будет оставлена в потоке ввода как есть.

window.noutrefresh()

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

window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

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

Для получения точного управления копируемой областью можно использовать вторую форму overlay(). sminrow и smincol — координаты верхнего левого угла исходного окна, а остальные переменные обозначают прямоугольник в целевом окне.

window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

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

Для получения точного управления копируемой областью можно использовать вторую форму overwrite(). sminrow и smincol — координаты верхнего левого угла исходного окна, а остальные переменные обозначают прямоугольник в целевом окне.

window.putwin(file)

Записывает все данные, связанные с окном, в предоставленный объект файла. Эту информацию можно позже получить с помощью функции getwin().

window.redrawln(beg, num)

Указывает, что num строк экрана, начиная со строки beg, повреждены и должны быть полностью перерисованы при следующем вызове refresh().

window.redrawwin()

Обновляет всё окно, вызывая его полную перерисовку при следующем вызове refresh().

window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])

Немедленно обновляет отображение (синхронизирует фактический экран с предыдущими методами рисования/удаления).

Эти 6 необязательных аргументов можно указать только в случае, если окно является областью, созданной с помощью newpad(). Дополнительные параметры необходимы для указания какой части области и экрана задействованы. pminrow и pmincol определяют верхний левый угол прямоугольника, отображаемого в области. sminrow, smincol, smaxrow и smaxcol определяют края прямоугольника, отображаемого на экране. Нижний правый угол прямоугольника, отображаемого в области, рассчитывается по координатам экрана, так как прямоугольники должны быть одинакового размера. Оба прямоугольника должны быть полностью заключены в соответствующие структуры. Отрицательные значения pminrow, pmincol, sminrow или smincol обрабатываются так, как будто они равны нулю.

window.resize(nlines, ncols)

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

window.scroll([lines=1])

Прокручивает экран или область прокрутки вверх на lines строк.

window.scrollok(flag)

Управление тем, что происходит, когда курсор окна перемещается за пределы окна или области прокрутки, либо в результате действия новой строки в нижней строке, либо при вводе последнего символа последней строки. Если flag равно False, курсор остается в нижней строке. Если flag равно True, окно прокручивается вверх на одну строку. Обратите внимание, что для получения физического эффекта прокрутки на терминале также необходимо вызвать idlok().

window.setscrreg(top, bottom)

Устанавливает область прокрутки от строки top до строки bottom. Все действия прокрутки будут происходить в этой области.

window.standend()

Отключает атрибут выделения. На некоторых терминалах это имеет побочный эффект отключения всех атрибутов.

window.standout()

Включает атрибут A_STANDOUT.

window.subpad(begin_y, begin_x)

window.subpad(nlines, ncols, begin_y, begin_x)

Возвращает подокно, верхний левый угол которого находится в (begin_y, begin_x), а ширина/высота равна ncols/nlines.

window.subwin(begin_y, begin_x)

window.subwin(nlines, ncols, begin_y, begin_x)

Возвращает подокно, верхний левый угол которого находится в (begin_y, begin_x), а ширина/высота равна ncols/nlines.

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

window.syncdown()

Обновляет каждый элемент в окне, который был изменён в любом из его родительских окон. Эта функция вызывается refresh(), поэтому вызывать её вручную почти никогда не требуется.

window.syncok(flag)

Если flag равно True, то syncup() вызывается автоматически всякий раз, когда происходит изменение в окне.

window.syncup()

Обновляет все элементы в родительских окнах, которые были изменены в текущем окне.

window.timeout(delay)

Устанавливает блокирующее или неблокирующее поведение чтения для окна. Если delay отрицательно, используется блокирующее чтение (которое будет ждать неопределённое время ввода). Если delay равно нулю, используется неблокирующее чтение, и getch() вернёт -1 если ввод не ожидается. Если delay положительно, то getch() заблокируется на delay миллисекунд и вернёт -1, если по истечении этого времени ввода всё ещё нет.

window.touchline(start, count[, changed])

Предполагается, что count строк были изменены, начиная со строки start. Если указан changed, он определяет, помечены ли изменённые строки как изменённые (changed=True) или неизменённые (changed=False).

window.touchwin()

Предполагается, что всё окно было изменено для оптимизации рисования.

window.untouchwin()

Помечает все строки в окне как неизменённые с момента последнего вызова refresh().

window.vline(ch, n)

window.vline(y, x, ch, n)

Отображает вертикальную линию, начинающуюся в (y, x), длиной n, состоящую из символа ch.

16.10.3. Постоянные значения

Модуль curses определяет следующие данные:

curses.ERR

Некоторые функции curses, которые возвращают целое число, такие как getch(), возвращают ERR при ошибке.

curses.OK

Некоторые функции curses, которые возвращают целое число, такие как napms(), возвращают OK при успешном выполнении.

curses.version

Объект bytes, представляющий текущую версию модуля. Также доступен как __version__.

Некоторые константы доступны для указания атрибутов ячеек символов. Точные доступные константы зависят от системы.

Несколько констант доступны для извлечения соответствующих атрибутов, возвращаемых некоторыми методами.

Ключи ссылаются на целочисленные константы с именами, начинающимися с KEY_. Доступные точные клавиши зависят от системы.

На VT100 и их программных эмуляциях, таких как эмуляторы X терминалов, обычно доступны как минимум четыре функциональные клавиши (KEY_F1, KEY_F2, KEY_F3, KEY_F4). Стрелки сопоставлены с KEY_UP, KEY_DOWN, KEY_LEFT и KEY_RIGHT в очевидном порядке. Если ваша машина имеет клавиатуру PC, можно ожидать стрелки и двенадцать функциональных клавиш (старые клавиатуры PC могут иметь только десять); также стандартны следующие сопоставления цифровой клавиатуры:

В следующей таблице перечислены символы из альтернативного набора символов. Они унаследованы от терминала VT100 и обычно доступны в программных эмуляциях, таких как X-терминалы. В случае отсутствия графического символа curses использует грубую печатную ASCII-приближение.

В следующей таблице перечислены предопределенные цвета:

curses.textpad — Виджет ввода текста для программ curses

Модуль curses.textpad предоставляет класс Textbox, который обрабатывает элементарный ввод текста в окне curses, поддерживая набор сочетаний клавиш, похожих на Emacs (а значит, и Netscape Navigator, BBedit 6.x, FrameMaker и многие другие программы). Модуль также предоставляет функцию рисования прямоугольника, полезную для обрамления текстовых полей или в других целях.

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

curses.textpad.rectangle(win, uly, ulx, lry, lrx)

Рисует прямоугольник. Первый аргумент должен быть объектом окна; оставшиеся аргументы — координаты, относительные к этому окну. Вторым и третьим аргументами являются координаты y и x верхнего левого угла прямоугольника, который нужно нарисовать; четвёртым и пятым аргументами являются координаты y и x нижнего правого угла. Прямоугольник будет нарисован с использованием символов VT100/IBM PC в терминалах, которые это позволяют (включая xterm и большинство других программных эмуляторов терминалов). В противном случае он будет нарисован с помощью ASCII-тире, вертикальных линий и знаков плюс.

16.11.1. Объекты Textbox

Вы можете создать объект Textbox следующим образом:

class curses.textpad.Textbox(win)

Возвращает объект виджета текстового поля. Аргумент win должен быть объектом окна curses, в котором будет содержаться текстовое поле. Курсор редактирования текстового поля изначально расположен в верхнем левом углу содержащего окна с координатами (0, 0). Флаг объекта stripspaces изначально включён.

Объекты Textbox имеют следующие методы:

edit([validator])

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

do_command(ch)

Обрабатывает одно нажатие управляющей клавиши. Вот поддерживаемые специальные нажатия клавиш:

Нажатие клавиши	Действие
Control-A	Перейти к левому краю окна.
Control-B	Курсор влево, переходя к предыдущей строке, если это необходимо.
Control-D	Удалить символ под курсором.
Control-E	Перейти к правому краю (stripspaces выключено) или концу строки (stripspaces включено).
Control-F	Курсор вправо, переходя к следующей строке, когда это уместно.
Control-G	Завершить, вернув содержимое окна.
Control-H	Удалить символ назад.
Control-J	Завершить, если окно состоит из 1 строки, иначе вставить новую строку.
Control-K	Если строка пуста, удалить её, иначе очистить до конца строки.
Control-L	Обновить экран.
Control-N	Курсор вниз; переместить вниз на одну строку.
Control-O	Вставить пустую строку в местоположение курсора.
Control-P	Курсор вверх; переместить вверх на одну строку.

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

Константа	Нажатие клавиши
KEY_LEFT	Control-B
KEY_RIGHT	Control-F
KEY_UP	Control-P
KEY_DOWN	Control-N
KEY_BACKSPACE	Control-h

Все остальные нажатия клавиш обрабатываются как команда вставки данного символа и перемещения вправо (с переходом на следующую строку).

gather()

Возвращает содержимое окна в виде строки; включение пробелов в окне зависит от члена stripspaces.

stripspaces

Этот атрибут является флагом, который контролирует интерпретацию пробелов в окне. Когда он включен, конечные пробелы в каждой строке игнорируются; любое перемещение курсора, которое поместило бы курсор на конечный пробел, переходит к концу этой строки вместо этого, и конечные пробелы удаляются при сборе содержимого окна.