Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > C

curses_intro(3X)

X/Open CURSES
HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

curses_intro — terminal and printer handling and optimization package

DESCRIPTION

Use and Implementation of Interfaces

These routines provide a method for updating screens with reasonable optimization in a terminal independent manner. Each of the following statements applies unless explicitly stated otherwise in the detailed descriptions that follow. If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer), the behaviour is undefined. Any function declared in a header may also be implemented as a macro defined in the header, so a library function should not be declared explicitly if its header is included. Any macro definition of a function can be suppressed locally by enclosing the name of the function in parentheses, because the name is then not followed by the left parenthesis that indicates expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro. The use of the C-language #undef construct to remove any such macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro will expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those function-like macros described in the following sections may be invoked in an expression anywhere a function with a compatible return type could be called.

Provided that a library function can be declared without reference to any type defined in a header, it is also permissible to declare the function, either explicitly or implicitly, and use it without including its associated header. If a function that accepts a variable number of arguments is not declared (explicitly or by including its associated header), the behaviour is undefined.

As a result of changes introduced in this version of the Curses Specification, application writers are only required to include the minimum number of headers. Implementations of XSI-conformant systems will make all necessary symbols visible as described in the Headers section of this document.

C Language Definition

The C language that is the basis for the synopses and code examples in this document is ISO C, as specified in the referenced ISO C standard. Common Usage C, which refers to the C language before standardisation, was the basis for previous editions of this specification.

The Compilation Environment

Applications should ensure that the feature test macro _XOPEN_SOURCE is defined before inclusion of any header. This is needed to enable the functionality described in this document, and possibly to enable functionality defined elsewhere in the Common Applications Environment.

The _XOPEN_SOURCE macro may be defined automatically by the compilation process, but to ensure maximum portability, applications should make sure that _XOPEN_SOURCE is defined by using either compiler options or #define directives in the source files, before any #include directives. Identifiers in this document may only be undefined using the #undef directive. These #undef directives must follow all #include directives of any headers.

Most strictly conforming POSIX and ISO C applications will compile on systems compliant to this specification. However, an application which uses any of the items marked as an extension to POSIX and ISO C, for any purpose other than that shown here, may not compile. In such cases, it may be necessary to alter those applications to use alternative identifiers.

Since this document is aligned with the ISO C standard, and since all functionality enabled by the _POSIX_C_SOURCE set equal to 2 should be enabled by _XOPEN_SOURCE, there should be no need to define either _POSIX_SOURCE or _POSIX_C_SOURCE if _XOPEN_SOURCE is defined. Therefore, if _XOPEN_SOURCE is defined and _POSIX_SOURCE is defined, or _POSIX_C_SOURCE is set equal to 1 or 2, the behaviour is the same as if only _XOPEN_SOURCE is defined. However should _POSIX_C_SOURCE be set to a value greater than 2, the behaviour is undefined.

The c89 and cc utilities recognise the additional -l operand for standard libraries:

-l curses

This operand makes visible all library functions referenced in this specification, (except for those labelled ENHANCED CURSES and except for portions marked with the EC margin legend).

If the implementation defines _XOPEN_CURSES and if the application defines the _XOPEN_SOURCE_EXTENDED feature test macro, then -l curses also makes visible all library functions referenced in this specification and labelled ENHANCED CURSES.

An application that uses any API specified as ENHANCED CURSES must define _XOPEN_SOURCE_EXTENDED = 1 in each source file or as part of its compilation environment. When _XOPEN_SOURCE_EXTENDED = 1 is defined in a source file, it must appear before any header is included.

If the implementation supports the utilities marked DEVELOPMENT in the Curses Specification, the lint utility recognises the additional -l curses operand for standard libraries:

-l curses

Names the library llib-lcurses.ln, which will contain functions specified in this document.

It is unspecified whether the library llib-lcurses.ln exists as a regular file.

The X/Open Name Space (ENHANCED CURSES)

The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance.

All identifiers in this document are defined in at least one of the headers <curses.h>, <term.h>, <unctrl.h>. When _XOPEN_SOURCE is defined, each header defines or declares some identifiers, potentially conflicting with identifiers used by the application. The set of identifiers visible to the application consists of precisely those identifiers from the header pages of the included headers, as well as additional identifiers reserved for the implementation. In addition, some headers may make visible identifiers from other headers as indicated on the relevant header pages.

The identifiers reserved for use by the implementation are described below.

1

Each identifier with external linkage described in the header section is reserved for use as an identifier with external linkage if the header is included.

2

Each macro name described in the header section is reserved for any use if the header is included.

3

