CURSES(3X)

НАЗВАНИЕ
curses - пакет подпрограмм управления выводом на терминал

ПРИМЕЧАНИЯ
Описание пакета curses устроено не совсем обычно.

В разделе СИНТАКСИС дается информация о компиляции, сводка имен аргументов процедур пакета и их типов, а также алфавитный указатель процедур пакета и их аргументов.

В разделе ОПИСАНИЕ рассказывается о том, как нужно использовать пакет curses.

В разделе ПРОЦЕДУРЫ приводится описание всех процедур пакета curses, процедуры при этом сгруппированы по следующим темам:

• управление всем экраном
• управление окнами
• вывод
• ввод
• установка режимов вывода
• установка режимов ввода
• запросы к оборудованию
• программируемые метки
• процедуры нижнего уровня
• процедуры уровня terminfo
• эмуляция termcap
• дополнительные процедуры
• использование curscr

Затем идут разделы АТРИБУТЫ, ФУНКЦИОНАЛЯНЫЕ КЛАВИШИ, ПСЕВДОГРАФИКА.

СИНТАКСИС

	cc  [опция ...] файл ... -lcurses [библиотека ...]



	#include <curses.h> (автоматически включает  <stdio.h>,

	                    <termio.h> и <unctrl.h>)

Ниже описаны аргументы процедур пакета curses, некоторые глобальные переменные, а затем сами процедуры. Все процедуры пакета, если не оговорено противное, возвращают значения ERR или OK типа int. В случае ошибки результат процедур, возвращающих значения-указатели, равен NULL. (Константы ERR, OK и NULL определяются во включаемом файле <curses.h>.)

	bool bf

	char **area, *boolnames [ ], *boolcodes [ ], *boolfnames [ ], *bp

	char *cap, *capname, *codename [2], erasechar, *filename, *fmt

	char *keyname, killchar, *label, *longname

	char *name, *numnames [ ], *numcodes [ ], *numfnames [ ]

	char *slk_label, *str, *strnames [ ], *strcodes [ ], strfnames [ ]

	char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type

	chtype attrs, ch, horch, vertch

	FILE *infd, *outfd

	int begin_x, begin_y, begline, bot, c, col, count

	int dmaxcol, dmaxrow, dmincol, dminrow, *erret, fildes

	int (*init ( )), labfmt, labnum, line

	int ms, ncols, new, newcol, newrow, nlines, numlines

	int oldcol, oldrow, overlay

	int p1, p2, p3, p4, p5, p6, p7, p8, p9

	int pmincol, pminrow, (*putc ( )), row

	int smaxcol, smaxrow, smincol, sminrow, startrow

	int tenths, top, visibility, x, y

	SCREEN *new, *newterm, *set_term

	TERMINAL *cur_term, *nterm, *oterm

	va_list varglist

	WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig

	WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win



	addch (ch)

	addstr (str)

	attroff (attrs)

	attron (attrs)

	attrset (attrs)

	baudrate ( )

	beep ( )

	box (win, vertch, horch)

	cbreak ( )

	clear ( )

	clearok (win, bf)

	clrtobot ( )

	clrtoeol ( )

	copywin (srcwin, dstwin, sminrow, smincol, dminrow, dmincol,

		dmaxrow, dmaxcol, overlay)

	curs_set (visibility)

	def_prg_mode ( )

	def_shell_mode ( )

	def_curterm (oterm)

	delay_output (ms)

	delch ( )

	deleteln ( )

	delwin (win)

	doupdate ( )

	draino (ms)

	echo ( )

	echochar (ch)

	endwin ( )

	erase ( )

	erasechar ( )

	filter ( )

	flash ( )

	flushinp ( )

	garbagedlines (win, begline, numlines)

	getbegyx (win, y, x)

	getch ( )

	getmaxyx (win, y, x)

	getstr (str)

	getsyx (y, x)

	getyx (win, y, x)

	halfdelay (tenths)

	has_ic ( )

	has_il ( )

	idlok (win, bf)

	inch ( )

	initscr ( )

	insch (ch)

	insertln ( )

	intrflush (win, bf)

	isendwin ( )

	keyname (c)

	keypad (win, bf)

	killchar ( )

	leaveok (win, bf)

	longname ( )

	meta (win, bf)

	move (y, x)

	mvaddch (y, x, ch)

	mvaddstr (y, x, str)

	mvcur (oldrow, oldcol, newrow, newcol)

	mvdelch (y, x)

	mvgetch (y, x)

	mvgetstr (y, x, str)

	mvinch (y, x)

	mvinsch (y, x, ch)

	mvprintw (y, x, fmt[, arg...])

	mvscanw (y, x, fmt[, arg...])

	mvwaddch (win, y, x, ch)

	mvwaddstr (win, y, x, str)

	mvwdelch (win, y, x)

	mvwgetch (win, y, x)

	mvwgetstr (win, y, x, str)

	mvwin (win, y, x)

	mvwinch (win, y, x)

	mvwinsch (win, y, x, ch)

	mvwprintw (win, y, x, fmt[, arg...])

	mvwscanw (win, y, x, fmt[, arg...])

	napms (ms)

	newpad (nlines, ncols)

	newterm (type, outfd, infd)

	newwin (nlines, ncols, begin_y, begin_x)

	nl ( )

	nocbreak ( )

	nodelay (win, bf)

	noecho ( )

	nonl ( )

	noraw ( )

	notimeout (win, bf)

	overlay (srcwin, dstwin)

	overwrite (srcwin, dstwin)

	pechochar (pad, ch)

	pnoutrefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)

	prefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)

	printw (fmt[, arg...])

	putp (str)

	raw ( )

	refresh ( )

	reset_prog_mode ( )

	reset_shell_mode ( )

	resetty ( )

	restartterm (term, fildes, erret)

	ripoffline (line, init)

	savetty ( )

	scanw (fmt[, arg...])

	scr_dump (filename)

	scr_init (filename)

	scr_restore (filename)

	scroll (win)

	scrollok (win, bf)

	set_curterm (nterm)

	set_term (new)

	setscrreg (top, bot)

	setsyx (y, x)

	setupterm (term, fildes, erret)

	slk_clear ( )

	slk_init (labfmt)

	slk_label (labnum)

	slk_noutrefresh ( )

	slk_refresh ( )

	slk_restore ( )

	slk_set (labnum, label, fmt)

	slk_touch ( )

	standend ( )

	standout ( )

	subpad (orig, nlines, ncols, begin_y, begin_x)

	subwin (orig, nlines, ncols, begin_y, begin_x)

	tgetent (bp, name)

	tgetflag (codename)

	tgetnum (codename)

	tgetstr (codename, area)

	tgoto (cap, col, row)

	tigetflag (capname)

	tigetnum (capname)

	tigetstr (capname)

	touchline (win, start, count)

	touchwin (win)

	tparm (str, p1, p2, p3, p4, p5, p6, p7, p8, p9)

	tputs (str, count, putc)

	traceoff ( )

	traceon ( )

	typeahead (fildes)

	unctrl (c)

	ungetch (c)

	vidattr (attrs)

	vidputs (attrs, putc)

	vwprintw (win, fmt, varglist)

	vwscanw (win, fmt, varglist)

	waddch (win, ch)

	waddstr (win, str)

	wattroff (win, attrs)

	wattron (win, attrs)

	wattrset (win, attrs)

	wclear (win)

	wclrtobot (win)

	wclrtoeol (win)

	wdelch (win)

	wdeleteln (win)

	wechochar (win, ch)

	werase (win)

	wgetch (win)

	wgetstr (win, str)

	winch (win)

	winsch (win, ch)

	winsertln (win)

	wmove (win, y, x)

	wnoutrefresh (win)

	wprintw (win, fmt[, arg...])

	wrefresh (win)

	wscanw (win, fmt[, arg...])

	wsetcrreg (win, top, bot)

	wstandend (win)

	wstandout (win)

