curses — обработка терминалов для символьных дисплеев

Функции

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

exception curses.error

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

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

curses.assume_default_colors(fg, bg, /)

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

• Назначает цвета переднего плана и фона терминала по умолчанию номеру цвета -1. Таким образом, init_pair(x, COLOR_RED, -1) инициализирует пару x красным цветом на фоне по умолчанию, а init_pair(x, -1, COLOR_BLUE) инициализирует пару x цветом переднего плана по умолчанию на синем фоне.
• Изменяет определение цветовой пары 0 на (fg, bg).

Это расширение ncurses.

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

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 - 1. Возвращает кортеж из 3 элементов со значениями R, G и B для указанного цвета. Каждое значение находится в диапазоне от 0 (отсутствие составляющей) до 1000 (максимальное значение составляющей). Вызывает исключение, если цвет не поддерживается.

curses.color_pair(pair_number)

Возвращает значение атрибута для отображения текста с указанной цветовой парой. Поддерживаются только первые 256 цветовых пар. Это значение атрибута можно комбинировать с 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 до 5: BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED, BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED, BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

Изменено в версии 3.10: Константы BUTTON5_* теперь доступны, если они предоставляются базовой библиотекой curses.

curses.getsyx()

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

curses.getwin(file)

Читает из файла данные, связанные с окном и сохранённые предыдущим вызовом window.putwin(). Затем процедура создаёт и инициализирует новое окно с использованием этих данных и возвращает новый объект окна. Аргумент file должен быть файловым объектом, открытым для чтения в двоичном режиме.

curses.has_colors()

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

curses.has_extended_color_support()

Возвращает True, если модуль поддерживает расширенную работу с цветами; в противном случае возвращает False. Расширенная поддержка цветов позволяет использовать более 256 цветовых пар на терминалах, поддерживающих более 16 цветов (например, xterm-256color).

Для расширенной поддержки цветов требуется ncurses версии 6.1 или новее.

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

curses.has_ic()

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

curses.has_il()

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

curses.has_key(ch)

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

curses.halfdelay(tenths)

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

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

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

curses.init_pair(pair_number, fg, bg)

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

curses.initscr()

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

Предупреждение о вызове этой функции до setupterm() см. в описании этой функции.

Примечание

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

curses.intrflush(flag)

Если flag имеет значение True, нажатие клавиши прерывания (interrupt, break или quit) очищает весь вывод в очереди драйвера терминала. Если flag имеет значение False, очистка не выполняется.

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.

Вызывает исключение ValueError, если k отрицательно.

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)

Задаёт максимальное время в миллисекундах, которое может пройти между событиями нажатия и отпускания, чтобы они распознавались как щелчок, и возвращает предыдущее значение интервала. Значение по умолчанию — 166 миллисекунд, или одна шестая секунды. Чтобы получить значение интервала без его изменения, задайте отрицательное значение interval.

curses.mousemask(mousemask)

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

curses.napms(ms)

Приостанавливает выполнение на ms миллисекунд.

curses.newpad(nlines, ncols)

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

Pad похож на окно, но не ограничен размером экрана и не обязательно связан с определённой его частью. Pad можно использовать, когда требуется большое окно, но одновременно на экране отображается лишь его часть. Автоматическое обновление 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(flag=True)

Включает режим перевода строки. В этом режиме клавиша возврата при вводе преобразуется в символ новой строки, а при выводе символ новой строки преобразуется в возврат каретки и перевод строки. Изначально режим перевода строки включён.

Если flag имеет значение False, эффект такой же, как при вызове nonl().

curses.nocbreak()

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

curses.noecho()

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

curses.nonl()

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

curses.noqiflush()

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

curses.noraw()

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

curses.pair_content(pair_number)

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

curses.pair_number(attr)

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

curses.putp(str)

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

Сначала необходимо вызвать setupterm() (или initscr()).

curses.qiflush([flag])

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

curses.raw()

Включает режим 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() пытается изменить размер всех окон. Однако из-за соглашения о вызовах для pad изменить их размер без дополнительного взаимодействия с приложением невозможно.

curses.resizeterm(nlines, ncols)

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

curses.savetty()

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

curses.get_escdelay()

Получает значение, заданное вызовом set_escdelay().

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

curses.set_escdelay(ms)

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

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