Each identifier with file scope described in the header section is reserved for use as an identifier with file scope in the same name space if the header is included.

4

All identifiers consisting of exactly 2 uppercase letters.

If any header in the following table is included, identifiers with the prefixes, suffixes or complete names shown are reserved for use by the implementation.

HeaderPrefixSuffixComplete Name
<curses.h>add, attr, get, in, mousr, mv, scr, slk, un, wadd, wattr, wbkg, win  
ANY header _t 

If any header in the following table is included, macros with the prefixes shown may be defined. After the last inclusion of a given header, an application may use identifiers with the corresponding prefixes for its own purpose, provided their use is preceded by an #undef of the corresponding macro.

HeaderPrefix
<curses.h>A_, ACS_, ALL_, BUTTON, COLOR_, KEY_, MOUSE, REPORT_, WA_, WACS_
<term.h>ext_

The following identifiers are reserved, regardless of the inclusion of headers:

1

All identifiers that begin with an underscore and either an uppercase letter or another underscore are always reserved for any use by the implementation.

2

All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary identifier and tag name spaces.

3

All identifiers listed as reserved in the X/Open System Interfaces and Headers, Issue 4, Version 2 specification are reserved for use as identifiers with external linkage.

All the identifiers defined in this document that have external linkage are always reserved for use as identifiers with external linkage.

No other identifiers are reserved.

Applications must not declare or define identifiers with the same name as an identifier reserved in the same context. Since macro names are replaced whenever found, independent of scope and name space, macro names matching any of the reserved identifier names must not be defined if any associated header is included.

Headers may be included in any order, and each may be included more than once in a given scope, with no difference in effect from that of being included only once.

If used, a header must be included outside of any external declaration or definition, and it must be first included before the first reference to any type or macro it defines, or to any function or object it declares. However, if an identifier is declared or defined in more than one header, the second and subsequent associated headers may be included after the initial reference to the identifier. Prior to the inclusion of a header, the program must not define any macros with names lexically identical to symbols defined by that header.

Interfaces Implemented as Macros (ENHANCED CURSES)

The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance.

The following interfaces with arguments must be implemented as macros. The relevance to the application programmer is that the & character cannot be used before the arguments.

MacrosManpage
COLOR_PAIR(), PAIR_NUMBER()can_change_color(3X)
getbegyx(), getmaxyx(), getparyx(), getyx()getbegyx(3X)

The descriptions in <curses.h>, <term.h>, <unctrl.h> list other macros, like COLOR_BLACK, that do not take arguments.

Relationship to the X/Open System Interfaces and Headers, Issue 4, Version 2 Specification

Error Numbers

Most functions provide an error number in errno, which is either a variable or macro defined in <errno.h>; the macro expands to a modifiable lvalue of type int.

A list of valid values for errno and advice to application writers on the use of errno appears in the X/Open System Interfaces and Headers, Issue 4, Version 2 specification .

Data Types

All of the data types used by Curses functions are defined by the implementation. The following list describes these types:

attr_t

An integral type that can contain at least an unsigned short. The type attr_t is used to hold an ORed set of attributes defined in <curses.h> that begin with the prefix WA_.

bool

Boolean data type

chtype

An integral type that can contain at least an unsignedchar and attributes. Values of type chtype are formed by ORing together an unsignedchar value and zero or more of the base attribute flags defined in <curses.h> that have the A_ prefix. The application can extract these components of a chtype value using the base masks defined in <curses.h> for this purpose.

The chtype data type also contains a colour-pair. Values of type chtype are formed by ORing together an unsignedchar value, a colour-pair, and zero or more of the attributes defined in <curses.h> that begin with the prefix A_. The application can extract these components of a chtype value using the masks defined in <curses.h> for this purpose.

SCREEN

An opaque terminal representation.

wchar_t

As described in <stddef.h>.

cchar_t

A type that can reference a string of wide characters of up to an implementation-dependent length, a colour-pair, and zero or more attributes from the set of all attributes defined in this document. A null cchar_t object is an object that references a empty wide-character string. Arrays of cchar_t objects are terminated by a null cchar_t object.

WINDOW

An opaque window representation.

Interface Overview

Components

A Curses initialisation function, usually initscr(), determines the terminal model in use, by reference to either an argument or an environment variable. If that model is defined in terminfo, then the same terminfo entry tells Curses exactly how to operate the terminal.

In this case, a comprehensive API lets the application perform terminal operations. The Curses run-time system receives each terminal request and sends appropriate commands to the terminal to achieve the desired effect.

Relationship to the Open System Interface Definitions, Issue 4, Version 2 Specification