ОПИСАНИЕ
Пакет curses дает пользователю независимый от терминала метод вывода на экран с разумной оптимизацией.

Инициализирующие процедуры initscr или newterm необходимо обязательно вызвать самыми первыми (три исключения из этого правила будут описаны ниже). При завершении работы нужно вызвать процедуру endwin. Чтобы вводимые символы не изображались на экране (большинству интерактивных экранных программ нужен именно такой режим) после вызова процедуры initscr необходимо вызвать

	cbreak (); noecho ()

	nonl ();

	intrflush (stdscr, FALSE); keypad (stdscr, TRUE)

Перед запуском программы, использующей пакет curses, на терминале необходимо установить позиции табуляции и, если требуется, вывести инициализирующие последовательности. Это обычно делается командой tput init, причем переменная окружения TERM должна быть предварительно определена и помещена в окружение командой export TERM. Подробнее см. profile(4), tput(1) и раздел Табуляции и инициализация в terminfo(4).

Библиотека curses содержит процедуры, манипулирующие структурами данных, называемыми окнами, которые можно мыслить как двумерные массивы символов, представляющие весь экран или его часть. Всегда имеется стандартное окно, размером с экран, называемое stdscr. Другие окна могут быть созданы процедурой newwin. В программах на окна ссылаются с помощью переменных типа WINDOW *; тип структур WINDOW определен во включаемом файле <curses.h>. Этими структурами данных можно манипулировать с помощью процедур, описанных ниже, среди которых основными являются move и addch. (Самыми общими являются процедуры, имена которых начинаются с буквы w, в них можно указать окно в качестве параметра. Процедуры, имена которых не начинаются с буквы w, обычно имеют дело с stdscr.) Затем вызывается процедура refresh, которая обращается к нужным процедурам, чтобы экран пользователя выглядел как stdscr. Символы в окне имеют тип chtype, что позволяет для каждого символа хранить дополнительную информацию.

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

Для каждого изображаемого на экране символа могут быть заданы атрибуты визуализации, что позволяет выводить подчеркнутые или инвертированные символы на терминалах, обладающих соответствующими возможностями. С помощью пакета curses можно вывести псевдографические символы. При вводе процедуры пакета могут преобразовывать последовательности, посылаемые стрелками и функциональными клавишами. Атрибуты визуализации, псевдографические символы и коды для функциональных клавиш описаны в файле <curses.h>, например A_REVERSE, ACS_HLINE, KEY_LEFT.

В пакете curses определена также переменная curscr типа WINDOW *, которую можно использовать в качестве аргумента некоторых процедур нижнего уровня, таких как перерисовка испорченного экрана. Если обратиться к процедуре clearok с аргументом curscr, то следующее обращение к wrefresh для любого окна приведет к очистке экрана и затем его полной перерисовке. Если обратиться к процедуре wrefresh с аргументом curscr, то экран немедленно очистится и перерисуется. Именно так большинство программ осуществляет перерисовку экрана.

Информация о размерах экрана, заданная в terminfo, может быть перекрыта переменными окружения LINES и COLUMNS, что используется, например, для терминала AT&T 5620, имеющего переменный размер экрана.

Если определена переменная окружения TERMINFO, процедуры пакета curses сначала ищут описание терминала не в стандартном месте, а в указанном. Например, если переменная окружения TERM имеет значение att4425, то скомпилированное описание характеристик по умолчанию извлекается из файла /usr/lib/terminfo/a/att4425. Однако, если значение переменной окружения TERMINFO равно $HOME/myterms, то curses вначале проверит файл $HOME/ myterms/a/att4425, и только если этот файл отсутствует, обратится к /usr/lib/terminfo/a/att4425. Подобное соглашение удобно для экспериментов с описаниями, а также тогда, когда нет прав на запись в каталог /usr/lib/ terminfo.

Во включаемом файле <curses.h> определены глобальные переменные LINES и COLS типа int. В процедуре initscr этим переменным присваивается число строк экрана и число символов в строке (более подробную информацию см. в разделе Процедуры уровня terminfo). Константы TRUE и FALSE суть 1 и 0 соответственно. Процедуры обычно возвращают значения ERR или OK; таким образом можно определить, успешно ли завершилась процедура. Константы ERR и OK также определены в файле <curses.h>

ПРОЦЕДУРЫ
Для многих описываемых ниже процедур имеется несколько версий. Процедуры с префиксом w имеют дополнительный аргумент - окно. Процедуры с префиксом p имеют дополнительный аргумент - спецокно. Процедуры без префикса работают с stdscr.

Процедуры с префиксом mv имеют дополнительные аргументы - координаты x и y места, куда нужно поместить курсор перед выполнением соответствующего действия. Эти процедуры вначале вызывают move (y, x), а затем соответствующую процедуру без префикса mv. Аргумент y всегда означает строку окна, а x - колонку. Левый верхний угол окна имеет координаты (0, 0), а не (1, 1). Для процедур с префиксом mvw в качестве дополнительных аргументов задаются и окно, и координаты курсора. Аргумент, задающий окно, всегда указывается перед координатами.

Во всех процедурах параметр win задает окно, а параметр pad - спецокно. (И win, и pad имеют тип WINDOW *.) Для процедур, устанавливающих режимы, аргумент bf типа bool должен иметь значение TRUE или FALSE. Типы WINDOWS *, bool и chtype определены во включаемом файле <curses.h>. Описание типов всех переменных приведено в разделе СИНТАКСИС.

Все процедуры, если не оговорено противное, возвращают значения ERR или OK. В случае ошибки результат процедур, возвращающих значения-указатели, равен NULL.

Управление всем экраном

WINDOW *initscr ( )

Первой вызываемой процедурой почти всегда является initscr. Есть только следующие три исключения: slk_init, filter и ripoffline. Процедура initscr определяет тип терминала и инициализирует структуры данных пакета curses. Выполняются такие действия, чтобы первое обращение к refresh очистило экран. Если обнаружены ошибки, initscr выводит сообщение в стандартный протокол и завершает программу; если ошибок не было, возвращается значение stdscr. Если программа сама желает обрабатывать ошибки инициализации, вместо initscr следует использовать newterm. Процедуру initscr нужно вызывать только один раз.

