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

Функции

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

exception curses.error

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

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

curses.baudrate()

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

curses.beep()

Издаёт короткий предупреждающий звук.

curses.can_change_color()

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

curses.cbreak()

Включает режим cbreak. В режиме cbreak (иногда называемом «редким» режимом) обычная буферизация строк tty отключается, и символы становятся доступными для чтения по одному. Однако, в отличие от небуферизованного режима, специальные символы (прерывание, выход, приостановка и управление потоком) сохраняют своё воздействие на драйвер 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(). Затем процедура создаёт и инициализирует новое окно с использованием этих данных и возвращает новый объект окна.

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)

Используется для режима половинной задержки, похожего на режим cbreak тем, что введённые пользователем символы сразу становятся доступны программе. Однако, если по истечении tenths десятых долей секунды ничего не введено, после ожидания возбуждается исключение. Значение tenths должно находиться в диапазоне от 1 до 255. Чтобы выйти из режима половинной задержки, используйте 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 фиксирована: белый на чёрном; её нельзя изменить). Значения аргументов fg и bg должны находиться в диапазоне от 0 до COLORS - 1 или, после вызова use_default_colors(), могут быть равны -1. Если пара цветов уже была инициализирована, экран обновляется, а все вхождения этой пары цветов заменяются в соответствии с новым определением.

curses.initscr()

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

Примечание

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

curses.is_term_resized(nlines, ncols)

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

curses.isendwin()

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

curses.keyname(k)

Возвращает имя клавиши с номером k в виде объекта bytes. Имя клавиши, генерирующей печатный символ ASCII, совпадает с этим символом. Имя комбинации с клавишей Control — это двухбайтовый объект 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)

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

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

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

Примечание

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

curses.update_lines_cols()

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

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

curses.unget_wch(ch)

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

Примечание

Перед вызовом 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()

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

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

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

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

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

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)

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

window.getyx()

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

window.hline(ch, n)

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

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

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

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

window.is_linetouched(line)

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

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

Отключить атрибут standout. На некоторых терминалах это также отключает все остальные атрибуты.

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[, 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

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():

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