Applications using Curses should not also control the terminal using capabilities of the general terminal interface defined in the X/Open System Interface Definitions, Issue 4, Version 2 specification, Chapter 9, "General Terminal Interface".

There is no requirement that the paradigms that exist while in Curses mode be carried over outside the Curses environment (see def_prog_mode(3X)).

Relationship to Signals

Curses implementations may provide for special handling of the SIGINT, SIGQUIT and SIGTSTP signals if their disposition is SIGDFL at the time initscr() is called (see initscr(3X)).

Any special handling for these signals may remain in effect for the life of the process or until the process changes the disposition of the signal.

None of the Curses functions are required to be safe with respect to signals (see sigaction(2) in the X/Open System Interfaces and Headers, Issue 4, Version 2 specification).

The behaviour of Curses with respect to signals not defined by the X/Open System Interfaces and Headers, Issue 4, Version 2 specification is unspecified.

Screens, Windows and Terminals

Screen

A screen is the physical output device of the terminal. In Curses, a SCREEN data type is an opaque data type associated with a terminal. Each window (see below) is associated with a SCREEN.

Windows

The Curses functions permit manipulation of window objects, which can be thought of as two-dimensional arrays of characters and their renditions. A default window called stdscr, which is the size of the terminal screen, is supplied. Others may be created with newwin().

Variables declared as WINDOW * refer to windows (and to subwindows, derived windows, and pads, as described below). These data structures are manipulated with functions described on the reference manpages in terminfo(4). Among the most basic functions are move() and addch(). More general versions of these functions are included that allow a process to specify a window.

After using functions to manipulate a window, refresh() is called, telling Curses to make the CRT screen look like stdscr.

Line drawing characters may be specified to be output. On input, Curses is also able to translate arrow and function keys that transmit escape sequences into single values. The line drawing characters and input values use names defined in <curses.h>.

Each window has a flag that indicates that the information in the window could differ from the information displayed on the terminal device. Making any change to the contents of the window, moving or modifying the window, or setting the window's cursor position, sets this flag (touches the window).

Subwindows

A subwindow is a window, created within another window (called the parent window), and positioned relative to the parent window. A subwindow can be created by calling derwin(), newpad() or subwin(). Changes made to a subwindow do not affect its parent window.

Subwindows can be created from a parent window by calling subwin(). The position and size of subwindows on the screen must be identical to or totally within the parent window. Changes to either the parent window or the subwindow affect both. Window clipping is not a property of subwindows.

Ancestors

The term ancestor refers to a window's parent, or its parent, or so on.

Derived Windows

Derived windows are subwindows whose position is defined by reference to the parent window rather than in absolute screen coordinates. Derived windows are otherwise no different from subwindows.

Pads

A pad is a specialised case of subwindow that is not necessarily associated with a viewable part of a screen. Functions that deal with pads are all discussed in newpad().

Terminal

A terminal is the logical input and output device through which character-based applications interact with the user. TERMINAL is an opaque data type associated with a terminal. A TERMINAL data structure primarily contains information about the capabilities of the terminal, as defined by terminfo. A TERMINAL also contains information about the terminal modes and current state for input and output operations. Each screen (see above) is associated with a TERMINAL.

Characters

Character Storage Size

Historically, a position on the screen has corresponded to a single stored byte. This correspondence is no longer true for several reasons:

  • Some characters may occupy several columns when displayed on the screen (see Multicolumn Characters).

  • Some characters may be nonspacing characters, defined only in association with a spacing character (see Nonspacing Characters (ENHANCED CURSES)).

  • The number of bytes to hold a character from the extended character sets depends on the LC_CTYPE locale category.

The internal storage format of characters and renditions is unspecified. There is no implied correspondence between the internal storage format and the external representation of characters and renditions in objects of type chtype and cchar_t.

Multicolumn Characters

Some character sets define multicolumn characters that occupy more than one column position when displayed on the screen.

Writing a character whose width is greater than the width of the destination window is an error.

Attributes

Each character can be displayed with attributes such as underlining, reverse video or colour on terminals that support such display enhancements. Current attributes of a window are applied to all characters that are written into the window with waddch(), wadd_wch(), waddstr(), waddchstr(), waddwstr(), wadd_wchstr() and wprintw(). Attributes can be combined.

Attributes can be specified using constants with the A_ prefix specified in <curses.h>. The A_ constants manipulate attributes in objects of type chtype. Additional attributes can be specified using constants with the WA_ prefix. The WA_ constants manipulate attributes in objects of type attr_t.