curses.get_tabsize()

Получает значение, установленное с помощью set_tabsize().

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

curses.set_tabsize(size)

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

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

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.error, если терминал не найден или не удалось прочитать его запись в базе данных terminfo. Если терминал уже инициализирован, функция ничего не делает.

Примечание

Вызов initscr() после setupterm() приводит к утечке терминала, выделенного setupterm(): библиотека curses хранит только один текущий терминал и не освобождает ранее выделенный.

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, если она отменена или отсутствует в описании терминала.

Сначала необходимо вызвать setupterm() (или initscr()).

curses.tigetnum(capname)

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

Сначала необходимо вызвать setupterm() (или initscr()).

curses.tigetstr(capname)

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

Сначала необходимо вызвать setupterm() (или initscr()).

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

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

Сначала необходимо вызвать setupterm() (или initscr()).

curses.typeahead(fd)

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

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

curses.unctrl(ch)

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

curses.ungetch(ch)

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

ch может быть целым числом (кодом клавиши или кодом закодированного байта), байтом или строкой длиной 1, которая кодируется одним байтом.

Примечание

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

curses.update_lines_cols()

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

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

curses.unget_wch(ch)

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

ch может быть целым числом (кодом символа, а не кодом клавиши) или строкой длиной 1.

Примечание

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

Добавлено в версии 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()

Эквивалентно assume_default_colors(-1, -1).

curses.wrapper(func, /, *args, **kwargs)

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

Объекты окон

class curses.window

Объекты окон, возвращаемые указанными выше функциями 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. Попытка записать в нижний правый угол окна, подокна или панели приведёт к возникновению исключения после вывода строки.
• Ошибка в ncurses, серверной части этого модуля Python, могла приводить к аварийному завершению при изменении размера окон. Она была исправлена в ncurses-6.1-20190511. Если вы вынуждены использовать более раннюю версию ncurses, можно избежать этой ошибки, не вызывая addstr() со значением str, содержащим символы перевода строки; вместо этого вызывайте addstr() отдельно для каждой строки.

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)

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

window.echochar(ch[, attr])

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

window.enclose(y, x)

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

Изменено в версии 3.10: Ранее функция возвращала 1 или 0 вместо True или False.

window.encoding

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

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

window.erase()

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

window.getbegyx()

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

window.getbkgd()

Вернуть текущую пару символа и атрибута фона указанного окна. Её компоненты можно извлечь так же, как компоненты inch().

window.getch([y, x])

Считать нажатие клавиши, предварительно переместив курсор в y, x, если они указаны, и вернуть результат в виде целого числа. Если окно не является панелью и было изменено после последнего обновления, сначала оно обновляется. Ожидать нажатия клавиши или вернуть -1, если чтение выполняется без блокировки или истёк тайм-аут (см. nodelay() и timeout()).

Обычная клавиша возвращается в виде кода одного байта её кодировки в текущей локали, поэтому для символа, закодированного несколькими байтами, потребуется несколько вызовов. Например, в локали UTF-8 'é' считывается как 195, затем 169. Используйте get_wch(), чтобы считать его как один символ.

В режиме клавиатуры (см. keypad()) функциональные и другие специальные клавиши возвращаются как одна из констант KEY_*, которые невозможно спутать с обычной клавишей. В противном случае, а также если их последовательность escape не поступает вовремя (см. notimeout() и set_escdelay()), байты возвращаются по одному.

В режиме эха (см. echo()) клавиша добавляется в окно, как при вызове addch(); специальные клавиши не отображаются.

window.get_wch([y, x])

Считать нажатие клавиши, предварительно переместив курсор в y, x, если они указаны, и вернуть результат в виде односимвольной строки str. Если окно не является панелью и было изменено после последнего обновления, сначала оно обновляется. Ожидать нажатия клавиши или вызвать исключение error, если чтение выполняется без блокировки или истёк тайм-аут (см. nodelay() и timeout()).

В режиме клавиатуры (см. keypad()) функциональные и другие специальные клавиши возвращаются как одно из целых чисел — констант KEY_*. В противном случае, а также если их последовательность escape не поступает вовремя (см. notimeout() и set_escdelay()), символы возвращаются по одному.

В режиме эха (см. echo()) клавиша добавляется в окно, как при вызове addch(); специальные клавиши не отображаются.

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

