##############################################################################
-# Copyright 2020 Thomas E. Dickey #
+# Copyright 2020,2022 Thomas E. Dickey #
# #
# Permission is hereby granted, free of charge, to any person obtaining a #
# copy of this software and associated documentation files (the "Software"), #
#
# Author: Thomas E. Dickey
#
-# $Id: split-path.awk,v 1.3 2020/02/02 23:34:34 tom Exp $
+# $Id: split-path.awk,v 1.4 2022/11/26 23:46:20 tom Exp $
BEGIN { cols = 72; }
/[$]THIS_DATADIR/ {
+ if (substr(this_datadir, length(this_datadir)) != "/")
+ this_datadir = this_datadir "/";
gsub("[$]THIS_DATADIR", "\"" this_datadir "\"");
if ( length ($0) > cols ) {
indent = index($0, "\"") - 1;
-- sale, use or other dealings in this Software without prior written --
-- authorization. --
-------------------------------------------------------------------------------
--- $Id: NEWS,v 1.3879 2022/11/19 21:20:17 tom Exp $
+-- $Id: NEWS,v 1.3882 2022/11/26 23:50:16 tom Exp $
-------------------------------------------------------------------------------
This is a log of changes that ncurses has gone through since Zeyd started
Changes through 1.9.9e did not credit all contributions;
it is not possible to add this information.
+20221126
+ + fix an error in pathname of explain.txt (cf: 20200201).
+ + fix an error in "@" command in test/ncurses.c F-menu (cf: 20190121).
+ + improve formatting of ncurses-intro.html and hackguide.html
+ + improve man/curs_clear.3x links to other pages
+
20221119
+ use static libraries for AdaCurses test-package for Mageia, since no
gprbuild package is available.
-5:0:10 6.3 20221119
+5:0:10 6.3 20221126
# use or other dealings in this Software without prior written #
# authorization. #
##############################################################################
-# $Id: dist.mk,v 1.1513 2022/11/19 11:24:10 tom Exp $
+# $Id: dist.mk,v 1.1514 2022/11/26 11:55:42 tom Exp $
# Makefile for creating ncurses distributions.
#
# This only needs to be used directly as a makefile by developers, but
# These define the major/minor/patch versions of ncurses.
NCURSES_MAJOR = 6
NCURSES_MINOR = 3
-NCURSES_PATCH = 20221119
+NCURSES_PATCH = 20221126
# We don't append the patch to the version, since this only applies to releases
VERSION = $(NCURSES_MAJOR).$(NCURSES_MINOR)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
-
<html>
<head>
<meta name="generator" content=
- "HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
-
+ "HTML Tidy for HTML5 for Linux version 5.6.0">
<title>NCURSES Programming HOWTO</title>
<meta name="GENERATOR" content=
"Modular DocBook HTML Stylesheet Version 1.79">
</head>
-
<body class="ARTICLE" bgcolor="#FFFFFF" text="#000000" link=
"#0000FF" vlink="#840084" alink="#0000FF">
<div class="ARTICLE">
<div class="AFFILIATION">
<div class="ADDRESS">
<p class="ADDRESS"><code class="EMAIL"><<a href=
- "mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code></p>
+ "mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code>
+ </p>
</div>
</div>
<table width="100%" border="0" summary="revisions">
<tr>
<th align="left" valign="top" colspan="3"><b>Revision
- History</b></th>
+ History</b>
+ </th>
</tr>
<tr>
<td align="left">Revision 1.9</td>
-
<td align="left">2005-06-20</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.8</td>
-
<td align="left">2005-06-17</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.7.1</td>
-
<td align="left">2002-06-25</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.7</td>
-
<td align="left">2002-06-25</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.6.1</td>
-
<td align="left">2002-02-24</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.6</td>
-
<td align="left">2002-02-16</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.5</td>
-
<td align="left">2002-01-05</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.3.1</td>
-
<td align="left">2001-07-26</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.3</td>
-
<td align="left">2001-07-24</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.2</td>
-
<td align="left">2001-06-05</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<tr>
<td align="left">Revision 1.1</td>
-
<td align="left">2001-05-22</td>
-
<td align="left">Revised by: ppadala</td>
</tr>
<div>
<div class="ABSTRACT">
<a name="AEN67" id="AEN67"></a>
-
<p><span class="emphasis"><i class="EMPHASIS">This
document is intended to be an "All in One" guide for
programming with ncurses and its sister libraries. We
complex form manipulation. No prior experience in ncurses
is assumed. Send comments to <a href=
"mailto:ppadala@gmail.com" target="_top">this
- address</a></i></span></p>
+ address</a></i></span>
+ </p>
</div>
</div>
+
<hr>
</div>
<div class="TOC">
<dl>
- <dt><b>Table of Contents</b></dt>
+ <dt><b>Table of Contents</b>
+ </dt>
<dt>1. <a href="#INTRO">Introduction</a></dt>
<p>Suppose you wanted to print a line in color. Try typing
this on your console.</p>
+
<pre class="PROGRAMLISTING">
echo "^[[0;31;40mIn Color"
</pre>
-
<p>The first character is an escape character, which looks
like two characters ^ and [. To be able to print it, you have
to press CTRL+V and then the ESC key. All the others are
normal printable characters. You should be able to see the
string "In Color" in red. It stays that way and to revert
back to the original mode type this.</p>
+
<pre class="PROGRAMLISTING">
echo "^[[0;37;40m"
</pre>
-
<p>Now, what do these magic characters mean? Difficult to
comprehend? They might even be different for different
terminals. So the designers of UNIX invented a mechanism
on.</p>
<p><span class="emphasis"><i class="EMPHASIS">Compiling the
- package</i></span></p>
+ package</i></span>
+ </p>
<p>NCURSES can be obtained from <a href=
"ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz" target=
<p>Read the README and INSTALL files for details on to how
to install it. It usually involves the following
operations.</p>
+
<pre class="PROGRAMLISTING">
tar zxvf ncurses<version>.tar.gz # unzip and untar the archive
cd ncurses<version> # cd to the directory
su root # become root
make install # install it
</pre>
-
<p><span class="emphasis"><i class="EMPHASIS">Using the
- RPM</i></span></p>
+ RPM</i></span>
+ </p>
<p>NCURSES RPM can be found and downloaded from <a href=
"http://rpmfind.net" target="_top">http://rpmfind.net</a> .
The RPM can be installed with the following command after
becoming root.</p>
+
<pre class="PROGRAMLISTING">
rpm -i <downloaded rpm>
</pre>
"http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz"
target="_top">here</a>. Unzip and untar it. The directory
structure looks like this.</p>
+
<pre class="PROGRAMLISTING">
ncurses
|
|----> README -- the top level README file. contains instructions
|----> COPYING -- copyright notice
</pre>
-
<p>The individual directories contain the following
files.</p>
+
<pre class="PROGRAMLISTING">
Description of files in each directory
--------------------------------------
perl
|----> 01-10.pl -- Perl equivalents of first ten example programs
</pre>
-
<p>There is a top level Makefile included in the main
directory. It builds all the files and puts the
ready-to-use exes in demo/exe directory. You can also do
<p>If above links are broken or if you want to experiment
with sgml read on.</p>
+
<pre class="PROGRAMLISTING">
Get both the source and the tar,gzipped programs, available at
http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps>
NCURSES-ONE-BIG-FILE.html
</pre>
-
<p>See <a href=
"http://www.tldp.org/LDP/LDP-Author-Guide/" target=
"_top">LDP Author guide</a> for more details. If all else
<hr>
<h3 class="SECT2"><a name="COMPILECURSES" id=
- "COMPILECURSES">2.1. Compiling With the NCURSES
- Library</a></h3>
+ "COMPILECURSES">2.1. Compiling With the NCURSES Library</a></h3>
<p>To use ncurses library functions, you have to include
ncurses.h in your programs. To link the program with
ncurses the flag -lncurses should be added.</p>
+
<pre class="PROGRAMLISTING">
#include <ncurses.h>
.
compile and link: gcc <program file> -lncurses
</pre>
-
<div class="EXAMPLE">
<a name="BHW" id="BHW"></a>
+ <p><b>Example 1. The Hello World !!! Program</b>
+ </p>
- <p><b>Example 1. The Hello World !!! Program</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
<div class="EXAMPLE">
<a name="BINFU" id="BINFU"></a>
-
<p><b>Example 2. Initialization Function Usage
- example</b></p>
+ example</b>
+ </p>
+
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
which explicitly work on the specified window.</p>
<p>For example, if you call</p>
+
<pre class="PROGRAMLISTING">
printw("Hi There !!!");
refresh();
</pre>
-
<p>It prints the string on stdscr at the present cursor
position. Similarly the call to refresh(), works on stdscr
only.</p>
<p>Say you have created <a href="#WINDOWS">windows</a> then
you have to call a function with a 'w' added to the usual
function.</p>
+
<pre class="PROGRAMLISTING">
wprintw(win, "Hi There !!!");
wrefresh(win);
</pre>
-
<p>As you will see in the rest of the document, naming of
functions follow the same convention. For each function there
usually are three more functions.</p>
+
<pre class="PROGRAMLISTING">
printw(string); /* Print on stdscr at present cursor position */
mvprintw(y, x, string);/* Move to (y, x) then print string */
mvwprintw(win, y, x, string); /* Move to (y, x) relative to window */
/* co-ordinates and then print */
</pre>
-
<p>Usually the w-less functions are macros which expand to
corresponding w-function with stdscr as the window
parameter.</p>
For example, you want to print a character ch(of type
char) bold and underlined, you would call addch() as
below.</p>
+
<pre class="PROGRAMLISTING">
addch(ch | A_BOLD | A_UNDERLINE);
</pre>
<p><tt class="LITERAL">mvaddch()</tt> is used to move the
cursor to a given point, and then print. Thus, the
calls:</p>
+
<pre class="PROGRAMLISTING">
move(row,col); /* moves the cursor to row<span class=
"emphasis"><i class=
"EMPHASIS">th</i></span> row and col<span class="emphasis"><i class="EMPHASIS">th</i></span> column */
addch(ch);
</pre>can be replaced by
+
<pre class="PROGRAMLISTING">
mvaddch(row,col,ch);
</pre>
-
<p><tt class="LITERAL">waddch()</tt> is similar to
<tt class="LITERAL">addch()</tt>, except that it adds a
character into the given window. (Note that <tt class=
<hr>
<h4 class="SECT3"><a name="WPRINTWMVWPRINTW" id=
- "WPRINTWMVWPRINTW">6.3.2. wprintw() and
- mvwprintw</a></h4>
+ "WPRINTWMVWPRINTW">6.3.2. wprintw() and mvwprintw</a></h4>
<p>These two functions are similar to above two except
that they print in the corresponding window given as
<div class="EXAMPLE">
<a name="BPREX" id="BPREX"></a>
+ <p><b>Example 3. A Simple printw example</b>
+ </p>
- <p><b>Example 3. A Simple printw example</b></p>
<pre class="PROGRAMLISTING">
<span class=
"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */
<div class="EXAMPLE">
<a name="BSCEX" id="BSCEX"></a>
+ <p><b>Example 4. A Simple scanw example</b>
+ </p>
- <p><b>Example 4. A Simple scanw example</b></p>
<pre class="PROGRAMLISTING">
<span class=
"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */
<div class="EXAMPLE">
<a name="BSIAT" id="BSIAT"></a>
+ <p><b>Example 5. A Simple Attributes example</b>
+ </p>
- <p><b>Example 5. A Simple Attributes example</b></p>
<pre class="PROGRAMLISTING">
<span class=
"INLINEMEDIAOBJECT">/* pager functionality by Joseph Spainhour" <spainhou@bellsouth.net> */
attributes and switch them on or off, respectively. The
following video attributes, which are defined in
<curses.h> can be passed to these functions.</p>
+
<pre class="PROGRAMLISTING">
A_NORMAL Normal display (no highlight)
COLOR_PAIR(n) Color-pair number n
</pre>
-
<p>The last one is the most colorful one :-) Colors are
explained in the <a href="#color" target="_top">next
sections</a>.</p>
<p>We can OR(|) any number of above attributes to get a
combined effect. If you wanted reverse video with blinking
characters you can use</p>
+
<pre class="PROGRAMLISTING">
attron(A_REVERSE | A_BLINK);
</pre>
<p>We can give -1 as the character count to update till end
of line. If you want to change attributes of characters
from current position to end of line, just use this.</p>
+
<pre class="PROGRAMLISTING">
chgat(-1, A_REVERSE, 0, NULL);
</pre>
-
<p>This function is useful when changing attributes for
characters that are already on the screen. Move to the
character from which you want to change and change the
<div class="EXAMPLE">
<a name="BWICH" id="BWICH"></a>
+ <p><b>Example 6. Chgat() Usage example</b>
+ </p>
- <p><b>Example 6. Chgat() Usage example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
<div class="EXAMPLE">
<a name="BWIBO" id="BWIBO"></a>
+ <p><b>Example 7. Window Border example</b>
+ </p>
- <p><b>Example 7. Window Border example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
-
WINDOW *create_newwin(int height, int width, int starty, int startx);
void destroy_win(WINDOW *local_win);
border around the window with the characters given to it as
the 4 corner points and the 4 lines. To put it clearly, if
you have called wborder as below:</p>
+
<pre class="PROGRAMLISTING">
wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');
</pre>
-
<p>it produces some thing like</p>
+
<pre class="PROGRAMLISTING">
+------------+
| |
<div class="EXAMPLE">
<a name="BOTBO" id="BOTBO"></a>
+ <p><b>Example 8. More border functions</b>
+ </p>
- <p><b>Example 8. More border functions</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
<div class="SECT1">
<hr>
- <h2 class="SECT1"><a name="COLOR" id="COLOR">10.
- Colors</a></h2>
+ <h2 class="SECT1"><a name="COLOR" id="COLOR">10. Colors</a></h2>
<div class="SECT2">
<h3 class="SECT2"><a name="COLORBASICS" id=
<div class="EXAMPLE">
<a name="BSICO" id="BSICO"></a>
+ <p><b>Example 9. A Simple Color example</b>
+ </p>
- <p><b>Example 9. A Simple Color example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
<p>The following colors are defined in <tt class=
"LITERAL">curses.h</tt>. You can use these as parameters
for various color functions.</p>
+
<pre class="PROGRAMLISTING">
COLOR_BLACK 0
COLOR_RED 1
curses initially. Say you wanted to lighten the intensity
of red color by a minuscule. Then you can use this function
as</p>
+
<pre class="PROGRAMLISTING">
init_color(COLOR_RED, 700, 0, 0);
/* param 1 : color name
* param 2, 3, 4 : rgb content min = 0, max = 1000 */
</pre>
-
<p>If your terminal cannot change the color definitions,
the function returns ERR. The function <tt class=
"LITERAL">can_change_color()</tt> can be used to find out
sensitive to key presses or the mouse actions done by the
user. Let's deal with the keys first.</p>
- <p>As you have seen in almost all of the above examples,
- it is very easy to get key input from the user. A simple way
+ <p>As you have seen in almost all of the above examples, it
+ is very easy to get key input from the user. A simple way
of getting key presses is to use <tt class=
"LITERAL">getch()</tt> function. The cbreak mode should be
enabled to read keys when you are interested in reading
keys portable and easy to manage.</p>
<p>For example, if you call getch() like this</p>
+
<pre class="PROGRAMLISTING">
int ch;
ch = getch();
</pre>
-
<p>getch() will wait for the user to press a key, (unless
you specified a timeout) and when user presses a key, the
corresponding integer is returned. Then you can check the
match against the keys you want.</p>
<p>The following code piece will do that job.</p>
+
<pre class="PROGRAMLISTING">
if(ch == KEY_LEFT)
printw("Left arrow is pressed\n");
</pre>
-
<p>Let's write a small program which creates a menu which
can be navigated by up and down arrows.</p>
</div>
<div class="EXAMPLE">
<a name="BSIKE" id="BSIKE"></a>
+ <p><b>Example 10. A Simple Key Usage example</b>
+ </p>
- <p><b>Example 10. A Simple Key Usage example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <stdio.h>
#include <ncurses.h>
return 0;
}
-
void print_menu(WINDOW *menu_win, int highlight)
{
int x, y, i;
<p>Before you do any thing else, the events you want to
receive have to be enabled with <tt class=
"LITERAL">mousemask()</tt>.</p>
+
<pre class="PROGRAMLISTING">
mousemask( mmask_t newmask, /* The events you want to listen to */
mmask_t *oldmask) /* The old events mask */
</pre>
-
<p>The first parameter to above function is a bit mask of
events you would like to listen. By default, all the events
are turned off. The bit mask <tt class=
events.</p>
<p>The following are all the event masks:</p>
+
<pre class="PROGRAMLISTING">
Name Description
---------------------------------------------------------------------
<tt class="LITERAL">getmouse()</tt>.</p>
<p>The code approximately looks like this:</p>
+
<pre class="PROGRAMLISTING">
MEVENT event;
.
.
</pre>
-
<p>getmouse() returns the event into the pointer given to
it. It is a structure which contains</p>
+
<pre class="PROGRAMLISTING">
typedef struct
{
mmask_t bstate; /* button state bits */
}
</pre>
-
<p>The <tt class="LITERAL">bstate</tt> is the main variable
we are interested in. It tells the button state of the
mouse.</p>
<p>Then with a code snippet like the following, we can find
out what happened.</p>
+
<pre class="PROGRAMLISTING">
if(event.bstate & BUTTON1_PRESSED)
printw("Left Button Pressed");
<div class="EXAMPLE">
<a name="BMOME" id="BMOME"></a>
+ <p><b>Example 11. Access the menu with mouse !!!</b>
+ </p>
- <p><b>Example 11. Access the menu with mouse !!!</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
return 0;
}
-
void print_menu(WINDOW *menu_win, int highlight)
{
int x, y, i;
fill the values of x and y co-ordinates in the arguments
given to it. Since getyx() is a macro you don't have to
pass the address of the variables. It can be called as</p>
+
<pre class="PROGRAMLISTING">
getyx(win, y, x);
/* win: window pointer
* y, x: y, x co-ordinates will be put into this variables
*/
</pre>
-
<p>The function getparyx() gets the beginning co-ordinates
of the sub window relative to the main window. This is some
times useful to update a sub window. When designing fancy
<p>This function can be used to make the cursor invisible.
The parameter to this function should be</p>
+
<pre class="PROGRAMLISTING">
0 : invisible or
1 : normal or
<div class="EXAMPLE">
<a name="BTELE" id="BTELE"></a>
+ <p><b>Example 12. Temporarily Leaving Curses Mode</b>
+ </p>
- <p><b>Example 12. Temporarily Leaving Curses Mode</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
<div class="EXAMPLE">
<a name="BACSVARS" id="BACSVARS"></a>
+ <p><b>Example 13. ACS Variables Example</b>
+ </p>
- <p><b>Example 13. ACS Variables Example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
interface design is such that windows may dive deeper into
the visibility stack or pop to the top at runtime, the
resulting book-keeping can be tedious and difficult to get
- right. Hence the panels library.</i></span></p>
+ right. Hence the panels library.</i></span>
+ </p>
<p>If you have lot of overlapping windows, then panels
library is the way to go. It obviates the need of doing
<hr>
<h3 class="SECT2"><a name="COMPILEPANELS" id=
- "COMPILEPANELS">16.2. Compiling With the Panels
- Library</a></h3>
+ "COMPILEPANELS">16.2. Compiling With the Panels Library</a></h3>
<p>To use panels library functions, you have to include
panel.h and to link the program with panels library the
flag -lpanel should be added along with -lncurses in that
order.</p>
+
<pre class="PROGRAMLISTING">
#include <panel.h>
.
compile and link: gcc <program file> -lpanel -lncurses
</pre>
-
<div class="EXAMPLE">
<a name="PPASI" id="PPASI"></a>
+ <p><b>Example 14. Panel basics</b>
+ </p>
- <p><b>Example 14. Panel basics</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <panel.h>
<div class="EXAMPLE">
<a name="PPABR" id="PPABR"></a>
+ <p><b>Example 15. Panel Window Browsing Example</b>
+ </p>
- <p><b>Example 15. Panel Window Browsing Example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <panel.h>
<div class="EXAMPLE">
<a name="PPARE" id="PPARE"></a>
+ <p><b>Example 16. Panel Moving and Resizing example</b>
+ </p>
- <p><b>Example 16. Panel Moving and Resizing
- example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <panel.h>
<div class="EXAMPLE">
<a name="PPAHI" id="PPAHI"></a>
+ <p><b>Example 17. Panel Hiding and Showing example</b>
+ </p>
- <p><b>Example 17. Panel Hiding and Showing
- example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <panel.h>
<hr>
<h3 class="SECT2"><a name="COMPILEMENUS" id=
- "COMPILEMENUS">17.2. Compiling With the Menu
- Library</a></h3>
+ "COMPILEMENUS">17.2. Compiling With the Menu Library</a></h3>
<p>To use menu library functions, you have to include
menu.h and to link the program with menu library the flag
-lmenu should be added along with -lncurses in that
order.</p>
+
<pre class="PROGRAMLISTING">
#include <menu.h>
.
compile and link: gcc <program file> -lmenu -lncurses
</pre>
-
<div class="EXAMPLE">
<a name="MMESI" id="MMESI"></a>
+ <p><b>Example 18. Menu Basics</b>
+ </p>
- <p><b>Example 18. Menu Basics</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
<p>The menu_driver accepts following navigational
requests.</p>
+
<pre class="PROGRAMLISTING">
REQ_LEFT_ITEM Move left to an item.
REQ_RIGHT_ITEM Move right to an item.
REQ_NEXT_MATCH Move to the next item matching the pattern match.
REQ_PREV_MATCH Move to the previous item matching the pattern match.
</pre>
-
<p>Don't get overwhelmed by the number of options. We will
see them slowly one after another. The options of interest
in this example are REQ_UP_ITEM and REQ_DOWN_ITEM. These
<ul>
<li>
<p><span class="emphasis"><i class=
- "EMPHASIS">REQ_LEFT_ITEM and
- REQ_RIGHT_ITEM</i></span></p>
+ "EMPHASIS">REQ_LEFT_ITEM and REQ_RIGHT_ITEM</i></span>
+ </p>
<p>A Menu can be displayed with multiple columns for
more than one item. This can be done by using the
<li>
<p><span class="emphasis"><i class=
- "EMPHASIS">REQ_UP_ITEM and REQ_DOWN_ITEM</i></span></p>
+ "EMPHASIS">REQ_UP_ITEM and REQ_DOWN_ITEM</i></span>
+ </p>
<p>These two options you have seen in the above
example. These options when given, makes the
<li>
<p><span class="emphasis"><i class="EMPHASIS">REQ_SCR_*
- options</i></span></p>
+ options</i></span>
+ </p>
<p>The four options REQ_SCR_ULINE, REQ_SCR_DLINE,
REQ_SCR_DPAGE, REQ_SCR_UPAGE are related to scrolling.
<li>
<p><span class="emphasis"><i class=
"EMPHASIS">REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM
- and REQ_PREV_ITEM</i></span></p>
+ and REQ_PREV_ITEM</i></span>
+ </p>
<p>These requests are self explanatory.</p>
</li>
<li>
<p><span class="emphasis"><i class=
- "EMPHASIS">REQ_TOGGLE_ITEM</i></span></p>
+ "EMPHASIS">REQ_TOGGLE_ITEM</i></span>
+ </p>
<p>This request when given, toggles the present
selection. This option is to be used only in a multi
<li>
<p><span class="emphasis"><i class="EMPHASIS">Pattern
- Requests</i></span></p>
+ Requests</i></span>
+ </p>
<p>Every menu has an associated pattern buffer, which
is used to find the nearest match to the ascii
<li>
<p><span class="emphasis"><i class="EMPHASIS">Mouse
- Requests</i></span></p>
+ Requests</i></span>
+ </p>
<p>In case of KEY_MOUSE requests, according to the
mouse position an action is taken accordingly. The
action to be taken is explained in the man page as,</p>
+
<pre class="PROGRAMLISTING">
<span class="emphasis"><i class=
"EMPHASIS"> If the second argument is the KEY_MOUSE special key, the
<div class="EXAMPLE">
<a name="MMEWI" id="MMEWI"></a>
+ <p><b>Example 19. Menu Windows Usage example</b>
+ </p>
- <p><b>Example 19. Menu Windows Usage example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <menu.h>
<div class="EXAMPLE">
<a name="MMESC" id="MMESC"></a>
+ <p><b>Example 20. Scrolling Menus example</b>
+ </p>
- <p><b>Example 20. Scrolling Menus example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
<div class="EXAMPLE">
<a name="MMEMUCO" id="MMEMUCO"></a>
+ <p><b>Example 21. Milt Columnar Menus Example</b>
+ </p>
- <p><b>Example 21. Milt Columnar Menus Example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
couple of functions set_menu_opts(), menu_opts_on() and
menu_opts() which can be used to manipulate menu options.
The following menu options can be specified.</p>
+
<pre class="PROGRAMLISTING">
O_ONEVALUE
Only one item can be selected for this menu.
Don't wrap around next-item and previous-item,
requests to the other end of the menu.
</pre>
-
<p>All options are on by default. You can switch specific
attributes on or off with menu_opts_on() and
menu_opts_off() functions. You can also use set_menu_opts()
<div class="EXAMPLE">
<a name="MMETO" id="MMETO"></a>
+ <p><b>Example 22. Multi Valued Menus example</b>
+ </p>
- <p><b>Example 22. Multi Valued Menus example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
<div class="EXAMPLE">
<a name="MMEAT" id="MMEAT"></a>
+ <p><b>Example 23. Menu Options example</b>
+ </p>
- <p><b>Example 23. Menu Options example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <menu.h>
"MENUUSERPTR">17.9. The useful User Pointer</a></h3>
<p>We can associate a user pointer with each item in the
- menu. It works the same way as user pointer in panels. It is
- not touched by menu system. You can store any thing you
+ menu. It works the same way as user pointer in panels. It
+ is not touched by menu system. You can store any thing you
like in that. I usually use it to store the function to be
executed when the menu option is chosen (It is selected and
may be the user pressed <ENTER>);</p>
<div class="EXAMPLE">
<a name="MMEUS" id="MMEUS"></a>
+ <p><b>Example 24. Menu User Pointer Usage</b>
+ </p>
- <p><b>Example 24. Menu User Pointer Usage</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
<hr>
<h3 class="SECT2"><a name="COMPILEFORMS" id=
- "COMPILEFORMS">18.2. Compiling With the Forms
- Library</a></h3>
+ "COMPILEFORMS">18.2. Compiling With the Forms Library</a></h3>
<p>To use forms library functions, you have to include
form.h and to link the program with forms library the flag
-lform should be added along with -lncurses in that
order.</p>
+
<pre class="PROGRAMLISTING">
#include <form.h>
.
compile and link: gcc <program file> -lform -lncurses
</pre>
-
<div class="EXAMPLE">
<a name="FFOSI" id="FFOSI"></a>
+ <p><b>Example 25. Forms Basics</b>
+ </p>
- <p><b>Example 25. Forms Basics</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <form.h>
height, width, starty, startx, number of offscreen rows,
and number of additional buffers into the parameters
given to it. It is a sort of inverse of new_field().</p>
+
<pre class="PROGRAMLISTING">
int field_info( FIELD *field, /* field from which to fetch */
int *height, *int width, /* field size */
<p>The location of the field can be moved to a different
position with move_field().</p>
+
<pre class="PROGRAMLISTING">
int move_field( FIELD *field, /* field to alter */
int top, int left); /* new upper-left corner */
</pre>
-
<p>As usual, the changed position can be queried with
field_infor().</p>
</div>
<p>The justification to be done for the field can be
fixed using the function set_field_just().</p>
+
<pre class="PROGRAMLISTING">
int set_field_just(FIELD *field, /* field to alter */
int justmode); /* mode to set */
int field_just(FIELD *field); /* fetch justify mode of field */
</pre>
-
<p>The justification mode valued accepted and returned by
these functions are NO_JUSTIFICATION, JUSTIFY_RIGHT,
JUSTIFY_LEFT, or JUSTIFY_CENTER.</p>
<hr>
<h4 class="SECT3"><a name="FIELDDISPATTRIB" id=
- "FIELDDISPATTRIB">18.3.4. Field Display
- Attributes</a></h4>
+ "FIELDDISPATTRIB">18.3.4. Field Display Attributes</a></h4>
<p>As you have seen, in the above example, display
attribute for the fields can be set with set_field_fore()
be used to query the present foreground, background
attributes and pad character for the field. The following
list gives the usage of functions.</p>
+
<pre class="PROGRAMLISTING">
int set_field_fore(FIELD *field, /* field to alter */
chtype attr); /* attribute to set */
chtype field_pad(FIELD *field); /* field to query */
/* returns present pad character */
</pre>
-
<p>Though above functions seem quite simple, using colors
with set_field_fore() may be frustrating in the
beginning. Let me first explain about foreground and
<div class="EXAMPLE">
<a name="FFOAT" id="FFOAT"></a>
+ <p><b>Example 26. Form Attributes example</b>
+ </p>
- <p><b>Example 26. Form Attributes example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <form.h>
you can set to control various aspects of forms
processing. You can manipulate them with these
functions:</p>
+
<pre class="PROGRAMLISTING">
int set_field_opts(FIELD *field, /* field to alter */
int attr); /* attribute to set */
int field_opts(FIELD *field); /* field to query */
</pre>
-
<p>The function set_field_opts() can be used to directly
set attributes of a field or you can choose to switch a
few attributes on and off with field_opts_on() and
<div class="EXAMPLE">
<a name="FFOOP" id="FFOOP"></a>
+ <p><b>Example 27. Field Options Usage example</b>
+ </p>
- <p><b>Example 27. Field Options Usage example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <form.h>
becomes TRUE. So a field's status can be queried to find
out whether it has been modified or not. The following
functions can assist in those operations.</p>
+
<pre class="PROGRAMLISTING">
int set_field_status(FIELD *field, /* field to alter */
int status); /* status to set */
int field_status(FIELD *field); /* fetch status of field */
</pre>
-
<p>It is better to check the field's status only after
after leaving the field, as data buffer might not have
been updated yet as the validation is still due. To
by forms library and can be used for any purpose by the
user. The following functions set and fetch user
pointer.</p>
+
<pre class="PROGRAMLISTING">
int set_field_userptr(FIELD *field,
char *userptr); /* the user pointer you wish to associate */
<hr>
<h4 class="SECT3"><a name="VARIABLESIZEFIELDS" id=
- "VARIABLESIZEFIELDS">18.3.8. Variable-Sized
- Fields</a></h4>
+ "VARIABLESIZEFIELDS">18.3.8. Variable-Sized Fields</a></h4>
<p>If you want a dynamically changing field with variable
width, this is the feature you want to put to full use.
<p>To make a field dynamically growable, the option
O_STATIC should be turned off. This can be done with
a</p>
+
<pre class="PROGRAMLISTING">
field_opts_off(field_pointer, O_STATIC);
</pre>
-
<p>But it is usually not advisable to allow a field to
grow infinitely. You can set a maximum limit to the
growth of the field with</p>
+
<pre class="PROGRAMLISTING">
int set_max_field(FIELD *field, /* Field on which to operate */
int max_growth); /* maximum growth allowed for the field */
</pre>
-
<p>The field info for a dynamically growable field can be
retrieved by</p>
+
<pre class="PROGRAMLISTING">
int dynamic_field_info( FIELD *field, /* Field on which to operate */
int *prows, /* number of rows will be filled in this */
</pre>Though field_info work as usual, it is advisable to use this
function to get the proper attributes of a dynamically growable
field.
-
<p>Recall the library routine new_field; a new field
created with height set to one will be defined to be a
one line field. A new field created with height greater
<div class="EXAMPLE">
<a name="FFOWI" id="FFOWI"></a>
+ <p><b>Example 28. Form Windows Example</b>
+ </p>
- <p><b>Example 28. Form Windows Example</b></p>
<pre class="PROGRAMLISTING">
<span class="INLINEMEDIAOBJECT">#include <form.h>
<p>Validation can be attached to a field with the following
function.</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
FIELDTYPE *ftype, /* type to associate */
...); /* additional arguments*/
</pre>Once set, the validation type for a field can be queried with
+
<pre class="PROGRAMLISTING">
FIELDTYPE *field_type(FIELD *field); /* field to query */
</pre>
-
<p>The form driver validates the data in a field only when
data is entered by the end-user. Validation does not occur
when</p>
<p>This field type accepts alphabetic data; no blanks, no
digits, no special characters (this is checked at
character-entry time). It is set up with:</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
TYPE_ALPHA, /* type to associate */
int width); /* minimum width of field */
</pre>
-
<p>The width argument sets a minimum width of data. The
user has to enter at-least width number of characters
before he can leave the field. Typically you'll want to set
<p>This field type accepts alphabetic data and digits; no
blanks, no special characters (this is checked at
character-entry time). It is set up with:</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
TYPE_ALNUM, /* type to associate */
int width); /* minimum width of field */
</pre>
-
<p>The width argument sets a minimum width of data. As with
TYPE_ALPHA, typically you'll want to set this to the field
- width; if it is greater than the field width, the validation
- check will always fail. A minimum width of zero makes field
- completion optional.</p>
+ width; if it is greater than the field width, the
+ validation check will always fail. A minimum width of zero
+ makes field completion optional.</p>
<h1 class="BRIDGEHEAD"><a name="AEN1077" id=
"AEN1077"></a>TYPE_ENUM</h1>
among a specified set of string values (for example, the
two-letter postal codes for U.S. states). It is set up
with:</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
TYPE_ENUM, /* type to associate */
int checkcase; /* case-sensitive? */
int checkunique); /* must specify uniquely? */
</pre>
-
<p>The valuelist parameter must point at a NULL-terminated
list of valid strings. The checkcase argument, if true,
makes comparison with the string case-sensitive.</p>
<p>This field type accepts an integer. It is set up as
follows:</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
TYPE_INTEGER, /* type to associate */
int padding, /* # places to zero-pad to */
int vmin, int vmax); /* valid range */
</pre>
-
<p>Valid characters consist of an optional leading minus
and digits. The range check is performed on exit. If the
range maximum is less than or equal to the minimum, the
<p>This field type accepts a decimal number. It is set up
as follows:</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
TYPE_NUMERIC, /* type to associate */
int padding, /* # places of precision */
int vmin, int vmax); /* valid range */
</pre>
-
<p>Valid characters consist of an optional leading minus
and digits. possibly including a decimal point. The range
check is performed on exit. If the range maximum is less
<p>This field type accepts data matching a regular
expression. It is set up as follows:</p>
+
<pre class="PROGRAMLISTING">
int set_field_type(FIELD *field, /* field to alter */
TYPE_REGEXP, /* type to associate */
char *regexp); /* expression to match */
</pre>
-
<p>The syntax for regular expressions is that of
regcomp(3). The check for regular-expression match is
performed on exit.</p>
<p>As in the menu system, form_driver() plays a very
important role in forms system. All types of requests to
forms system should be funneled through form_driver().</p>
+
<pre class="PROGRAMLISTING">
int form_driver(FORM *form, /* form on which to operate */
int request) /* form request code */
</pre>
-
<p>As you have seen some of the examples above, you have to
be in a loop looking for user input and then decide whether
it is a field data or a form request. The form requests are
lot of fields and logical sections, then you can divide
the form into pages. The function set_new_page() to set a
new page at the field specified.</p>
+
<pre class="PROGRAMLISTING">
int set_new_page(FIELD *field,/* Field at which page break to be set or unset */
bool new_page_flag); /* should be TRUE to put a break */
</pre>
-
<p>The following requests allow you to move to different
pages</p>
<p><span class="emphasis"><i class="EMPHASIS">CDK stands
for 'Curses Development Kit' and it currently contains 21
ready to use widgets which facilitate the speedy
- development of full screen curses programs.</i></span></p>
+ development of full screen curses programs.</i></span>
+ </p>
<p>The kit provides some useful widgets, which can be used
- in your programs directly. It is pretty well written and the
- documentation is very good. The examples in the examples
- directory can be a good place to start for beginners. The
- CDK can be downloaded from <a href=
+ in your programs directly. It is pretty well written and
+ the documentation is very good. The examples in the
+ examples directory can be a good place to start for
+ beginners. The CDK can be downloaded from <a href=
"https://invisible-island.net/cdk/" target=
"_top">https://invisible-island.net/cdk/</a> . Follow the
instructions in README file to install it.</p>
<p>The following is the list of widgets provided with cdk
and their description.</p>
+
<pre class="PROGRAMLISTING">
Widget Type Quick Description
===========================================================================
when you need to display loads of information.
===========================================================================
</pre>
-
<p>A few of the widgets are modified by Thomas Dickey in
recent versions.</p>
</div>
which are passed to CDK functions. For Example</p>
<p>If the string</p>
+
<pre class="PROGRAMLISTING">
"</B/1>This line should have a yellow foreground and a blue
background.<!1>"
</pre>
-
<p>given as a parameter to newCDKLabel(), it prints the
line with yellow foreground and blue background. There
are other tags available for justifying string, embedding
professional-looking dialog boxes from within shell
scripts. This article presents a tutorial introduction to
the dialog utility, and shows examples of how and where it
- can be used</i></span></p>
+ can be used</i></span>
+ </p>
<p>As he explains, dialog is a real gem in making
professional-looking dialog boxes with ease. It creates a
<p>Game of life is a wonder of math. In <a href=
"http://www.math.com/students/wonders/life/life.html"
target="_top">Paul Callahan</a>'s words</p>
+
<pre class="PROGRAMLISTING">
<span class="emphasis"><i class=
"EMPHASIS">The Game of Life (or simply Life) is not a game in the conventional sense. There
at a starting position (or pattern) and see what will happen in the future. The
only way to find out is to follow the rules of the game.</i></span>
</pre>
-
<p>This program starts with a simple inverted U pattern and
shows how wonderful life works. There is a lot of room for
improvement in the program. You can let the user enter
life.</p>
<p><span class="emphasis"><i class="EMPHASIS">File Path:
- JustForFun/life.c</i></span></p>
+ JustForFun/life.c</i></span>
+ </p>
</div>
<div class="SECT2">
order.</p>
<p><span class="emphasis"><i class="EMPHASIS">File Path:
- JustForFun/magic.c</i></span></p>
+ JustForFun/magic.c</i></span>
+ </p>
</div>
<div class="SECT2">
larger disk over a small disk at any time.</p>
<p><span class="emphasis"><i class="EMPHASIS">File Path:
- JustForFun/hanoi.c</i></span></p>
+ JustForFun/hanoi.c</i></span>
+ </p>
</div>
<div class="SECT2">
technique.</p>
<p><span class="emphasis"><i class="EMPHASIS">File Path:
- JustForFun/queens.c</i></span></p>
+ JustForFun/queens.c</i></span>
+ </p>
</div>
<div class="SECT2">
<p>A fun game, if you have time to kill.</p>
<p><span class="emphasis"><i class="EMPHASIS">File Path:
- JustForFun/shuffle.c</i></span></p>
+ JustForFun/shuffle.c</i></span>
+ </p>
</div>
<div class="SECT2">
helpful.</p>
<p><span class="emphasis"><i class="EMPHASIS">File Path:
- JustForFun/tt.c</i></span></p>
+ JustForFun/tt.c</i></span>
+ </p>
</div>
</div>
<div class="SECT1">
<hr>
- <h2 class="SECT1"><a name="REF" id="REF">21.
- References</a></h2>
+ <h2 class="SECT1"><a name="REF" id="REF">21. References</a></h2>
<ul>
<li>
<!--
- $Id: announce.html,v 1.66 2021/10/20 22:54:22 tom Exp $
+ $Id: announce.html,v 1.67 2022/11/26 17:41:51 tom Exp $
****************************************************************************
- * Copyright 2018-2020,2021 Thomas E. Dickey *
+ * Copyright 2018-2021,2022 Thomas E. Dickey *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
* copy of this software and associated documentation files (the *
including</p>
<ul>
- <li><a href="https://invisible-island.net/ncurses/man/captoinfo.1m.html"><span class=
- "part-name">captoinfo</span></a>, a termcap conversion
- tool</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/captoinfo.1m.html"><span class="part-name">
+ captoinfo</span></a>, a termcap conversion tool</li>
- <li><a href="https://invisible-island.net/ncurses/man/clear.1.html"><span class=
- "part-name">clear</span></a>, utility for clearing the
- screen</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/clear.1.html"><span class="part-name">
+ clear</span></a>, utility for clearing the screen</li>
- <li><a href="https://invisible-island.net/ncurses/man/infocmp.1m.html"><span class=
- "part-name">infocmp</span></a>, the terminfo decompiler</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/infocmp.1m.html"><span class="part-name">
+ infocmp</span></a>, the terminfo decompiler</li>
- <li><a href="https://invisible-island.net/ncurses/man/tabs.1.html"><span class=
- "part-name">tabs</span></a>, set tabs on a terminal</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/tabs.1.html"><span class="part-name">
+ tabs</span></a>, set tabs on a terminal</li>
- <li><a href="https://invisible-island.net/ncurses/man/tic.1m.html"><span class=
- "part-name">tic</span></a>, the terminfo compiler</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/tic.1m.html"><span class="part-name">
+ tic</span></a>, the terminfo compiler</li>
- <li><a href="https://invisible-island.net/ncurses/man/toe.1m.html"><span class=
- "part-name">toe</span></a>, list (table of) terminfo
- entries</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/toe.1m.html"><span class="part-name">
+ toe</span></a>, list (table of) terminfo entries</li>
- <li><a href="https://invisible-island.net/ncurses/man/tput.1.html"><span class=
- "part-name">tput</span></a>, utility for retrieving terminal
- capabilities in shell scripts</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/tput.1.html"><span class="part-name">
+ tput</span></a>, utility for retrieving terminal capabilities
+ in shell scripts</li>
- <li><a href="https://invisible-island.net/ncurses/man/tset.1.html"><span class=
- "part-name">tset</span></a>, to initialize the terminal</li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/man/tset.1.html"><span class="part-name">
+ tset</span></a>, to initialize the terminal</li>
</ul>
<p>Full manual pages are provided for the library and tools.</p>
<li>
<p>A script is provided which enables <a href=
- "https://invisible-island.net/ncurses/ncurses-openbsd.html">OpenBSD</a> users to
- upgrade their system to use ncurses 6.3 (OpenBSD developers
- are also invited to do this).</p>
+ "https://invisible-island.net/ncurses/ncurses-openbsd.html">OpenBSD</a>
+ users to upgrade their system to use ncurses 6.3 (OpenBSD
+ developers are also invited to do this).</p>
</li>
</ul>
<li>
<p>check for screen size-change in <a href=
- "https://invisible-island.net/ncurses/man/curs_scr_dump.3x.html">scr_init</a> and
- <a href=
- "https://invisible-island.net/ncurses/man/curs_scr_dump.3x.html">scr_restore</a>, in
- case a screen dump does not match the current screen
- dimensions</p>
+ "https://invisible-island.net/ncurses/man/curs_scr_dump.3x.html">
+ scr_init</a> and <a href=
+ "https://invisible-island.net/ncurses/man/curs_scr_dump.3x.html">
+ scr_restore</a>, in case a screen dump does not match the
+ current screen dimensions</p>
</li>
</ul>
<p>Along with the library and utilities, improvements were made
to the <a href=
- "https://invisible-island.net/ncurses/ncurses-examples.html">ncurses-examples</a>. Most of
- this activity aimed at improving the test-packages. A few changes
- are more generally useful, e.g., for the main ncurses
+ "https://invisible-island.net/ncurses/ncurses-examples.html">ncurses-examples</a>.
+ Most of this activity aimed at improving the test-packages. A few
+ changes are more generally useful, e.g., for the main ncurses
test-program, and for analyzing traces using the
<em>tracemunch</em> script:</p>
</dt>
<dd>to demonstrate <a href=
- "https://invisible-island.net/ncurses/man/form_field.3x.html">move_field</a>, and a stub
- for a corresponding demo of <a href=
- "https://invisible-island.net/ncurses/man/form_field_new.3x.html">dup_field</a>.</dd>
+ "https://invisible-island.net/ncurses/man/form_field.3x.html">move_field</a>,
+ and a stub for a corresponding demo of <a href=
+ "https://invisible-island.net/ncurses/man/form_field_new.3x.html">
+ dup_field</a>.</dd>
<dt><span class="part-name"><em>test_tparm</em></span>
</dt>
<blockquote style="word-break:keep-all">
<p><tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-absolute">absolute</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-att610_cvis">att610+cvis</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot">foot</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot-direct">foot-direct</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-hp98550-color">hp98550-color</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-hpterm-color2">hpterm-color2</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-hterm">hterm</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-hterm-256color">hterm-256color</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux-s">linux-s</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty_keypad">putty+keypad</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty_screen">putty+screen</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty-screen">putty-screen</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-screen.linux-s">screen.linux-s</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-scrt/securecrt">scrt/securecrt</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-tmux-direct">tmux-direct</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_cvis">vt220+cvis</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_cvis8">vt220+cvis8</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_pcedit">vt220+pcedit</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_vtedit">vt220+vtedit</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220-base">vt220-base</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt52_keypad">vt52+keypad</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_256color2">xterm+256color2</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_88color2">xterm+88color2</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-direct16">xterm-direct16</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-direct256">xterm-direct256</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_nofkeys">xterm+nofkeys</a></tt>,
- and <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_nopcfkeys">xterm+nopcfkeys</a></tt>.</p>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-absolute">
+ absolute</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-att610_cvis">
+ att610+cvis</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot">
+ foot</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot-direct">
+ foot-direct</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-hp98550-color">
+ hp98550-color</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-hpterm-color2">
+ hpterm-color2</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-hterm">
+ hterm</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-hterm-256color">
+ hterm-256color</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux-s">
+ linux-s</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty_keypad">
+ putty+keypad</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty_screen">
+ putty+screen</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty-screen">
+ putty-screen</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-screen.linux-s">
+ screen.linux-s</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-scrt/securecrt">
+ scrt/securecrt</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-tmux-direct">
+ tmux-direct</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_cvis">
+ vt220+cvis</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_cvis8">
+ vt220+cvis8</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_pcedit">
+ vt220+pcedit</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_vtedit">
+ vt220+vtedit</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220-base">
+ vt220-base</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt52_keypad">
+ vt52+keypad</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_256color2">
+ xterm+256color2</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_88color2">
+ xterm+88color2</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-direct16">
+ xterm-direct16</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-direct256">
+ xterm-direct256</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_nofkeys">
+ xterm+nofkeys</a></tt>, and <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_nopcfkeys">
+ xterm+nopcfkeys</a></tt>.</p>
</blockquote>
<p>There are many changes to existing terminal descriptions. Some
<ul>
<li>correct use-ordering in some <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-direct">xterm-direct</a>
- flavors</li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-direct">
+ xterm-direct</a> flavors</li>
<li>fix some sgr inconsistencies in <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-d230c">d230c</a>, <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-ibm6153">ibm6153</a>,
- <a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-ibm6154">ibm6154</a>,
- <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-ncrvt100an">ncrvt100an</a></li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-d230c">
+ d230c</a>, <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ibm6153">
+ ibm6153</a>, <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ibm6154">
+ ibm6154</a>, <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ncrvt100an">
+ ncrvt100an</a></li>
<li>improve <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt50h">vt50h</a> and <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt52">vt52</a> based on
- DECScope manual</li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt50h">
+ vt50h</a> and <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt52">
+ vt52</a> based on DECScope manual</li>
<li>use <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-hp_arrows">hp+arrows</a> in a
- few places</li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-hp_arrows">
+ hp+arrows</a> in a few places</li>
<li>use <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-hp_pfk-cr">hp+pfk-cr</a> in a
- few places</li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-hp_pfk-cr">
+ hp+pfk-cr</a> in a few places</li>
<li>use <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_cvis">vt220+cvis</a> in
- <tt>st</tt>, <tt>terminology</tt>, <tt>termite</tt> since they
- ignore blinking-cursor detail in <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-att610_cvis">att610+cvis</a></li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_cvis">
+ vt220+cvis</a> in <tt>st</tt>, <tt>terminology</tt>,
+ <tt>termite</tt> since they ignore blinking-cursor detail in
+ <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-att610_cvis">
+ att610+cvis</a></li>
</ul>
<p>while others affected specific descriptions. These were
<blockquote>
<p><tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-kitty_common">kitty+common</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-mlterm3">mlterm3</a></tt>,
- <tt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-terminal">ms-terminal</a></tt></p>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-kitty_common">
+ kitty+common</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-mlterm3">
+ mlterm3</a></tt>, <tt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-terminal">
+ ms-terminal</a></tt></p>
</blockquote>
<p>while these are specific fixes based on reviewing
<dl>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-aaa_dec">aaa+dec</a>,
- aaa+rv</dt>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-aaa_dec">
+ aaa+dec</a>, aaa+rv</dt>
<dd>correct rmacs/smacs</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-aaa_rv">aaa+rv</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-aaa_rv">
+ aaa+rv</a>
</dt>
<dd>correct sgr</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-icl6404">icl6404</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-icl6404">
+ icl6404</a>
</dt>
<dd>correct csr</dd>
- <dt><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-kitty">kitty</a>
+ <dt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-kitty">
+ kitty</a>
</dt>
<dd>use att610+cvis, xterm+tmux and ansi+enq</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-konsole-base">konsole-base</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-konsole-base">
+ konsole-base</a>
</dt>
<dd>re-enable "bel"</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux2.6">linux2.6</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux2.6">
+ linux2.6</a>
</dt>
<dd>fix pound-sign mapping in acsc</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux3.0">linux3.0</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux3.0">
+ linux3.0</a>
</dt>
<dd>modify to reflect default mapping of shift-tab by kbd
1.14</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-pccons">pccons</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-pccons">
+ pccons</a>
</dt>
<dd>fill in some missing pieces, to make it comparable to the
vt220 entry</dd>
- <dt><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-putty">putty</a>
+ <dt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty">
+ putty</a>
</dt>
<dd>use vt100+fnkeys, add rep</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-screen">screen</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-screen">
+ screen</a>
</dt>
<dd>use vt100+enq</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-terminator">terminator</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-terminator">
+ terminator</a>
</dt>
<dd>corrected tsl capability</dd>
- <dt><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-ti916">ti916</a>
+ <dt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ti916">
+ ti916</a>
</dt>
<dd>correct cup</dd>
- <dt><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-tmux">tmux</a>
+ <dt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-tmux">
+ tmux</a>
</dt>
<dd>change kbs to ^?</dd>
- <dt><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220">vt220</a>
+ <dt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220">
+ vt220</a>
</dt>
<dd>use vt220+cvis</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt420_lrmm">vt420+lrmm</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt420_lrmm">
+ vt420+lrmm</a>
</dt>
<dd>add smglp and smgrp</dd>
- <dt><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-vt420">vt420</a>
+ <dt><a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt420">
+ vt420</a>
</dt>
<dd>use vt420+lrmm</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-new">xterm-new</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-new">
+ xterm-new</a>
</dt>
<dd>add nel</dd>
<dt><a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-vt52">xterm-vt52</a>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-vt52">
+ xterm-vt52</a>
</dt>
<dd>use vt52+keypad</dd>
<ul>
<li>add shifted Linux console keys in <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux_sfkeys">linux+sfkeys</a>
- entry for <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-screen.linux">screen.linux</a></li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux_sfkeys">
+ linux+sfkeys</a> entry for <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-screen.linux">
+ screen.linux</a></li>
<li>add Smulx to <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-alacritty">alacritty</a></li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-alacritty">
+ alacritty</a></li>
<li>add kbeg to <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_keypad">xterm+keypad</a>
- to accommodate termcap applications</li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_keypad">
+ xterm+keypad</a> to accommodate termcap applications</li>
<li>add extensions in <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_tmux">xterm+tmux</a>
- and <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-ecma_strikeout">ecma+strikeout</a>
- to <a href=
- "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-terminal">ms-terminal</a>,
- but cancel the non-working Cr and Ms capabilities</li>
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_tmux">
+ xterm+tmux</a> and <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ecma_strikeout">
+ ecma+strikeout</a> to <a href=
+ "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-terminal">
+ ms-terminal</a>, but cancel the non-working Cr and Ms
+ capabilities</li>
</ul>
<h3><a name="h3-documentation" id=
<li>
<p>fills in overlooked descriptions of features which were
- described in the <a href="https://invisible-island.net/ncurses/NEWS.html">NEWS</a> file
- but treated sketchily in manual pages.</p>
+ described in the <a href=
+ "https://invisible-island.net/ncurses/NEWS.html">NEWS</a>
+ file but treated sketchily in manual pages.</p>
</li>
</ul>
<ul>
<li>
<p>make <em>opts</em> extension for <a href=
- "https://invisible-island.net/ncurses/man/curs_getcchar.3x.html#h3-getcchar"><tt>getcchar</tt></a>
- work as documented for <a href=
- "https://invisible-island.net/ncurses/announce-6.1.htmll#h4-new-library">ncurses
- 6.1</a>, adding “<tt>-g</tt>” flag to
+ "https://invisible-island.net/ncurses/man/curs_getcchar.3x.html#h3-getcchar">
+ <tt>getcchar</tt></a> work as documented for <a href=
+ "https://invisible-island.net/ncurses/announce-6.1.html#h4-new-library">
+ ncurses 6.1</a>, adding “<tt>-g</tt>” flag to
<em>demo_new_pair</em> to illustrate.</p>
</li>
<li>
- <p>modify <a href="https://invisible-island.net/ncurses/man/tset.1.html">tset</a>
+ <p>modify <a href=
+ "https://invisible-island.net/ncurses/man/tset.1.html">tset</a>
“-q” option to refrain from modifying
terminal modes, to match the documentation.</p>
</li>
<li>
<p>add history note to <a href=
- "https://invisible-island.net/ncurses/man/curs_scanw.3x.html#h2-HISTORY">curs_scanw.3x</a>
- for <stdarg.h> and <varargs.h></p>
+ "https://invisible-island.net/ncurses/man/curs_scanw.3x.html#h2-HISTORY">
+ curs_scanw.3x</a> for <stdarg.h> and
+ <varargs.h></p>
</li>
<li>
<p>add history note to <a href=
- "https://invisible-island.net/ncurses/man/curs_printw.3x.html#h2-HISTORY">curs_printw.3x</a>
- for <stdarg.h> and <varargs.h></p>
+ "https://invisible-island.net/ncurses/man/curs_printw.3x.html#h2-HISTORY">
+ curs_printw.3x</a> for <stdarg.h> and
+ <varargs.h></p>
</li>
<li>
<p>add portability note to <a href=
- "https://invisible-island.net/ncurses/man/ncurses.3x.html#h3-Header-files">ncurses.3x</a>
- regarding <stdarg.h></p>
+ "https://invisible-island.net/ncurses/man/ncurses.3x.html#h3-Header-files">
+ ncurses.3x</a> regarding <stdarg.h></p>
</li>
<li>
<p>add historical notes to <a href=
- "https://invisible-island.net/ncurses/man/tput.1.html#h2-HISTORY">tput</a>,
- <a href="https://invisible-island.net/ncurses/man/curs_terminfo.3x.html#h2-HISTORY">
+ "https://invisible-island.net/ncurses/man/tput.1.html#h2-HISTORY">
+ tput</a>, <a href=
+ "https://invisible-island.net/ncurses/man/curs_terminfo.3x.html#h2-HISTORY">
curses-terminfo</a> and <a href=
- "https://invisible-island.net/ncurses/man/curs_color.3x.html#h2-HISTORY">curses-color</a>
- manpages based on source-code for SVr2, SVr3 and
- SVr4.</p>
+ "https://invisible-island.net/ncurses/man/curs_color.3x.html#h2-HISTORY">
+ curses-color</a> manpages based on source-code for SVr2,
+ SVr3 and SVr4.</p>
</li>
<li>
<p>improve history section for <a href=
- "https://invisible-island.net/ncurses/man/tset.1.html#h2-HISTORY">tset</a> manpage
- based on the 1BSD tarball, which preceded BSD's SCCS
- checkins by more than three years.</p>
+ "https://invisible-island.net/ncurses/man/tset.1.html#h2-HISTORY">
+ tset</a> manpage based on the 1BSD tarball, which
+ preceded BSD's SCCS checkins by more than three
+ years.</p>
</li>
</ul>
</li>
<li>
<p>improve manual page for <a href=
- "https://invisible-island.net/ncurses/man/panel.3x.html#h2-PORTABILITY">panel</a>
- library, extending the portability section as well as
- documenting error-returns.</p>
+ "https://invisible-island.net/ncurses/man/panel.3x.html#h2-PORTABILITY">
+ panel</a> library, extending the portability section as
+ well as documenting error-returns.</p>
</li>
<li>
<p>add section on margins to <a href=
- "https://invisible-island.net/ncurses/man/terminfo.5.html#h3-Margins">terminfo.5</a>,
- adapted from X/Open Curses.</p>
+ "https://invisible-island.net/ncurses/man/terminfo.5.html#h3-Margins">
+ terminfo.5</a>, adapted from X/Open Curses.</p>
</li>
<li>
<p>improve <a href=
- "https://invisible-island.net/ncurses/man/term.5.html#h3-LEGACY-STORAGE-FORMAT">man/term.5</a>
- section on legacy storage format.</p>
+ "https://invisible-island.net/ncurses/man/term.5.html#h3-LEGACY-STORAGE-FORMAT">
+ man/term.5</a> section on legacy storage format.</p>
</li>
<li>
<li>
<p>improve description of BSD-style padding in <a href=
- "https://invisible-island.net/ncurses/man/curs_termcap.3x.html#h2-BUGS">curs_termcap.3x</a></p>
+ "https://invisible-island.net/ncurses/man/curs_termcap.3x.html#h2-BUGS">
+ curs_termcap.3x</a></p>
</li>
<li>
<p>add a note in manual page to explain <a href=
"https://invisible-island.net/ncurses/man/curs_getch.3x.html#h3-Ungetting-characters">
ungetch</a> vs <a href=
- "https://invisible-island.net/ncurses/man/curs_get_wch.3x.html#h3-unget_wch">unget_wch</a>.</p>
+ "https://invisible-island.net/ncurses/man/curs_get_wch.3x.html#h3-unget_wch">
+ unget_wch</a>.</p>
</li>
<li>
<p>improve description of error-returns in <a href=
- "https://invisible-island.net/ncurses/man/curs_addch.3x.html#h2-RETURN-VALUE">waddch</a>
- and <a href=
- "https://invisible-island.net/ncurses/man/curs_addstr.3x.html#h2-RETURN-VALUE">waddnstr</a>
- manual pages.</p>
+ "https://invisible-island.net/ncurses/man/curs_addch.3x.html#h2-RETURN-VALUE">
+ waddch</a> and <a href=
+ "https://invisible-island.net/ncurses/man/curs_addstr.3x.html#h2-RETURN-VALUE">
+ waddnstr</a> manual pages.</p>
</li>
</ul>
</li>
and interesting. Most of the bug-fixes were for local issues
which did not affect compatibility across releases. Since those
are detailed in the <a href=
- "https://invisible-island.net/ncurses/NEWS.html#t20211018">NEWS</a> file no elaboration is
- needed here.</p>
+ "https://invisible-island.net/ncurses/NEWS.html#t20211018">NEWS</a>
+ file no elaboration is needed here.</p>
<p>The interesting bugs were:</p>
<ul>
<li>
<p>modify <a href=
- "https://invisible-island.net/ncurses/man/curs_bkgd.3x.html#h3-bkgd">wbkgd</a> and
- <a href=
- "https://invisible-island.net/ncurses/man/curs_bkgrnd.3x.html#h3-bkgrnd">wbkgrnd</a> to
- avoid storing a null in the background character, because it
- may be used in cases where the corresponding 0x80 is not
- treated as a null.</p>
+ "https://invisible-island.net/ncurses/man/curs_bkgd.3x.html#h3-bkgd">
+ wbkgd</a> and <a href=
+ "https://invisible-island.net/ncurses/man/curs_bkgrnd.3x.html#h3-bkgrnd">
+ wbkgrnd</a> to avoid storing a null in the background
+ character, because it may be used in cases where the
+ corresponding 0x80 is not treated as a null.</p>
<p>This was a regression introduced in ncurses 6.2 (<a href=
"https://lists.gnu.org/archive/html/bug-ncurses/2020-03/msg00000.html">reported</a>
<li>
<p>remove output-related checks for <a href=
- "https://invisible-island.net/ncurses/man/curs_outopts.3x.html">nl/nonl</a> (also
- <a href=
+ "https://invisible-island.net/ncurses/man/curs_outopts.3x.html">
+ nl/nonl</a> (also <a href=
"https://lists.gnu.org/archive/html/bug-ncurses/2020-09/msg00018.html">
reported</a> on the mailing list).</p>
</li>
in any implementation of curses, aside from source code.
Unlike the other two fixes, the problem was discovered while
studying OpenBSD's version of <a href=
- "https://invisible-island.net/ncurses/ncurses-openbsd.html#issue_tput">tset</a>.</p>
+ "https://invisible-island.net/ncurses/ncurses-openbsd.html#issue_tput">
+ tset</a>.</p>
</li>
</ul>
<li>
<p>add a special case in the configure script to work around
one of the build-time breakages reported for <a href=
- "https://invisible-island.net/ncurses/ncurses-openbsd.html">OpenBSD 6</a> here:</p>
+ "https://invisible-island.net/ncurses/ncurses-openbsd.html">OpenBSD
+ 6</a> here:</p>
<blockquote>
<p><a href=
</li>
<li>
- <p>The <a href="https://invisible-island.net/ncurses/man/tic.1m.html"><span class=
- "part-name">tic</span></a>/<a href=
- "https://invisible-island.net/ncurses/man/captoinfo.1m.html">captoinfo</a> utility
- provided with <span class="main-name">ncurses</span> has the
- ability to translate many termcaps from the XENIX, IBM and
- AT&T extension sets.</p>
+ <p>The <a href=
+ "https://invisible-island.net/ncurses/man/tic.1m.html"><span class="part-name">
+ tic</span></a>/<a href=
+ "https://invisible-island.net/ncurses/man/captoinfo.1m.html">captoinfo</a>
+ utility provided with <span class="main-name">ncurses</span>
+ has the ability to translate many termcaps from the XENIX,
+ IBM and AT&T extension sets.</p>
</li>
<li>
<p>A BSD-like <a href=
- "https://invisible-island.net/ncurses/man/tset.1.html"><span class=
- "part-name">tset</span></a> utility is provided.</p>
+ "https://invisible-island.net/ncurses/man/tset.1.html"><span class="part-name">
+ tset</span></a> utility is provided.</p>
</li>
<li>
<li>
<p>The table-of-entries utility <a href=
- "https://invisible-island.net/ncurses/man/toe.1m.html"><span class=
- "part-name">toe</span></a> makes it easy for users to see
- exactly what terminal types are available on the system.</p>
+ "https://invisible-island.net/ncurses/man/toe.1m.html"><span class="part-name">
+ toe</span></a> makes it easy for users to see exactly what
+ terminal types are available on the system.</p>
</li>
<li>
<li>
<p>Extensive documentation is provided (see the <em><a href=
- "https://invisible-island.net/ncurses/ncurses.faq.html#additional_reading">Additional
- Reading</a></em> section of the <em><a href=
- "https://invisible-island.net/ncurses/ncurses.faq.html"><span class=
- "main-name">ncurses</span> FAQ</a></em> for online
- documentation).</p>
+ "https://invisible-island.net/ncurses/ncurses.faq.html#additional_reading">
+ Additional Reading</a></em> section of the <em><a href=
+ "https://invisible-island.net/ncurses/ncurses.faq.html"><span class="main-name">
+ ncurses</span> FAQ</a></em> for online documentation).</p>
</li>
</ul>
<dd>
<p>Curses Development Kit</p>
- <p><a href="https://invisible-island.net/cdk/">https://invisible-island.net/cdk/</a><br>
+ <p><a href=
+ "https://invisible-island.net/cdk/">https://invisible-island.net/cdk/</a><br>
+
</p>
</dd>
<dd>
<p>directory-editor</p>
- <p><a href="https://invisible-island.net/ded/">https://invisible-island.net/ded/</a></p>
+ <p><a href=
+ "https://invisible-island.net/ded/">https://invisible-island.net/ded/</a></p>
</dd>
<dt><span class="part-name">dialog</span>
and the basis for similar install/configure applications on
many systems.</p>
- <p><a href="https://invisible-island.net/dialog/">https://invisible-island.net/dialog/</a></p>
+ <p><a href=
+ "https://invisible-island.net/dialog/">https://invisible-island.net/dialog/</a></p>
</dd>
<dt><span class="part-name">lynx</span>
<dd>
<p>terminfo action checker</p>
- <p><a href="https://invisible-island.net/ncurses/tack.html">https://invisible-island.net/ncurses/tack.html</a></p>
+ <p><a href=
+ "https://invisible-island.net/ncurses/tack.html">https://invisible-island.net/ncurses/tack.html</a></p>
</dd>
<dt><span class="part-name">tmux</span>
<p><em>vi-like-emacs</em> may be built to use the terminfo,
termcap or curses interfaces.</p>
- <p><a href="https://invisible-island.net/vile/">https://invisible-island.net/vile/</a></p>
+ <p><a href=
+ "https://invisible-island.net/vile/">https://invisible-island.net/vile/</a></p>
</dd>
</dl>
</blockquote>
"mailto:dickey@invisible-island.net">Thomas E. Dickey</a>. Thomas
E. Dickey has acted as the maintainer for the Free Software
Foundation, which held a <a href=
- "https://invisible-island.net/ncurses/ncurses-license.html">copyright on ncurses</a> for
- releases 4.2 through 6.1. Following the release of ncurses 6.1,
- effective as of release 6.2, copyright for ncurses reverted to
- Thomas E. Dickey (see the <a href=
- "https://invisible-island.net/ncurses/ncurses.faq.html#relicensed">ncurses FAQ</a> for
- additional information).</p>
+ "https://invisible-island.net/ncurses/ncurses-license.html">copyright
+ on ncurses</a> for releases 4.2 through 6.1. Following the
+ release of ncurses 6.1, effective as of release 6.2, copyright
+ for ncurses reverted to Thomas E. Dickey (see the <a href=
+ "https://invisible-island.net/ncurses/ncurses.faq.html#relicensed">
+ ncurses FAQ</a> for additional information).</p>
<p>Contact the current maintainers at</p>
which may be interesting by themselves:</p>
<ul>
- <li><a href="https://invisible-island.net/ncurses/ncurses-license.html"><span class=
- "main-name">ncurses</span> licensing</a></li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/ncurses-license.html"><span class="main-name">
+ ncurses</span> licensing</a></li>
- <li><a href="https://invisible-island.net/ncurses/ncurses-mapsyms.html">Symbol versioning
- in <span class="main-name">ncurses</span></a></li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/ncurses-mapsyms.html">Symbol
+ versioning in <span class="main-name">ncurses</span></a></li>
- <li><a href="https://invisible-island.net/ncurses/ncurses-slang.html">Comments on
- <span class="main-name">ncurses</span> versus <span class=
+ <li><a href=
+ "https://invisible-island.net/ncurses/ncurses-slang.html">Comments
+ on <span class="main-name">ncurses</span> versus <span class=
"main-name">slang</span> (S-Lang)</a></li>
- <li><a href="https://invisible-island.net/ncurses/ncurses-openbsd.html">Comments on
- <span class="main-name">OpenBSD</span></a></li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/ncurses-openbsd.html">Comments
+ on <span class="main-name">OpenBSD</span></a></li>
- <li><a href="https://invisible-island.net/ncurses/tack.html">tack – terminfo action
- checker</a></li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/tack.html">tack –
+ terminfo action checker</a></li>
- <li><a href="https://invisible-island.net/ncurses/tctest.html">tctest – termcap
- library checker</a></li>
+ <li><a href=
+ "https://invisible-island.net/ncurses/tctest.html">tctest
+ – termcap library checker</a></li>
<li><a href=
- "https://invisible-island.net/ncurses/ncurses.html#download_database">Terminal
- Database</a></li>
+ "https://invisible-island.net/ncurses/ncurses.html#download_database">
+ Terminal Database</a></li>
</ul>
<h2><a name="h2-other-stuff" id="h2-other-stuff">Other
<!--
- $Id: hackguide.html,v 1.33 2020/02/02 23:34:34 tom Exp $
+ $Id: hackguide.html,v 1.36 2022/11/26 19:31:56 tom Exp $
****************************************************************************
- * Copyright 2019,2020 Thomas E. Dickey *
+ * Copyright 2019-2020,2022 Thomas E. Dickey *
* Copyright 2000-2013,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
****************************************************************************
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
-
<html>
<head>
<meta name="generator" content=
- "HTML Tidy for HTML5 for Linux version 5.2.0">
-
+ "HTML Tidy for HTML5 for Linux version 5.6.0">
<title>A Hacker's Guide to Ncurses Internals</title>
<link rel="author" href="mailto:bugs-ncurses@gnu.org">
<meta http-equiv="Content-Type" content=
this one.
-->
</head>
-
<body>
- <h1>A Hacker's Guide to NCURSES</h1>
+ <h1 class="no-header">A Hacker's Guide to NCURSES</h1>
- <h1>Contents</h1>
+ <h2>A Hacker's Guide to NCURSES</h2>
- <ul>
- <li><a href="#abstract">Abstract</a></li>
+ <div class="nav">
+ <h2>Contents</h2>
- <li>
- <a href="#objective">Objective of the Package</a>
+ <ul>
+ <li><a href="#abstract">Abstract</a></li>
- <ul>
- <li><a href="#whysvr4">Why System V Curses?</a></li>
+ <li>
+ <a href="#objective">Objective of the Package</a>
+ <ul>
+ <li><a href="#whysvr4">Why System V Curses?</a></li>
- <li><a href="#extensions">How to Design Extensions</a></li>
- </ul>
- </li>
-
- <li><a href="#portability">Portability and Configuration</a></li>
+ <li><a href="#extensions">How to Design Extensions</a></li>
+ </ul>
+ </li>
- <li><a href="#documentation">Documentation Conventions</a></li>
+ <li><a href="#portability">Portability and Configuration</a></li>
- <li><a href="#bugtrack">How to Report Bugs</a></li>
-
- <li>
- <a href="#ncurslib">A Tour of the Ncurses Library</a>
+ <li><a href="#documentation">Documentation Conventions</a></li>
- <ul>
- <li><a href="#loverview">Library Overview</a></li>
+ <li><a href="#bugtrack">How to Report Bugs</a></li>
- <li><a href="#engine">The Engine Room</a></li>
+ <li>
+ <a href="#ncurslib">A Tour of the Ncurses Library</a>
+ <ul>
+ <li><a href="#loverview">Library Overview</a></li>
- <li><a href="#input">Keyboard Input</a></li>
+ <li><a href="#engine">The Engine Room</a></li>
- <li><a href="#mouse">Mouse Events</a></li>
+ <li><a href="#input">Keyboard Input</a></li>
- <li><a href="#output">Output and Screen Updating</a></li>
- </ul>
- </li>
+ <li><a href="#mouse">Mouse Events</a></li>
- <li><a href="#fmnote">The Forms and Menu Libraries</a></li>
+ <li><a href="#output">Output and Screen Updating</a></li>
+ </ul>
+ </li>
- <li>
- <a href="#tic">A Tour of the Terminfo Compiler</a>
+ <li><a href="#fmnote">The Forms and Menu Libraries</a></li>
- <ul>
- <li><a href="#nonuse">Translation of
- Non-<strong>use</strong> Capabilities</a></li>
+ <li>
+ <a href="#tic">A Tour of the Terminfo Compiler</a>
+ <ul>
+ <li><a href="#nonuse">Translation of
+ Non-<strong>use</strong> Capabilities</a></li>
- <li><a href="#uses">Use Capability Resolution</a></li>
+ <li><a href="#uses">Use Capability Resolution</a></li>
- <li><a href="#translation">Source-Form Translation</a></li>
- </ul>
- </li>
+ <li><a href="#translation">Source-Form Translation</a></li>
+ </ul>
+ </li>
- <li><a href="#utils">Other Utilities</a></li>
+ <li><a href="#utils">Other Utilities</a></li>
- <li><a href="#style">Style Tips for Developers</a></li>
+ <li><a href="#style">Style Tips for Developers</a></li>
- <li><a href="#port">Porting Hints</a></li>
- </ul>
+ <li><a href="#port">Porting Hints</a></li>
+ </ul>
+ </div>
- <h1><a name="abstract" id="abstract">Abstract</a></h1>
+ <h2><a name="abstract" id="abstract">Abstract</a></h2>
<p>This document is a hacker's tour of the
<strong>ncurses</strong> library and utilities. It discusses
anyone who is interested in porting, extending or improving the
package.</p>
- <h1><a name="objective" id="objective">Objective of the
- Package</a></h1>
+ <h2><a name="objective" id="objective">Objective of the
+ Package</a></h2>
<p>The objective of the <strong>ncurses</strong> package is to
provide a free software API for character-cell terminals and
— we cannot add features if it means breaking the portion
of the API corresponding to historical curses versions.</p>
- <h2><a name="whysvr4" id="whysvr4">Why System V Curses?</a></h2>
+ <h3><a name="whysvr4" id="whysvr4">Why System V Curses?</a></h3>
<p>We used System V curses as a model, reverse-engineering their
API, in order to fulfill the first two objectives.</p>
So conformance with System V took us most of the way to
base-level XSI conformance.</p>
- <h2><a name="extensions" id="extensions">How to Design
- Extensions</a></h2>
+ <h3><a name="extensions" id="extensions">How to Design
+ Extensions</a></h3>
<p>The third objective (standards conformance) requires that it
be easy to condition source code using <strong>ncurses</strong>
library header. You can use this to condition the calls to the
mouse API calls.</p>
- <h1><a name="portability" id="portability">Portability and
- Configuration</a></h1>
+ <h2><a name="portability" id="portability">Portability and
+ Configuration</a></h2>
<p>Code written for <strong>ncurses</strong> may assume an
ANSI-standard C compiler and POSIX-compatible OS interface. It
(configure.in and aclocal.m4) to set up a new feature macro,
which you then use to condition your code.</p>
- <h1><a name="documentation" id="documentation">Documentation
- Conventions</a></h1>
+ <h2><a name="documentation" id="documentation">Documentation
+ Conventions</a></h2>
<p>There are three kinds of documentation associated with this
package. Each has a different preferred format:</p>
<ol>
<li><strong>Maintain package-internal files in plain
- text.</strong> The expected viewer for them <em>more(1)</em> or
+ text.</strong> The expected viewer for them is <em>more(1)</em> or
an editor window; there is no point in elaborate mark-up.</li>
<li><strong>Mark up manual pages in the man macros.</strong>
course, it make exporting things like the announcement document
to WWW pretty trivial.</p>
- <h1><a name="bugtrack" id="bugtrack">How to Report Bugs</a></h1>
+ <h2><a name="bugtrack" id="bugtrack">How to Report Bugs</a></h2>
<p>The <a name="bugreport" id="bugreport">reporting address for
bugs</a> is <a href=
<code>bug-ncurses-request@gnu.org</code> with a message
containing the line:</p>
- <pre>
+ <pre class="code-block">
subscribe <name>@<host.domain>
</pre>
-
<p>The <code>ncurses</code> code is maintained by a small group
of volunteers. While we try our best to fix bugs promptly, we
simply do not have a lot of hours to spend on elementary
tail end and have to wait a while.</p>
<ol>
- <li>Develop a recipe to reproduce the bug.
-
+ <li><p>Develop a recipe to reproduce the bug.
<p>Bugs we can reproduce are likely to be fixed very quickly,
often within days. The most effective single thing you can do
to get a quick fix is develop a way we can duplicate the bad
with the distribution.)</p>
</li>
- <li>Try to reproduce the bug on a different terminal type.
-
+ <li><p>Try to reproduce the bug on a different terminal type.
<p>In our experience, most of the behaviors people report as
library bugs are actually due to subtle problems in terminal
descriptions. This is especially likely to be true if you are
triggered or masked by these.</p>
</li>
- <li>Generate and examine a trace file for the broken behavior.
-
+ <li><p>Generate and examine a trace file for the broken behavior.
<p>Recompile your program with the debugging versions of the
libraries. Insert a <code>trace()</code> call with the
argument set to <code>TRACE_UPDATE</code>. (See <a href=
screen-update logic quite exactly.</p>
</li>
- <li>Report details and symptoms, not just interpretations.
-
+ <li><p>Report details and symptoms, not just interpretations.
<p>If you do the preceding two steps, it is very likely that
you will discover the nature of the problem yourself and be
able to send us a fix. This will create happy feelings all
out. You can also test the hardware-scrolling optimization
separately with <code>hardscroll</code>.</p>
- <h1><a name="ncurslib" id="ncurslib">A Tour of the Ncurses
- Library</a></h1>
+ <h2><a name="ncurslib" id="ncurslib">A Tour of the Ncurses
+ Library</a></h2>
- <h2><a name="loverview" id="loverview">Library Overview</a></h2>
+ <h3><a name="loverview" id="loverview">Library Overview</a></h3>
<p>Most of the library is superstructure — fairly trivial
convenience interfaces to a small set of basic functions and data
<p>We will discuss these in the compiler tour.</p>
- <h2><a name="engine" id="engine">The Engine Room</a></h2>
+ <h3><a name="engine" id="engine">The Engine Room</a></h3>
- <h3><a name="input" id="input">Keyboard Input</a></h3>
+ <h4><a name="input" id="input">Keyboard Input</a></h4>
<p>All <code>ncurses</code> input funnels through the function
<code>wgetch()</code>, defined in <code>lib_getch.c</code>. This
The function <code>timed_wait()</code> effectively simulates a
System V select.</p>
- <h3><a name="mouse" id="mouse">Mouse Events</a></h3>
+ <h4><a name="mouse" id="mouse">Mouse Events</a></h4>
<p>If the mouse interface is active, <code>wgetch()</code> polls
for mouse events each call, before it goes to the keyboard for
reports (low-level events) into a gesture (a high-level or
composite event).</p>
- <h3><a name="output" id="output">Output and Screen Updating</a></h3>
+ <h4><a name="output" id="output">Output and Screen Updating</a></h4>
<p>With the single exception of character echoes during a
<code>wgetnstr()</code> call (which simulates cooked-mode line
<code>include/curses.h.in</code> for mask values, near the
end.</p>
- <h1><a name="fmnote" id="fmnote">The Forms and Menu Libraries</a></h1>
+ <h2><a name="fmnote" id="fmnote">The Forms and Menu Libraries</a></h2>
<p>The forms and menu libraries should work reliably in any
environment you can port ncurses to. The only portability issue
This version has been slightly cleaned up for
<code>ncurses</code>.</p>
- <h1><a name="tic" id="tic">A Tour of the Terminfo Compiler</a></h1>
+ <h2><a name="tic" id="tic">A Tour of the Terminfo Compiler</a></h2>
<p>The <strong>ncurses</strong> implementation of
<strong>tic</strong> is rather complex internally; it has to do a
values; the grammar above it is trivial, just "parse entries till
you run out of file".</p>
- <h2><a name="nonuse" id="nonuse">Translation of
- Non-<strong>use</strong> Capabilities</a></h2>
+ <h3><a name="nonuse" id="nonuse">Translation of
+ Non-<strong>use</strong> Capabilities</a></h3>
<p>Translation of most things besides <strong>use</strong>
capabilities is pretty straightforward. The lexical analyzer's
file. We will have more to say about this in the section on
<a href="#translation">Source-Form Translation</a>.</p>
- <h2><a name="uses" id="uses">Use Capability Resolution</a></h2>
+ <h3><a name="uses" id="uses">Use Capability Resolution</a></h3>
<p>The background problem that makes <strong>tic</strong> tricky
is not the capability translation itself, it is the resolution of
overwriting entries newly made during the <strong>tic</strong>
run, but not about overwriting ones that predate it.</p>
- <h2><a name="translation" id="translation">Source-Form
- Translation</a></h2>
+ <h3><a name="translation" id="translation">Source-Form
+ Translation</a></h3>
<p>Another use of <strong>tic</strong> is to do source
translation between various termcap and terminfo formats. There
where the AIX <strong>box1</strong> capability get translated to
an <strong>acsc</strong> string.</p>
- <h1><a name="utils" id="utils">Other Utilities</a></h1>
+ <h2><a name="utils" id="utils">Other Utilities</a></h2>
<p>The <strong>infocmp</strong> utility is just a wrapper around
the same entry-dumping code used by <strong>tic</strong> for
just do an entry load followed by a <code>tputs()</code> of a
selected capability.</p>
- <h1><a name="style" id="style">Style Tips for Developers</a></h1>
+ <h2><a name="style" id="style">Style Tips for Developers</a></h2>
<p>See the TO-DO file in the top-level directory of the source
distribution for additions that would be particularly useful.</p>
<p>Have fun!</p>
- <h1><a name="port" id="port">Porting Hints</a></h1>
+ <h2><a name="port" id="port">Porting Hints</a></h2>
<p>The following notes are intended to be a first step towards
DOS and Macintosh ports of the ncurses libraries.</p>
<!--
- $Id: index.html,v 1.9 2020/02/02 23:34:34 tom Exp $
+ $Id: index.html,v 1.11 2022/11/26 17:39:53 tom Exp $
****************************************************************************
- * Copyright 2019,2020 Thomas E. Dickey *
+ * Copyright 2019-2020,2022 Thomas E. Dickey *
* Copyright 2000-2013,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
****************************************************************************
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
-
<html>
<head>
<meta name="generator" content=
- "HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
-
+ "HTML Tidy for HTML5 for Linux version 5.6.0">
<title>Welcome to ncurses</title>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii">
</head>
-
<body>
- <h1>Welcome to ncurses</h1>From this index page you have access
- to these further documents
+ <h1>Welcome to ncurses</h1>
+
+ <p>From this index page you have access to these further
+ documents</p>
<ul>
<li>The <a href="announce.html">Announcement</a> of the current
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG>xterm(1)</STRONG>.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_clear.3x,v 1.23 2022/02/12 20:06:41 tom Exp @
+ * @Id: curs_clear.3x,v 1.27 2022/11/26 16:23:47 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+
+</PRE><H3><a name="h3-erase_werase">erase/werase</a></H3><PRE>
The <STRONG>erase</STRONG> and <STRONG>werase</STRONG> routines copy blanks to every position in the win-
dow, clearing the screen.
- The <STRONG>clear</STRONG> and <STRONG>wclear</STRONG> routines are like <STRONG>erase</STRONG> and <STRONG>werase</STRONG>, but they also
- call <STRONG>clearok</STRONG>, so that the screen is cleared completely on the next call
- to <STRONG>wrefresh</STRONG> for that window and repainted from scratch.
+ Blanks created by erasure have the current background rendition (as set
+ by <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG>) merged into them.
+
+
+</PRE><H3><a name="h3-clear_wclear">clear/wclear</a></H3><PRE>
+ The <STRONG>clear</STRONG> and <STRONG>wclear</STRONG> routines are like <STRONG>erase</STRONG> and <STRONG>werase</STRONG>, but they also
+ call <STRONG><A HREF="curs_outopts.3x.html">clearok(3x)</A></STRONG>, so that the screen is cleared completely on the next
+ call to <STRONG>wrefresh</STRONG> for that window and repainted from scratch.
+
+</PRE><H3><a name="h3-clrtobot_wclrtobot">clrtobot/wclrtobot</a></H3><PRE>
The <STRONG>clrtobot</STRONG> and <STRONG>wclrtobot</STRONG> routines erase from the cursor to the end of
- screen. That is, they erase all lines below the cursor in the window.
- Also, the current line to the right of the cursor, inclusive, is
+ screen. That is, they erase all lines below the cursor in the window.
+ Also, the current line to the right of the cursor, inclusive, is
erased.
+
+</PRE><H3><a name="h3-clrtoeol_wclrtoeol">clrtoeol/wclrtoeol</a></H3><PRE>
The <STRONG>clrtoeol</STRONG> and <STRONG>wclrtoeol</STRONG> routines erase the current line to the right
of the cursor, inclusive, to the end of the current line.
- Blanks created by erasure have the current background rendition (as set
- by <STRONG>wbkgdset</STRONG>) merged into them.
-
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
All routines return the integer <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.
error conditions.
The SVr4.0 manual says that these functions could return "a non-nega-
- tive integer if <STRONG>immedok</STRONG> is set", referring to the return-value of <STRONG>wre-</STRONG>
- <STRONG>fresh</STRONG>. In that implementation, <STRONG>wrefresh</STRONG> would return a count of the
+ tive integer if <STRONG><A HREF="curs_outopts.3x.html">immedok(3x)</A></STRONG> is set", referring to the return-value of
+ <STRONG>wrefresh</STRONG>. In that implementation, <STRONG>wrefresh</STRONG> would return a count of the
number of characters written to the terminal.
Some historic curses implementations had, as an undocumented feature,
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
-<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<ul>
+<li><a href="#h3-erase_werase">erase/werase</a></li>
+<li><a href="#h3-clear_wclear">clear/wclear</a></li>
+<li><a href="#h3-clrtobot_wclrtobot">clrtobot/wclrtobot</a></li>
+<li><a href="#h3-clrtoeol_wclrtoeol">clrtoeol/wclrtoeol</a></li>
+</ul>
+</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed
descriptions of the entry points.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
https://invisible-island.net/ncurses/tctest.html
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "menu_" for detailed
descriptions of the entry points.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
method of updating character screens with reasonable optimization.
This implementation is "new curses" (ncurses) and is the approved
replacement for 4.4BSD classic curses, which has been discontinued.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
The <STRONG>ncurses</STRONG> library emulates the curses library of System V Release 4
UNIX, and XPG4 (X/Open Portability Guide) curses (also known as XSI
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
have, by specifying how to perform screen operations, and by specifying
padding requirements and initialization sequences.
- This manual describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This manual describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H3><a name="h3-Terminfo-Entry-Syntax">Terminfo Entry Syntax</a></H3><PRE>
<STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>, <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG><A HREF="term.5.html">term(5)</A></STRONG>. <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
<STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
<STRONG>csh(1)</STRONG>, <STRONG>sh(1)</STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG>tty(4)</STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>,
<STRONG>ttys(5)</STRONG>, <STRONG>environ(7)</STRONG>
- This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221029).
+ This describes <STRONG>ncurses</STRONG> version 6.3 (patch 20221126).
<!--
- $Id: ncurses-intro.html,v 1.54 2020/02/02 23:34:34 tom Exp $
+ $Id: ncurses-intro.html,v 1.57 2022/11/26 19:33:46 tom Exp $
****************************************************************************
- * Copyright 2019,2020 Thomas E. Dickey *
+ * Copyright 2019-2020,2022 Thomas E. Dickey *
* Copyright 2000-2013,2017 Free Software Foundation, Inc. *
* *
* Permission is hereby granted, free of charge, to any person obtaining a *
****************************************************************************
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
-
<html>
<head>
<meta name="generator" content=
- "HTML Tidy for HTML5 for Linux version 5.2.0">
-
+ "HTML Tidy for HTML5 for Linux version 5.6.0">
<title>Writing Programs with NCURSES</title>
<link rel="author" href="mailto:bugs-ncurses@gnu.org">
<meta http-equiv="Content-Type" content=
"text/html; charset=us-ascii">
</head>
-
<body>
- <h1>Writing Programs with NCURSES</h1>
+ <h1 class="no-header">Writing Programs with NCURSES</h1>
+
+ <h2>Writing Programs with NCURSES</h2>
<blockquote>
by Eric S. Raymond and Zeyd M. Ben-Halim<br>
updates since release 1.9.9e by Thomas Dickey
</blockquote>
- <h1>Contents</h1>
-
- <ul>
- <li>
- <a href="#introduction">Introduction</a>
-
- <ul>
- <li><a href="#history">A Brief History of Curses</a></li>
-
- <li><a href="#scope">Scope of This Document</a></li>
-
- <li><a href="#terminology">Terminology</a></li>
- </ul>
- </li>
-
- <li>
- <a href="#curses">The Curses Library</a>
-
- <ul>
- <li>
- <a href="#overview">An Overview of Curses</a>
-
- <ul>
- <li><a href="#compiling">Compiling Programs using
- Curses</a></li>
-
- <li><a href="#updating">Updating the Screen</a></li>
-
- <li><a href="#stdscr">Standard Windows and Function
- Naming Conventions</a></li>
-
- <li><a href="#variables">Variables</a></li>
- </ul>
- </li>
-
- <li>
- <a href="#using">Using the Library</a>
-
- <ul>
- <li><a href="#starting">Starting up</a></li>
+ <div class="nav">
+ <h2>Contents</h2>
- <li><a href="#output">Output</a></li>
+ <ul>
+ <li>
+ <a href="#introduction">Introduction</a>
+ <ul>
+ <li><a href="#history">A Brief History of Curses</a></li>
- <li><a href="#input">Input</a></li>
+ <li><a href="#scope">Scope of This Document</a></li>
- <li><a href="#formschars">Using Forms Characters</a></li>
+ <li><a href="#terminology">Terminology</a></li>
+ </ul>
+ </li>
- <li><a href="#attributes">Character Attributes and
- Color</a></li>
+ <li>
+ <a href="#curses">The Curses Library</a>
+ <ul>
+ <li>
+ <a href="#overview">An Overview of Curses</a>
+ <ul>
+ <li><a href="#compiling">Compiling Programs using
+ Curses</a></li>
- <li><a href="#mouse">Mouse Interfacing</a></li>
+ <li><a href="#updating">Updating the Screen</a></li>
- <li><a href="#finishing">Finishing Up</a></li>
- </ul>
- </li>
+ <li><a href="#stdscr">Standard Windows and Function
+ Naming Conventions</a></li>
- <li>
- <a href="#functions">Function Descriptions</a>
+ <li><a href="#variables">Variables</a></li>
+ </ul>
+ </li>
- <ul>
- <li><a href="#init">Initialization and Wrapup</a></li>
+ <li>
+ <a href="#using">Using the Library</a>
+ <ul>
+ <li><a href="#starting">Starting up</a></li>
- <li><a href="#flush">Causing Output to the Terminal</a></li>
+ <li><a href="#output">Output</a></li>
- <li><a href="#lowlevel">Low-Level Capability Access</a></li>
+ <li><a href="#input">Input</a></li>
- <li><a href="#debugging">Debugging</a></li>
- </ul>
- </li>
+ <li><a href="#formschars">Using Forms Characters</a></li>
- <li>
- <a href="#hints">Hints, Tips, and Tricks</a>
+ <li><a href="#attributes">Character Attributes and
+ Color</a></li>
- <ul>
- <li><a href="#caution">Some Notes of Caution</a></li>
+ <li><a href="#mouse">Mouse Interfacing</a></li>
- <li><a href="#leaving">Temporarily Leaving ncurses
- Mode</a></li>
+ <li><a href="#finishing">Finishing Up</a></li>
+ </ul>
+ </li>
- <li><a href="#xterm">Using <code>ncurses</code> under
- <code>xterm</code></a></li>
+ <li>
+ <a href="#functions">Function Descriptions</a>
+ <ul>
+ <li><a href="#init">Initialization and Wrapup</a></li>
- <li><a href="#screens">Handling Multiple Terminal
- Screens</a></li>
+ <li><a href="#flush">Causing Output to the
+ Terminal</a></li>
- <li><a href="#testing">Testing for Terminal
- Capabilities</a></li>
+ <li><a href="#lowlevel">Low-Level Capability
+ Access</a></li>
- <li><a href="#tuning">Tuning for Speed</a></li>
+ <li><a href="#debugging">Debugging</a></li>
+ </ul>
+ </li>
- <li><a href="#special">Special Features of
- <code>ncurses</code></a></li>
- </ul>
- </li>
+ <li>
+ <a href="#hints">Hints, Tips, and Tricks</a>
+ <ul>
+ <li><a href="#caution">Some Notes of Caution</a></li>
- <li>
- <a href="#compat">Compatibility with Older Versions</a>
+ <li><a href="#leaving">Temporarily Leaving ncurses
+ Mode</a></li>
- <ul>
- <li><a href="#refbug">Refresh of Overlapping
- Windows</a></li>
+ <li><a href="#xterm">Using <code>ncurses</code> under
+ <code>xterm</code></a></li>
- <li><a href="#backbug">Background Erase</a></li>
- </ul>
- </li>
+ <li><a href="#screens">Handling Multiple Terminal
+ Screens</a></li>
- <li><a href="#xsifuncs">XSI Curses Conformance</a></li>
- </ul>
- </li>
+ <li><a href="#testing">Testing for Terminal
+ Capabilities</a></li>
- <li>
- <a href="#panels">The Panels Library</a>
+ <li><a href="#tuning">Tuning for Speed</a></li>
- <ul>
- <li><a href="#pcompile">Compiling With the Panels
- Library</a></li>
+ <li><a href="#special">Special Features of
+ <code>ncurses</code></a></li>
+ </ul>
+ </li>
- <li><a href="#poverview">Overview of Panels</a></li>
+ <li>
+ <a href="#compat">Compatibility with Older Versions</a>
+ <ul>
+ <li><a href="#refbug">Refresh of Overlapping
+ Windows</a></li>
- <li><a href="#pstdscr">Panels, Input, and the Standard
- Screen</a></li>
+ <li><a href="#backbug">Background Erase</a></li>
+ </ul>
+ </li>
- <li><a href="#hiding">Hiding Panels</a></li>
+ <li><a href="#xsifuncs">XSI Curses Conformance</a></li>
+ </ul>
+ </li>
- <li><a href="#pmisc">Miscellaneous Other Facilities</a></li>
- </ul>
- </li>
+ <li>
+ <a href="#panels">The Panels Library</a>
+ <ul>
+ <li><a href="#pcompile">Compiling With the Panels
+ Library</a></li>
- <li>
- <a href="#menu">The Menu Library</a>
+ <li><a href="#poverview">Overview of Panels</a></li>
- <ul>
- <li><a href="#mcompile">Compiling with the menu Library</a></li>
+ <li><a href="#pstdscr">Panels, Input, and the Standard
+ Screen</a></li>
- <li><a href="#moverview">Overview of Menus</a></li>
+ <li><a href="#hiding">Hiding Panels</a></li>
- <li><a href="#mselect">Selecting items</a></li>
+ <li><a href="#pmisc">Miscellaneous Other Facilities</a></li>
+ </ul>
+ </li>
- <li><a href="#mdisplay">Menu Display</a></li>
+ <li>
+ <a href="#menu">The Menu Library</a>
+ <ul>
+ <li><a href="#mcompile">Compiling with the menu
+ Library</a></li>
- <li><a href="#mwindows">Menu Windows</a></li>
+ <li><a href="#moverview">Overview of Menus</a></li>
- <li><a href="#minput">Processing Menu Input</a></li>
+ <li><a href="#mselect">Selecting items</a></li>
- <li><a href="#mmisc">Miscellaneous Other Features</a></li>
- </ul>
- </li>
+ <li><a href="#mdisplay">Menu Display</a></li>
- <li>
- <a href="#form">The Forms Library</a>
+ <li><a href="#mwindows">Menu Windows</a></li>
- <ul>
- <li><a href="#fcompile">Compiling with the forms
- Library</a></li>
+ <li><a href="#minput">Processing Menu Input</a></li>
- <li><a href="#foverview">Overview of Forms</a></li>
+ <li><a href="#mmisc">Miscellaneous Other Features</a></li>
+ </ul>
+ </li>
- <li><a href="#fcreate">Creating and Freeing Fields and
- Forms</a></li>
+ <li>
+ <a href="#form">The Forms Library</a>
+ <ul>
+ <li><a href="#fcompile">Compiling with the forms
+ Library</a></li>
- <li>
- <a href="#fattributes">Fetching and Changing Field
- Attributes</a>
+ <li><a href="#foverview">Overview of Forms</a></li>
- <ul>
- <li><a href="#fsizes">Fetching Size and Location
- Data</a></li>
+ <li><a href="#fcreate">Creating and Freeing Fields and
+ Forms</a></li>
- <li><a href="#flocation">Changing the Field
- Location</a></li>
+ <li>
+ <a href="#fattributes">Fetching and Changing Field
+ Attributes</a>
+ <ul>
+ <li><a href="#fsizes">Fetching Size and Location
+ Data</a></li>
- <li><a href="#fjust">The Justification Attribute</a></li>
+ <li><a href="#flocation">Changing the Field
+ Location</a></li>
- <li><a href="#fdispatts">Field Display Attributes</a></li>
+ <li><a href="#fjust">The Justification Attribute</a></li>
- <li><a href="#foptions">Field Option Bits</a></li>
+ <li><a href="#fdispatts">Field Display Attributes</a></li>
- <li><a href="#fstatus">Field Status</a></li>
+ <li><a href="#foptions">Field Option Bits</a></li>
- <li><a href="#fuser">Field User Pointer</a></li>
- </ul>
- </li>
+ <li><a href="#fstatus">Field Status</a></li>
- <li><a href="#fdynamic">Variable-Sized Fields</a></li>
+ <li><a href="#fuser">Field User Pointer</a></li>
+ </ul>
+ </li>
- <li>
- <a href="#fvalidation">Field Validation</a>
+ <li><a href="#fdynamic">Variable-Sized Fields</a></li>
- <ul>
- <li><a href="#ftype_alpha">TYPE_ALPHA</a></li>
+ <li>
+ <a href="#fvalidation">Field Validation</a>
+ <ul>
+ <li><a href="#ftype_alpha">TYPE_ALPHA</a></li>
- <li><a href="#ftype_alnum">TYPE_ALNUM</a></li>
+ <li><a href="#ftype_alnum">TYPE_ALNUM</a></li>
- <li><a href="#ftype_enum">TYPE_ENUM</a></li>
+ <li><a href="#ftype_enum">TYPE_ENUM</a></li>
- <li><a href="#ftype_integer">TYPE_INTEGER</a></li>
+ <li><a href="#ftype_integer">TYPE_INTEGER</a></li>
- <li><a href="#ftype_numeric">TYPE_NUMERIC</a></li>
+ <li><a href="#ftype_numeric">TYPE_NUMERIC</a></li>
- <li><a href="#ftype_regexp">TYPE_REGEXP</a></li>
- </ul>
- </li>
+ <li><a href="#ftype_regexp">TYPE_REGEXP</a></li>
+ </ul>
+ </li>
- <li><a href="#fbuffer">Direct Field Buffer Manipulation</a></li>
+ <li><a href="#fbuffer">Direct Field Buffer
+ Manipulation</a></li>
- <li><a href="#formattrs">Attributes of Forms</a></li>
+ <li><a href="#formattrs">Attributes of Forms</a></li>
- <li><a href="#fdisplay">Control of Form Display</a></li>
+ <li><a href="#fdisplay">Control of Form Display</a></li>
- <li>
- <a href="#fdriver">Input Processing in the Forms
- Driver</a>
+ <li>
+ <a href="#fdriver">Input Processing in the Forms
+ Driver</a>
+ <ul>
+ <li><a href="#fpage">Page Navigation Requests</a></li>
- <ul>
- <li><a href="#fpage">Page Navigation Requests</a></li>
+ <li><a href="#ffield">Inter-Field Navigation
+ Requests</a></li>
- <li><a href="#ffield">Inter-Field Navigation
- Requests</a></li>
+ <li><a href="#fifield">Intra-Field Navigation
+ Requests</a></li>
- <li><a href="#fifield">Intra-Field Navigation
- Requests</a></li>
+ <li><a href="#fscroll">Scrolling Requests</a></li>
- <li><a href="#fscroll">Scrolling Requests</a></li>
+ <li><a href="#fedit">Field Editing Requests</a></li>
- <li><a href="#fedit">Field Editing Requests</a></li>
+ <li><a href="#forder">Order Requests</a></li>
- <li><a href="#forder">Order Requests</a></li>
+ <li><a href="#fappcmds">Application Commands</a></li>
+ </ul>
+ </li>
- <li><a href="#fappcmds">Application Commands</a></li>
- </ul>
- </li>
+ <li><a href="#fhooks">Field Change Hooks</a></li>
- <li><a href="#fhooks">Field Change Hooks</a></li>
+ <li><a href="#ffocus">Field Change Commands</a></li>
- <li><a href="#ffocus">Field Change Commands</a></li>
+ <li><a href="#frmoptions">Form Options</a></li>
- <li><a href="#frmoptions">Form Options</a></li>
+ <li>
+ <a href="#fcustom">Custom Validation Types</a>
+ <ul>
+ <li><a href="#flinktypes">Union Types</a></li>
- <li>
- <a href="#fcustom">Custom Validation Types</a>
+ <li><a href="#fnewtypes">New Field Types</a></li>
- <ul>
- <li><a href="#flinktypes">Union Types</a></li>
+ <li><a href="#fcheckargs">Validation Function
+ Arguments</a></li>
- <li><a href="#fnewtypes">New Field Types</a></li>
+ <li><a href="#fcustorder">Order Functions For Custom
+ Types</a></li>
- <li><a href="#fcheckargs">Validation Function
- Arguments</a></li>
-
- <li><a href="#fcustorder">Order Functions For Custom
- Types</a></li>
-
- <li><a href="#fcustprobs">Avoiding Problems</a></li>
- </ul>
- </li>
- </ul>
- </li>
- </ul>
+ <li><a href="#fcustprobs">Avoiding Problems</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </div>
<hr>
- <h1><a name="introduction" id="introduction">Introduction</a></h1>
+ <h2><a name="introduction" id="introduction">Introduction</a></h2>
<p>This document is an introduction to programming with
<code>curses</code>. It is not an exhaustive reference for the
<code>curses</code> will typically be a great deal simpler and
less expensive than one using an X toolkit.</p>
- <h2><a name="history" id="history">A Brief History of Curses</a></h2>
+ <h3><a name="history" id="history">A Brief History of Curses</a></h3>
<p>Historically, the first ancestor of <code>curses</code> was
the routines written to provide screen-handling for the
to use more facilities and offer more capabilities, going far
beyond BSD curses in power and flexibility.</p>
- <h2><a name="scope" id="scope">Scope of This Document</a></h2>
+ <h3><a name="scope" id="scope">Scope of This Document</a></h3>
<p>This document describes <code>ncurses</code>, a free
implementation of the System V <code>curses</code> API with some
libraries, also cloned from System V, which support easy
construction and sequences of menus and fill-in forms.</p>
- <h2><a name="terminology" id="terminology">Terminology</a></h2>
+ <h3><a name="terminology" id="terminology">Terminology</a></h3>
<p>In this document, the following terminology is used with
reasonable consistency:</p>
screen.</dd>
</dl>
- <h1><a name="curses" id="curses">The Curses Library</a></h1>
+ <h2><a name="curses" id="curses">The Curses Library</a></h2>
- <h2><a name="overview" id="overview">An Overview of Curses</a></h2>
+ <h3><a name="overview" id="overview">An Overview of Curses</a></h3>
- <h3><a name="compiling" id="compiling">Compiling Programs using
- Curses</a></h3>
+ <h4><a name="compiling" id="compiling">Compiling Programs using
+ Curses</a></h4>
<p>In order to use the library, it is necessary to have certain
types and variables defined. Therefore, the programmer must have
a line:</p>
- <pre>
+ <pre class="code-block">
#include <curses.h>
</pre>
-
<p>at the top of the program source. The screen package uses the
Standard I/O library, so <code><curses.h></code> includes
<code><stdio.h></code>. <code><curses.h></code> also
your LDFLAGS or on the command line. There is no need for any
other libraries.</p>
- <h3><a name="updating" id="updating">Updating the Screen</a></h3>
+ <h4><a name="updating" id="updating">Updating the Screen</a></h4>
<p>In order to update the screen optimally, it is necessary for
the routines to know what the screen currently looks like and
like this,” and let the package implementation determine
the most efficient way to repaint the screen.</p>
- <h3><a name="stdscr" id="stdscr">Standard Windows and Function
- Naming Conventions</a></h3>
+ <h4><a name="stdscr" id="stdscr">Standard Windows and Function
+ Naming Conventions</a></h4>
<p>As hinted above, the routines can use several windows, but two
are automatically given: <code>curscr</code>, which knows what
“mv” and the desired (y, x) coordinates prepended to
the arguments to the function. For example, the calls</p>
- <pre>
+ <pre class="code-block">
move(y, x);
addch(ch);
</pre>
-
<p>can be replaced by</p>
- <pre>
+ <pre class="code-block">
mvaddch(y, x, ch);
</pre>
-
<p>and</p>
- <pre>
+ <pre class="code-block">
wmove(win, y, x);
waddch(win, ch);
</pre>
-
<p>can be replaced by</p>
- <pre>
+ <pre class="code-block">
mvwaddch(win, y, x, ch);
</pre>
-
<p>Note that the window description pointer (win) comes before
the added (y, x) coordinates. If a function requires a window
pointer, it is always the first parameter passed.</p>
- <h3><a name="variables" id="variables">Variables</a></h3>
+ <h4><a name="variables" id="variables">Variables</a></h4>
<p>The <code>curses</code> library sets some variables describing
the terminal capabilities.</p>
- <pre>
+ <pre class="code-block">
type name description
------------------------------------------------------------------
int LINES number of lines on the terminal
int COLS number of columns on the terminal
</pre>
-
<p>The <code>curses.h</code> also introduces some
<code>#define</code> constants and types of general
usefulness:</p>
<dd>error flag returned by routines when things go right.</dd>
</dl>
- <h2><a name="using" id="using">Using the Library</a></h2>
+ <h3><a name="using" id="using">Using the Library</a></h3>
<p>Now we describe how to actually use the screen package. In it,
we assume all updating, reading, etc. is applied to
<p>Here is a sample program to motivate the discussion:</p>
- <pre>
+ <pre class="code-block">
#include <stdlib.h>
#include <curses.h>
#include <signal.h>
exit(0);
}
</pre>
-
- <h3><a name="starting" id="starting">Starting up</a></h3>
+ <h4><a name="starting" id="starting">Starting up</a></h4>
<p>In order to use the screen package, the routines must know
about terminal characteristics, and the space for
allow you to get rid of old windows. All the options described
above can be applied to any window.</p>
- <h3><a name="output" id="output">Output</a></h3>
+ <h4><a name="output" id="output">Output</a></h4>
<p>Now that we have set things up, we will want to actually
update the terminal. The basic functions used to change what will
implementing a command which would redraw the screen in case it
get messed up.</p>
- <h3><a name="input" id="input">Input</a></h3>
+ <h4><a name="input" id="input">Input</a></h4>
<p>The complementary function to <code>addch()</code> is
<code>getch()</code> which, if echo is set, will call
<code>#define</code> values is determined by <code>key_</code>
capabilities in the terminal's terminfo entry.</p>
- <h3><a name="formschars" id="formschars">Using Forms
- Characters</a></h3>
+ <h4><a name="formschars" id="formschars">Using Forms
+ Characters</a></h4>
<p>The <code>addch()</code> function (and some others, including
<code>box()</code> and <code>border()</code>) can accept some
<code>curses.h</code> will map them to a recognizable (though
ugly) set of ASCII defaults.</p>
- <h3><a name="attributes" id="attributes">Character Attributes and
- Color</a></h3>
+ <h4><a name="attributes" id="attributes">Character Attributes and
+ Color</a></h4>
<p>The <code>ncurses</code> package supports screen highlights
including standout, reverse-video, underline, and blink. It also
that <code>COLOR_PAIR(N)</code>, for constant N, is itself a
compile-time constant and can be used in initializers.</p>
- <h3><a name="mouse" id="mouse">Mouse Interfacing</a></h3>
+ <h4><a name="mouse" id="mouse">Mouse Interfacing</a></h4>
<p>The <code>ncurses</code> library also provides a mouse
interface.</p>
<p>See the manual page <code>curs_mouse(3X)</code> for full
details of the mouse-interface functions.</p>
- <h3><a name="finishing" id="finishing">Finishing Up</a></h3>
+ <h4><a name="finishing" id="finishing">Finishing Up</a></h4>
<p>In order to clean up after the <code>ncurses</code> routines,
the routine <code>endwin()</code> is provided. It restores tty
anytime after the call to initscr, <code>endwin()</code> should
be called before exiting.</p>
- <h2><a name="functions" id="functions">Function Descriptions</a></h2>
+ <h3><a name="functions" id="functions">Function Descriptions</a></h3>
<p>We describe the detailed behavior of some important curses
functions here, as a supplement to the manual page
descriptions.</p>
- <h3><a name="init" id="init">Initialization and Wrapup</a></h3>
+ <h4><a name="init" id="init">Initialization and Wrapup</a></h4>
<dl>
<dt><code>initscr()</code>
reference.</dd>
</dl>
- <h3><a name="flush" id="flush">Causing Output to the Terminal</a></h3>
+ <h4><a name="flush" id="flush">Causing Output to the Terminal</a></h4>
<dl>
<dt><code>refresh()</code> and <code>wrefresh(win)</code></dt>
each update).</dd>
</dl>
- <h3><a name="lowlevel" id="lowlevel">Low-Level Capability
- Access</a></h3>
+ <h4><a name="lowlevel" id="lowlevel">Low-Level Capability
+ Access</a></h4>
<dl>
<dt><code>setupterm(term, filenum, errret)</code>
indication is returned. The values returned can be 1 (all is
well), 0 (no such terminal), or -1 (some problem locating the
terminfo database).
-
<p>The value of <code>term</code> can be given as NULL, which
will cause the value of <code>TERM</code> in the environment
to be used. The <code>errret</code> pointer can also be given
</dd>
</dl>
- <h3><a name="debugging" id="debugging">Debugging</a></h3>
+ <h4><a name="debugging" id="debugging">Debugging</a></h4>
<blockquote>
<strong>NOTE:</strong> These functions are not part of the
be distinguished by the fact that they are named in capital
letters.</p>
- <h2><a name="hints" id="hints">Hints, Tips, and Tricks</a></h2>
+ <h3><a name="hints" id="hints">Hints, Tips, and Tricks</a></h3>
<p>The <code>ncurses</code> manual pages are a complete reference
for this library. In the remainder of this document, we discuss
various useful methods that may not be obvious from the manual
page descriptions.</p>
- <h3><a name="caution" id="caution">Some Notes of Caution</a></h3>
+ <h4><a name="caution" id="caution">Some Notes of Caution</a></h4>
<p>If you find yourself thinking you need to use
<code>noraw()</code> or <code>nocbreak()</code>, think again and
with window resizes, in which case several screens could be open
with different sizes.</p>
- <h3><a name="leaving" id="leaving">Temporarily Leaving NCURSES
- Mode</a></h3>
+ <h4><a name="leaving" id="leaving">Temporarily Leaving NCURSES
+ Mode</a></h4>
<p>Sometimes you will want to write a program that spends most of
its time in screen mode, but occasionally returns to ordinary
<p>Here is some sample code for shellout:</p>
- <pre>
+ <pre class="code-block">
addstr("Shelling out...");
def_prog_mode(); /* save current tty modes */
endwin(); /* restore original tty modes */
addstr("returned.\n"); /* prepare return message */
refresh(); /* restore save modes, repaint screen */
</pre>
-
- <h3><a name="xterm" id="xterm">Using NCURSES under XTERM</a></h3>
+ <h4><a name="xterm" id="xterm">Using NCURSES under XTERM</a></h4>
<p>A resize operation in X sends <code>SIGWINCH</code> to the
application running under xterm. The easiest way to handle
special-purpose code to handle <code>KEY_RESIZE</code>
yourself.</p>
- <h3><a name="screens" id="screens">Handling Multiple Terminal
- Screens</a></h3>
+ <h4><a name="screens" id="screens">Handling Multiple Terminal
+ Screens</a></h4>
<p>The <code>initscr()</code> function actually calls a function
named <code>newterm()</code> to do most of its work. If you are
<code>def_shell_mode</code> and <code>def_prog_mode</code> on
each tty yourself.</p>
- <h3><a name="testing" id="testing">Testing for Terminal
- Capabilities</a></h3>
+ <h4><a name="testing" id="testing">Testing for Terminal
+ Capabilities</a></h4>
<p>Sometimes you may want to write programs that test for the
presence of various capabilities before deciding whether to go
include the <code>term.h</code> file and test the value of the
macro <code>cursor_address</code>.</p>
- <h3><a name="tuning" id="tuning">Tuning for Speed</a></h3>
+ <h4><a name="tuning" id="tuning">Tuning for Speed</a></h4>
<p>Use the <code>addchstr()</code> family of functions for fast
screen-painting of text when you know the text does not contain
on your screens. Do not use the <code>immedok()</code>
option!</p>
- <h3><a name="special" id="special">Special Features of
- NCURSES</a></h3>
+ <h4><a name="special" id="special">Special Features of
+ NCURSES</a></h4>
<p>The <code>wresize()</code> function allows you to resize a
window in place. The associated <code>resizeterm()</code>
only 8 colors, about a quarter (including XFree86 xterm) support
16 colors.</p>
- <h2><a name="compat" id="compat">Compatibility with Older
- Versions</a></h2>
+ <h3><a name="compat" id="compat">Compatibility with Older
+ Versions</a></h3>
<p>Despite our best efforts, there are some differences between
<code>ncurses</code> and the (undocumented!) behavior of older
curses implementations. These arise from ambiguities or omissions
in the documentation of the API.</p>
- <h3><a name="refbug" id="refbug">Refresh of Overlapping
- Windows</a></h3>
+ <h4><a name="refbug" id="refbug">Refresh of Overlapping
+ Windows</a></h4>
<p>If you define two windows A and B that overlap, and then
alternately scribble on and refresh them, the changes made to the
<code>doupdate()</code> and there will be a <em>single</em> burst
of physical I/O that will do all your updates.</p>
- <h3><a name="backbug" id="backbug">Background Erase</a></h3>
+ <h4><a name="backbug" id="backbug">Background Erase</a></h4>
<p>If you have been using a very old versions of
<code>ncurses</code> (1.8.7 or older) you may be surprised by the
<p>This change in behavior conforms <code>ncurses</code> to
System V Release 4 and the XSI Curses standard.</p>
- <h2><a name="xsifuncs" id="xsifuncs">XSI Curses Conformance</a></h2>
+ <h3><a name="xsifuncs" id="xsifuncs">XSI Curses Conformance</a></h3>
<p>The <code>ncurses</code> library is intended to be base-level
conformant with the XSI Curses standard from X/Open. Many
be linked (and will be prototype-checked) if the macro definition
is disabled with <code>#undef</code>.</p>
- <h1><a name="panels" id="panels">The Panels Library</a></h1>
+ <h2><a name="panels" id="panels">The Panels Library</a></h2>
<p>The <code>ncurses</code> library by itself provides good
support for screen displays in which the windows are tiled
System V. The version documented here is the <code>panel</code>
code distributed with <code>ncurses</code>.</p>
- <h2><a name="pcompile" id="pcompile">Compiling With the Panels
- Library</a></h2>
+ <h3><a name="pcompile" id="pcompile">Compiling With the Panels
+ Library</a></h3>
<p>Your panels-using modules must import the panels library
declarations with</p>
- <pre>
+ <pre class="code-block">
#include <panel.h>
</pre>
-
<p>and must be linked explicitly with the panels library using an
<code>-lpanel</code> argument. Note that they must also link the
<code>ncurses</code> library with <code>-lncurses</code>. Many
still good practice to put <code>-lpanel</code> first and
<code>-lncurses</code> second.</p>
- <h2><a name="poverview" id="poverview">Overview of Panels</a></h2>
+ <h3><a name="poverview" id="poverview">Overview of Panels</a></h3>
<p>A panel object is a window that is implicitly treated as part
of a <dfn>deck</dfn> including all other panel objects. The deck
you will generate a lot of unnecessary refresh activity and
screen flicker.</p>
- <h2><a name="pstdscr" id="pstdscr">Panels, Input, and the
- Standard Screen</a></h2>
+ <h3><a name="pstdscr" id="pstdscr">Panels, Input, and the
+ Standard Screen</a></h3>
<p>You should not mix <code>wnoutrefresh()</code> or
<code>wrefresh()</code> operations with panels code; this will
<p>There is presently no way to display changes to one obscured
panel without repainting all panels.</p>
- <h2><a name="hiding" id="hiding">Hiding Panels</a></h2>
+ <h3><a name="hiding" id="hiding">Hiding Panels</a></h3>
<p>It is possible to remove a panel from the deck temporarily;
use <code>hide_panel</code> for this. Use
cannot do <code>top_panel()</code> or <code>bottom_panel</code>
on a hidden panel(). Other panels operations are applicable.</p>
- <h2><a name="pmisc" id="pmisc">Miscellaneous Other Facilities</a></h2>
+ <h3><a name="pmisc" id="pmisc">Miscellaneous Other Facilities</a></h3>
<p>It is possible to navigate the deck using the functions
<code>panel_above()</code> and <code>panel_below</code>. Handed a
page documentation of <code>set_panel_userptr()</code> and
<code>panel_userptr</code> for details.</p>
- <h1><a name="menu" id="menu">The Menu Library</a></h1>
+ <h2><a name="menu" id="menu">The Menu Library</a></h2>
<p>A menu is a screen display that assists the user to choose
some subset of a given set of items. The <code>menu</code>
System V. The version documented here is the <code>menu</code>
code distributed with <code>ncurses</code>.</p>
- <h2><a name="mcompile" id="mcompile">Compiling With the menu
- Library</a></h2>
+ <h3><a name="mcompile" id="mcompile">Compiling With the menu
+ Library</a></h3>
<p>Your menu-using modules must import the menu library
declarations with</p>
- <pre>
+ <pre class="code-block">
#include <menu.h>
</pre>
-
<p>and must be linked explicitly with the menus library using an
<code>-lmenu</code> argument. Note that they must also link the
<code>ncurses</code> library with <code>-lncurses</code>. Many
still good practice to put <code>-lmenu</code> first and
<code>-lncurses</code> second.</p>
- <h2><a name="moverview" id="moverview">Overview of Menus</a></h2>
+ <h3><a name="moverview" id="moverview">Overview of Menus</a></h3>
<p>The menus created by this library consist of collections of
<dfn>items</dfn> including a name string part and a description
<li>Terminate <code>curses</code>.</li>
</ol>
- <h2><a name="mselect" id="mselect">Selecting items</a></h2>
+ <h3><a name="mselect" id="mselect">Selecting items</a></h3>
<p>Menus may be multi-valued or (the default) single-valued (see
the manual page <code>menu_opts(3x)</code> to see how to change
so far defined for menus, but it is good practice to code as
though other option bits might be on.</p>
- <h2><a name="mdisplay" id="mdisplay">Menu Display</a></h2>
+ <h3><a name="mdisplay" id="mdisplay">Menu Display</a></h3>
<p>The menu library calculates a minimum display size for your
window, based on the following variables:</p>
which the library allows you to change (see the
<code>menu_attribs(3x)</code> manual page.</p>
- <h2><a name="mwindows" id="mwindows">Menu Windows</a></h2>
+ <h3><a name="mwindows" id="mwindows">Menu Windows</a></h3>
<p>Each menu has, as mentioned previously, a pair of associated
windows. Both these windows are painted when the menu is posted
the screen. To do that, call <code>wrefresh()</code> or some
equivalent.</p>
- <h2><a name="minput" id="minput">Processing Menu Input</a></h2>
+ <h3><a name="minput" id="minput">Processing Menu Input</a></h3>
<p>The main loop of your menu-processing code should call
<code>menu_driver()</code> repeatedly. The first argument of this
commands. The <code>menu_driver()</code> code ignores them and
returns <code>E_UNKNOWN_COMMAND</code>.</p>
- <h2><a name="mmisc" id="mmisc">Miscellaneous Other Features</a></h2>
+ <h3><a name="mmisc" id="mmisc">Miscellaneous Other Features</a></h3>
<p>Various menu options can affect the processing and visual
appearance and input processing of menus. See <code>menu_opts(3x)
<code>mitem_userptr(3x)</code> and
<code>menu_userptr(3x)</code>.</p>
- <h1><a name="form" id="form">The Forms Library</a></h1>
+ <h2><a name="form" id="form">The Forms Library</a></h2>
<p>The <code>form</code> library is a curses extension that
supports easy programming of on-screen forms for data entry and
System V. The version documented here is the <code>form</code>
code distributed with <code>ncurses</code>.</p>
- <h2><a name="fcompile" id="fcompile">Compiling With the form
- Library</a></h2>
+ <h3><a name="fcompile" id="fcompile">Compiling With the form
+ Library</a></h3>
<p>Your form-using modules must import the form library
declarations with</p>
- <pre>
+ <pre class="code-block">
#include <form.h>
</pre>
-
<p>and must be linked explicitly with the forms library using an
<code>-lform</code> argument. Note that they must also link the
<code>ncurses</code> library with <code>-lncurses</code>. Many
still good practice to put <code>-lform</code> first and
<code>-lncurses</code> second.</p>
- <h2><a name="foverview" id="foverview">Overview of Forms</a></h2>
+ <h3><a name="foverview" id="foverview">Overview of Forms</a></h3>
<p>A form is a collection of fields; each field may be either a
label (explanatory text) or a data-entry location. Long forms may
Besides menu-like navigation operations, the menu driver loop has
to support field editing and data validation.</p>
- <h2><a name="fcreate" id="fcreate">Creating and Freeing Fields
- and Forms</a></h2>
+ <h3><a name="fcreate" id="fcreate">Creating and Freeing Fields
+ and Forms</a></h3>
<p>The basic function for creating fields is
<code>new_field()</code>:</p>
- <pre>
+ <pre class="code-block">
FIELD *new_field(int height, int width, /* new field size */
int top, int left, /* upper left corner */
int offscreen, /* number of offscreen rows */
int nbuf); /* number of working buffers */
</pre>
-
<p>Menu items always occupy a single row, but forms fields may
have multiple rows. So <code>new_field()</code> requires you to
specify a width and height (the first two arguments, which mist
buffers to allocate for the field; your application can use them
for its own purposes.</p>
- <pre>
+ <pre class="code-block">
FIELD *dup_field(FIELD *field, /* field to copy */
int top, int left); /* location of new copy */
</pre>
-
<p>The function <code>dup_field()</code> duplicates an existing
field at a new location. Size and buffering information are
copied; some attribute flags and status bits are not (see the
<code>form_field_new(3X)</code> for details).</p>
- <pre>
+ <pre class="code-block">
FIELD *link_field(FIELD *field, /* field to copy */
int top, int left); /* location of new copy */
</pre>
-
<p>The function <code>link_field()</code> also duplicates an
existing field at a new location. The difference from
<code>dup_field()</code> is that it arranges for the new field's
<p>To connect fields to a form, use</p>
- <pre>
+ <pre class="code-block">
FORM *new_form(FIELD **fields);
</pre>
-
<p>This function expects to see a NULL-terminated array of field
pointers. Said fields are connected to a newly-allocated form
object; its address is returned (or else NULL if the allocation
form, but not vice-versa; thus, you will generally free your form
objects first.</p>
- <h2><a name="fattributes" id="fattributes">Fetching and Changing
- Field Attributes</a></h2>
+ <h3><a name="fattributes" id="fattributes">Fetching and Changing
+ Field Attributes</a></h3>
<p>Each form field has a number of location and size attributes
associated with it. There are other field attributes used to
to it persist as defaults until your forms application
terminates.</p>
- <h3><a name="fsizes" id="fsizes">Fetching Size and Location
- Data</a></h3>
+ <h4><a name="fsizes" id="fsizes">Fetching Size and Location
+ Data</a></h4>
<p>You can retrieve field sizes and locations through:</p>
- <pre>
+ <pre class="code-block">
int field_info(FIELD *field, /* field from which to fetch */
int *height, *int width, /* field size */
int *top, int *left, /* upper left corner */
int *offscreen, /* number of offscreen rows */
int *nbuf); /* number of working buffers */
</pre>
-
<p>This function is a sort of inverse of
<code>new_field()</code>; instead of setting size and location
attributes of a new field, it fetches them from an existing
one.</p>
- <h3><a name="flocation" id="flocation">Changing the Field
- Location</a></h3>
+ <h4><a name="flocation" id="flocation">Changing the Field
+ Location</a></h4>
<p>It is possible to move a field's location on the screen:</p>
- <pre>
+ <pre class="code-block">
int move_field(FIELD *field, /* field to alter */
int top, int left); /* new upper-left corner */
</pre>
-
<p>You can, of course. query the current location through
<code>field_info()</code>.</p>
- <h3><a name="fjust" id="fjust">The Justification Attribute</a></h3>
+ <h4><a name="fjust" id="fjust">The Justification Attribute</a></h4>
<p>One-line fields may be unjustified, justified right, justified
left, or centered. Here is how you manipulate this attribute:</p>
- <pre>
+ <pre class="code-block">
int set_field_just(FIELD *field, /* field to alter */
int justmode); /* mode to set */
int field_just(FIELD *field); /* fetch mode of field */
</pre>
-
<p>The mode values accepted and returned by this functions are
preprocessor macros <code>NO_JUSTIFICATION</code>,
<code>JUSTIFY_RIGHT</code>, <code>JUSTIFY_LEFT</code>, or
<code>JUSTIFY_CENTER</code>.</p>
- <h3><a name="fdispatts" id="fdispatts">Field Display
- Attributes</a></h3>
+ <h4><a name="fdispatts" id="fdispatts">Field Display
+ Attributes</a></h4>
<p>For each field, you can set a foreground attribute for entered
characters, a background attribute for the entire field, and a
appearance of the field on the screen, without affecting in any
way the data in the field buffer.</p>
- <pre>
+ <pre class="code-block">
int set_field_fore(FIELD *field, /* field to alter */
chtype attr); /* attribute to set */
chtype new_page(FIELD *field); /* field to query */
</pre>
-
<p>The attributes set and returned by the first four functions
are normal <code>curses(3x)</code> display attribute values
(<code>A_STANDOUT</code>, <code>A_BOLD</code>,
<code>A_REVERSE</code> etc). The page bit of a field controls
whether it is displayed at the start of a new form screen.</p>
- <h3><a name="foptions" id="foptions">Field Option Bits</a></h3>
+ <h4><a name="foptions" id="foptions">Field Option Bits</a></h4>
<p>There is also a large collection of field option bits you can
set to control various aspects of forms processing. You can
manipulate them with these functions:</p>
- <pre>
+ <pre class="code-block">
int set_field_opts(FIELD *field, /* field to alter */
int attr); /* attribute to set */
int field_opts(FIELD *field); /* field to query */
</pre>
-
<p>By default, all options are on. Here are the available option
bits:</p>
<p>The option values are bit-masks and can be composed with
logical-or in the obvious way.</p>
- <h2><a name="fstatus" id="fstatus">Field Status</a></h2>
+ <h3><a name="fstatus" id="fstatus">Field Status</a></h3>
<p>Every field has a status flag, which is set to FALSE when the
field is created and TRUE when the value in field buffer 0
changes. This flag can be queried and set directly:</p>
- <pre>
+ <pre class="code-block">
int set_field_status(FIELD *field, /* field to alter */
int status); /* mode to set */
int field_status(FIELD *field); /* fetch mode of field */
</pre>
-
<p>Setting this flag under program control can be useful if you
use the same form repeatedly, looking for modified fields each
time.</p>
just after a <code>REQ_VALIDATION</code> request has been
processed by the forms driver.</p>
- <h2><a name="fuser" id="fuser">Field User Pointer</a></h2>
+ <h3><a name="fuser" id="fuser">Field User Pointer</a></h3>
<p>Each field structure contains one character pointer slot that
is not used by the forms library. It is intended to be used by
applications to store private per-field data. You can manipulate
it with:</p>
- <pre>
+ <pre class="code-block">
int set_field_userptr(FIELD *field, /* field to alter */
char *userptr); /* mode to set */
</pre>(Properly, this user pointer field ought to have <code>(void
*)</code> type. The <code>(char *)</code> type is retained for
System V compatibility.)
-
<p>It is valid to set the user pointer of the default field (with
a <code>set_field_userptr()</code> call passed a NULL field
pointer.) When a new field is created, the default-field user
pointer is copied to initialize the new field's user pointer.</p>
- <h2><a name="fdynamic" id="fdynamic">Variable-Sized Fields</a></h2>
+ <h3><a name="fdynamic" id="fdynamic">Variable-Sized Fields</a></h3>
<p>Normally, a field is fixed at the size specified for it at
creation time. If, however, you turn off its O_STATIC bit, it
But it is possible to set an upper limit on the size of a dynamic
field. You do it with this function:</p>
- <pre>
+ <pre class="code-block">
int set_max_field(FIELD *field, /* field to alter (may not be NULL) */
int max_size); /* upper limit on field size */
</pre>
-
<p>If the field is one-line, <code>max_size</code> is taken to be
a column size limit; if it is multi-line, it is taken to be a
line size limit. To disable any limit, use an argument of zero.
size.</li>
</ul>
- <h2><a name="fvalidation" id="fvalidation">Field Validation</a></h2>
+ <h3><a name="fvalidation" id="fvalidation">Field Validation</a></h3>
<p>By default, a field will accept any data that will fit in its
input buffer. However, it is possible to attach a validation type
define custom ones of your own. You can examine and change field
validation attributes with the following functions:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
FIELDTYPE *ftype, /* type to associate */
...); /* additional arguments*/
FIELDTYPE *field_type(FIELD *field); /* field to query */
</pre>
-
<p>The validation type of a field is considered an attribute of
the field. As with other field attributes, Also, doing
<code>set_field_type()</code> with a <code>NULL</code> field
<p>Here are the pre-defined validation types:</p>
- <h3><a name="ftype_alpha" id="ftype_alpha">TYPE_ALPHA</a></h3>
+ <h4><a name="ftype_alpha" id="ftype_alpha">TYPE_ALPHA</a></h4>
<p>This field type accepts alphabetic data; no blanks, no digits,
no special characters (this is checked at character-entry time).
It is set up with:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
TYPE_ALPHA, /* type to associate */
int width); /* maximum width of field */
</pre>
-
<p>The <code>width</code> argument sets a minimum width of data.
Typically you will want to set this to the field width; if it is
greater than the field width, the validation check will always
fail. A minimum width of zero makes field completion
optional.</p>
- <h3><a name="ftype_alnum" id="ftype_alnum">TYPE_ALNUM</a></h3>
+ <h4><a name="ftype_alnum" id="ftype_alnum">TYPE_ALNUM</a></h4>
<p>This field type accepts alphabetic data and digits; no blanks,
no special characters (this is checked at character-entry time).
It is set up with:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
TYPE_ALNUM, /* type to associate */
int width); /* maximum width of field */
</pre>
-
<p>The <code>width</code> argument sets a minimum width of data.
As with TYPE_ALPHA, typically you will want to set this to the
field width; if it is greater than the field width, the
validation check will always fail. A minimum width of zero makes
field completion optional.</p>
- <h3><a name="ftype_enum" id="ftype_enum">TYPE_ENUM</a></h3>
+ <h4><a name="ftype_enum" id="ftype_enum">TYPE_ENUM</a></h4>
<p>This type allows you to restrict a field's values to be among
a specified set of string values (for example, the two-letter
postal codes for U.S. states). It is set up with:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
TYPE_ENUM, /* type to associate */
char **valuelist; /* list of possible values */
int checkcase; /* case-sensitive? */
int checkunique); /* must specify uniquely? */
</pre>
-
<p>The <code>valuelist</code> parameter must point at a
NULL-terminated list of valid strings. The <code>checkcase</code>
argument, if true, makes comparison with the string
<code>REQ_PREV_CHOICE</code> input requests can be particularly
useful with these fields.</p>
- <h3><a name="ftype_integer" id="ftype_integer">TYPE_INTEGER</a></h3>
+ <h4><a name="ftype_integer" id="ftype_integer">TYPE_INTEGER</a></h4>
<p>This field type accepts an integer. It is set up as
follows:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
TYPE_INTEGER, /* type to associate */
int padding, /* # places to zero-pad to */
int vmin, int vmax); /* valid range */
</pre>
-
<p>Valid characters consist of an optional leading minus and
digits. The range check is performed on exit. If the range
maximum is less than or equal to the minimum, the range is
<p>A <code>TYPE_INTEGER</code> value buffer can conveniently be
interpreted with the C library function <code>atoi(3)</code>.</p>
- <h3><a name="ftype_numeric" id="ftype_numeric">TYPE_NUMERIC</a></h3>
+ <h4><a name="ftype_numeric" id="ftype_numeric">TYPE_NUMERIC</a></h4>
<p>This field type accepts a decimal number. It is set up as
follows:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
TYPE_NUMERIC, /* type to associate */
int padding, /* # places of precision */
double vmin, double vmax); /* valid range */
</pre>
-
<p>Valid characters consist of an optional leading minus and
digits. possibly including a decimal point. If your system
supports locale's, the decimal point character used must be the
<p>A <code>TYPE_NUMERIC</code> value buffer can conveniently be
interpreted with the C library function <code>atof(3)</code>.</p>
- <h3><a name="ftype_regexp" id="ftype_regexp">TYPE_REGEXP</a></h3>
+ <h4><a name="ftype_regexp" id="ftype_regexp">TYPE_REGEXP</a></h4>
<p>This field type accepts data matching a regular expression. It
is set up as follows:</p>
- <pre>
+ <pre class="code-block">
int set_field_type(FIELD *field, /* field to alter */
TYPE_REGEXP, /* type to associate */
char *regexp); /* expression to match */
</pre>
-
<p>The syntax for regular expressions is that of
<code>regcomp(3)</code>. The check for regular-expression match
is performed on exit.</p>
- <h2><a name="fbuffer" id="fbuffer">Direct Field Buffer
- Manipulation</a></h2>
+ <h3><a name="fbuffer" id="fbuffer">Direct Field Buffer
+ Manipulation</a></h3>
<p>The chief attribute of a field is its buffer contents. When a
form has been completed, your application usually needs to know
the state of each field buffer. You can find this out with:</p>
- <pre>
+ <pre class="code-block">
char *field_buffer(FIELD *field, /* field to query */
int bufindex); /* number of buffer to query */
</pre>
-
<p>Normally, the state of the zero-numbered buffer for each field
is set by the user's editing actions on that field. It is
sometimes useful to be able to set the value of the zero-numbered
(or some other) buffer from your application:</p>
- <pre>
+ <pre class="code-block">
int set_field_buffer(FIELD *field, /* field to alter */
int bufindex, /* number of buffer to alter */
char *value); /* string value to set */
</pre>
-
<p>If the field is not large enough and cannot be resized to a
sufficiently large size to contain the specified value, the value
will be truncated to fit.</p>
<code>REQ_VALIDATION</code> request has been processed by the
forms driver.</p>
- <h2><a name="formattrs" id="formattrs">Attributes of Forms</a></h2>
+ <h3><a name="formattrs" id="formattrs">Attributes of Forms</a></h3>
<p>As with field attributes, form attributes inherit a default
from a system default form structure. These defaults can be
<p>The principal attribute of a form is its field list. You can
query and change this list with:</p>
- <pre>
+ <pre class="code-block">
int set_form_fields(FORM *form, /* form to alter */
FIELD **fields); /* fields to connect */
int field_count(FORM *form); /* count connect fields */
</pre>
-
<p>The second argument of <code>set_form_fields()</code> may be a
NULL-terminated field pointer array like the one required by
<code>new_form()</code>. In that case, the old fields of the form
number of fields connected to a given from. It returns -1 if the
form-pointer argument is NULL.</p>
- <h2><a name="fdisplay" id="fdisplay">Control of Form Display</a></h2>
+ <h3><a name="fdisplay" id="fdisplay">Control of Form Display</a></h3>
<p>In the overview section, you saw that to display a form you
normally start by defining its size (and fields), posting it, and
need to know the size of the form's bounding rectangle. You can
get this information with:</p>
- <pre>
+ <pre class="code-block">
int scale_form(FORM *form, /* form to query */
int *rows, /* form rows */
int *cols); /* form cols */
</pre>
-
<p>The form dimensions are passed back in the locations pointed
to by the arguments. Once you have this information, you can use
it to declare of windows, then use one of these functions:</p>
- <pre>
+ <pre class="code-block">
int set_form_win(FORM *form, /* form to alter */
WINDOW *win); /* frame window to connect */
WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */
</pre>
-
<p>Note that curses operations, including <code>refresh()</code>,
on the form, should be done on the frame window, not the form
subwindow.</p>
scrollable field is actually displayed within the menu subwindow.
Use these functions:</p>
- <pre>
+ <pre class="code-block">
int data_ahead(FORM *form); /* form to be queried */
int data_behind(FORM *form); /* form to be queried */
</pre>
-
<p>The function <code>data_ahead()</code> returns TRUE if (a) the
current field is one-line and has undisplayed data off to the
right, (b) the current field is multi-line and there is data
<p>Finally, there is a function to restore the form window's
cursor to the value expected by the forms driver:</p>
- <pre>
+ <pre class="code-block">
int pos_form_cursor(FORM *) /* form to be queried */
</pre>
-
<p>If your application changes the form window cursor, call this
function before handing control back to the forms driver in order
to re-synchronize it.</p>
- <h2><a name="fdriver" id="fdriver">Input Processing in the Forms
- Driver</a></h2>
+ <h3><a name="fdriver" id="fdriver">Input Processing in the Forms
+ Driver</a></h3>
<p>The function <code>form_driver()</code> handles virtualized
input requests for form navigation, editing, and validation
requests, just as <code>menu_driver</code> does for menus (see
the section on <a href="#minput">menu input handling</a>).</p>
- <pre>
+ <pre class="code-block">
int form_driver(FORM *form, /* form to pass input to */
int request); /* form request code */
</pre>
-
<p>Your input virtualization function needs to take input and
then convert it to either an alphanumeric character (which is
treated as data to be entered in the currently-selected field),
check that the input taken by the driver matched what was
expected.</p>
- <h3><a name="fpage" id="fpage">Page Navigation Requests</a></h3>
+ <h4><a name="fpage" id="fpage">Page Navigation Requests</a></h4>
<p>These requests cause page-level moves through the form,
triggering display of a new form screen.</p>
and <code>REQ_PREV_PAGE</code> from the first page goes to the
last.</p>
- <h3><a name="ffield" id="ffield">Inter-Field Navigation
- Requests</a></h3>
+ <h4><a name="ffield" id="ffield">Inter-Field Navigation
+ Requests</a></h4>
<p>These requests handle navigation between fields on the same
page.</p>
from A will go to B only if A, B, and C <em>all</em> share the
same first line; otherwise it will skip over B to C.</p>
- <h3><a name="fifield" id="fifield">Intra-Field Navigation
- Requests</a></h3>
+ <h4><a name="fifield" id="fifield">Intra-Field Navigation
+ Requests</a></h4>
<p>These requests drive movement of the edit cursor within the
currently selected field.</p>
end of line or field look for the first or last non-pad character
in their ranges.</p>
- <h3><a name="fscroll" id="fscroll">Scrolling Requests</a></h3>
+ <h4><a name="fscroll" id="fscroll">Scrolling Requests</a></h4>
<p>Fields that are dynamic and have grown and fields explicitly
created with offscreen rows are scrollable. One-line fields
<p>For scrolling purposes, a <em>page</em> of a field is the
height of its visible part.</p>
- <h3><a name="fedit" id="fedit">Editing Requests</a></h3>
+ <h4><a name="fedit" id="fedit">Editing Requests</a></h4>
<p>When you pass the forms driver an ASCII character, it is
treated as a request to add the character to the field's data
<p>See <a href="#frmoptions">Form Options</a> for discussion of
how to set and clear the overload options.</p>
- <h3><a name="forder" id="forder">Order Requests</a></h3>
+ <h4><a name="forder" id="forder">Order Requests</a></h4>
<p>If the type of your field is ordered, and has associated
functions for getting the next and previous values of the type
field type of your own (see <a href="#fcustom">Custom Validation
Types</a>), you can associate our own ordering functions.</p>
- <h3><a name="fappcmds" id="fappcmds">Application Commands</a></h3>
+ <h4><a name="fappcmds" id="fappcmds">Application Commands</a></h4>
<p>Form requests are represented as integers above the
<code>curses</code> value greater than <code>KEY_MAX</code> and
your input-virtualization routine returns a value above
<code>MAX_COMMAND</code>, the forms driver will ignore it.</p>
- <h2><a name="fhooks" id="fhooks">Field Change Hooks</a></h2>
+ <h3><a name="fhooks" id="fhooks">Field Change Hooks</a></h3>
<p>It is possible to set function hooks to be executed whenever
the current field or form changes. Here are the functions that
support this:</p>
- <pre>
+ <pre class="code-block">
typedef void (*HOOK)(); /* pointer to function returning void */
int set_form_init(FORM *form, /* form to alter */
HOOK field_term(FORM *form); /* form to query */
</pre>
-
<p>These functions allow you to either set or query four
different hooks. In each of the set functions, the second
argument should be the address of a hook function. These
<p>You can disable any of these hooks by (re)setting them to
NULL, the default value.</p>
- <h2><a href="#ffocus">Field Change Commands</a></h2>
+ <h3><a href="#ffocus">Field Change Commands</a></h3>
<p>Normally, navigation through the form will be driven by the
user's input requests. But sometimes it is useful to be able to
application, or ask which field it currently is in. The following
functions help you accomplish this:</p>
- <pre>
+ <pre class="code-block">
int set_current_field(FORM *form, /* form to alter */
FIELD *field); /* field to shift to */
int field_index(FORM *form, /* form to query */
FIELD *field); /* field to get index of */
</pre>
-
<p>The function <code>field_index()</code> returns the index of
the given field in the given form's field array (the array passed
to <code>new_form()</code> or
<p>It is also possible to move around by pages.</p>
- <pre>
+ <pre class="code-block">
int set_form_page(FORM *form, /* form to alter */
int page); /* page to go to (0-origin) */
int form_page(FORM *form); /* return form's current page */
</pre>
-
<p>The initial page of a newly-created form is 0. The function
<code>set_form_fields()</code> resets this.</p>
- <h2><a name="frmoptions" id="frmoptions">Form Options</a></h2>
+ <h3><a name="frmoptions" id="frmoptions">Form Options</a></h3>
<p>Like fields, forms may have control option bits. They can be
changed or queried with these functions:</p>
- <pre>
+ <pre class="code-block">
int set_form_opts(FORM *form, /* form to alter */
int attr); /* attribute to set */
int form_opts(FORM *form); /* form to query */
</pre>
-
<p>By default, all options are on. Here are the available option
bits:</p>
<p>The option values are bit-masks and can be composed with
logical-or in the obvious way.</p>
- <h2><a name="fcustom" id="fcustom">Custom Validation Types</a></h2>
+ <h3><a name="fcustom" id="fcustom">Custom Validation Types</a></h3>
<p>The <code>form</code> library gives you the capability to
define custom validation types of your own. Further, the optional
the handling of the additional arguments within custom validation
functions.</p>
- <h3><a name="flinktypes" id="flinktypes">Union Types</a></h3>
+ <h4><a name="flinktypes" id="flinktypes">Union Types</a></h4>
<p>The simplest way to create a custom data type is to compose it
from two preexisting ones:</p>
- <pre>
+ <pre class="code-block">
FIELD *link_fieldtype(FIELDTYPE *type1,
FIELDTYPE *type2);
</pre>
-
<p>This function creates a field type that will accept any of the
values legal for either of its argument field types (which may be
either predefined or programmer-defined). If a
function for the first type, then for the second, to figure what
type the buffer contents should be treated as.</p>
- <h3><a name="fnewtypes" id="fnewtypes">New Field Types</a></h3>
+ <h4><a name="fnewtypes" id="fnewtypes">New Field Types</a></h4>
<p>To create a field type from scratch, you need to specify one
or both of the following things:</p>
<p>Here is how you do that:</p>
- <pre>
+ <pre class="code-block">
typedef int (*HOOK)(); /* pointer to function returning int */
FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
int free_fieldtype(FIELDTYPE *ftype); /* type to free */
</pre>
-
<p>At least one of the arguments of <code>new_fieldtype()</code>
must be non-NULL. The forms driver will automatically call the
new type's validation functions at appropriate points in
argument. It too should return TRUE if the character is valid,
FALSE otherwise.</p>
- <h3><a name="fcheckargs" id="fcheckargs">Validation Function
- Arguments</a></h3>
+ <h4><a name="fcheckargs" id="fcheckargs">Validation Function
+ Arguments</a></h4>
<p>Your field- and character- validation functions will be passed
a second argument as well. This second argument is the address of
<p>Here is how you make the association:</p>
- <pre>
+ <pre class="code-block">
typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */
typedef void (*VOIDHOOK)(); /* pointer to function returning void */
PTRHOOK copy_str, /* make copy of structure */
VOIDHOOK free_str); /* free structure storage */
</pre>
-
<p>Here is how the storage-management hooks are used:</p>
<dl>
this happens. Thus, your validation functions should never see a
NULL file pointer and need not check specially for it.</p>
- <h3><a name="fcustorder" id="fcustorder">Order Functions For
- Custom Types</a></h3>
+ <h4><a name="fcustorder" id="fcustorder">Order Functions For
+ Custom Types</a></h4>
<p>Some custom field types are simply ordered in the same
well-defined way that <code>TYPE_ENUM</code> is. For such types,
support the <code>REQ_NEXT_CHOICE</code> and
<code>REQ_PREV_CHOICE</code> requests. Here is how:</p>
- <pre>
+ <pre class="code-block">
typedef int (*INTHOOK)(); /* pointer to function returning int */
int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */
INTHOOK succ, /* get successor value */
INTHOOK pred); /* get predecessor value */
</pre>
-
<p>The successor and predecessor arguments will each be passed
two arguments; a field pointer, and a pile pointer (as for the
validation functions). They are expected to use the function
(a legal next or previous value was set) or FALSE to indicate
failure.</p>
- <h3><a name="fcustprobs" id="fcustprobs">Avoiding Problems</a></h3>
+ <h4><a name="fcustprobs" id="fcustprobs">Avoiding Problems</a></h4>
<p>The interface for defining custom types is complicated and
tricky. Rather than attempting to create a custom type entirely
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_clear.3x,v 1.23 2022/02/12 20:06:41 tom Exp $
+.\" $Id: curs_clear.3x,v 1.27 2022/11/26 16:23:47 tom Exp $
.TH curs_clear 3X ""
.na
.hy 0
\fBint wclrtoeol(WINDOW *\fIwin\fB);\fR
.br
.SH DESCRIPTION
+.SS erase/werase
The \fBerase\fP and \fBwerase\fP routines copy blanks to every
position in the window, clearing the screen.
.PP
+Blanks created by erasure have the current background rendition (as set
+by \fBwbkgdset\fP(3X)) merged into them.
+.SS clear/wclear
+.PP
The \fBclear\fP and \fBwclear\fP routines are like \fBerase\fP and
-\fBwerase\fP, but they also call \fBclearok\fP, so that the screen is
+\fBwerase\fP, but they also call \fBclearok\fP(3X), so that the screen is
cleared completely on the next call to \fBwrefresh\fP for that window
and repainted from scratch.
+.SS clrtobot/wclrtobot
.PP
The \fBclrtobot\fP and \fBwclrtobot\fP routines erase from the cursor to the
end of screen.
That is, they erase all lines below the cursor in the window.
Also, the current line to the right of the cursor, inclusive, is erased.
+.SS clrtoeol/wclrtoeol
.PP
The \fBclrtoeol\fP and \fBwclrtoeol\fP routines erase the current line
to the right of the cursor, inclusive, to the end of the current line.
-.PP
-Blanks created by erasure have the current background rendition (as set
-by \fBwbkgdset\fP) merged into them.
.SH RETURN VALUE
All routines return the integer \fBOK\fP on success and \fBERR\fP on failure.
.PP
error conditions.
.PP
The SVr4.0 manual says that these functions could
-return "a non-negative integer if \fBimmedok\fP is set",
+return "a non-negative integer if \fBimmedok\fP(3X) is set",
referring to the return-value of \fBwrefresh\fP.
In that implementation, \fBwrefresh\fP would return a count of
the number of characters written to the terminal.
-# $Id: manhtml.aliases,v 1.20 2022/02/20 00:39:41 tom Exp $
+# $Id: manhtml.aliases,v 1.21 2022/11/26 13:57:22 tom Exp $
#***************************************************************************
# Copyright 2019-2020,2022 Thomas E. Dickey *
# Copyright 2013,2017 Free Software Foundation, Inc. *
# Items in this list will be linked to the corresponding manpages by man2html
addch(3X) curs_addch(3X)
assume_default_colors(3X) default_colors(3X)
+clearok(3X) curs_outopts(3X)
curs_set(3X) curs_kernel(3X)
delscreen(3X) curs_initscr(3X)
doupdate(3X) curs_refresh(3X)
get_wch(3X) curs_get_wch(3X)
getcchar(3X) curs_getcchar(3X)
getch(3X) curs_getch(3X)
+immedok(3X) curs_outopts(3X)
inch(3X) curs_inch(3X)
infocmp(1) infocmp(1M)
initscr(3X) curs_initscr(3X)
use_extended_names(3X) curs_extend(3X)
use_legacy_coding(3X) legacy_coding(3X)
vidputs(3X) curs_terminfo(3X)
+wbkgdset(3X) curs_bkgd(3X)
wgetch(3X) curs_getch(3X)
wnoutrefresh(3X) curs_refresh(3X)
wrefresh(3X) curs_refresh(3X)
-ncurses6 (6.3+20221119) unstable; urgency=low
+ncurses6 (6.3+20221126) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 19 Nov 2022 06:24:10 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 26 Nov 2022 06:55:42 -0500
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.3+20221119) unstable; urgency=low
+ncurses6 (6.3+20221126) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 19 Nov 2022 06:24:10 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 26 Nov 2022 06:55:42 -0500
ncurses6 (5.9+20131005) unstable; urgency=low
-ncurses6 (6.3+20221119) unstable; urgency=low
+ncurses6 (6.3+20221126) unstable; urgency=low
* latest weekly patch
- -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 19 Nov 2022 06:24:10 -0500
+ -- Thomas E. Dickey <dickey@invisible-island.net> Sat, 26 Nov 2022 06:55:42 -0500
ncurses6 (5.9+20120608) unstable; urgency=low
-; $Id: mingw-ncurses.nsi,v 1.552 2022/11/19 11:24:10 tom Exp $\r
+; $Id: mingw-ncurses.nsi,v 1.553 2022/11/26 11:55:42 tom Exp $\r
\r
; TODO add examples\r
; TODO bump ABI to 6\r
!define VERSION_MAJOR "6"\r
!define VERSION_MINOR "3"\r
!define VERSION_YYYY "2022"\r
-!define VERSION_MMDD "1119"\r
+!define VERSION_MMDD "1126"\r
!define VERSION_PATCH ${VERSION_YYYY}${VERSION_MMDD}\r
\r
!define MY_ABI "5"\r
Summary: shared libraries for terminal handling
Name: mingw32-ncurses6
Version: 6.3
-Release: 20221119
+Release: 20221126
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
Summary: shared libraries for terminal handling
Name: ncurses6
Version: 6.3
-Release: 20221119
+Release: 20221126
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
Summary: Curses library with POSIX thread support.
Name: ncursest6
Version: 6.3
-Release: 20221119
+Release: 20221126
License: X11
Group: Development/Libraries
Source: ncurses-%{version}-%{release}.tgz
Author: Eric S. Raymond <esr@snark.thyrsus.com> 1993
Thomas E. Dickey (beginning revision 1.27 in 1996).
-$Id: ncurses.c,v 1.528 2022/02/26 22:41:02 tom Exp $
+$Id: ncurses.c,v 1.529 2022/11/26 23:16:04 tom Exp $
***************************************************************************/
if (pending_code) {
_nc_SPRINTF(at_page, _nc_SLIMIT(sizeof(at_page)) "%02x", digit);
} else if (at_page[0] != '\0') {
- _nc_SPRINTF(at_page, _nc_SLIMIT(sizeof(at_page)) "%x", digit);
+ sscanf(at_page, "%x", &digit);
}
break;
default:
install-stamp: build-stamp
dh_testdir
dh_testroot
- dh_clean -k
+ dh_prep
dh_installdirs
$(MAKE) install DESTDIR=$(MINGW_TMP)
install-stamp: build-stamp
dh_testdir
dh_testroot
- dh_clean -k
+ dh_prep
dh_installdirs
$(MAKE) install DESTDIR=$(MINGW_TMP)