Two constants that begin with A_ and WA_ and that represent the same terminal capability refer to the same attribute in the terminfo database and in the window data structure. The effect on a window does not differ depending on whether the application specifies A_ or WA_ constants. For example, when an application updates window attributes using the interfaces that support the A_ values, a query of the window attribute using the function that returns WA_ values reflects this update. When it updates window attributes using the interfaces that support the WA_ values, for which corresponding A_ values exist, a query of the window attribute using the function that returns A_ values reflects this update.

Rendition

The rendition of a character displayed on the screen is its attributes and a colour-pair.

The rendition of a character written to the screen becomes a property of the character and moves with the character through any scrolling and insert/delete line/character operations. To the extent possible on a particular terminal, a character's rendition corresponds to the graphic rendition of the character put on the screen.

If a given terminal does not support a rendition that an application program is trying to use, Curses may substitute a different rendition for it.

Colours are always used in pairs (referred to as colour-pairs). A colour-pair consists of a foreground colour (for characters) and a background colour (for the field on which the characters are displayed).

Nonspacing Characters

The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance.

Some character sets may contain nonspacing characters. (Nonspacing characters are those for which wcwidth() returns a width of zero.) The application may write nonspacing characters to a window. Every nonspacing character in a window is associated with a spacing character and modifies the spacing character. Nonspacing characters in a window cannot be addressed separately. A nonspacing character is implicitly addressed whenever a Curses operation affects the spacing character with which the nonspacing character is associated.

Nonspacing characters do not support attributes. For interfaces that use wide characters and attributes, the attributes are ignored if the wide character is a nonspacing character. Multicolumn characters have a single set of attributes for all columns. The association of nonspacing characters with spacing characters can be controlled by the application using the wide character interfaces. The wide character string functions provide codeset-dependent association.

Two typical effects of a nonspacing character associated with a spacing character called c, are as follows:

  • The nonspacing character may modify the appearance of c. (For instance, there may be nonspacing characters that add diacritical marks to characters. However, there may also be spacing characters with built-in diacritical marks.)

  • The nonspacing character may bridge c to the character following c. (Examples of this usage are the formation of ligatures and the conversion of characters into compound display forms, words, or ideograms.)

Implementations may limit the number of nonspacing characters that can be associated with a spacing character, provided any limit is at least 5.

Complex Characters

A complex character is a set of associated characters, which may include a spacing character and may include any nonspacing characters associated with it. A spacing complex character is a spacing character followed by any nonspacing characters associated with it. That is, a spacing complex character is a complex character that includes one spacing character. An example of a code set that has complex characters is ISO/IEC 10646-1:1993.

A complex character can be written to the screen; if it does not include a spacing character, any nonspacing characters are associated with the spacing complex character that exists at the specified screen position. When the application reads information back from the screen, it obtains spacing complex characters.

The cchar_t data type represents a complex character and its rendition. When a cchar_t represents a nonspacing complex character (that is, when there is no spacing character within the complex character), then its rendition is not used; when it is written to the screen, it uses the rendition specified by the spacing character already displayed.

An object of type cchar_t can be initialised using setcchar() and its contents can be extracted using getcchar(). The behaviour of functions that take a cchar_t input argument is undefined if the application provides a cchar_t value that was not initialised in this way or obtained from a Curses function that has a cchar_t output argument.

Window Properties

Associated with each window are the following properties that affect the placing of characters into the window (see Rendition of Characters Placed into a Window).

Window Rendition

Each window has a rendition, which is separate from the rendition component of the window's background property described below.

Window Background

Each window has a background property. The background property specifies:

  • A spacing complex character (the background character) that will be used in a variety of situations where visible information is deleted from the screen.

  • A rendition to use in displaying the background character in those situations, and in other situations specified in Rendition of Characters Placed into a Window.

Conceptual Operations

Screen Addressing

Many Curses functions use a coordinate pair. In the DESCRIPTION, coordinate locations are represented as (y, x) since the y argument always precedes the x argument in the function call. These coordinates denote a line/column position, not a character position.

The coordinate y always refers to the row (of the window), and x always refers to the column. The first row and the first column is number 0, not 1. The position (0, 0) is the window's origin.

For example, for terminals that display the ISO 8859-1 character set (with left-to-right writing), (0, 0) represents the upper lefthand corner of the screen.

Functions that start with mv take arguments that specify a (y, x) position and move the cursor (as though move() were called) before performing the requested action. As part of the requested action, further cursor movement may occur, specified on the respective reference manpage.

Basic Character Operations

Adding (Overwriting)

The Curses functions that contain the word add, such as addch(), actually specify one or more characters to replace (overwrite) characters already in the window. If these functions specify only nonspacing characters, they are appended to a spacing character already in the window; see also Nonspacing Characters (ENHANCED CURSES).

