From 205ea499dbbceba5201d997fbd8b6b1f7f29bd50 Mon Sep 17 00:00:00 2001 From: "Thomas E. Dickey" Date: Sun, 27 Nov 2022 01:53:44 +0000 Subject: [PATCH] ncurses 6.3 - patch 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 --- Ada95/samples/split-path.awk | 6 +- NEWS | 8 +- VERSION | 2 +- dist.mk | 4 +- doc/html/NCURSES-Programming-HOWTO.html | 341 ++++++----- doc/html/announce.html | 522 +++++++++-------- doc/html/hackguide.html | 163 +++--- doc/html/index.html | 15 +- doc/html/man/adacurses6-config.1.html | 2 +- doc/html/man/captoinfo.1m.html | 2 +- doc/html/man/clear.1.html | 2 +- doc/html/man/curs_clear.3x.html | 39 +- doc/html/man/form.3x.html | 2 +- doc/html/man/infocmp.1m.html | 2 +- doc/html/man/infotocap.1m.html | 2 +- doc/html/man/menu.3x.html | 2 +- doc/html/man/ncurses.3x.html | 2 +- doc/html/man/ncurses6-config.1.html | 2 +- doc/html/man/panel.3x.html | 2 +- doc/html/man/tabs.1.html | 2 +- doc/html/man/terminfo.5.html | 2 +- doc/html/man/tic.1m.html | 2 +- doc/html/man/toe.1m.html | 2 +- doc/html/man/tput.1.html | 2 +- doc/html/man/tset.1.html | 2 +- doc/html/ncurses-intro.html | 740 +++++++++++------------- man/curs_clear.3x | 16 +- man/manhtml.aliases | 5 +- package/debian-mingw/changelog | 4 +- package/debian-mingw64/changelog | 4 +- package/debian/changelog | 4 +- package/mingw-ncurses.nsi | 4 +- package/mingw-ncurses.spec | 2 +- package/ncurses.spec | 2 +- package/ncursest.spec | 2 +- test/ncurses.c | 4 +- test/package/debian-mingw/rules | 2 +- test/package/debian-mingw64/rules | 2 +- 38 files changed, 987 insertions(+), 936 deletions(-) diff --git a/Ada95/samples/split-path.awk b/Ada95/samples/split-path.awk index 86e8ccdc..5b340ba5 100644 --- a/Ada95/samples/split-path.awk +++ b/Ada95/samples/split-path.awk @@ -1,5 +1,5 @@ ############################################################################## -# 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"), # @@ -28,9 +28,11 @@ # # 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; diff --git a/NEWS b/NEWS index dbf5b8df..1638dc9e 100644 --- a/NEWS +++ b/NEWS @@ -26,7 +26,7 @@ -- 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 @@ -46,6 +46,12 @@ See the AUTHORS file for the corresponding full names. 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. diff --git a/VERSION b/VERSION index 4e6e0fb1..a2a8606b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -5:0:10 6.3 20221119 +5:0:10 6.3 20221126 diff --git a/dist.mk b/dist.mk index 22e4fc9c..46c90fad 100644 --- a/dist.mk +++ b/dist.mk @@ -26,7 +26,7 @@ # 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 @@ -38,7 +38,7 @@ SHELL = /bin/sh # 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) diff --git a/doc/html/NCURSES-Programming-HOWTO.html b/doc/html/NCURSES-Programming-HOWTO.html index e973c9ec..99591d58 100644 --- a/doc/html/NCURSES-Programming-HOWTO.html +++ b/doc/html/NCURSES-Programming-HOWTO.html @@ -1,16 +1,13 @@ - - + "HTML Tidy for HTML5 for Linux version 5.6.0"> NCURSES Programming HOWTO -
@@ -24,7 +21,8 @@

+ "mailto:ppadala@gmail.com">ppadala@gmail.com> +

@@ -34,14 +32,13 @@ + History + - - @@ -53,9 +50,7 @@ - - @@ -68,9 +63,7 @@ - - @@ -82,9 +75,7 @@ - - @@ -96,9 +87,7 @@ - - @@ -109,9 +98,7 @@ - - @@ -122,9 +109,7 @@ - - @@ -135,9 +120,7 @@ - - @@ -148,9 +131,7 @@ - - @@ -162,9 +143,7 @@ - - @@ -176,9 +155,7 @@ - - @@ -192,7 +169,6 @@
-

This document is intended to be an "All in One" guide for programming with ncurses and its sister libraries. We @@ -200,15 +176,18 @@ complex form manipulation. No prior experience in ncurses is assumed. Send comments to this - address

+ address +

+
-
Table of Contents
+
Table of Contents +
1. Introduction
@@ -676,20 +655,20 @@

Suppose you wanted to print a line in color. Try typing this on your console.

+
 echo "^[[0;31;40mIn Color"
 
-

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.

+
 echo "^[[0;37;40m"
 
-

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 @@ -778,7 +757,8 @@ echo "^[[0;37;40m" on.

Compiling the - package

+ package +

NCURSES can be obtained from Read the README and INSTALL files for details on to how to install it. It usually involves the following operations.

+
     tar zxvf ncurses<version>.tar.gz  # unzip and untar the archive
     cd ncurses<version>               # cd to the directory
@@ -799,14 +780,15 @@ echo "^[[0;37;40m"
     su root                                 # become root
     make install                            # install it
 
-

Using the - RPM

+ RPM +

NCURSES RPM can be found and downloaded from http://rpmfind.net . The RPM can be installed with the following command after becoming root.

+
     rpm -i <downloaded rpm>
 
@@ -837,6 +819,7 @@ echo "^[[0;37;40m" "http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz" target="_top">here. Unzip and untar it. The directory structure looks like this.

+
 ncurses
    |
@@ -854,9 +837,9 @@ ncurses
    |----> README         -- the top level README file. contains instructions
    |----> COPYING        -- copyright notice
 
-

The individual directories contain the following files.

+
 Description of files in each directory
 --------------------------------------
@@ -919,7 +902,6 @@ JustForFun
   perl
     |----> 01-10.pl          -- Perl equivalents of first ten example programs
 
-

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 @@ -995,6 +977,7 @@ JustForFun

If above links are broken or if you want to experiment with sgml read on.

+
 
    Get both the source and the tar,gzipped programs, available at
         http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
@@ -1019,7 +1002,6 @@ JustForFun
         htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps>
         NCURSES-ONE-BIG-FILE.html
 
-

See LDP Author guide for more details. If all else @@ -1147,12 +1129,12 @@ JustForFun


2.1. Compiling With the NCURSES - Library

+ "COMPILECURSES">2.1. Compiling With the NCURSES Library

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.

+
     #include <ncurses.h>
     .
@@ -1161,11 +1143,11 @@ JustForFun
 
     compile and link: gcc <program file> -lncurses
 
-
+

Example 1. The Hello World !!! Program +

-

Example 1. The Hello World !!! Program

 #include <ncurses.h>
 
@@ -1401,9 +1383,10 @@ int main()
 
         
-

Example 2. Initialization Function Usage - example

+ example +

+
 #include <ncurses.h>
 