window.getkey([y, x])

Считать нажатие клавиши, как это делает getch(), но вернуть результат в виде str: обычную клавишу — в виде односимвольной строки, байт, декодированный как Latin-1, а специальную клавишу — в виде её имени, например 'KEY_UP' (см. keyname()). Если ввода нет, вызвать исключение error вместо возврата -1.

window.getmaxyx()

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

window.getparyx()

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

window.getstr()

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

Считать строку ввода пользователя с простейшими возможностями редактирования, предварительно переместив курсор в y, x, если они указаны. Вернуть её в виде объекта bytes в кодировке текущей локали, без завершающего символа новой строки. Считывается не более n байт; по умолчанию n равно 2047, и это значение нельзя превысить.

Изменено в версии 3.14: Максимальное значение n увеличено с 1023 до 2047.

window.getyx()

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

window.hline(ch, n[, attr])

window.hline(y, x, ch, n[, attr])

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

window.idcok(flag)

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

window.idlok(flag)

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

window.immedok(flag)

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

window.inch([y, x])

Вернуть символ в указанной позиции окна. Младшие 8 бит содержат сам символ, а старшие биты — атрибуты; извлечь их можно с помощью битовых масок A_CHARTEXT и A_ATTRIBUTES, а пару цветов — с помощью pair_number(). Байтом символа является байт кодировки локали для символа ячейки, что соответствует результату instr(). В сборке с поддержкой широких символов, если символ не помещается в один байт в текущей локали, байт символа равен 0; для чтения таких символов используйте instr().

window.insch(ch[, attr])

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

Вставить символ ch с атрибутами attr перед символом под курсором или в позицию (y, 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, если они указаны, до конца строки и вернуть его в виде объекта bytes в кодировке текущей локали. Атрибуты и пары цветов удаляются. Считывается не более n байт; по умолчанию n равно 2047, и это значение нельзя превысить.

Изменено в версии 3.14: Максимальное значение n увеличено с 1023 до 2047.

window.is_linetouched(line)

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

window.is_wintouched()

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

window.keypad(flag)

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

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).

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

window.nodelay(flag)

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

window.notimeout(flag)

Если flag равно True, время ожидания управляющих последовательностей не ограничивается.

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

window.noutrefresh()

window.noutrefresh(pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)

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

6 аргументов можно указать только для окна, являющегося падом, созданным с помощью newpad(); в этом случае они обязательны. Их значения имеют тот же смысл, что и для refresh().

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 прокручивает вверх на указанное число строк, при отрицательном — вниз. Прокрутка действует только в том случае, если она включена для окна с помощью scrollok().

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 соответственно. Координаты задаются относительно родительского пада (в отличие от subwin(), где используются координаты экрана). Этот метод доступен только для падов, созданных с помощью newpad().

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() ожидает ввода указанное число миллисекунд и возвращает -1, если по истечении этого времени ввода всё ещё нет.

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

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

window.touchwin()

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

window.untouchwin()

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

window.vline(ch, n[, attr])

window.vline(y, x, ch, n[, attr])

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

Константы

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

curses.ERR

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

curses.OK

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

curses.version

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

curses.ncurses_version

Именованный кортеж, содержащий три компонента версии библиотеки ncurses: major, minor и patch. Все значения являются целыми числами. К компонентам также можно обращаться по имени, поэтому curses.ncurses_version[0] эквивалентно curses.ncurses_version.major и так далее.

Доступность: если используется библиотека ncurses.

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

curses.COLORS

Максимальное количество цветов, поддерживаемое терминалом. Определяется только после вызова start_color().

curses.COLOR_PAIRS

Максимальное количество цветовых пар, поддерживаемое терминалом. Определяется только после вызова start_color().

curses.COLS

Ширина экрана, то есть количество столбцов. Определяется только после вызова initscr(). Обновляется функциями update_lines_cols(), resizeterm() и resize_term().

curses.LINES

Высота экрана, то есть количество строк. Определяется только после вызова initscr(). Обновляется функциями update_lines_cols(), resizeterm() и resize_term().

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

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

Клавиши обозначаются целочисленными константами, имена которых начинаются с KEY_. Точный набор доступных клавиш зависит от системы.

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

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

В следующей таблице перечислены константы кнопок мыши, используемые функцией getmouse():

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