When replacing a multicolumn character with a character that requires fewer columns, the new character is added starting at the specified or implied column position. All columns that the former multicolumn character occupied that the new character does not require are orphaned columns, which are filled using the background character and rendition.

Replacing a character with a character that requires more columns also replaces one or more subsequent characters on the line. This process may also produce orphaned columns.

Truncation, Wrapping and Scrolling

If the application specifies a character or a string of characters such that writing them to a window would extend beyond the end of the line (for example, if the application tries to deposit any multicolumn character at the last column in a line), the behaviour depends on whether the function supports line wrapping:

  • If the function does not wrap, it fails.

  • If the function wraps, then it places one or more characters in the window at the start of the next line, beginning with the first character that would not completely fit on the original line.

    If the final character on the line is a multicolumn character that does not completely fit on the line, the entire character wraps to the next line and columns at the end of the original line may be orphaned.

    If the original line was the last line in the window, the wrap may cause a scroll to occur:

    If scrolling is enabled, a scroll occurs. The contents of the first line of the window are lost. The contents of each remaining line in the window move to the previous line. The last line of the window is filled with any characters that wrapped. Any remaining space on the last line is filled with the background character and rendition.

    If scrolling is disabled, any characters that would extend beyond the last column of the last line are truncated.

    The scrollok() function enables and disables scrolling.

Some add functions move the cursor just beyond the end of the last character added. If this position is beyond the end of a line, it causes wrapping and scrolling under the conditions specified in the second bullet above.

Insertion

Insertion functions (such as insch()) insert characters immediately before the character at the specified or implied cursor position.

The insertion shifts all characters that were formerly at or beyond the cursor position on the cursor line toward the end of that line. The disposition of the characters that would thus extend beyond the end of the line depends on whether the function supports wrapping:

  • If the function does not wrap, those characters are removed from the window. This may produce orphaned columns.

  • If the function supports wrapping, the effect is as described above in truncation (except that the overwriting discussed in the final dash is an insertion).

If multicolumn characters are displayed, some cursor positions are within a multicolumn character but not at the beginning of a character. Any request to insert data at a position that is not the beginning of a multicolumn character will be adjusted so that the actual cursor position is at the beginning of the multicolumn character in which the requested position occurs.

There are no warning indications relative to cursor relocation. The application should not maintain an image of the cursor position, since this constitutes placing terminal-specific information in the application and defeats the purpose of using Curses.

Portable applications cannot assume that a cursor position specified in an insert function is a reusable indication of the actual cursor position.

Deletion

Deletion functions (such as delch()) delete the simple or complex character at the specified or implied cursor position, no matter which column of the character this is. All column positions are replaced by the background character and rendition and the cursor is not relocated. If a character-deletion operation would cause a previous wrapping operation to be undone, then the results are unspecified.

Window Operations

Overlapping a window (that is, placing one window on top of another) and overwriting a window (that is, copying the contents of one window into another) follows the operation of overwriting multicolumn glyphs around its edge. Any orphaned columns are handled as in the character operations.

Characters that Straddle the Subwindow Border

A subwindow can be defined such that multicolumn characters straddle the subwindow border. The character operations deal with these straddling characters as follows:

  • Reading the subwindow with a function such as in_wch() reads the entire straddling character.

  • Adding, inserting or deleting in the subwindow deletes the entire straddling character before the requested operation begins and does not relocate the cursor.

  • Scrolling lines in the subwindow has the following effects:

    A straddling character at the start of the line is completely erased before the scroll operation begins.

    A straddling character at the end of the line moves in the direction of the scroll and continues to straddle the subwindow border. Column positions outside the subwindow at the straddling character's former position are orphaned unless another straddling character scrolls into those positions.

If the application calls a function such as border(), the above situations do not occur because writing the border on the subwindow deletes any straddling characters.

In the above cases involving multicolumn characters, operations confined to a subwindow can modify the screen outside the subwindow. Therefore, saving a subwindow, performing operations within the subwindow, and then restoring the subwindow may disturb the appearance of the screen. To overcome these effects (for example, for pop-up windows), the application should refresh the entire screen.

Special Characters

Some functions process special characters as specified below.

In functions that do not move the cursor based on the information placed in the window, these special characters would only be used within a string in order to affect the placement of subsequent characters; the cursor movement specified below does not persist in the visible cursor beyond the end of the operation. In functions that do move the cursor, these special characters can be used to affect the placement of subsequent characters and to achieve movement of the visible cursor.

backspace

Unless the cursor was already in column 0, backspace moves the cursor one column toward the start of the current line and any characters after the backspace are added or inserted starting there.

carriage return