endwin ( )

Процедуру endwin необходимо обязательно вызывать перед завершением программы, а также, например, перед запуском порожденного процесса shell или выполнением функции system(3S). Процедура endwin восстанавливает начальные характеристики драйвера tty(7), помещает курсор в левый нижний угол экрана и переводит терминал в нормальный режим визуализации. Чтобы продолжить пользование пакетом curses, необходимо вызвать процедуру wrefresh или doupdate.

isendwin ( )

Возвращает значение TRUE, если перед этим был вызов процедуры endwin, но еще не было вызова wrefresh или doupdate.

SCREEN *newterm (type, outgf, infd)

Программа, осуществляющая вывод на несколько терминалов одновременно, должна использовать для инициализации каждого из них не initscr, а newterm. Программа, которая сама может обрабатывать ошибки инициализации, например, путем работы в строчном режиме вместо экранного, также должна использовать для инициализации процедуру newterm. В случае нескольких терминалов процедура newterm должна быть вызвана для каждого терминала. Процедура возвращает значение типа SCREEN *, которое должно быть сохранено для последующих ссылок на терминал. Аргумент type задает имя терминала, которое будет использоваться вместо значения переменной окружения TERM, аргумент outfd является указателем потока, открытого на вывод [см. stdio(3S)], а аргумент infd - это указатель потока, открытого на ввод. При завершении программа должна вызвать процедуру endwin для каждого терминала. Если newterm вызывался несколько раз для одного и того же терминала, endwin должен вызываться в порядке, обратном вызовам newterm.

SCREEN *set_term (new)

Эта процедура используется для переключения между несколькими терминалами. Терминал, на который ссылается аргумент new, становится текущим. Процедура возвращает указатель на терминал, бывший до этого текущим. Это единственная процедура, которая манипулирует указателями типа SCREEN *; все остальные процедуры относятся к текущему терминалу.

Управление окнами

refresh ( )
wrefresh (win)

Эти процедуры (или процедуры prefresh, pnoutrefresh, wnoutrefresh или doupdate) должны вызываться для реального вывода на экран, тогда как большинство остальных процедур только манипулируют структурами данных. Процедура wrefresh копирует указанное окно на экран терминала, принимая во внимание то, что на экран уже выведено, чтобы не выводить информацию повторно (это называется оптимизацией вывода). Процедура refresh делает то же самое для стандартного окна stdscr. Если не установлен режим leaveok, физический курсор терминала помещается на текущее место в окне. Процедура возвращает количество символов, выведенных на терминал.

Отметим, что refresh является макросом.

wnoutrefresh (win)
doupdate ( )

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

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

WINDOW *newwin (nlines, ncols, begin_y, begin_x)

Создать новое окно, содержащее nlines строк и ncols колонок, и возвратить указатель на него. Левый верхний угол окна помещается в строке begin_y, колонке begin_x. Если nlines или ncols равны 0, размер окна будет LINES-begin_y строк и COLS begin_x колонок соответственно. Новое окно размером с целый экран создается вызовом newwin (0, 0, 0, 0).

mvwin (win, y, x)

Переместить указанное окно так, чтобы его левый верхний угол находился в позиции (y, x). Если перемещение выводит окно за пределы экрана, это считается ошибкой и перемещение окна не выполняется.

WINDOW *subwin (orig, nlines, ncols, begin_y, begin_x)

Создать новое окно, содержащее nlines строк и ncols колонок, и возвратить указатель на него. Левый верхний угол окна помещается в строке begin_y, колонке begin_x (номер строки и колонки относительно экрана, а не относительно окна orig). Считается, что новое окно перекрывается с окном orig, то есть изменения в одном окне влияют на оба окна. При использовании этой процедуры обычно требуется перед обращением к wrefresh вызвать процедуры touchwin и touchline для окна orig.

delwin (win)

Удалить указанное окно, освободив всю память, связанную с ним. В случае перекрытия окон сначала должны быть удалены окна, созданные с помощью процедур subwin или subpad.

WINDOW *newpad (nlines, ncols)

Создать новое спецокно, содержащее nlines строк и ncols колонок, и возвратить указатель на него. Спецокна не ограничены размерами экрана и даже не обязательно связаны с какой-либо частью экрана. Спецокна используются, когда требуется большое окно, из которого на экране будет изображаться только часть. Автоматической перерисовки спецокон (например, при роллировании) не происходит. Спецокно нельзя указывать в качестве аргумента процедуры wrefresh, вместо этого необходимо пользоваться процедурами prefresh и pnoutrefresh. Отметим, что эти процедуры имеют дополнительные аргументы, посредством которых задается та часть спецокна, которая должна изображаться, и та часть экрана, на которой должно располагаться изображение.

WINDOW *subpad (orig, nlines, ncols, begin_y, begin_x)

Создать новое спецокно, содержащее nlines строк и ncols колонок, и возвратить указатель на него. В отличие от процедуры subwin, левый верхний угол нового спецокна задается относительно спецокна orig. Новое окно перекрывается с окном orig, то есть изменения в одном окне влияют на оба окна. При использовании этой процедуры обычно требуется перед обращением к prefresh вызвать процедуры touchwin и touchline для окна orig.

prefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) pnoutrefresh (pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)

Эти процедуры аналогичны процедурам wrefresh и wnoutrefresh, только работают они над спецокнами. Дополнительные аргументы задают место на экране, куда пойдет вывод. Аргументы pminrow и pmincol задают левый верхний угол области спецокна, которая будет изображаться; sminrow, smincol, smaxrow, smaxcol задают прямоугольник на экране, в котором будет вестисть отображение. Правый нижний угол изображаемого прямоугольника в спецокне вычисляется по координатам на экране, так как прямоугольники имеют одинаковые размеры. Оба прямоугольника не должны выходить за пределы спецокна и экрана. Отрицательные значения pminrow, pmincol, sminrow и smincol трактуются как нули.

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

addch (ch)
waddch (win, ch)
mvaddch (y, x, ch)
mvwaddch (win, y, x, ch)

Символ ch помещается в текущую позицию окна, текущая позиция при этом сдвигается на единицу вправо. На правой границе окна происходит автоматический перевод строки, на нижней строке окна, если установлен режим scrollok, происходит роллирование.

Если ch является символом табуляции, перевода строки или возврата на шаг, выполняется соответствующее действие в окне. Для перевода строки перед перемещением вызывается процедура clrtoeol. Считается, что позиции табуляции расположены в каждой восьмой позиции. Другие управляющие символы будут выведены в виде ^X. (Вызов процедуры winch после вывода управляющего символа вернет не сам управляющий символ, а его печатное представление.)

К символу могут быть добавлены атрибуты визуализации с помощью логической операции ИЛИ, текст будет визуализироваться с этими атрибутами. Копирование текста с атрибутами из одного места экрана в другое может быть выполнено с помощью процедур inch и addch. См. ниже описание процедуры standout.

Отметим, что ch имеет тип chtype, а не char, а addch, mvaddch и mvwaddch являются макросами.

echochar (ch)
wechochar (win, ch)
pechochar (pad, ch)

