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

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

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

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

Функции

Модуль 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()

Возвращает текущий символ удаления пользователя как объект строки байтов длиной один байт. В операционных системах 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, включает эхо и отключает клавиатуру терминала.

Объекты окна

Объекты окна, возвращаемые 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])

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

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

Кодировка, используемая для кодирования аргументов метода (строки и символы Unicode). Атрибут 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, последовательности экранирования, сгенерированные некоторыми клавишами (клавиатурой, функциональными клавишами), будут интерпретированы curses. Если flag равно False, последовательности экранирования будут оставлены как есть в потоке входных данных.

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 равно False, последовательности экранирования не будут вызывать таймаут.

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

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.

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

Модуль 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 очевидным образом. Если ваша машина имеет клавиатуру ПК, можно ожидать клавиши со стрелками и двенадцать функциональных клавиш (более старые клавиатуры ПК могут иметь только десять функциональных клавиш); также стандартны следующие сопоставления набора:

В следующей таблице перечислены символы из альтернативного набора символов. Они унаследованы от терминала 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 тире, вертикальных линий и знаков плюс.

Объекты 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

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