Unless the cursor was already in column 0, carriage return moves the cursor to the start of the current line. Any characters after the carriage return are added or inserted starting there.

newline

In an add operation, Curses adds the background character into successive columns until reaching the end of the line. Scrolling occurs as described in Truncation, Wrapping and Scrolling. Any characters after the newline character are added at the start of the new line.

In an insert operation, newline moves the cursor to the start of a new line (causing scrolling as described in Truncation, Wrapping and Scrolling). Any characters after the newline character are placed at the start of the new line.

The filter() function may inhibit this processing.

tab

Tab characters in text move subsequent characters to the next horizontal tab stop. By default, tab stops are in column 0, 8, 16, and so on.

In an insert or add operation, Curses inserts or adds, respectively, the background character into successive columns until reaching the next tab stop. If there are no more tab stops in the current line, wrapping and scrolling occur as described in Truncation, Wrapping and Scrolling.

Control Characters

The Curses functions that perform special-character processing conceptually convert control characters to the caret (^) character followed by a second character (which is an uppercase letter if it is alphabetic) and write this string to the window in place of the control character. The functions that retrieve text from the window will not retrieve the original control character.

Rendition of Characters Placed into a Window

When the application adds or inserts characters into a window, the effect is as follows:

If the character is not the space character, then the window receives:

  • the character that the application specifies

  • the colour that the application specifies; or the window colour, if the application does not specify a colour

  • the attributes specified, ORed with the window attributes.

If the character is the space character, then the window receives:

  • the background character

  • the colour that the application specifies; or the background colour, if the application does not specify a colour

  • the attributes specified, ORed with the background attributes.

Input Processing

The Curses input model provides a variety of ways to obtain input from the keyboard.

Keypad Processing

The application can enable or disable keypad translation by calling keypad(). When translation is enabled, Curses attempts to translate a sequence of terminal input that represents the pressing of a function key into a single key code. When translation is disabled, Curses passes terminal input to the application without such translation, and any interpretation of the input as representing the pressing of a keypad key must be done by the application.

The complete set of key codes for keypad keys that Curses can process is specified by the constants defined in <curses.h> whose names begin with KEY_. Each terminal type described in the terminfo database may support some or all of these key codes. The terminfo database specifies the sequence of input characters from the terminal type that correspond to each key code (see Keypad in terminfo(4)).

The Curses implementation cannot translate keypad keys on terminals where pressing the keys does not transmit a unique sequence.

When translation is enabled and a character that could be the beginning of a function key (such as escape) is received, Curses notes the time and begins accumulating characters. If Curses receives additional characters that represent the pressing of a keypad key, within an unspecified interval from the time the first character was received, then Curses converts this input to a key code for presentation to the application. If such characters are not received during this interval, translation of this input does not occur and the individual characters are presented to the application separately. (Because Curses waits for this interval to accumulate a key code, many terminals experience a delay between the time a user presses the escape key and the time the escape is returned to the application.)

In addition, No Timeout Mode provides that in any case where Curses has received part of a function key sequence, it waits indefinitely for the complete key sequence. The "unspecified interval" in the previous paragraph becomes infinite in No Timeout Mode. No Timeout Mode allows the use of function keys over slow communication lines. No Timeout Mode lets the user type the individual characters of a function key sequence, but also delays application response when the user types a character (not a function key) that begins a function key sequence. For this reason, in No Timeout Mode many terminals will appear to hang between the time a user presses the escape key and the time another key is pressed. No Timeout Mode is switchable by calling notimeout().

If any special characters (see Special Characters) are defined or redefined to be characters that are members of a function key sequence, then Curses will be unable to recognise and translate those function keys.

Several of the modes discussed below are described in terms of availability of input. If keypad translation is enabled, then input is not available once Curses has begun receiving a keypad sequence until the sequence is completely received or the interval has elapsed.

Input Mode

The X/Open System Interface Definitions, Issue 4, Version 2 specification ("Special Characters") defines flow-control characters, the interrupt character, the erase character, and the kill character. Four mutually exclusive Curses modes let the application control the effect of these input characters:

Input Mode

Effect

Cooked Mode

This achieves normal line-at-a-time processing with all special characters handled outside the application. This achieves the same effect as canonical-mode input processing as specified in the X/Open System Interface Definitions, Issue 4, Version 2 specification . The state of the ISIG and IXON flags are not changed upon entering this mode by calling cbreak(), and are set upon entering this mode by calling noraw().

The implementation supports erase and kill characters from any supported locale, no matter what the width of the character is.

cbreak Mode