Эти процедуры соответственно эквивалентны вызову addch (ch), за которым следует refresh ( ), вызову waddch (win, ch), за которым следует wrefresh (win), вызову waddch (pad, ch), за которым следует prefresh (pad). При этом нужно учитывать, что на экран выводится ровно один символ, поэтому расходы на вывод возрастают. Для процедуры pechochar используется та область экрана, в которую последний раз выводилось указанное спецокно.

Отметим, что ch имеет тип chtype, а не char, а echochar является макросом.

addstr (str)
waddstr (win, str)
mvaddstr (y, x, str)
mvwaddstr (win, y, x, str) Эти процедуры выводят цепочку символов str, ограниченную нулевым байтом, в указанное окно. Они эквивалентны вызову waddch для каждого символа цепочки.

Отметим, что addstr, mvaddstr и mvwaddstr являются макросами.

attroff (attrs)
wattroff (win, attrs)
attron (attrs)
wattron (win, attrs)
attrset (attrs)
wattrset (win, attrs)
standend ( )
wstandend (win)
standout ( )
wstandout (win)

Эти процедуры манипулируют атрибутами визуализации в указанном окне. Атрибуты могут быть любой комбинацией из следующих: A_STANDOUT (сообщение), A_REVERSE (инверсия), A_BOLD (выделение), A_DIM (пониженная яркость), A_BLINK (мерцание), A_UNDERLINE (подчеркивание), A_ALTCHARSET (альтернативный набор символов). Все константы определены в файле <curses.h> и могут комбинироваться операцией логическое ИЛИ (| в языке C).

Текущие атрибуты окна применяются ко всем символам, которые записываются в окно процедурой waddch. Атрибуты принадлежат символу и перемещаются вместе с символом при роллировании и вставке/ удалении строк/символов. Пакет curses изображает все атрибуты в той степени, в какой это позволяет конкретный терминал.

Процедура attrset устанавливает текущий набор атрибутов окна равным аргументу attrs. Процедура attroff сбрасывает указанные атрибуты, остальные атрибуты при этом не меняются. Процедура attron устанавливает указанные атрибуты без изменения остальных. Вызов standout ( ) эквивалентен attron (A_STANDOUT), а вызов standend ( ) эквивалентен attrset (0), то есть сбрасывает все атрибуты.

Отметим, что ch имеет тип chtype, а не char, а attroff, attron, attrset, standend и standout являются макросами.

beep ( )
flash ( )

Эти процедуры используются для привлечения внимания пользователя, сидящего за терминалом. Процедура beep подает звуковой сигнал, если это возможно, а если нет, то делает вспышку на экране. Процедура flash делает вспышку на экране, если это возможно, а если нет, подает звуковой сигнал. Если терминал не умеет подавать звуковой сигнал и не умеет делать вспышку на экране, то ничего не происходит. Почти все терминалы умеют подавать звуковой сигнал, но только некоторые умеют делать вспышку на экране.

box (win, vertch, horch)

По краю окна win рисуется рамка. Аргументы vertch и horch - это символы, с помощью которых рисуются вертикальные и горизонтальные линии. Если vertch и horch равны 0, то используются символы по умолчанию - ACS_VLINE и ACS_HLINE соответственно.

Отметим, что аргументы vertch и horch имеют тип chtype, а не char.

erase ( )
werase (win)

Эти процедуры помещают пробелы во все позиции окна.

Отметим, что erase является макросом.

clear ( )
wclear (win)

Эти процедуры совпадают с erase ( ) и werase (win), но они еще дополнительно вызывают процедуру clearok. Вследствие этого при следующем обращении к wrefresh экран будет очищен и перерисован.

Отметим, что clear является макросом.

clrtobot ( )
wclrtobot (win)

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

Отметим, что clrtobot является макросом.

clrtoeol ( )
wclrtoeol (win)

Текущая строка правее позиции курсора, включая саму позицию, очищается.

Отметим, что clrtoeol является макросом.

delay_output (ms)

При выводе сделать паузу на ms миллисекунд. Не рекомендуется, однако, интенсивно применять эту процедуру. Предпочтительнее использовать символы-заполнители, а не паузу процессора.

delch ( )
wdelch (win)
mvdelch (y, x)
mvwdelch (win, y, x)

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

Отметим, что delch и mvdelch являются макросами.

deleteln ( )
wdeleteln (win)

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

Отметим, что deleteln является макросом.

getyx (win, y, x)

Позиция курсора в окне помещается в аргументы y и x. Поскольку getyx является макросом, перед именами аргументов не требуется знак &.

getbegyx (win, y, x)
getmaxyx (win, y, x)

В духе getyx эти процедуры позволяют получить координаты левого верхнего угла окна на экране и его размеры.

Отметим, что getbegyx и getmaxyx являются макросами.

insch (ch)
winsch (win, ch)
mvinsch (y, x, ch)
mvwinsch (win, y, x, ch)

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

Отметим, что ch имеет тип chtype, а не char, а insch, mvinsch и mvwinsch являются макросами.

insertln ( )
winsertln (win)

Перед текущей строкой окна вставляется пустая. Нижняя строка окна теряется. Описываемые процедуры не требуют использования аппаратной функции вставки строки.

Отметим, что insertln является макросом.

move (y, x)
wmove (win, y, x)

Текущая позиция, соответствующая окну, перемещается в строку y, колонку x. Физический курсор на экране не перемещается до тех пор, пока не будет вызвана процедура refresh. Позиция указывается относительно левого верхнего угла окна, имеющего координаты (0, 0).

Отметим, что move является макросом.

overlay (srcwin, dstwin)
overwrite (srcwin, dstwin)

Эти процедуры помещают окно srcwin поверх окна dstwin, то есть текст из srcwin копируется в dstwin. Окна не обязаны иметь одинаковый размер, копируется только пересекающаяся часть. Разница между двумя процедурами заключается в том, что overlay не копирует пробелы, оставляя на этом месте то, что было, а overwrite производит полное копирование.

copywin (srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol, overlay)

Эта процедура дает существенно больше, чем процедуры overlay и overwrite. Как и в процедуре prefresh, задается прямоугольник в окне-приемнике (dminrow, dmincol, dmaxrow, dmaxcol) и левый верхний угол в окне-источнике (sminrow, smincol). Если аргумент overlay не равен 0, то пробелы не копируются, как в overlay.

printw (fmt[, arg...])
wprintw (win, fmt[, arg...])
mvprintw (y, x, fmt[, arg...])
mvwprintw (win, y, x, fmt[, arg...])

Эти процедуры аналогичны printf(3S), только сгенерированная цепочка символов выводится с помощью waddstr в указанное окно.

vwprintw (win, fmt, varglist)

Эта процедура аналогична vfprintf(3S). Она вызывает wprintw с переменным списком аргументов. Третий аргумент, varglist, является указателем на список аргументов, как это определено в . O работе со списком аргументов переменной длины см. vprintf(3S) и varargs(5).

scroll (win)

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

touchwin (win)
touchline (win, start, count)

