ncurses 6.0 - patch 20161217
[ncurses.git] / doc / ncurses-intro.doc
index 3e607e658401daa817bae94086cfcf31e11c50ce..1d72f8087af6fd779552852f18d288d51a30b95a 100644 (file)
@@ -174,7 +174,7 @@ Scope of This Document
    The  ncurses  package  was  originated  by  Pavel Curtis. The original
    maintainer  of  this  package is Zeyd Ben-Halim <zmbenhal@netcom.com>.
    Eric S. Raymond <esr@snark.thyrsus.com> wrote many of the new features
-   in  versions  after  1.8.1 and wrote most of this introduction. Jürgen
+   in  versions  after 1.8.1 and wrote most of this introduction. Juergen
    Pfeifer  wrote  all  of  the  menu and forms code as well as the Ada95
    binding.  Ongoing  work  is  being done by Thomas Dickey (maintainer).
    Contact the current maintainers at bug-ncurses@gnu.org.
@@ -332,6 +332,7 @@ Using the Library
    function names and parameters as mentioned above.
 
    Here is a sample program to motivate the discussion:
+#include <stdlib.h>
 #include <curses.h>
 #include <signal.h>
 
@@ -798,15 +799,9 @@ Hints, Tips, and Tricks
   Using NCURSES under XTERM
 
    A  resize  operation  in  X  sends SIGWINCH to the application running
-   under  xterm.  The  ncurses  library  provides  an experimental signal
-   handler,  but in general does not catch this signal, because it cannot
-   know  how  you  want  the  screen re-painted. You will usually have to
-   write the SIGWINCH handler yourself. Ncurses can give you some help.
-
-   The  easiest  way  to  code  your SIGWINCH handler is to have it do an
-   endwin, followed by an refresh and a screen repaint you code yourself.
-   The  refresh  will  pick  up  the  new  screen  size  from the xterm's
-   environment.
+   under  xterm.  The  easiest way to handle SIGWINCH is to do an endwin,
+   followed  by  an  refresh  and a screen repaint you code yourself. The
+   refresh will pick up the new screen size from the xterm's environment.
 
    That  is the standard way, of course (it even works with some vendor's
    curses  implementations). Its drawback is that it clears the screen to
@@ -816,8 +811,13 @@ Hints, Tips, and Tricks
    limited  to  the new screen dimensions, and pads stdscr with blanks if
    the screen is larger.
 
-   Finally,  ncurses  can  be  configured  to  provide  its  own SIGWINCH
-   handler, based on resizeterm.
+   The ncurses library provides a SIGWINCH signal handler, which pushes a
+   KEY_RESIZE  via the wgetch() calls. When ncurses returns that code, it
+   calls  resizeterm  to update the size of the standard screen's window,
+   repainting that (filling with blanks or truncating as needed). It also
+   resizes other windows, but its effect may be less satisfactory because
+   it  cannot  know  how you want the screen re-painted. You will usually
+   have to write special-purpose code to handle KEY_RESIZE yourself.
 
   Handling Multiple Terminal Screens
 
@@ -889,11 +889,11 @@ Compatibility with Older Versions
    To  understand why this is a problem, remember that screen updates are
    calculated  between  two  representations  of  the entire display. The
    documentation  says that when you refresh a window, it is first copied
-   to  the  virtual screen,  and  then  changes  are calculated to update
-   the  physical screen (and applied to the terminal). But "copied to" is
-   not  very  specific,  and  subtle differences in how copying works can
-   produce  different behaviors in the case where two overlapping windows
-   are each being refreshed at unpredictable intervals.
+   to  the  virtual screen, and then changes are calculated to update the
+   physical  screen (and applied to the terminal). But "copied to" is not
+   very specific, and subtle differences in how copying works can produce
+   different behaviors in the case where two overlapping windows are each
+   being refreshed at unpredictable intervals.
 
    What  happens to the overlapping region depends on what wnoutrefresh()
    does  with  its  argument  --  what portions of the argument window it