Characters typed by the user are immediately available to the application and Curses does not perform special processing on either the erase character or the kill character. An application can select cbreak mode to do its own line editing but to let the abort character be used to abort the task. This mode achieves the same effect as noncanonical-mode, Case B input processing (with MIN set to 1 and ICRNL cleared) as specified in the X/Open System Interface Definitions, Issue 4, Version 2 specification. The state of the ISIG and IXON flags are not changed upon entering this mode.

Half-Delay Mode

The effect is the same as cbreak, except that input functions wait until a character is available or an interval defined by the application elapses, whichever comes first. This mode achieves the same effect as noncanonical-mode, Case C input processing (with TIME set to the value specified by the application) as specified in the X/Open System Interface Definitions, Issue 4, Version 2 specification . The state of the ISIG and IXON flags are not changed upon entering this mode.

Raw Mode

Raw mode gives the application maximum control over terminal input. The application sees each character as it is typed. This achieves the same effect as noncanonical mode, Case D input processing as specified in the X/Open System Interface Definitions, Issue 4, Version 2 specification . The ISIG and IXON flags are cleared upon entering this mode.

The terminal interface settings are recorded when the process calls initscr() or newterm() to initialise Curses and restores these settings when endwin() is called. The initial input mode for Curses operations is unspecified unless the implementation supports Enhanced Curses compliance, in which the initial input mode is cbreak mode.

The behaviour of the BREAK key depends on other bits in the display driver that are not set by Curses.

Delay Mode

Two mutually exclusive delay modes specify how quickly certain Curses functions return to the application when there is no terminal input waiting when the function is called:

No Delay

The function fails.

Delay

The application waits until the implementation passes text through to the application. If cbreak or Raw Mode is set, this is after one character. Otherwise, this is after the first newline character, end-of-line character, or end-of-file character.

The effect of No Delay Mode on function key processing is unspecified.

Echo Processing

Echo mode determines whether Curses echoes typed characters to the screen. The effect of Echo mode is analogous to the effect of the ECHO flag in the local mode field of the termios structure associated with the terminal device connected to the window. However, Curses always clears the ECHO flag while it is operating, to inhibit the operating system from performing echoing. The method of echoing characters is not identical to the operating system's method of echoing characters, because Curses performs additional processing of terminal input.

If in Echo mode, Curses performs its own echoing: Any visible input character is stored in the current or specified window by the input function that the application called, at that window's cursor position, as though addch() were called, with all consequent effects such as cursor movement and wrapping.

If not in Echo mode, any echoing of input must be performed by the application. Applications often perform their own echoing in a controlled area of the screen, or do not echo at all, so they disable Echo mode.

The Set of Curses Functions

The Curses functions allow: overall screen, window and pad manipulation; output to windows and pads; reading terminal input; control over terminal and Curses input and output options; environment query functions; colour manipulation; use of soft label keys; access to the terminfo database of terminal capabilities; and access to low-level functions.

Function Name Conventions

The reference manpages present families of multiple Curses functions. Most function families have different functions that give the programmer the following options:

  • A function with the basic name operates on the window stdscr. A function with the same name plus the w prefix operates on a window specified by the win argument.

    When the reference manpage for a function family refers to the current or specified window, it means stdscr for the basic functions and the window specified by win for any w function.

    Functions whose names have the p prefix require an argument that is a pad instead of a window.

  • A function with the basic name operates based on the current cursor position (of the current or specified window, as described above). A function with the same name plus the mv prefix moves the cursor to a position specified by the y and x arguments before performing the specified operation.

    When the reference manpage for a function family refers to the current or specified position, it means the cursor position for the basic functions and the position (y, x) for any mv function.

    The mvw prefix exists and combines the mv semantics discussed here with the w semantics discussed above. The window argument is always specified before the coordinates.

  • A function with the basic name is often provided for historical compatibility and operates only on single-byte characters. A function with the same name plus the w infix operates on wide (multibyte) characters. A function with the same name plus the _w infix operates on complex characters and their renditions.

  • When a function with the basic name operates on a single character, there is sometimes a function with the same name plus the n infix that operates on multiple characters. An n argument specifies the number of characters to process. The respective manpage specifies the outcome if the value of n is inappropriate.

Function Families Provided

Function NamesDescriptionswcRefer to
 Add (Overwrite)    
[mv][w]addch()add a characterYYYaddch(3X)
[mv][w]addch[n]str()add a character stringNNNaddchstr(3X)
[mv][w]add[n]str()add a stringYYYaddnstr(3X)
[mv][w]add[n]wstr()add a wide-character stringYYYaddnwstr(3X)
[mv][w]add_wch()add a wide character and renditionYYYadd_wch(3X)
[mv][w]add_wch[n]str()add an array of wide characters and renditions?NNadd_wchnstr(3X)
 Change Renditions    