@@ -1476,11 +1459,11 @@ int main()
       which explicitly work on the specified window.

For example, if you call

+
     printw("Hi There !!!");
     refresh();
 
-

It prints the string on stdscr at the present cursor position. Similarly the call to refresh(), works on stdscr only.

@@ -1488,14 +1471,15 @@ int main()

Say you have created windows then you have to call a function with a 'w' added to the usual function.

+
     wprintw(win, "Hi There !!!");
     wrefresh(win);
 
-

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.

+
     printw(string);        /* Print on stdscr at present cursor position */
     mvprintw(y, x, string);/* Move to (y, x) then print string     */
@@ -1504,7 +1488,6 @@ int main()
     mvwprintw(win, y, x, string);   /* Move to (y, x) relative to window */
                                     /* co-ordinates and then print         */
 
-

Usually the w-less functions are macros which expand to corresponding w-function with stdscr as the window parameter.

@@ -1570,6 +1553,7 @@ int main() For example, you want to print a character ch(of type char) bold and underlined, you would call addch() as below.

+
     addch(ch | A_BOLD | A_UNDERLINE);
 
@@ -1604,16 +1588,17 @@ int main()

mvaddch() is used to move the cursor to a given point, and then print. Thus, the calls:

+
     move(row,col);    /* moves the cursor to rowth row and colth column */
     addch(ch);
 
can be replaced by +
     mvaddch(row,col,ch);
 
-

waddch() is similar to addch(), except that it adds a character into the given window. (Note that

6.3.2. wprintw() and - mvwprintw

+ "WPRINTWMVWPRINTW">6.3.2. wprintw() and mvwprintw

These two functions are similar to above two except that they print in the corresponding window given as @@ -1694,8 +1678,9 @@ int main()

+

Example 3. A Simple printw example +

-

Example 3. A Simple printw example

 #include <ncurses.h>                   /* ncurses.h includes stdio.h */  
@@ -1891,8 +1876,9 @@ int main()
 
         
+

Example 4. A Simple scanw example +

-

Example 4. A Simple scanw example

 #include <ncurses.h>                   /* ncurses.h includes stdio.h */  
@@ -1935,8 +1921,9 @@ int main()
 
       
+

Example 5. A Simple Attributes example +

-

Example 5. A Simple Attributes example

 /* pager functionality by Joseph Spainhour" <spainhou@bellsouth.net> */
@@ -2034,6 +2021,7 @@ int main(int argc, char *argv[])
         attributes and switch them on or off, respectively. The
         following video attributes, which are defined in
         <curses.h> can be passed to these functions.

+
     
     A_NORMAL        Normal display (no highlight)
@@ -2050,7 +2038,6 @@ int main(int argc, char *argv[])
     COLOR_PAIR(n)   Color-pair number n 
     
 
-

The last one is the most colorful one :-) Colors are explained in the next sections.

@@ -2058,6 +2045,7 @@ int main(int argc, char *argv[])

We can OR(|) any number of above attributes to get a combined effect. If you wanted reverse video with blinking characters you can use

+
     attron(A_REVERSE | A_BLINK);
 
@@ -2141,10 +2129,10 @@ int main(int argc, char *argv[])

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.

+
     chgat(-1, A_REVERSE, 0, NULL);
 
-

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 @@ -2159,8 +2147,9 @@ int main(int argc, char *argv[])

+

Example 6. Chgat() Usage example +

-

Example 6. Chgat() Usage example

 #include <ncurses.h>
 
@@ -2249,12 +2238,12 @@ int main(int argc, char *argv[])
 
         
+

Example 7. Window Border example +

-

Example 7. Window Border example

 #include <ncurses.h>
 
-
 WINDOW *create_newwin(int height, int width, int starty, int startx);
 void destroy_win(WINDOW *local_win);
 
@@ -2369,11 +2358,12 @@ 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:

+
     wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');
 
-

it produces some thing like

+
     +------------+
     |            |
@@ -2423,8 +2413,9 @@ void destroy_win(WINDOW *local_win)
 
         
+

Example 8. More border functions +

-

Example 8. More border functions

 #include <ncurses.h>
 
@@ -2554,8 +2545,7 @@ void create_box(WIN *p_win, bool flag)
     

-

10. - Colors

+

10. Colors

+

Example 9. A Simple Color example +

-

Example 9. A Simple Color example

 #include <ncurses.h>
 
@@ -2644,6 +2635,7 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
         

The following colors are defined in curses.h. You can use these as parameters for various color functions.

+
         COLOR_BLACK   0
         COLOR_RED     1
@@ -2667,12 +2659,12 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
         curses initially. Say you wanted to lighten the intensity
         of red color by a minuscule. Then you can use this function
         as

+
     init_color(COLOR_RED, 700, 0, 0);
     /* param 1     : color name
      * param 2, 3, 4 : rgb content min = 0, max = 1000 */
 
-

If your terminal cannot change the color definitions, the function returns ERR. The function can_change_color() can be used to find out @@ -2710,8 +2702,8 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin sensitive to key presses or the mouse actions done by the user. Let's deal with the keys first.

-

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 +

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 getch() function. The cbreak mode should be enabled to read keys when you are interested in reading @@ -2731,12 +2723,12 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin keys portable and easy to manage.

For example, if you call getch() like this

+
     int ch;
 
     ch = getch();
 
-

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 @@ -2744,11 +2736,11 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin match against the keys you want.

The following code piece will do that job.

+
     if(ch == KEY_LEFT)
         printw("Left arrow is pressed\n");
 
-

Let's write a small program which creates a menu which can be navigated by up and down arrows.

@@ -2761,8 +2753,9 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
+

Example 10. A Simple Key Usage example +

-

Example 10. A Simple Key Usage example

 #include <stdio.h>
 #include <ncurses.h>
@@ -2835,7 +2828,6 @@ int main()
         return 0;
 }
 
-
 void print_menu(WINDOW *menu_win, int highlight)
 {
         int x, y, i;    
@@ -2880,11 +2872,11 @@ void print_menu(WINDOW *menu_win, int highlight)
         

Before you do any thing else, the events you want to receive have to be enabled with mousemask().

+
     mousemask(  mmask_t newmask,    /* The events you want to listen to */
                 mmask_t *oldmask)    /* The old events mask                */
 
-

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

The following are all the event masks:

+
     Name            Description
        ---------------------------------------------------------------------
@@ -2935,6 +2928,7 @@ void print_menu(WINDOW *menu_win, int highlight)
         getmouse().

The code approximately looks like this:

+
     MEVENT event;
 
@@ -2945,9 +2939,9 @@ void print_menu(WINDOW *menu_win, int highlight)
             .
             .
 
-

getmouse() returns the event into the pointer given to it. It is a structure which contains

+
     typedef struct
     {
@@ -2956,13 +2950,13 @@ void print_menu(WINDOW *menu_win, int highlight)
         mmask_t bstate;   /* button state bits */
     }    
 
-

The bstate is the main variable we are interested in. It tells the button state of the mouse.

Then with a code snippet like the following, we can find out what happened.

+
     if(event.bstate & BUTTON1_PRESSED)
         printw("Left Button Pressed");
@@ -2981,8 +2975,9 @@ void print_menu(WINDOW *menu_win, int highlight)
 
         
+

Example 11. Access the menu with mouse !!! +

-

Example 11. Access the menu with mouse !!!

 #include <ncurses.h>
 
@@ -3053,7 +3048,6 @@ end:
         return 0;
 }
 
