4
4
****************************************************************************
5
* Copyright (c) 1998-2004,2005 Free Software Foundation, Inc. *
5
* Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. *
7
7
* Permission is hereby granted, free of charge, to any person obtaining a *
8
8
* copy of this software and associated documentation files (the *
62
62
independent method of updating character screens with rea-
63
63
sonable optimization. This implementation is ``new
64
64
curses'' (ncurses) and is the approved replacement for
65
4.4BSD classic curses, which has been discontinued.
65
4.4BSD classic curses, which has been discontinued. This
66
describes <STRONG>ncurses</STRONG> version 5.5 (patch 20061209).
67
The <STRONG>ncurses</STRONG> routines emulate the <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> library of
68
The <STRONG>ncurses</STRONG> routines emulate the <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> library of
68
69
System V Release 4 UNIX, and the XPG4 curses standard (XSI
69
curses) but the <STRONG>ncurses</STRONG> library is freely redistributable
70
curses) but the <STRONG>ncurses</STRONG> library is freely redistributable
70
71
in source form. Differences from the SVr4 curses are sum-
71
marized under the EXTENSIONS and PORTABILITY sections
72
below and described in detail in the respective EXTEN-
73
SIONS, PORTABILITY and BUGS sections of individual man
72
marized under the <STRONG>EXTENSIONS</STRONG> and <STRONG>PORTABILITY</STRONG> sections
73
below and described in detail in the respective <STRONG>EXTEN-</STRONG>
74
<STRONG>SIONS</STRONG>, <STRONG>PORTABILITY</STRONG> and <STRONG>BUGS</STRONG> sections of individual man
76
A program using these routines must be linked with the
77
<STRONG>-lncurses</STRONG> option, or (if it has been generated) with the
78
debugging library <STRONG>-lncurses_g</STRONG>. (Your system integrator
79
may also have installed these libraries under the names
77
A program using these routines must be linked with the
78
<STRONG>-lncurses</STRONG> option, or (if it has been generated) with the
79
debugging library <STRONG>-lncurses_g</STRONG>. (Your system integrator
80
may also have installed these libraries under the names
80
81
<STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>.) The ncurses_g library generates
81
82
trace logs (in a file called 'trace' in the current direc-
82
tory) that describe curses actions.
83
tory) that describe curses actions. See also the section
84
on <STRONG>ALTERNATE</STRONG> <STRONG>CONFIGURATIONS</STRONG>.
84
86
The <STRONG>ncurses</STRONG> package supports: overall screen, window and
85
87
pad manipulation; output to windows and pads; reading ter-
127
129
Windows are referred to by variables declared as <STRONG>WINDOW</STRONG> <STRONG>*</STRONG>.
128
130
These data structures are manipulated with routines
129
131
described here and elsewhere in the <STRONG>ncurses</STRONG> manual pages.
130
Among which the most basic routines are <STRONG>move</STRONG> and <STRONG>addch</STRONG>.
132
Among those, the most basic routines are <STRONG>move</STRONG> and <STRONG>addch</STRONG>.
131
133
More general versions of these routines are included with
132
134
names beginning with <STRONG>w</STRONG>, allowing the user to specify a
133
window. The routines not beginning with <STRONG>w</STRONG> affect <STRONG>stdscr</STRONG>.)
135
window. The routines not beginning with <STRONG>w</STRONG> affect <STRONG>stdscr</STRONG>.
135
137
After using routines to manipulate a window, <STRONG>refresh</STRONG> is
136
138
called, telling <STRONG>curses</STRONG> to make the user's CRT screen look
242
244
_tracedump <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
243
245
_tracef <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
244
246
_tracemouse <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>*
245
248
add_wch <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
246
249
add_wchnstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
248
250
add_wchstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
249
251
addch <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
250
252
addchnstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
308
310
get_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>
309
311
get_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
310
312
getbegyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
311
314
getbkgd <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
312
315
getbkgrnd <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>
314
316
getcchar <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>
315
317
getch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>
316
318
getmaxyx <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>
374
376
mousemask <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>*
375
377
move <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>
376
378
mvadd_wch <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>
377
380
mvadd_wchnstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
378
381
mvadd_wchstr <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>
380
382
mvaddch <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>
381
383
mvaddchnstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
382
384
mvaddchstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
440
442
mvwin_wch <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG>
441
443
mvwin_wchnstr <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
442
444
mvwin_wchstr <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG>
443
446
mvwinch <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>
444
447
mvwinchnstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
446
448
mvwinchstr <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>
447
449
mvwinnstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>
448
450
mvwinnwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>
506
508
setterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
507
509
setupterm <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
508
510
slk_attr <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>*
509
512
slk_attr_off <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
510
513
slk_attr_on <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
512
514
slk_attr_set <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
513
515
slk_attroff <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
514
516
slk_attron <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
572
574
waddchnstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
573
575
waddchstr <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>
574
576
waddnstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>
575
578
waddnwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
576
579
waddstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>
578
580
waddwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>
579
581
wattr_get <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
580
582
wattr_off <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
638
640
wscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>
639
641
wscrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>
640
642
wsetscrreg <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
641
644
wstandend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
642
645
wstandout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>
644
646
wsyncdown <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
645
647
wsyncup <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG>
646
648
wtimeout <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>
774
776
nal's default colors are white-on-black (see
775
777
<STRONG><A HREF="assume_default_colors.3x.html">assume_default_colors(3x)</A></STRONG>). You may set the fore-
776
778
ground and background color values with this environ-
777
ment variable by proving a 2-element list: fore-
778
ground,background. For example, to tell ncurses to
779
not assume anything about the colors, set this to
779
ment variable by proving a 2-element list:
780
foreground,background. For example, to tell ncurses
781
to not assume anything about the colors, set this to
780
782
"-1,-1". To make it green-on-black, set it to "2,0".
781
783
Any positive value from zero to the terminfo <STRONG>max_col-</STRONG>
782
784
<STRONG>ors</STRONG> value is allowed.
787
<STRONG>Ncurses</STRONG> may use tabs as part of the cursor movement
788
optimization. In some cases, your terminal driver
789
may not handle these properly. Set this environment
790
variable to disable the feature. You can also adjust
791
your <STRONG>stty</STRONG> settings to avoid the problem.
793
NCURSES_NO_MAGIC_COOKIES
794
Some terminals use a magic-cookie feature which
795
requires special handling to make highlighting and
796
other video attributes display properly. You can
797
suppress the highlighting entirely for these termi-
798
nals by setting this environment variable.
784
800
NCURSES_NO_PADDING
785
801
Most of the terminal descriptions in the terminfo
786
802
database are written for real "hardware" terminals.
895
911
If TERMCAP does not hold a file name then <STRONG>ncurses</STRONG>
896
checks the TERMPATH symbol. This is a list of file-
897
names separated by spaces or colons (i.e., ":") on
898
Unix, semicolons on OS/2 EMX. If the TERMPATH symbol
899
is not set, <STRONG>ncurses</STRONG> looks in the files /etc/termcap,
900
/usr/share/misc/termcap and $HOME/.termcap, in that
912
checks the TERMPATH symbol. This is a list of
913
filenames separated by spaces or colons (i.e., ":")
914
on Unix, semicolons on OS/2 EMX. If the TERMPATH
915
symbol is not set, <STRONG>ncurses</STRONG> looks in the files
916
/etc/termcap, /usr/share/misc/termcap and
917
$HOME/.termcap, in that order.
903
919
The library may be configured to disregard the following
904
920
variables when the current user is the superuser (root),
926
<H2>ALTERNATE CONFIGURATIONS</H2><PRE>
927
Several different configurations are possible, depending
928
on the configure script options used when building
929
<STRONG>ncurses</STRONG>. There are a few main options whose effects are
930
visible to the applications developer using <STRONG>ncurses</STRONG>:
933
The standard include for <STRONG>ncurses</STRONG> is as noted in <STRONG>SYN-</STRONG>
934
<STRONG>OPSIS</STRONG>:
936
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
938
This option is used to avoid filename conflicts when
939
<STRONG>ncurses</STRONG> is not the main implementation of curses of
940
the computer. If <STRONG>ncurses</STRONG> is installed disabling
941
overwrite, it puts its headers in a subdirectory,
944
<STRONG>#include</STRONG> <STRONG><ncurses/curses.h></STRONG>
946
It also omits a symbolic link which would allow you
947
to use <STRONG>-lcurses</STRONG> to build executables.
950
The configure script renames the library and (if the
951
<STRONG>--disable-overwrite</STRONG> option is used) puts the header
952
files in a different subdirectory. All of the
953
library names have a "w" appended to them, i.e.,
956
<STRONG>-lncurses</STRONG>
960
<STRONG>-lncursesw</STRONG>
962
You must also define <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> when com-
963
piling for the wide-character library to use the
964
extended (wide-character) functions. The <STRONG>curses.h</STRONG>
965
file which is installed for the wide-character
966
library is designed to be compatible with the normal
967
library's header. Only the size of the <STRONG>WINDOW</STRONG> struc-
968
ture differs, and very few applications require more
969
than a pointer to <STRONG>WINDOW</STRONG>s. If the headers are
970
installed allowing overwrite, the wide-character
971
library's headers should be installed last, to allow
972
applications to be built using either library from
973
the same set of headers.
982
The shared and normal (static) library names differ
983
by their suffixes, e.g., <STRONG>libncurses.so</STRONG> and
984
<STRONG>libncurses.a</STRONG>. The debug and profiling libraries add
985
a "_g" and a "_p" to the root names respectively,
986
e.g., <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>.
989
The <STRONG>trace</STRONG> function normally resides in the debug
990
library, but it is sometimes useful to configure this
991
in the shared library. Configure scripts should
992
check for the function's existence rather than assum-
993
ing it is always in the debug library.
910
997
<H2>FILES</H2><PRE>
911
998
/usr/share/tabset
912
999
directory containing initialization files for the
913
terminal capability database /usr/share/terminfo
914
terminal capability database
1000
terminal capability database /usr/share/terminfo ter-
1001
minal capability database
added
removed
doc/html/man/ncurses.3x.html