[mv][w]chgat()change renditions of characters in a window-NNchgat(3X)
 Delete    
[mv][w]delch()delete a character--Ndelch(3X)
 Get (Input from Keyboard to Window)    
[mv][w]getch()get a characterYYYgetch(3X)
[mv][w]get[n]str()get a character stringYYYgetnstr(3X)
[mv][w]get_wch()get a wide characterYYYget_wch(3X)
[mv][w]get[n]_wstr()get an array of wide characters and key codesYYYget_wstr(3X)
 Explicit Cursor Movement    
[w]move()move the cursor---move(3X)
 Input (Read Back from Window)    
[mv][w]inch()input a character---inch(3X)
[mv][w]inch[n]str()input an array of characters and attributes---inchnstr(3X)
[mv][w]in[n]str()input a string---innstr(3X)
[mv][w]in[n]wstr()input a string of wide characters---innwstr(3X)
[mv][w]in_wch()input a wide character and rendition---in_wch(3X)
[mv][w]in_wch[n]str()input an array of wide characters and renditions---in_wchnstr(3X)
 Insert    
[mv][w]insch()insert a characterYNNinsch(3X)
[mv][w]ins[n]str()insert a character stringYNNinsnstr(3X)
[mv][w]ins_[n]wstr()insert a wide-character stringYNNins_nwstr(3X)
[mv][w]ins_wch()insert a wide characterYNNins_wch(3X)
 Print and Scan    
[mv][w]printw()print formatted output---mvprintw(3X)
[mv][w]scanw()convert formatted output---mvscanw(3X)

Legend

The following notation indicates the effect when characters are moved to the screen. (For the Get functions, this applies only when echoing is enabled.)

s

Y means these functions perform special-character processing (see Special Characters). N means they do not. ? means the results are unspecified when these functions are applied to special characters.

w

Y means these functions perform wrapping (see Truncation, Wrapping and Scrolling). N means they do not.

c

Y means these functions advance the cursor (see Truncation, Wrapping and Scrolling). N means they do not.

-

The attribute specified by this column does not apply to these functions.

Interfaces Implemented as Macros

The following interfaces with arguments must be implemented as macros. The relevance to the application programmer is that the & character cannot be used before the arguments.

MacrosManpage
COLOR_PAIR()can_change_color(3X)
getbegyx(), getmaxyx(), getparyx(), getyx()getbegyx(3X)

The header file reference manpages list other macros, like COLOR_BLACK, that do not take arguments.

Initialised Curses Environment

Before executing an application that uses Curses, the terminal must be prepared as follows:

  • If the terminal has hardware tab stops, they should be set.

  • Any initialisation strings defined for the terminal must be output to the terminal.

The resulting state of the terminal must be compatible with the model of the terminal that Curses has, as reflected in the terminal's entry in the terminfo database (see terminfo(4)).

To initialise Curses, the application must call initscr() or newterm() before calling any of the other functions that deal with windows and screens, and it must call endwin() before exiting. To get character-at-a-time input without echoing (most interactive, screen-oriented programs want this), the following sequence should be used:

initscr(); cbreak(); noecho();

Most programs would additionally use the sequence:

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

Synchronous and Networked Asynchronous Terminals

This section indicates to the application writer some considerations to be borne in mind when driving synchronous, networked asynchronous (NWA) or nonstandard directly connected asynchronous terminals.

Such terminals are often used in a mainframe environment and communicate to the host in block mode. That is, the user types characters at the terminal then presses a special key to initiate transmission of the characters to the host.

Frequently, although it may be possible to send arbitrary sized blocks to the host, it is not possible or desirable to cause a character to be transmitted with only a single keystroke.

This can cause severe problems to an application wishing to make use of single-character input; see Input Processing.

Output

The Curses interface can be used in the normal way for all operations pertaining to output to the terminal, with the possible exception that on some terminals the refresh() routine may have to redraw the entire screen contents in order to perform any update.

If it is additionally necessary to clear the screen before each such operation, the result could be undesirable.

Input

Because of the nature of operation of synchronous (block-mode) and NWA terminals, it might not be possible to support all or any of the Curses input functions. In particular, the following points should be noted:

  • Single-character input might not be possible. It may be necessary to press a special key to cause all characters typed at the terminal to be transmitted to the host.

  • It is sometimes not possible to disable echo. Character echo may be performed directly by the terminal. On terminals that behave in this way, any Curses application that performs input should be aware that any characters typed will appear on the screen at wherever the cursor is positioned. This does not necessarily correspond to the position of the cursor in the window.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.