5.12.1 Output Options Setting

These routines set options within curses that deal with output. All options are initially #f, unless otherwise stated. It is not necessary to turn these options off before calling endwin.

Function: clearok win bf ¶

If enabled (bf is #t), the next call to force-output or refresh with win will clear the screen completely and redraw the entire screen from scratch. This is useful when the contents of the screen are uncertain, or in some cases for a more pleasing visual effect.

Function: idlok win bf ¶

If enabled (bf is #t), curses will consider using the hardware “insert/delete-line” feature of terminals so equipped. If disabled (bf is #f), curses will very seldom use this feature. The “insert/delete-character” feature is always considered. This option should be enabled only if your application needs “insert/delete-line”, for example, for a screen editor. It is disabled by default because

“insert/delete-line” tends to be visually annoying when used in applications where it is not really needed. If “insert/delete-line” cannot be used, curses will redraw the changed portions of all lines.

Function: leaveok win bf ¶

Normally, the hardware cursor is left at the location of the window cursor being refreshed. This option allows the cursor to be left wherever the update happens to leave it. It is useful for applications where the cursor is not used, since it reduces the need for cursor motions. If possible, the cursor is made invisible when this option is enabled.

Function: scrollok win bf ¶

This option controls what happens when the cursor of window win is moved off the edge of the window or scrolling region, either from a newline on the bottom line, or typing the last character of the last line. If disabled (bf is #f), the cursor is left on the bottom line at the location where the offending character was entered. If enabled (bf is #t), force-output is called on the window win, and then the physical terminal and window win are scrolled up one line.

Note in order to get the physical scrolling effect on the terminal, it is also necessary to call idlok.

Function: nodelay win bf ¶

This option causes wgetch to be a non-blocking call. If no input is ready, wgetch will return an eof-object. If disabled, wgetch will hang until a key is pressed.

---

5.12.2 Terminal Mode Setting

These routines set options within curses that deal with input. The options involve using ioctl(2) and therefore interact with curses routines. It is not necessary to turn these options off before calling endwin. The routines in this section all return an unspecified value.

Function: cbreak ¶

Function: nocbreak ¶

These two routines put the terminal into and out of CBREAK mode, respectively. In CBREAK mode, characters typed by the user are immediately available to the program and erase/kill character processing is not performed. When in NOCBREAK mode, the tty driver will buffer characters typed until a LFD or RET is typed. Interrupt and flowcontrol characters are unaffected by this mode. Initially the terminal may or may not be in CBREAK mode, as it is inherited, therefore, a program should call cbreak or nocbreak explicitly. Most interactive programs using curses will set CBREAK mode.

Note cbreak overrides raw. For a discussion of how these routines interact with echo and noecho See read-char.

Function: raw ¶

Function: noraw ¶

The terminal is placed into or out of RAW mode. RAW mode is similar to CBREAK mode, in that characters typed are immediately passed through to the user program. The differences are that in RAW mode, the interrupt, quit, suspend, and flow control characters are passed through uninterpreted, instead of generating a signal. RAW mode also causes 8-bit input and output. The behavior of the BREAK key depends on other bits in the terminal driver that are not set by curses.

Function: echo ¶

Function: noecho ¶

These routines control whether characters typed by the user are echoed by read-char as they are typed. Echoing by the tty driver is always disabled, but initially read-char is in ECHO mode, so characters typed are echoed. Authors of most interactive programs prefer to do their own echoing in a controlled area of the screen, or not to echo at all, so they disable echoing by calling noecho. For a discussion of how these routines interact with echo and noecho See read-char.

Function: nl ¶

Function: nonl ¶

These routines control whether LFD is translated into RET and LFD on output, and whether RET is translated into LFD on input. Initially, the translations do occur. By disabling these translations using nonl, curses is able to make better use of the linefeed capability, resulting in faster cursor motion.

Function: resetty ¶

Function: savetty ¶

These routines save and restore the state of the terminal modes. savetty saves the current state of the terminal in a buffer and resetty restores the state to what it was at the last call to savetty.

---

5.12.3 Window Manipulation

Function: newwin nlines ncols begy begx ¶

Create and return a new window with the given number of lines (or rows), nlines, and columns, ncols. The upper left corner of the window is at line begy, column begx. If either nlines or ncols is 0, they will be set to the value of LINES-begy and COLS-begx. A new full-screen window is created by calling newwin(0,0,0,0).

Function: subwin orig nlines ncols begy begx ¶

Create and return a pointer to a new window with the given number of lines (or rows), nlines, and columns, ncols. The window is at position (begy, begx) on the screen. This position is relative to the screen, and not to the window orig. The window is made in the middle of the window orig, so that changes made to one window will affect both windows. When using this routine, often it will be necessary to call touchwin or touchline on orig before calling force-output.

Function: close-port win ¶

Deletes the window win, freeing up all memory associated with it. In the case of sub-windows, they should be deleted before the main window win.

Function: refresh ¶

Function: force-output win ¶

These routines are called to write output to the terminal, as most other routines merely manipulate data structures. force-output copies the window win to the physical terminal screen, taking into account what is already there in order to minimize the amount of information that’s sent to the terminal (called optimization). Unless leaveok has been enabled, the physical cursor of the terminal is left at the location of window win’s cursor. With refresh, the number of characters output to the terminal is returned.

Function: mvwin win y x ¶

Move the window win so that the upper left corner will be at position (y, x). If the move would cause the window win to be off the screen, it is an error and the window win is not moved.

Function: overlay srcwin dstwin ¶

Function: overwrite srcwin dstwin ¶

These routines overlay srcwin on top of dstwin; that is, all text in srcwin is copied into dstwin. srcwin and dstwin need not be the same size; only text where the two windows overlap is copied. The difference is that overlay is non-destructive (blanks are not copied), while overwrite is destructive.

Function: touchwin win ¶

Function: touchline win start count ¶

Throw away all optimization information about which parts of the window win have been touched, by pretending that the entire window win has been drawn on. This is sometimes necessary when using overlapping windows, since a change to one window will affect the other window, but the records of which lines have been changed in the other window will not reflect the change. touchline only pretends that count lines have been changed, beginning with line start.

Function: wmove win y x ¶

The cursor associated with the window win is moved to line (row) y, column x. This does not move the physical cursor of the terminal until refresh (or force-output) is called. The position specified is relative to the upper left corner of the window win, which is (0, 0).

---

5.12.4 Output

These routines are used to draw text on windows

Function: display ch win ¶

Function: display str win ¶

Function: wadd win ch ¶

Function: wadd win str ¶

The character ch or characters in str are put into the window win at the current cursor position of the window and the position of win’s cursor is advanced. At the right margin, an automatic newline is performed. At the bottom of the scrolling region, if scrollok is enabled, the scrolling region will be scrolled up one line.

If ch is a TAB, LFD, or backspace, the cursor will be moved appropriately within the window win. A LFD also does a wclrtoeol before moving. TAB characters are considered to be at every eighth column. If ch is another control character, it will be drawn in the C-x notation. (Calling winch after adding a control character will not return the control character, but instead will return the representation of the control character.)

Video attributes can be combined with a character by or-ing them into the parameter. This will result in these attributes also being set. The intent here is that text, including attributes, can be copied from one place to another using inch and display. See standout, below.

Note For wadd ch can be an integer and will insert the character of the corresponding value.

Function: werase win ¶

This routine copies blanks to every position in the window win.

Function: wclear win ¶

This routine is like werase, but it also calls clearok, arranging that the screen will be cleared completely on the next call to refresh or force-output for window win, and repainted from scratch.

Function: wclrtobot win ¶

All lines below the cursor in window win are erased. Also, the current line to the right of the cursor, inclusive, is erased.

Function: wclrtoeol win ¶

The current line to the right of the cursor, inclusive, is erased.

Function: wdelch win ¶

The character under the cursor in the window win is deleted. All characters to the right on the same line are moved to the left one position and the last character on the line is filled with a blank. The cursor position does not change. This does not imply use of the hardware “delete-character” feature.

Function: wdeleteln win ¶

The line under the cursor in the window win is deleted. All lines below the current line are moved up one line. The bottom line win is cleared. The cursor position does not change. This does not imply use of the hardware “deleteline” feature.

Function: winsch win ch ¶

The character ch is inserted before the character under the cursor. All characters to the right are moved one SPC to the right, possibly losing the rightmost character of the line. The cursor position does not change . This does not imply use of the hardware “insertcharacter” feature.

Function: winsertln win ¶

A blank line is inserted above the current line and the bottom line is lost. This does not imply use of the hardware “insert-line” feature.

Function: scroll win ¶

The window win is scrolled up one line. This involves moving the lines in win’s data structure. As an optimization, if win is stdscr and the scrolling region is the entire window, the physical screen will be scrolled at the same time.

---

5.12.5 Input

Function: read-char win ¶

A character is read from the terminal associated with the window win. Depending on the setting of cbreak, this will be after one character (CBREAK mode), or after the first newline (NOCBREAK mode). Unless noecho has been set, the character will also be echoed into win.

When using read-char, do not set both NOCBREAK mode (nocbreak) and ECHO mode (echo) at the same time. Depending on the state of the terminal driver when each character is typed, the program may produce undesirable results.

Function: winch win ¶

The character, of type chtype, at the current position in window win is returned. If any attributes are set for that position, their values will be OR’ed into the value returned.

Function: getyx win ¶

A list of the y and x coordinates of the cursor position of the window win is returned

---

5.12.6 Curses Miscellany

Function: wstandout win ¶

Function: wstandend win ¶

These functions set the current attributes of the window win. The current attributes of win are applied to all characters that are written into it. Attributes are a property of the character, and move with the character through any scrolling and insert/delete line/character operations. To the extent possible on the particular terminal, they will be displayed as the graphic rendition of characters put on the screen.

wstandout sets the current attributes of the window win to be visibly different from other text. wstandend turns off the attributes.

Function: box win vertch horch ¶

A box is drawn around the edge of the window win. vertch and horch are the characters the box is to be drawn with. If vertch and horch are 0, then appropriate default characters, ACS_VLINE and ACS_HLINE, will be used.

Note vertch and horch can be an integers and will insert the character (with attributes) of the corresponding values.

Function: unctrl c ¶

This macro expands to a character string which is a printable representation of the character c. Control characters are displayed in the C-x notation. Printing characters are displayed as is.