Забыть информацию о том, какие части окна изменились (эта информация используется для оптимизации вывода). Считать, что все окно требует перерисовки. Это часто бывает необходимо для пересекающихся окон, так как изменение одних окон вызывает изменение и других, но информация об этих изменениях в структурах данных других окон не отражается. Обращение к touchline говорит о том, что изменилось count строк окна, начиная со строки с номером start.

Ввод

getch ( )
wgetch (win)
mvgetch (y, x)
mvwgetch (win, y, x)

С клавиатуры терминала, связанного с окном, считывается символ. Если установлен режим NODELAY и символ еще не введен, возвращается значение ERR. Если установлен режим DELAY, программа приостанавливается до тех пор, пока система не передаст ей введенный текст. В зависимости от режима CBREAK это будет после ввода одного символа (режим CBREAK) или после ввода строки целиком (режим NOCBREAK). В режиме HALF-DELAY программа приостанавливается до тех пор, пока не будет введен символ или истечет указанный период времени. Если не установлен режим NOECHO, вводимые символы отображаются в соответствующем окне. Между обращениями к move и getch, вызываемыми из процедур mvgetch и mvwgetch, не делается refresh.

Используя процедуры getch, wgetch, mvgetch и mvwgetch, нельзя устанавливать одновременно режимы NOCBREAK и ECHO. Результаты могут оказаться непредсказуемыми и зависят от состояния, в котором находится драйвер tty(7).

Если предварительно была вызвана процедура keypad (win, TRUE) и нажата функциональная клавиша, то вместо посланных ею кодов будет возвращено значение, соответсвующее клавише (см. keypad в Установке режимов ввода). Функциональные клавиши определены в <curses.h>, их значения начинаются с числа 0401, а имена - с префикса KEY_. Если поступает символ, который может быть началом функциональной клавиши (например, ESC), curses запускает таймер. Если за ожидаемое время не будет получено продолжения, то символ передается сам по себе, в противном случае возвращается значение функциональной клавиши. Поэтому на многих терминалах после нажатия клавиши ESC необходимо немного подождать, прежде чем эта клавиша попадет программе. По этой же причине не рекомендуется программистам использовать клавишу ESC как односимвольную команду программе. См. также notimeout ниже.

Отметим, что getch, mvgetch и mvwgetch являются макросами.

getstr (str)
wgetstr (win, str)
mvgetstr (y, x, str)
mvwgetstr (win, y, x, str)

Процедура getch вызывается до тех пор, пока не будет нажата клавиша перевода строки, возврата каретки или клавиша "ввод". Результат помещается в область памяти, на которую указывает аргумент str. При вводе обрабатываются управляющие символы erase и kill. Так же как и в процедуре mvgetch, между обращениями к move и getstr, вызываемыми из процедур mvgetstr и mvwgetstr, не делается refresh.

Отметим, что getstr, mvgetstr и mvwgetstr являются макросами.

flushinp ( )

Проигнорировать все символы, введенные пользователем к этому моменту, но еще не считанные программой.

ungetch (c)

Положить символ c обратно во входную очередь, так что он будет считан следующим вызовом wgetch.

chtype inch ( )
chtype winch (win)
chtype mvinch (y, x)
chtype mvwinch (win, y, x)

Эти процедуры возвращают символ (типа chtype), расположенный в текущей позиции указанного окна, вместе с имеющимися атрибутами (как логическое ИЛИ атрибутов и кода символа). Константы A_CHARTEXT и A_ATTRIBUTES, определенные в файле <curses.h>, можно использовать в операции "логическое И" (& в языке C) для выделения из возвращаемого значения только кода символа или только атрибутов.

Отметим, что inch, winch, mvinch и mvwinch являются макросами.

scanw (fmt[, arg...])
wscanw (win, fmt[, arg...])
mvscanw (y, x, fmt[, arg...])
mvwscanw (win, y, x, fmt[, arg...])

Эти процедуры аналогичны scanf(3S) и по аргументам, и по возвращаемым значениям. В окне вызывается процедура wgetstr, а полученная цепочка символов сканируется в соответствии с указанным форматом.

vwscanw (win, fmt, varglist)

Эта процедура аналогична процедуре vwprintw, описанной выше. Она вызывает wscanw с переменным списком аргументов. Третий аргумент, varglist, является указателем на список аргументов, как это определено в . O работе со списком аргументов переменной длины см. vprintf(3S) и varargs(5).

Установка режимов вывода
Следующие процедуры устанавливают режимы вывода для пакета curses. Все режимы при инициализации равны FALSE. Нет необходимости перед вызовом endwin возвращать все режимы в состояние FALSE.

clearok (win, bf)

Если значение аргумента bf равно TRUE, то следующий вызов wrefresh приведет к очистке окна и полной его перерисовке. Это удобно, если содержимое окна испортилось, кроме того, иногда полная перерисовка окна дает лучший визуальный эффект, чем частичная.

idlok (win, bf)

Если значение аргумента bf равно TRUE, то процедуры пакета curses для вставки и удаления строк будут использовать аппаратные команды (если они имеются). Если bf равно FALSE, то curses этими командами пользуется редко (команды вставки/удаления символов используются всегда). Этот режим следует использовать только если Вам действительно нужно вставлять и удалять строки (например, в программе - экранном редакторе). По умолчанию этот режим имеет значение FALSE, так как применение аппаратной вставки и удаления строк в программах, в которых это реально не требуется, приводит к неприятным визуальным эффектам. Если использование аппаратных команд запрещено, то curses перерисовывает изменившуюся часть всех строк.

leaveok (win, bf)

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

setscrreg (top, bot)
wsetscrreg (win, top, bot)

Эти процедуры позволяют установить роллируемую область в окне. Аргументы top и bot - это номера верхней и нижней строки задаваемой области (номер верхней строки окна равен 0). Если задана область роллирования и установлен режим scrollok, то из нижней строки окна происходит роллирование только заданной области. Описываемые процедуры не требуют использования аппаратного роллирования полос, как это имеет место в терминале DEC vt100. Однако, если установлен режим idlok и терминал умеет роллировать полосы или вставлять и удалять строки, то эти возможности будут использованы процедурами вывода.

Отметим, что обе процедуры setscrreg и wsetscrreg являются макросами.

scrollok (win, bf)

Процедура служит для формирования режима обработки ситуации, когда курсор в окне выходит за границы роллируемой области из-за перевода строки в последней строке области или вывода символа в последнюю позицию последней строки. Если этот режим не установлен (значение bf равно FALSE), курсор остается в последней строке на том же месте. Если режим установлен (значение bf равно TRUE) происходит вызов wrefresh, а затем окно и экран физического терминала роллируются на одну строку вверх. Обратите внимание, что для того, чтобы физический экран роллировался, необходимо установить режим idlok.

nl ( )
nonl ( )

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

Установка режимов ввода
Следующие процедуры устанавливают режимы ввода для пакета curses. Установка режимов включает в себя обращение к системному вызову ioctl(2) и может оказывать влияние на другие режимы. Нет необходимости перед выполнением endwin возвращать все режимы в начальное состояние.