-
 void print_menu(WINDOW *menu_win, int highlight)
 {
         int x, y, i;    
@@ -3134,13 +3128,13 @@ void report_choice(int mouse_x, int mouse_y, int *p_choice)
         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

+
     getyx(win, y, x);
     /* win: window pointer
      *   y, x: y, x co-ordinates will be put into this variables 
      */
 
-

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 @@ -3214,6 +3208,7 @@ void report_choice(int mouse_x, int mouse_y, int *p_choice)

This function can be used to make the cursor invisible. The parameter to this function should be

+
     0 : invisible      or
     1 : normal    or
@@ -3242,8 +3237,9 @@ void report_choice(int mouse_x, int mouse_y, int *p_choice)
 
         
+

Example 12. Temporarily Leaving Curses Mode +

-

Example 12. Temporarily Leaving Curses Mode

 #include <ncurses.h>
 
@@ -3286,8 +3282,9 @@ int main()
 
         
+

Example 13. ACS Variables Example +

-

Example 13. ACS Variables Example

 #include <ncurses.h>
 
@@ -3372,7 +3369,8 @@ int main()
       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.

+ right. Hence the panels library. +

If you have lot of overlapping windows, then panels library is the way to go. It obviates the need of doing @@ -3446,13 +3444,13 @@ int main()


16.2. Compiling With the Panels - Library

+ "COMPILEPANELS">16.2. Compiling With the Panels Library

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.

+
     #include <panel.h>
     .
@@ -3461,11 +3459,11 @@ int main()
 
     compile and link: gcc <program file> -lpanel -lncurses
 
-
+

Example 14. Panel basics +

-

Example 14. Panel basics

 #include <panel.h>
 
@@ -3528,8 +3526,9 @@ int main()
 
         
+

Example 15. Panel Window Browsing Example +

-

Example 15. Panel Window Browsing Example

 #include <panel.h>
 
@@ -3705,9 +3704,9 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
 
         
+

Example 16. Panel Moving and Resizing example +

-

Example 16. Panel Moving and Resizing - example

 #include <panel.h>
 
@@ -3997,9 +3996,9 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
 
         
+

Example 17. Panel Hiding and Showing example +

-

Example 17. Panel Hiding and Showing - example

 #include <panel.h>
 
@@ -4262,13 +4261,13 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
         

17.2. Compiling With the Menu - Library

+ "COMPILEMENUS">17.2. Compiling With the Menu Library

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.

+
     #include <menu.h>
     .
@@ -4277,11 +4276,11 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin
 
     compile and link: gcc <program file> -lmenu -lncurses
 
-
+

Example 18. Menu Basics +

-

Example 18. Menu Basics

 #include <curses.h>
 #include <menu.h>
@@ -4357,6 +4356,7 @@ int main()
 
         

The menu_driver accepts following navigational requests.

+
 
     REQ_LEFT_ITEM         Move left to an item.
      REQ_RIGHT_ITEM      Move right to an item.
@@ -4376,7 +4376,6 @@ int main()
      REQ_NEXT_MATCH     Move to the next item matching the pattern match.
      REQ_PREV_MATCH     Move to the previous item matching the pattern match.
 
-

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 @@ -4402,8 +4401,8 @@ int main()

-

The Curses Library

+

The Curses Library

-

An Overview of Curses

+

An Overview of Curses

-

Compiling Programs using - Curses

+

Compiling Programs using + Curses

In order to use the library, it is necessary to have certain types and variables defined. Therefore, the programmer must have a line:

-
+  
           #include <curses.h>
 
-

at the top of the program source. The screen package uses the Standard I/O library, so <curses.h> includes <stdio.h>. <curses.h> also @@ -502,7 +492,7 @@ your LDFLAGS or on the command line. There is no need for any other libraries.

-

Updating the Screen

+

Updating the Screen

In order to update the screen optimally, it is necessary for the routines to know what the screen currently looks like and @@ -533,8 +523,8 @@ like this,” and let the package implementation determine the most efficient way to repaint the screen.

-

Standard Windows and Function - Naming Conventions

+

Standard Windows and Function + Naming Conventions

As hinted above, the routines can use several windows, but two are automatically given: curscr, which knows what @@ -563,46 +553,41 @@ “mv” and the desired (y, x) coordinates prepended to the arguments to the function. For example, the calls

-
+  
           move(y, x);
           addch(ch);
 
-

can be replaced by

-
+  
           mvaddch(y, x, ch);
 
-

and

-
+  
           wmove(win, y, x);
           waddch(win, ch);
 
-

can be replaced by

-
+  
           mvwaddch(win, y, x, ch);
 
-

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.

-

Variables

+

Variables

The curses library sets some variables describing the terminal capabilities.

-
+  
       type   name      description
       ------------------------------------------------------------------
       int    LINES     number of lines on the terminal
       int    COLS      number of columns on the terminal
 
-

The curses.h also introduces some #define constants and types of general usefulness:

@@ -635,7 +620,7 @@
error flag returned by routines when things go right.
-

Using the Library

+

Using the Library

Now we describe how to actually use the screen package. In it, we assume all updating, reading, etc. is applied to @@ -645,7 +630,7 @@

Here is a sample program to motivate the discussion:

-
+  
 #include <stdlib.h>
 #include <curses.h>
 #include <signal.h>
@@ -707,8 +692,7 @@ static void finish(int sig)
     exit(0);
 }
 
- -

Starting up

+

Starting up

In order to use the screen package, the routines must know about terminal characteristics, and the space for @@ -740,7 +724,7 @@ static void finish(int sig) allow you to get rid of old windows. All the options described above can be applied to any window.

-

Output

+

Output

Now that we have set things up, we will want to actually update the terminal. The basic functions used to change what will @@ -775,7 +759,7 @@ static void finish(int sig) implementing a command which would redraw the screen in case it get messed up.

-

Input

+

Input

The complementary function to addch() is getch() which, if echo is set, will call @@ -804,8 +788,8 @@ static void finish(int sig) #define values is determined by key_ capabilities in the terminal's terminfo entry.

-

Using Forms - Characters

+

Using Forms + Characters

The addch() function (and some others, including box() and border()) can accept some @@ -820,8 +804,8 @@ static void finish(int sig) curses.h will map them to a recognizable (though ugly) set of ASCII defaults.

-

Character Attributes and - Color

+

Character Attributes and + Color

The ncurses package supports screen highlights including standout, reverse-video, underline, and blink. It also @@ -859,7 +843,7 @@ static void finish(int sig) that COLOR_PAIR(N), for constant N, is itself a compile-time constant and can be used in initializers.

-

Mouse Interfacing

+

Mouse Interfacing

The ncurses library also provides a mouse interface.

@@ -947,7 +931,7 @@ static void finish(int sig)

