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

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

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

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

1. Функции

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

exception curses.error

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

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

curses.baudrate()

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

curses.beep()

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

curses.can_change_color()

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

curses.cbreak()

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

curses.color_content(color_number)

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

curses.color_pair(color_number)

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

curses.curs_set(visibility)

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

curses.def_prog_mode()

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

curses.def_shell_mode()

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

curses.delay_output(ms)

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

curses.doupdate()

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

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

curses.echo()

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

curses.endwin()

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

curses.erasechar()

Возвращает текущий символ стирания пользователя. В операционных системах 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(), все вхождения этого цвета на экране сразу же изменяются на новое определение. Эта функция является бесполезной операцией на большинстве терминалов; она активна только если can_change_color() возвращает 1.

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. Имя клавиши, генерирующей печатаемый символ ASCII, — это символ клавиши. Имя комбинации управляющей клавиши — строка из двух символов, состоящая из каретки, за которой следует соответствующий печатаемый символ ASCII. Имя комбинации клавиши alt (128–255) — это строка, начинающаяся с префикса 'M-' и продолжающаяся именем соответствующего символа ASCII.

curses.killchar()

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

curses.longname()

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

curses.meta(yes)

Если yes равно 1, разрешить ввод 8-битных символов. Если yes равно 0, разрешить только 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()

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

curses.pair_content(pair_number)

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

curses.pair_number(attr)

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

curses.putp(string)

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

curses.qiflush([flag])

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

curses.raw()

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

curses.resizeterm(nlines, ncols)

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

curses.savetty()

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

curses.setsyx(y, x)

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

curses.setupterm([termstr, fd])

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

curses.start_color()

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

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

curses.termattrs()

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

curses.termname()

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

curses.tigetflag(capname)

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

curses.tigetnum(capname)

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

curses.tigetstr(capname)

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

curses.tparm(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)

Возвращает строку, которая является удобочитаемым представлением символа ch. Управляющие символы отображаются как символ «^» за которым следует символ, например, как ^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, включает отображение символов и отключает режим клавиатуры терминала.

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

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

window.addch(ch[, attr])

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

Примечание

Символ означает символ C (код ASCII), а не символ Python (строка длиной 1). (Это примечание верно всякий раз, когда в документации упоминается символ.) Встроенная функция ord() полезна для преобразования строк в коды.

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

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, перезаписывая всё, что было ранее на дисплее.

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 не указано или num = -1, атрибут будет установлен для всех символов до конца строки. Эта функция не перемещает курсор. Изменённая строка будет отмечена с помощью метода touchline(), чтобы её содержимое перерисовывалось при следующем обновлении окна.

window.clear()

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

window.clearok(yes)

Если yes равно 1, при следующем вызове 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 и символы). Атрибут кодировки наследуется от родительского окна при создании подокна, например, с помощью window.subwin(). По умолчанию используется кодировка локали (см. locale.getpreferredencoding()).

Новое в версии 3.3.

window.erase()

Очищает окно.

window.getbegyx()

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

window.getbkgd()

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

window.getch([y, x])

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

window.get_wch([y, x])

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

Новое в версии 3.3.

window.getkey([y, x])

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

window.getmaxyx()

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

window.getparyx()

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

window.getstr([y, x])

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

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

Если вызвано с yes равным 1, 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(yes)

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

window.leaveok(yes)

Если yes равно 1, курсор остаётся на месте при обновлении, а не в "позиции курсора". Это уменьшает перемещение курсора, где это возможно. Если возможно, курсор будет сделан невидимым.

Если yes равно 0, курсор всегда будет в "позиции курсора" после обновления.

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

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

window.notimeout(yes)

Если yes равно 1, последовательности escape не будут иметь таймаута.

Если yes равно 0, после нескольких миллисекунд последовательность 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 ложно, курсор остается в нижней строке. Если flag истинно, окно прокручивается вверх на одну строку. Обратите внимание, что для получения физического эффекта прокрутки на терминале необходимо также вызвать 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 равно нулю, используется неблокирующее чтение, и -1 будет возвращено getch(), если ввод не ожидает. Если delay положительно, то getch() будет блокироваться на delay миллисекунд и возвращать -1, если ввода все ещё нет в конце этого времени.

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

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

window.touchwin()

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

window.untouchwin()

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

window.vline(ch, n)

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

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

3. Константы

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

curses.ERR

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

curses.OK

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

curses.version

Строка, представляющая текущую версию модуля. Также доступна как __version__.

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

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

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

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

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

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

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

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

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

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

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

1. Объекты Textbox

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

class curses.textpad.Textbox(win)

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

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

edit([validator])

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

do_command(ch)

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

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

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

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

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

gather()

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

stripspaces

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