cbreak ( )
nocbreak ( )

Эти две процедуры соответственно устанавливают и сбрасывают режим CBREAK. В режиме CBREAK вводимые символы сразу передаются программе, обработка символов erase и kill не производится. В режиме NOCBREAK драйвер tty(7) буферизует вводимые символы до тех пор, пока не будет введен символ перевода строки или возврата каретки. Символы прерывания и управления передачей в этом режиме не затрагиваются [см. termio(7)]. Начальное состояние терминала может быть любым, поэтому, если требуется, необходимо явно вызвать процедуру cbreak или nocbreak. Большинство интерактивных программ, использующих curses, устанавливают режим CBREAK.

Отметим, что процедура cbreak устанавливает режим raw. См. также getch в разделе Ввод по поводу того, как описываемые процедуры взаимодействуют с процедурами echo и noecho.

echo ( )
noecho ( )

Эти процедуры управляют тем, отображаются ли на экране символы, вводимые по getch. Эхо, выполняемое драйвером, всегда отменено, но при инициализации для getch устанавливается режим ECHO, то есть вводимые символы отображаются. Авторы большинства интерактивных программ предпочитают самостоятельно отображать вводимые символы в отдельной части экрана, либо не отображать их вовсе, для чего вызывается процедура noecho. См. getch в разделе Ввод по поводу того, как описываемые процедуры взаимодействуют с процедурами cbreak и nocbreak.

halfdelay (tenths)

Этот режим похож на режим CBREAK тем, что вводимые символы сразу передаются программе. Однако если ни одна клавиша не была нажата на протяжении tenths десятых долей секунды, будет возвращено значение ERR. Число tenths должно быть от 1 до 255. Для выключения этого режима используется процедура nocbreak.

intrflush (win, bf)

Если установлен этот режим, то при нажатии одного из символов прерывания (interrupt, break, quit) весь ввод, накопленный в драйвере tty(7), будет проигнорирован, что позволяет быстро отреагировать на прерывание. Правда, состояние экрана при этом может перестать соответствовать представлению, имеющемуся в структурах curses. Отмена этого режима предотвращает очистку буферов в драйвере. Начальное значение данного режима зависит от состояния драйвера. Аргумент win игнорируется.

keypad (win, bf)

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

meta (win, bf)

Если этот режим установлен, все 8 бит символов, вводимых с клавиатуры, передаются программе, иначе процедура wgetch сбрасывает восьмой бит. Чтобы режим META работал правильно, необходимо, чтобы в базе данных terminfo(4) для данного терминала была задана характеристика km (клавиша МЕТА).

nodelay (win, bf)

Этот режим не позволяет процедуре wgetch уходить в ожидание. Если этот режим установлен и нет готового символа, то возвращается значение ERR. Если режим не установлен, то wgetch ожидает ввода следующего символа.

notimeout (win, bf)

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

raw ( )
noraw ( )

Устанавливается или отменяется режим RAW. Режим RAW аналогичен режиму CBREAK, вводимые символы сразу передаются программе. Отличие заключается в том, что символы прерывания (interrupt, quit), а также символы управления передачей (xon, xoff) передаются без интерпретации, сигналы при этом не генерируются. Режим RAW устанавливает восьмибитный ввод и вывод. Реакция на клавишу BREAK зависит от других бит в характеристиках драйвера tty(7), эти биты пакетом curses не устанавливаются.

typeahead (fildes)

Обычно curses выполняет следующий вид оптимизации. Перед выводом на экран проверяется, нет ли уже нажатых клавиш, и, если есть, то вывод откладывается до следующего вызова refresh или doupdate. Это позволяет быстрее реагировать на последовательности команд. Обычно для проверки используется дескриптор файла, переданного в качестве аргумента процедуре newterm, или stdin, если инициализация проводилась с помощью initscr. Процедура typeahead позволяет заменить проверяемый файл на файл с дескриптором fildes. Если fildes равен -1, то описанная выше оптимизация не выполняется.

Отметим, что fildes - это дескриптор файла, а не указатель на структуру типа FILE.

Запросы к оборудованию

baudrate ( )

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

char erasechar ( )

Возвращается текущее значение символа erase.

has_ic ( )

Истина, если терминал умеет вставлять и удалять символы.

has_il ( )

Истина, если терминал умеет вставлять и удалять строки.

char killchar ( )

Возвращается текущее значение символа kill.

char *longname ( )

Процедура возвращает указатель на статическую область, содержащую словесное описание данного терминала. Максимальная длина словесного описания 128 символов. К данной процедуре можно обращаться только после initscr или newterm. Статическая область изменяется при последующих вызовах newterm и не восстанавливается вызовами set_term, поэтому, если предполагается пользоваться словесными описаниями для нескольких терминалов, то описание необходимо скопировать в другое место.

Программируемые метки
Пакет curses дает доступ к программируемым меткам на клавишах, которые имеются на некоторых терминалах. Для тех терминалов, на которых нет программируемых меток, имеется возможность их эмуляции в верхней строке окна stdscr, при этом уменьшается на единицу размер окна stdscr и значение переменной LINES. Curses поддерживает восемь меток по восемь символов каждая.

slk_init (labfmt)

Чтобы использовать программируемые метки, процедура slk_init должна быть вызвана раньше процедур initscr и newterm. Если процедура initscr будет использовать верхнюю строку экрана для меток, то аргумент labfmt задает их расположение в строке. Если значение labfmt равно 0, метки размещаются тремя группами 3-2-3, а если значение labfmt равно 1, то двумя группами 4-4.

slk_set (labnum, label, labfmt)

Аргумент labnum - это номер метки, от 1 до 8. Аргумент label представляет собой цепочку символов (длиной не более 8), которая помещается в виде метки. Пустая цепочка или адрес, равный NULL, задают пустую метку. Значения labfmt, равные 0, 1 или 2, говорят о том, что метка соответственно выровнена влево, центрирована или выровнена вправо.

slk_refresh ( )
slk_noutrefresh ( )

Эти процедуры соответствуют процедурам wrefresh и wnoutrefresh. Большинство программ вызывают slk_noutrefresh, так как обычно довольно скоро приходится вызывать wrefresh.

char *slk_label (labnum)

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

slk_clear ( )

Программируемые метки убираются с экрана.

slk_restore ( )

Программируемые метки, убранные с экрана процедурой slk_clear, восстанавливаются.

slk_touch ( )

При следующем обращении к slk_noutrefresh все программируемые метки будут выведены на экран заново.

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

def_prog_mode ( )
def_shell_mode ( )

Сохранить текущие значения характеристик терминала, как значения, необходимые для выполнения самой программы (с пакетом curses) или программы shell (без пакета curses) для последующего восстановления процедурами reset_prog_mode и reset_shell_mode. Эти процедуры вызываются процедурой initscr.

reset_prog_mode ( )
reset_shell_mode ( )

Восстановить запомненные значения характеристик терминала для продолжения работы пакета curses или для запуска программы shell. Эти процедуры вызываются процедурами endwin и doupdate.

