# info > Curses

---
type: CommandReference
command: Curses
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `use Curses; initscr; ...; endwin;` — basic terminal screen handling
- `$win = new Curses; $win->addstr(10, 10, 'foo'); $win->refresh;` — object-oriented usage
- `getchar` — read a character (wide-character-aware)
- `getstring` — read a line of input (wide-character-aware)
- `addstring("Hello")` — add a string to the window (wide-character-aware)
- `keypad($win, 1)` — enable function key interpretation
- `cbreak()` — disable line buffering
- `noecho()` — suppress echoing of typed characters

## Name

Curses — terminal screen handling and optimization

## Synopsis

perl
use Curses;

initscr;
...
endwin;
Or with objects:

perl
$win = new Curses;
$win->addstr(10, 10, 'foo');
$win->refresh;
...
## Options

### Unified Functions

Many curses functions have variants (`w-`, `mv-`, `mvw-`). In Curses, these are unified into a single function that accepts optional window and coordinate arguments:

perl
function( [win], [y, x], args );
- `win` defaults to `stdscr`
- `y, x` moves cursor before operation (default: no move)
- `args` are the required arguments of the base function

Key unified functions:

- `addch(ch)` — add a character
- `addstr(str)` — add a string
- `getch()` — get a character
- `getstr()` — get a string (deprecated; use `getnstr` or `getstring`)
- `getnstr(size)` — get a string with buffer limit
- `refresh()` — refresh window
- `move(y, x)` — move cursor
- `clear()` — clear window
- `erase()` — erase window
- `border(ls, rs, ts, bs, tl, tr, bl, br)` — draw border
- `box(vch, hch)` — draw box around window
- `attron(attrs)` — turn on attributes
- `attroff(attrs)` — turn off attributes
- `attrset(attrs)` — set attributes
- `chgat(n, attr, color, opts)` — change attributes for `n` characters

### Wide-Character-Aware Functions (preferred for string handling)

These functions use wide-character curses routines when available, falling back to legacy versions.

| Function | Description |
|----------|-------------|
| `getchar()` | Read a character. Returns a one-character string for normal keys, or `(undef, key-number)` for function keys. |
| `getstring()` | Read a line of input. Returns string or `undef`. |
| `addstring(str)` | Add string to window. |
| `insstring(str)` | Insert string at cursor. |
| `instring()` | Get string from cursor to end of line. |
| `ungetchar(ch)` | Push a character back to input queue. |

### Other Important Functions

- `initscr()` — initialize curses
- `endwin()` — end curses mode
- `cbreak()` / `nocbreak()` — set cbreak mode
- `raw()` / `noraw()` — set raw mode
- `echo()` / `noecho()` — enable/disable echo
- `nl()` / `nonl()` — enable/disable newline translation
- `keypad(win, bool)` — enable function key mapping
- `nodelay(win, bool)` — non-blocking input
- `timeout(ms)` — set input timeout
- `curs_set(visibility)` — set cursor visibility
- `start_color()` — initialize color support
- `init_pair(pair, fg, bg)` — define color pair
- `has_colors()` — check terminal color support
- `COLOR_PAIR(n)` — create color attribute
- `PAIR_NUMBER(attr)` — extract pair number from attribute
- `beep()` — audible bell
- `flash()` — visual bell
- `getyx(y, x)` — get cursor position
- `getmaxyx(y, x)` — get window dimensions

### Variables

- `LINES`, `COLS` — terminal dimensions
- `stdscr`, `curscr` — standard and current screen windows
- `COLORS`, `COLOR_PAIRS` — color capabilities

### Constants

Available constants include:

- `ERR`, `OK` — return codes
- `ACS_*` — alternate character set symbols (e.g., `ACS_HLINE`, `ACS_VLINE`)
- `A_*` — attributes (e.g., `A_BOLD`, `A_REVERSE`, `A_UNDERLINE`)
- `COLOR_*` — color names (e.g., `COLOR_RED`, `COLOR_GREEN`)
- `KEY_*` — function key codes (e.g., `KEY_UP`, `KEY_DOWN`, `KEY_HOME`)
- `BUTTON*` — mouse event constants
- Form and menu constants (`REQ_*`, `O_*`, `E_*`, etc.)

## Examples

### Basic curses program

perl
use Curses;

initscr();
addstr(10, 10, "Hello, world!");
refresh();
getch();
endwin();
### Object-oriented with wide-character functions

perl
use Curses;

my $win = new Curses;
$win->addstring(5, 5, "Hello, world!");
$win->refresh();
my $ch = $win->getchar();
die "getchar failed" unless defined $ch;
### Handling function keys

perl
use Curses;

initscr();
keypad(1);
cbreak();
noecho();

my ($ch, $key) = getchar();
if (defined $key) {
    print "Function key $key\n";
} elsif (defined $ch) {
    print "Character: $ch\n";
} else {
    die "getchar failed";
}

endwin();
## See Also

- System `curses(3)` man page
- [Curses::OldCurses](http://localhost/phpMan.php/perldoc/Curses%3A%3AOldCurses/markdown) for compatibility with Perl 4
- Perl documentation for other terminal modules