See the manual page curs_mouse(3X) for full details of the mouse-interface functions.

-

Finishing Up

+

Finishing Up

In order to clean up after the ncurses routines, the routine endwin() is provided. It restores tty @@ -956,13 +940,13 @@ static void finish(int sig) anytime after the call to initscr, endwin() should be called before exiting.

-

Function Descriptions

+

Function Descriptions

We describe the detailed behavior of some important curses functions here, as a supplement to the manual page descriptions.

-

Initialization and Wrapup

+

Initialization and Wrapup

initscr() @@ -1025,7 +1009,7 @@ static void finish(int sig) reference.
-

Causing Output to the Terminal

+

Causing Output to the Terminal

refresh() and wrefresh(win)
@@ -1064,8 +1048,8 @@ static void finish(int sig) each update).
-

Low-Level Capability - Access

+

Low-Level Capability + Access

setupterm(term, filenum, errret) @@ -1082,7 +1066,6 @@ static void finish(int sig) indication is returned. The values returned can be 1 (all is well), 0 (no such terminal), or -1 (some problem locating the terminfo database). -

The value of term can be given as NULL, which will cause the value of TERM in the environment to be used. The errret pointer can also be given @@ -1107,7 +1090,7 @@ static void finish(int sig)

-

Debugging

+

Debugging

NOTE: These functions are not part of the @@ -1149,14 +1132,14 @@ static void finish(int sig) be distinguished by the fact that they are named in capital letters.

-

Hints, Tips, and Tricks

+

Hints, Tips, and Tricks

The ncurses 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.

-

Some Notes of Caution

+

Some Notes of Caution

If you find yourself thinking you need to use noraw() or nocbreak(), think again and @@ -1196,8 +1179,8 @@ static void finish(int sig) with window resizes, in which case several screens could be open with different sizes.

-

Temporarily Leaving NCURSES - Mode

+

Temporarily Leaving NCURSES + Mode

Sometimes you will want to write a program that spends most of its time in screen mode, but occasionally returns to ordinary @@ -1220,7 +1203,7 @@ static void finish(int sig)

Here is some sample code for shellout:

-
+  
     addstr("Shelling out...");
     def_prog_mode();           /* save current tty modes */
     endwin();                  /* restore original tty modes */
@@ -1228,8 +1211,7 @@ static void finish(int sig)
     addstr("returned.\n");     /* prepare return message */
     refresh();                 /* restore save modes, repaint screen */
 
- -

Using NCURSES under XTERM

+

Using NCURSES under XTERM

A resize operation in X sends SIGWINCH to the application running under xterm. The easiest way to handle @@ -1258,8 +1240,8 @@ static void finish(int sig) special-purpose code to handle KEY_RESIZE yourself.

-

Handling Multiple Terminal - Screens

+

Handling Multiple Terminal + Screens

The initscr() function actually calls a function named newterm() to do most of its work. If you are @@ -1274,8 +1256,8 @@ static void finish(int sig) def_shell_mode and def_prog_mode on each tty yourself.

-

Testing for Terminal - Capabilities

+

Testing for Terminal + Capabilities

Sometimes you may want to write programs that test for the presence of various capabilities before deciding whether to go @@ -1292,7 +1274,7 @@ static void finish(int sig) include the term.h file and test the value of the macro cursor_address.

-

Tuning for Speed

+

Tuning for Speed

Use the addchstr() family of functions for fast screen-painting of text when you know the text does not contain @@ -1300,8 +1282,8 @@ static void finish(int sig) on your screens. Do not use the immedok() option!

-

Special Features of - NCURSES

+

Special Features of + NCURSES

The wresize() function allows you to resize a window in place. The associated resizeterm() @@ -1325,16 +1307,16 @@ static void finish(int sig) only 8 colors, about a quarter (including XFree86 xterm) support 16 colors.

-

Compatibility with Older - Versions

+

Compatibility with Older + Versions

Despite our best efforts, there are some differences between ncurses and the (undocumented!) behavior of older curses implementations. These arise from ambiguities or omissions in the documentation of the API.

-

Refresh of Overlapping - Windows

+

Refresh of Overlapping + Windows

If you define two windows A and B that overlap, and then alternately scribble on and refresh them, the changes made to the @@ -1392,7 +1374,7 @@ static void finish(int sig) doupdate() and there will be a single burst of physical I/O that will do all your updates.

-

Background Erase

+

Background Erase

If you have been using a very old versions of ncurses (1.8.7 or older) you may be surprised by the @@ -1409,7 +1391,7 @@ static void finish(int sig)

This change in behavior conforms ncurses to System V Release 4 and the XSI Curses standard.

-

XSI Curses Conformance

+

XSI Curses Conformance

The ncurses library is intended to be base-level conformant with the XSI Curses standard from X/Open. Many @@ -1426,7 +1408,7 @@ static void finish(int sig) be linked (and will be prototype-checked) if the macro definition is disabled with #undef.

-

The Panels Library

+

The Panels Library

The ncurses library by itself provides good support for screen displays in which the windows are tiled @@ -1446,16 +1428,15 @@ static void finish(int sig) System V. The version documented here is the panel code distributed with ncurses.

-

Compiling With the Panels - Library

+

Compiling With the Panels + Library

Your panels-using modules must import the panels library declarations with

-
+  
           #include <panel.h>
 
-

and must be linked explicitly with the panels library using an -lpanel argument. Note that they must also link the ncurses library with -lncurses. Many @@ -1463,7 +1444,7 @@ static void finish(int sig) still good practice to put -lpanel first and -lncurses second.

-

Overview of Panels

+

Overview of Panels

A panel object is a window that is implicitly treated as part of a deck including all other panel objects. The deck @@ -1514,8 +1495,8 @@ static void finish(int sig) you will generate a lot of unnecessary refresh activity and screen flicker.

-

Panels, Input, and the - Standard Screen

+

Panels, Input, and the + Standard Screen

You should not mix wnoutrefresh() or wrefresh() operations with panels code; this will @@ -1536,7 +1517,7 @@ static void finish(int sig)

There is presently no way to display changes to one obscured panel without repainting all panels.

-

Hiding Panels

+

Hiding Panels

It is possible to remove a panel from the deck temporarily; use hide_panel for this. Use @@ -1548,7 +1529,7 @@ static void finish(int sig) cannot do top_panel() or bottom_panel on a hidden panel(). Other panels operations are applicable.

-

Miscellaneous Other Facilities

+

Miscellaneous Other Facilities

It is possible to navigate the deck using the functions panel_above() and panel_below. Handed a @@ -1561,7 +1542,7 @@ static void finish(int sig) page documentation of set_panel_userptr() and panel_userptr for details.

-

The Menu Library

+

The Menu Library

A menu is a screen display that assists the user to choose some subset of a given set of items. The menu @@ -1572,16 +1553,15 @@ static void finish(int sig) System V. The version documented here is the menu code distributed with ncurses.

-

Compiling With the menu - Library

+

Compiling With the menu + Library

Your menu-using modules must import the menu library declarations with

-
+  
           #include <menu.h>
 
-