resetty ( )
savetty ( )

Эти процедуры запоминают и восстанавливают запомненные характеристики терминала. Процедура savetty запоминает характеристики в буфере, а resetty восстанавливает последние запомненные характеристики.

getsyx (y, x)

Аргументам y и x присваиваются значения координат курсора на виртуальном экране. Как и в getyx, перед именами переменных не нужно указывать &. Если установлен режим leaveok, то переменным присваиваются значения (-1,-1). Если верхние строки экрана были удалены с помощью процедуры ripoffline и полученные значения предполагается не просто передать процедуре setyx, а использовать еще как-то, то значение y должно быть скорректировано путем прибавления значения stdscr->_yoffset.

Отметим, что getsyx является макросом.

setsyx (y, x)

Виртуальный курсор устанавливается в позицию (y, x). Если оба значения y и x равны -1, то устанавливается режим leaveok. Две процедуры getsyx и setsyx созданы для того, чтобы библиотечные процедуры могли манипулировать окнами, не испортив текущей позиции курсора. Библиотечные процедуры вначале вызывают getsyx, затем производят манипуляции над окнами, вызывают для измененных окон wnoutrefresh, после чего вызывают setsyx и заканчивают вызовом doupdate.

ripoffline (line, init)

Эта процедура позволяет уменьшить размер экрана, ею пользуется процедура slk_init. Процедуру ripoffline необходимо вызывать раньше процедур initscr и newterm. Если значение line положительно, удаляется одна строка сверху окна sdtscr, если отрицательно - удаляется строка снизу. После этого из процедуры initscr вызывается процедура init с двумя аргументами: указателем на созданное окно единичной высоты и шириной этого окна в колонках. При вызове данной процедуры не гарантируется правильность глобальных переменных LINES и COLS (определенных в <curses.h>), кроме того, из этой процедуры нельзя обращаться к процедурам wrefresh и doupdate, но можно обращаться к wnoutrefresh.

Перед обращением к initscr или newterm процедуру ripoffline можно вызывать несколько раз (до пяти).

scr_dump (filename)

Текущее состояние виртуального экрана записывается в файл filename.

scr_restore (filename)

Текущее состояние виртуального экрана восстанавливается из файла filename, куда оно должно быть предварительно записано командой scr_dump. После восстановления необходимо вызвать процедуру doupdate для изображения восстановленного состояния.

scr_init (filename)

Содержимое файла filename используется для коррекции информации о том, что изображено на экране. Если данные пройдут проверку на корректность, то curses при следующей перерисовке экрана использует полученную информацию. Процедура scr_init обычно используется после initscr и после системного вызова system(3S) для сохранения состояния экрана, сформированного другим процессом, который должен предварительно, после обращения к endwin, обратиться к scr_dump. Проверка на корректность заключается в проверке времени модификации файла с состоянием экрана, кроме того в базе данных terminfo(4) для данного терминала должна присутствовать характеристика nrrmc.

curs_set (visibility)

Курсор делается невидимым, нормальным или более ярким, если значение visibility равно, соответственно, 0, 1 или 2.

draino (ms)

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

garbagedlines (win, begline, numlines)

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

napms (ms)

Пауза на ms миллисекунд.

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

Вначале должна быть вызвана процедура setupterm (эта процедура автоматически вызывается процедурами initscr и newterm. В ней присваиваются значения всем переменным, определенным в terminfo(4). Значения переменным terminfo(4) lines и columns присваиваются следующим образом: если определены переменные окружения LINES и COLUMNS, используются их значения. Иначе используются значения, заданные в базе данных terminfo(4).

Для того, чтобы программа имела доступ ко всем необходимым переменным, цепочкам, числам и флагам, в нее должны быть включены файлы <curses.h> и в указанном порядке. Параметризованные цепочки должны быть конкретизированы процедурой tparm. Все цепочки terminfo(4), включая цепочки, выходные для tparm, должны выводиться на экран процедурами tputs или putp. Перед завершением необходимо вызвать процедуру reset_shell_mode для восстановления характеристик терминала. Программы, в которых используется адресация курсора, должны вывести цепочку enter_ca_mode в начале работы и цепочку exit_ca_mode перед концом работы [см. terminfo(4)]. Программы, предусматривающие запуск порожденного процесса shell, должны вызвать процедуру reset_shell_mode и вывести цепочку exit_ca_mode перед запуском shell, а после завершения порожденного процесса необходимо вывести цепочку enter_ca_mode и вызвать процедуру reset_prog_mode. Обратите внимание на отличие этой процедуры от стандартной процедуры для пакета curses [см. endwin].

setupterm (term, fildes, erret)

Читает базу данных terminfo(4), инициализирует структуры данных terminfo(4). Структуры управления выводом для пакета curses при этом не устанавливаются. Тип терминала задается аргументом term, являющемся цепочкой символов. Если значение term равно NULL, используется значение переменной окружения TERM. Вывод ведется в файл с дескриптором fildes. Если значение erret не равно NULL, то setupterm возвратит значение OK или ERR и поместит в переменную *erret код завершения. Код, равный 1, означает нормальное завершение, 0 означает, что терминал не найден в базе данных, -1 означает, что не удалось найти саму базу данных terminfo(4). Если значение erret равно NULL, то в случае наличия ошибок setupterm напечатает сообщения о них и завершит программу. Таким образом, самый простой вызов, при котором используются только подразумеваемые значение, выглядит следующим образом:

	setupterm ((char *) 0, 1, (int *) 0)

Все переменные terminfo(4) булева, числового и символьного типа размещаются в структуре типа TERMINAL. После успешного завершения процедуры setupterm глобальной переменной cur_term типа TERMINAL * присваивается значение указателя на заполненную структуру. Этот указатель может быть сохранен перед следующим вызовом setupterm. Повторный вызов setupterm размещает в памяти новую структуру и записывает новую информацию в новое место.

set_curterm (nterm)

Аргумент nterm имеет тип TERMINAL *. Процедура set_curterm присваивает переменной cur_term значение nterm, после этого все переменные terminfo(4) получают значения, заданные для nterm.

del_curterm (oterm)

Аргумент oterm имеет тип TERMINAL *. Процедура del_curterm освобождает память, занятую структурой, на которую указывает oterm. Если oterm совпадает с cur_term, то после этого нельзя обращаться ни к одной переменной terminfo(4) до тех пор, пока снова не будет вызвана процедура setupterm.

restartterm (term, fildes, erret)

То же, что и setupterm после восстановления памяти.

char *tparm (str, p1, p2, p3, p4, p5, p6, p7, p8, p9)

Подставляет в цепочку str аргументы p1, p2, ... p9. Возвращается указатель на цепочку с подставленными аргументами.

tputs (str, count, putc)

Добавляет, если надо, заполнитель к цепочке str и выводит ее. Цепочка str должна быть значением какой либо символьной переменной terminfo(4), либо результатом работы процедур tparm, tsgetstr, tigetstr или tgoto. Аргумент count задает количество строк, которые затрагиваются выводом; если оно неизвестно, задается 1. Аргумент putc - это процедура, аналогичная putchar(3S). Этой процедуре символы передаются последовательно.

putp (str)

Процедура, вызывающая tputs (str, 1, putchar).

vidputs (attrs, putc)

Выводит цепочку, переводящую терминал в режим визуализации символов с атрибутами attrs - комбинацией атрибутов, описанных ниже, в разделе АТРИБУТЫ. Символы передаются процедуре putc, аналогичной putchar(3S).

mvcur (oldrow, oldcol, newrow, newcol)

Процедура нижнего уровня для перемещения курсора.

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

tigetflag (capname)

Если capname не является булевой характеристикой, возвращается значение -1.

tigetnum (capname)

Если capname не является числовой характеристикой, возвращается значение -2.

char *tigetstr (capname)

Если capname не является символьной характеристикой, возвращается значение (char*) -1.

char *boolnames [ ], *boolcodes [ ], *boolfnames [ ]
char *numnames [ ], *numcodes [ ], *numfnames [ ]
char *strnames [ ], *strcodes [ ], strfnames [ ]

Эти массивы, завершающиеся нулевыми байтами, содержат имена, коды termcap и длинные C-имена для каждой переменной terminfo(4).

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

tgetent (bp, name)

Найти элемент termcap для имени name. При эмуляции параметр bp игнорируется.

tgetflag (codename)

Получить булево значение элемента codename.

tgetnum (codename)

Получить числовое значение элемента codename.

char *tgetnum (codename, area)

Получить символьное значение элемента codename. Если указатель area не равен NULL, то поместить то же значение в буфер, на который указывает *area, и продвинуть *area. Для вывода возвращенной цепочки символов необходимо использовать процедуру tputs.

char *tgoto (cap, col, row)

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

tputs (str, count, putc)

См. выше раздел Процедуры уровня terminfo.

Дополнительные процедуры

traceoff ( )
traceon ( )

Включить и выключить трассировочную печать отладочной версии библиотеки curses (/usr/lib/ libdcurses.a). Эта библиотека доступна только тем, кто приобрел лицензию на исходные тексты пакета curses.

unctrl (c)

Этот макрос преобразует символ в цепочку, содержащую его печатное представление. Управляющие символы изображаются в виде ^X. Печатные символы не изменяются.

Отметим, что unctrl - это макрос, определенный в файле <unctrl.h>, автоматически подключающемся к <curses.h>.

char *keyname (c)

Возвращается цепочка символов, соответствующая клавише c.

filter ( )

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

Использование curscr
Спецокно curscr может использоваться только несколькими процедурами. Если обратиться к процедуре clearok с аргументом curscr, то следующее обращение к wrefresh для любого окна приведет к очистке экрана и затем его полной перерисовке. Если обратиться к процедуре wrefresh с аргументом curscr, то экран немедленно очистится и перерисуется. Именно так большинство программ осуществляет перерисовку экрана. Если curscr указывается в качестве аргумента процедур overlay, overwite или copywin, то доступ производится к текущему состоянию виртуального экрана терминала.

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

АТРИБУТЫ
Следующие атрибуты визуализации, определенные в файле <curses.h>, могут передаваться в качестве аргументов процедурам attron, attroff и attrset. Их можно также добавить (операцией логическое ИЛИ) к символам, передаваемым процедуре addch.

A_STANDOUT

Режим, в котором лучше всего выводить сообщения, привлекающие внимание.

A_UNDERLINE

Подчеркивание.

A_REVERSE

Инверсия.

A_BLINK

Мерцание.

A_DIM

Пониженная яркость.

A_BOLD

Выделение - жирность или повышенная яркость.

A_ALTCHARSET

Альтернативный набор символов.

A_CHARTEXT

Битная маска для выделения кода символа [см. winch].

A_ATTRIBUTES

Битная маска для выделения атрибутов [см. winch].

A_NORMAL

Битная маска для сброса всех атрибутов (например, attrset (A_NORMAL)).

ФУНКЦИОНАЛЯНЫЕ КЛАВИШИ
Следующие коды функциональных клавиш, определенные в файле <curses.h>, могут быть возвращены процедурой getch, если установлен режим keypad. Отметим, что не все клавиши на конкретном терминале могут поддерживаться, особенно если они не посылают уникальных кодов, а также если определение клавиши отсутствует в базе данных terminfo(4).

ПСЕВДОГРАФИКА
Следующие переменные могут быть использованы для рисования рамочек на экране терминала с помощью процедуры waddch. Если соответствующий символ может быть выведен на терминал, значение переменной будет иметь установленный бит A_ALTCHARSET. В противном случае переменная имеет подразумеваемое значение. Отправной точкой для набора символов послужили возможности терминала vt100.

ДИАГНОСТИКА
Все процедуры, для которых при описании не указано возвращаемое значение, возвращают целое значение OK при успешном завершении и ERR при неудаче.

Все макросы возвращают значение то же, что и соответствующие w-процедуры, кроме setscrreg, wsetscrreg, getsyx, getyx, getbegy, getmaxyx, возвращаемые значения которых описаны выше.

В случае ошибки результат процедур, возвращающих значения-указатели, равен (тип *) NULL.

СЮРПРИЗЫ
В настоящее время при использовании пакета curses непрерывно производится проверка ввода путем чтения без ожидания и возврата символа обратно, если он вдруг оказался прочитанным. Проверка ввода начинается после первого вызова wgetch. В дальнейшем, когда появится соответствующая поддержка со стороны ядра операционной системы, это будет изменено. Программы, которые перемешивают ввод от пакета curses и свой собственный, должны вызвать typeahead (-1) для отключения проверки ввода.

Аргумент функции napms в настоящее время округляется до ближайшего целого числа секунд.

Процедура draino (ms) работает, только если значение ms равно 0.

ПРЕДОСТЕРЕЖЕНИЯ
Для версии операционной системы 3.1 необходимо пользоваться пакетом curses версии 3.1. Программы, использовавшие пакет curses в операционной системе версии 2 для выполнения в операционной системе версии 3.1 требуют пересборки об ектных файлов с новой библиотекой libcurses.a версии 3.1. Если Ваша программа не пользуется новыми возможностями пакета версии 3.1, то об ектные файлы можно собрать с библиотекой версии 2 и выполнять в операционной системе версии 2.

Библиотеки plot(3X) и curses(3X) используют одинаковые имена процедур erase и move, причем версии пакета curses являются макросами. Если Вам требуется работать с обеими библиотеками, то соответствующие фрагменты нужно поместить в разные исходные файлы или использовать в тексте, работающем с пакетом plot(3X), директивы #undef move и #undef erase.

Между вызовами initscr и endwin выводить на экран можно только с помощью процедур пакета curses. Использование для этих целей процедур стандартного пакета ввода/вывода [см. stdio(3S)] может привести к непредсказуемым результатам.

СМ. ТАКЖЕ
ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S), system(3S), vprintf(3S), profile(4), term(4), terminfo(4), varargs(5).
cc(1), ld(1) в Справочнике пользователя.
termio(7), tty(7) в Справочнике администратора.