and must be linked explicitly with the menus library using an -lmenu argument. Note that they must also link the ncurses library with -lncurses. Many @@ -1589,7 +1569,7 @@ static void finish(int sig) still good practice to put -lmenu first and -lncurses second.

-

Overview of Menus

+

Overview of Menus

The menus created by this library consist of collections of items including a name string part and a description @@ -1633,7 +1613,7 @@ static void finish(int sig)

  • Terminate curses.
  • -

    Selecting items

    +

    Selecting items

    Menus may be multi-valued or (the default) single-valued (see the manual page menu_opts(3x) to see how to change @@ -1654,7 +1634,7 @@ static void finish(int sig) so far defined for menus, but it is good practice to code as though other option bits might be on.

    -

    Menu Display

    +

    Menu Display

    The menu library calculates a minimum display size for your window, based on the following variables:

    @@ -1710,7 +1690,7 @@ static void finish(int sig) which the library allows you to change (see the menu_attribs(3x) manual page.

    -

    Menu Windows

    +

    Menu Windows

    Each menu has, as mentioned previously, a pair of associated windows. Both these windows are painted when the menu is posted @@ -1732,7 +1712,7 @@ static void finish(int sig) the screen. To do that, call wrefresh() or some equivalent.

    -

    Processing Menu Input

    +

    Processing Menu Input

    The main loop of your menu-processing code should call menu_driver() repeatedly. The first argument of this @@ -1784,7 +1764,7 @@ static void finish(int sig) commands. The menu_driver() code ignores them and returns E_UNKNOWN_COMMAND.

    -

    Miscellaneous Other Features

    +

    Miscellaneous Other Features

    Various menu options can affect the processing and visual appearance and input processing of menus. See menu_opts(3x) @@ -1807,7 +1787,7 @@ static void finish(int sig) mitem_userptr(3x) and menu_userptr(3x).

    -

    The Forms Library

    +

    The Forms Library

    The form library is a curses extension that supports easy programming of on-screen forms for data entry and @@ -1817,16 +1797,15 @@ static void finish(int sig) System V. The version documented here is the form code distributed with ncurses.

    -

    Compiling With the form - Library

    +

    Compiling With the form + Library

    Your form-using modules must import the form library declarations with

    -
    +  
               #include <form.h>
     
    -

    and must be linked explicitly with the forms library using an -lform argument. Note that they must also link the ncurses library with -lncurses. Many @@ -1834,7 +1813,7 @@ static void finish(int sig) still good practice to put -lform first and -lncurses second.

    -

    Overview of Forms

    +

    Overview of Forms

    A form is a collection of fields; each field may be either a label (explanatory text) or a data-entry location. Long forms may @@ -1903,19 +1882,18 @@ static void finish(int sig) Besides menu-like navigation operations, the menu driver loop has to support field editing and data validation.

    -

    Creating and Freeing Fields - and Forms

    +

    Creating and Freeing Fields + and Forms

    The basic function for creating fields is new_field():

    -
    +  
     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 */
     
    -

    Menu items always occupy a single row, but forms fields may have multiple rows. So new_field() requires you to specify a width and height (the first two arguments, which mist @@ -1943,21 +1921,19 @@ FIELD *new_field(int height, int width, /* new field size */ buffers to allocate for the field; your application can use them for its own purposes.

    -
    +  
     FIELD *dup_field(FIELD *field,            /* field to copy */
                      int top, int left);      /* location of new copy */
     
    -

    The function dup_field() duplicates an existing field at a new location. Size and buffering information are copied; some attribute flags and status bits are not (see the form_field_new(3X) for details).

    -
    +  
     FIELD *link_field(FIELD *field,           /* field to copy */
                       int top, int left);     /* location of new copy */
     
    -

    The function link_field() also duplicates an existing field at a new location. The difference from dup_field() is that it arranges for the new field's @@ -1978,10 +1954,9 @@ FIELD *link_field(FIELD *field, /* field to copy */

    To connect fields to a form, use

    -
    +  
     FORM *new_form(FIELD **fields);
     
    -

    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 @@ -1999,8 +1974,8 @@ FORM *new_form(FIELD **fields); form, but not vice-versa; thus, you will generally free your form objects first.

    -

    Fetching and Changing - Field Attributes

    +

    Fetching and Changing + Field Attributes

    Each form field has a number of location and size attributes associated with it. There are other field attributes used to @@ -2016,56 +1991,53 @@ FORM *new_form(FIELD **fields); to it persist as defaults until your forms application terminates.

    -

    Fetching Size and Location - Data

    +

    Fetching Size and Location + Data

    You can retrieve field sizes and locations through:

    -
    +  
     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 */
     
    -

    This function is a sort of inverse of new_field(); instead of setting size and location attributes of a new field, it fetches them from an existing one.

    -

    Changing the Field - Location

    +

    Changing the Field + Location

    It is possible to move a field's location on the screen:

    -
    +  
     int move_field(FIELD *field,              /* field to alter */
                    int top, int left);        /* new upper-left corner */
     
    -

    You can, of course. query the current location through field_info().

    -

    The Justification Attribute

    +

    The Justification Attribute

    One-line fields may be unjustified, justified right, justified left, or centered. Here is how you manipulate this attribute:

    -
    +  
     int set_field_just(FIELD *field,          /* field to alter */
                        int justmode);         /* mode to set */
     
     int field_just(FIELD *field);             /* fetch mode of field */
     
    -

    The mode values accepted and returned by this functions are preprocessor macros NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER.

    -

    Field Display - Attributes

    +

    Field Display + Attributes

    For each field, you can set a foreground attribute for entered characters, a background attribute for the entire field, and a @@ -2076,7 +2048,7 @@ int field_just(FIELD *field); /* fetch mode of field */ appearance of the field on the screen, without affecting in any way the data in the field buffer.

    -
    +  
     int set_field_fore(FIELD *field,          /* field to alter */
                        chtype attr);          /* attribute to set */
     
    @@ -2097,20 +2069,19 @@ int set_new_page(FIELD *field,            /* field to alter */
     
     chtype new_page(FIELD *field);            /* field to query */
     
    -

    The attributes set and returned by the first four functions are normal curses(3x) display attribute values (A_STANDOUT, A_BOLD, A_REVERSE etc). The page bit of a field controls whether it is displayed at the start of a new form screen.

    -

    Field Option Bits

    +

    Field Option Bits

    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:

    -
    +  
     int set_field_opts(FIELD *field,          /* field to alter */
                        int attr);             /* attribute to set */
     
    @@ -2122,7 +2093,6 @@ int field_opts_off(FIELD *field,          /* field to alter */
     
     int field_opts(FIELD *field);             /* field to query */
     
    -

    By default, all options are on. Here are the available option bits:

    @@ -2209,19 +2179,18 @@ int field_opts(FIELD *field); /* field to query */

    The option values are bit-masks and can be composed with logical-or in the obvious way.

    -

    Field Status

    +

    Field Status

    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:

    -
    +  
     int set_field_status(FIELD *field,      /* field to alter */
                        int status);         /* mode to set */
     
     int field_status(FIELD *field);         /* fetch mode of field */
     
    -

    Setting this flag under program control can be useful if you use the same form repeatedly, looking for modified fields each time.

    @@ -2238,14 +2207,14 @@ int field_status(FIELD *field); /* fetch mode of field */ just after a REQ_VALIDATION request has been processed by the forms driver.

    -

    Field User Pointer

    +

    Field User Pointer

    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:

    -
    +  
     int set_field_userptr(FIELD *field,       /* field to alter */
                        char *userptr);        /* mode to set */
     
    @@ -2253,13 +2222,12 @@ char *field_userptr(FIELD *field);        /* fetch mode of field */
     
    (Properly, this user pointer field ought to have (void *) type. The (char *) type is retained for System V compatibility.) -

    It is valid to set the user pointer of the default field (with a set_field_userptr() 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.

    -

    Variable-Sized Fields

    +

    Variable-Sized Fields

    Normally, a field is fixed at the size specified for it at creation time. If, however, you turn off its O_STATIC bit, it @@ -2279,11 +2247,10 @@ System V compatibility.) But it is possible to set an upper limit on the size of a dynamic field. You do it with this function:

    -
    +  
     int set_max_field(FIELD *field,     /* field to alter (may not be NULL) */
                        int max_size);   /* upper limit on field size */
     
    -

    If the field is one-line, max_size 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. @@ -2314,7 +2281,7 @@ int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ size. -

    Field Validation

    +

    Field Validation

    By default, a field will accept any data that will fit in its input buffer. However, it is possible to attach a validation type @@ -2332,14 +2299,13 @@ int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ define custom ones of your own. You can examine and change field validation attributes with the following functions:

    -
    +  
     int set_field_type(FIELD *field,          /* field to alter */
                        FIELDTYPE *ftype,      /* type to associate */
                        ...);                  /* additional arguments*/
     
     FIELDTYPE *field_type(FIELD *field);      /* field to query */
     
    -

    The validation type of a field is considered an attribute of the field. As with other field attributes, Also, doing set_field_type() with a NULL field @@ -2348,56 +2314,53 @@ FIELDTYPE *field_type(FIELD *field); /* field to query */

    Here are the pre-defined validation types:

    -

    TYPE_ALPHA

    +

    TYPE_ALPHA

    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:

    -
    +  
     int set_field_type(FIELD *field,          /* field to alter */
                        TYPE_ALPHA,            /* type to associate */
                        int width);            /* maximum width of field */
     
    -

    The width 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.

    -

    TYPE_ALNUM

    +

    TYPE_ALNUM

    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:

    -
    +  
     int set_field_type(FIELD *field,          /* field to alter */
                        TYPE_ALNUM,            /* type to associate */
                        int width);            /* maximum width of field */
     
    -

    The width 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.

    -

    TYPE_ENUM

    +

    TYPE_ENUM

    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:

    -
    +  
     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? */
     
    -

    The valuelist parameter must point at a NULL-terminated list of valid strings. The checkcase argument, if true, makes comparison with the string @@ -2419,18 +2382,17 @@ int set_field_type(FIELD *field, /* field to alter */ REQ_PREV_CHOICE input requests can be particularly useful with these fields.

    -

    TYPE_INTEGER

    +

    TYPE_INTEGER

    This field type accepts an integer. It is set up as follows:

    -
    +  
     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 */
     
    -

    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 @@ -2443,18 +2405,17 @@ int set_field_type(FIELD *field, /* field to alter */

    A TYPE_INTEGER value buffer can conveniently be interpreted with the C library function atoi(3).

    -

    TYPE_NUMERIC

    +

    TYPE_NUMERIC

    This field type accepts a decimal number. It is set up as follows:

    -
    +  
     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 */
     
    -

    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 @@ -2469,44 +2430,41 @@ int set_field_type(FIELD *field, /* field to alter */

    A TYPE_NUMERIC value buffer can conveniently be interpreted with the C library function atof(3).

    -

    TYPE_REGEXP

    +

    TYPE_REGEXP

    This field type accepts data matching a regular expression. It is set up as follows:

    -
    +  
     int set_field_type(FIELD *field,          /* field to alter */
                        TYPE_REGEXP,           /* type to associate */
                        char *regexp);         /* expression to match */
     
    -

    The syntax for regular expressions is that of regcomp(3). The check for regular-expression match is performed on exit.

    -

    Direct Field Buffer - Manipulation

    +

    Direct Field Buffer + Manipulation

    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:

    -
    +  
     char *field_buffer(FIELD *field,          /* field to query */
                        int bufindex);         /* number of buffer to query */
     
    -

    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:

    -
    +  
     int set_field_buffer(FIELD *field,        /* field to alter */
                        int bufindex,          /* number of buffer to alter */
                        char *value);          /* string value to set */
     
    -

    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.

    @@ -2525,7 +2483,7 @@ int set_field_buffer(FIELD *field, /* field to alter */ REQ_VALIDATION request has been processed by the forms driver.

    -

    Attributes of Forms

    +

    Attributes of Forms

    As with field attributes, form attributes inherit a default from a system default form structure. These defaults can be @@ -2535,7 +2493,7 @@ int set_field_buffer(FIELD *field, /* field to alter */

    The principal attribute of a form is its field list. You can query and change this list with:

    -
    +  
     int set_form_fields(FORM *form,           /* form to alter */
                         FIELD **fields);      /* fields to connect */
     
    @@ -2543,7 +2501,6 @@ char *form_fields(FORM *form);            /* fetch fields of form */
     
     int field_count(FORM *form);              /* count connect fields */
     
    -

    The second argument of set_form_fields() may be a NULL-terminated field pointer array like the one required by new_form(). In that case, the old fields of the form @@ -2557,7 +2514,7 @@ int field_count(FORM *form); /* count connect fields */ number of fields connected to a given from. It returns -1 if the form-pointer argument is NULL.

    -

    Control of Form Display

    +

    Control of Form Display

    In the overview section, you saw that to display a form you normally start by defining its size (and fields), posting it, and @@ -2589,17 +2546,16 @@ int field_count(FORM *form); /* count connect fields */ need to know the size of the form's bounding rectangle. You can get this information with:

    -
    +  
     int scale_form(FORM *form,                /* form to query */
                    int *rows,                 /* form rows */
                    int *cols);                /* form cols */
     
    -

    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:

    -
    +  
     int set_form_win(FORM *form,              /* form to alter */
                      WINDOW *win);            /* frame window to connect */
     
    @@ -2610,7 +2566,6 @@ int set_form_sub(FORM *form,              /* form to alter */
     
     WINDOW *form_sub(FORM *form);             /* fetch form subwindow of form */
     
    -

    Note that curses operations, including refresh(), on the form, should be done on the frame window, not the form subwindow.

    @@ -2619,12 +2574,11 @@ WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ scrollable field is actually displayed within the menu subwindow. Use these functions:

    -
    +  
     int data_ahead(FORM *form);               /* form to be queried */
     
     int data_behind(FORM *form);              /* form to be queried */
     
    -

    The function data_ahead() 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 @@ -2637,27 +2591,25 @@ int data_behind(FORM *form); /* form to be queried */

    Finally, there is a function to restore the form window's cursor to the value expected by the forms driver:

    -
    +  
     int pos_form_cursor(FORM *)               /* form to be queried */
     
    -

    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.

    -

    Input Processing in the Forms - Driver

    +

    Input Processing in the Forms + Driver

    The function form_driver() handles virtualized input requests for form navigation, editing, and validation requests, just as menu_driver does for menus (see the section on menu input handling).

    -
    +  
     int form_driver(FORM *form,               /* form to pass input to */
                     int request);             /* form request code */
     
    -

    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), @@ -2668,7 +2620,7 @@ int form_driver(FORM *form, /* form to pass input to */ check that the input taken by the driver matched what was expected.

    -

    Page Navigation Requests

    +

    Page Navigation Requests

    These requests cause page-level moves through the form, triggering display of a new form screen.

    @@ -2700,8 +2652,8 @@ int form_driver(FORM *form, /* form to pass input to */ and REQ_PREV_PAGE from the first page goes to the last.

    -

    Inter-Field Navigation - Requests

    +

    Inter-Field Navigation + Requests

    These requests handle navigation between fields on the same page.

    @@ -2794,8 +2746,8 @@ int form_driver(FORM *form, /* form to pass input to */ from A will go to B only if A, B, and C all share the same first line; otherwise it will skip over B to C.

    -

    Intra-Field Navigation - Requests

    +

    Intra-Field Navigation + Requests

    These requests drive movement of the edit cursor within the currently selected field.

    @@ -2877,7 +2829,7 @@ int form_driver(FORM *form, /* form to pass input to */ end of line or field look for the first or last non-pad character in their ranges.

    -

    Scrolling Requests

    +

    Scrolling Requests

    Fields that are dynamic and have grown and fields explicitly created with offscreen rows are scrollable. One-line fields @@ -2952,7 +2904,7 @@ int form_driver(FORM *form, /* form to pass input to */

    For scrolling purposes, a page of a field is the height of its visible part.

    -

    Editing Requests

    +

    Editing Requests

    When you pass the forms driver an ASCII character, it is treated as a request to add the character to the field's data @@ -3068,7 +3020,7 @@ int form_driver(FORM *form, /* form to pass input to */

    See Form Options for discussion of how to set and clear the overload options.

    -

    Order Requests

    +

    Order Requests

    If the type of your field is ordered, and has associated functions for getting the next and previous values of the type @@ -3094,7 +3046,7 @@ int form_driver(FORM *form, /* form to pass input to */ field type of your own (see Custom Validation Types), you can associate our own ordering functions.

    -

    Application Commands

    +

    Application Commands

    Form requests are represented as integers above the curses value greater than KEY_MAX and @@ -3102,13 +3054,13 @@ int form_driver(FORM *form, /* form to pass input to */ your input-virtualization routine returns a value above MAX_COMMAND, the forms driver will ignore it.

    -

    Field Change Hooks

    +

    Field Change Hooks

    It is possible to set function hooks to be executed whenever the current field or form changes. Here are the functions that support this:

    -
    +  
     typedef void    (*HOOK)();       /* pointer to function returning void */
     
     int set_form_init(FORM *form,    /* form to alter */
    @@ -3131,7 +3083,6 @@ int set_field_term(FORM *form,   /* form to alter */
     
     HOOK field_term(FORM *form);     /* form to query */
     
    -

    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 @@ -3182,7 +3133,7 @@ HOOK field_term(FORM *form); /* form to query */

    You can disable any of these hooks by (re)setting them to NULL, the default value.

    -

    Field Change Commands

    +

    Field Change Commands

    Normally, navigation through the form will be driven by the user's input requests. But sometimes it is useful to be able to @@ -3190,7 +3141,7 @@ HOOK field_term(FORM *form); /* form to query */ application, or ask which field it currently is in. The following functions help you accomplish this:

    -
    +  
     int set_current_field(FORM *form,         /* form to alter */
                           FIELD *field);      /* field to shift to */
     
    @@ -3199,7 +3150,6 @@ FIELD *current_field(FORM *form);         /* form to query */
     int field_index(FORM *form,               /* form to query */
                     FIELD *field);            /* field to get index of */
     
    -

    The function field_index() returns the index of the given field in the given form's field array (the array passed to new_form() or @@ -3211,22 +3161,21 @@ int field_index(FORM *form, /* form to query */

    It is also possible to move around by pages.

    -
    +  
     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 */
     
    -

    The initial page of a newly-created form is 0. The function set_form_fields() resets this.

    -

    Form Options

    +

    Form Options

    Like fields, forms may have control option bits. They can be changed or queried with these functions:

    -
    +  
     int set_form_opts(FORM *form,             /* form to alter */
                       int attr);              /* attribute to set */
     
    @@ -3238,7 +3187,6 @@ int form_opts_off(FORM *form,             /* form to alter */
     
     int form_opts(FORM *form);                /* form to query */
     
    -

    By default, all options are on. Here are the available option bits:

    @@ -3261,7 +3209,7 @@ int form_opts(FORM *form); /* form to query */

    The option values are bit-masks and can be composed with logical-or in the obvious way.

    -

    Custom Validation Types

    +

    Custom Validation Types

    The form library gives you the capability to define custom validation types of your own. Further, the optional @@ -3271,16 +3219,15 @@ int form_opts(FORM *form); /* form to query */ the handling of the additional arguments within custom validation functions.

    -

    Union Types

    +

    Union Types

    The simplest way to create a custom data type is to compose it from two preexisting ones:

    -
    +  
     FIELD *link_fieldtype(FIELDTYPE *type1,
                           FIELDTYPE *type2);
     
    -

    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 @@ -3292,7 +3239,7 @@ FIELD *link_fieldtype(FIELDTYPE *type1, function for the first type, then for the second, to figure what type the buffer contents should be treated as.

    -

    New Field Types

    +

    New Field Types

    To create a field type from scratch, you need to specify one or both of the following things:

    @@ -3307,7 +3254,7 @@ FIELD *link_fieldtype(FIELDTYPE *type1,

    Here is how you do that:

    -
    +  
     typedef int     (*HOOK)();       /* pointer to function returning int */
     
     FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
    @@ -3315,7 +3262,6 @@ FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */
     
     int free_fieldtype(FIELDTYPE *ftype);     /* type to free */
     
    -

    At least one of the arguments of new_fieldtype() must be non-NULL. The forms driver will automatically call the new type's validation functions at appropriate points in @@ -3334,8 +3280,8 @@ int free_fieldtype(FIELDTYPE *ftype); /* type to free */ argument. It too should return TRUE if the character is valid, FALSE otherwise.

    -

    Validation Function - Arguments

    +

    Validation Function + Arguments

    Your field- and character- validation functions will be passed a second argument as well. This second argument is the address of @@ -3353,7 +3299,7 @@ int free_fieldtype(FIELDTYPE *ftype); /* type to free */

    Here is how you make the association:

    -
    +  
     typedef char    *(*PTRHOOK)();    /* pointer to function returning (char *) */
     typedef void    (*VOIDHOOK)();    /* pointer to function returning void */
     
    @@ -3362,7 +3308,6 @@ int set_fieldtype_arg(FIELDTYPE *type,    /* type to alter */
                           PTRHOOK copy_str,   /* make copy of structure */
                           VOIDHOOK free_str); /* free structure storage */
     
    -

    Here is how the storage-management hooks are used:

    @@ -3398,8 +3343,8 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ this happens. Thus, your validation functions should never see a NULL file pointer and need not check specially for it.

    -

    Order Functions For - Custom Types

    +

    Order Functions For + Custom Types

    Some custom field types are simply ordered in the same well-defined way that TYPE_ENUM is. For such types, @@ -3407,14 +3352,13 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ support the REQ_NEXT_CHOICE and REQ_PREV_CHOICE requests. Here is how:

    -
    +  
     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 */
     
    -

    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 @@ -3424,7 +3368,7 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ (a legal next or previous value was set) or FALSE to indicate failure.

    -

    Avoiding Problems

    +

    Avoiding Problems

    The interface for defining custom types is complicated and tricky. Rather than attempting to create a custom type entirely diff --git a/man/curs_clear.3x b/man/curs_clear.3x index fd307711..36ff2781 100644 --- a/man/curs_clear.3x +++ b/man/curs_clear.3x @@ -27,7 +27,7 @@ .\" 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 @@ -66,24 +66,28 @@ \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 @@ -104,7 +108,7 @@ standard specifies that they return \fBERR\fP on failure, but specifies no 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. diff --git a/man/manhtml.aliases b/man/manhtml.aliases index 9f33e273..1f85bc5c 100644 --- a/man/manhtml.aliases +++ b/man/manhtml.aliases @@ -1,4 +1,4 @@ -# $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. * @@ -30,6 +30,7 @@ # 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) @@ -38,6 +39,7 @@ filter(3X) curs_util(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) @@ -65,6 +67,7 @@ use_env(3X) curs_util(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) diff --git a/package/debian-mingw/changelog b/package/debian-mingw/changelog index fa907341..0aa5c537 100644 --- a/package/debian-mingw/changelog +++ b/package/debian-mingw/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.3+20221119) unstable; urgency=low +ncurses6 (6.3+20221126) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sat, 19 Nov 2022 06:24:10 -0500 + -- Thomas E. Dickey Sat, 26 Nov 2022 06:55:42 -0500 ncurses6 (5.9+20131005) unstable; urgency=low diff --git a/package/debian-mingw64/changelog b/package/debian-mingw64/changelog index fa907341..0aa5c537 100644 --- a/package/debian-mingw64/changelog +++ b/package/debian-mingw64/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.3+20221119) unstable; urgency=low +ncurses6 (6.3+20221126) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sat, 19 Nov 2022 06:24:10 -0500 + -- Thomas E. Dickey Sat, 26 Nov 2022 06:55:42 -0500 ncurses6 (5.9+20131005) unstable; urgency=low diff --git a/package/debian/changelog b/package/debian/changelog index 4dc776a4..592417af 100644 --- a/package/debian/changelog +++ b/package/debian/changelog @@ -1,8 +1,8 @@ -ncurses6 (6.3+20221119) unstable; urgency=low +ncurses6 (6.3+20221126) unstable; urgency=low * latest weekly patch - -- Thomas E. Dickey Sat, 19 Nov 2022 06:24:10 -0500 + -- Thomas E. Dickey Sat, 26 Nov 2022 06:55:42 -0500 ncurses6 (5.9+20120608) unstable; urgency=low diff --git a/package/mingw-ncurses.nsi b/package/mingw-ncurses.nsi index 7187a563..7d2d5ab5 100644 --- a/package/mingw-ncurses.nsi +++ b/package/mingw-ncurses.nsi @@ -1,4 +1,4 @@ -; $Id: mingw-ncurses.nsi,v 1.552 2022/11/19 11:24:10 tom Exp $ +; $Id: mingw-ncurses.nsi,v 1.553 2022/11/26 11:55:42 tom Exp $ ; TODO add examples ; TODO bump ABI to 6 @@ -10,7 +10,7 @@ !define VERSION_MAJOR "6" !define VERSION_MINOR "3" !define VERSION_YYYY "2022" -!define VERSION_MMDD "1119" +!define VERSION_MMDD "1126" !define VERSION_PATCH ${VERSION_YYYY}${VERSION_MMDD} !define MY_ABI "5" diff --git a/package/mingw-ncurses.spec b/package/mingw-ncurses.spec index c57a88f3..628c6137 100644 --- a/package/mingw-ncurses.spec +++ b/package/mingw-ncurses.spec @@ -3,7 +3,7 @@ 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 diff --git a/package/ncurses.spec b/package/ncurses.spec index c75549b6..bc899a5a 100644 --- a/package/ncurses.spec +++ b/package/ncurses.spec @@ -1,7 +1,7 @@ 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 diff --git a/package/ncursest.spec b/package/ncursest.spec index eb11be93..93906589 100644 --- a/package/ncursest.spec +++ b/package/ncursest.spec @@ -1,7 +1,7 @@ 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 diff --git a/test/ncurses.c b/test/ncurses.c index 2aa78b22..b9d1831d 100644 --- a/test/ncurses.c +++ b/test/ncurses.c @@ -41,7 +41,7 @@ AUTHOR Author: Eric S. Raymond 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 $ ***************************************************************************/ @@ -4417,7 +4417,7 @@ x_acs_test(bool recur GCC_UNUSED) 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: diff --git a/test/package/debian-mingw/rules b/test/package/debian-mingw/rules index e61cf71a..152cd3c7 100755 --- a/test/package/debian-mingw/rules +++ b/test/package/debian-mingw/rules @@ -70,7 +70,7 @@ install: install-stamp install-stamp: build-stamp dh_testdir dh_testroot - dh_clean -k + dh_prep dh_installdirs $(MAKE) install DESTDIR=$(MINGW_TMP) diff --git a/test/package/debian-mingw64/rules b/test/package/debian-mingw64/rules index 7db9c5ac..02175a66 100755 --- a/test/package/debian-mingw64/rules +++ b/test/package/debian-mingw64/rules @@ -70,7 +70,7 @@ install: install-stamp install-stamp: build-stamp dh_testdir dh_testroot - dh_clean -k + dh_prep dh_installdirs $(MAKE) install DESTDIR=$(MINGW_TMP) -- 2.45.0

    Revision - History
    Revision 1.92005-06-20Revised by: ppadala
    Revision 1.82005-06-17Revised by: ppadala
    Revision 1.7.12002-06-25Revised by: ppadala
    Revision 1.72002-06-25Revised by: ppadala
    Revision 1.6.12002-02-24Revised by: ppadala
    Revision 1.62002-02-16Revised by: ppadala
    Revision 1.52002-01-05Revised by: ppadala
    Revision 1.3.12001-07-26Revised by: ppadala
    Revision 1.32001-07-24Revised by: ppadala
    Revision 1.22001-06-05Revised by: ppadala
    Revision 1.12001-05-22Revised by: ppadala