ncurses 5.9 - patch 20110404

[ncurses.git] / doc / ncurses-intro.doc

diff --git a/doc/ncurses-intro.doc b/doc/ncurses-intro.doc
index 750777ede0b2a8b3cf4138e702a429e8eab2f60d..85179d1666961b41f7f6e9e540502a804d27e20d 100644 (file)
--- a/doc/ncurses-intro.doc
+++ b/doc/ncurses-intro.doc
@@ -1,4 +1,3 @@
-

                          Writing Programs with NCURSES
 
      by Eric S. Raymond and Zeyd M. Ben-Halim
                          Writing Programs with NCURSES
 
      by Eric S. Raymond and Zeyd M. Ben-Halim


@@ -175,12 +174,10 @@ 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
    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
    Pfeifer  wrote  all  of  the  menu and forms code as well as the Ada95

-   binding.  Ongoing  work  is  being  done  by  Thomas Dickey and Jürgen
-   Pfeifer. Florian La Roche acts as the maintainer for the Free Software
-   Foundation,  which holds the copyright on ncurses. Contact the current
-   maintainers at bug-ncurses@gnu.org.
+   binding.  Ongoing  work  is  being done by Thomas Dickey (maintainer).
+   Contact the current maintainers at bug-ncurses@gnu.org.

 
    This  document  also describes the panels extension library, similarly
    modeled  on  the  SVr4  panels  facility.  This  library allows you to
 
    This  document  also describes the panels extension library, similarly
    modeled  on  the  SVr4  panels  facility.  This  library allows you to


@@ -535,6 +532,7 @@ static void finish(int sig)
      * xterm and similar programs such as rxvt.
      * Linux  console,  when  configured with gpm(1), Alessandro Rubini's
        mouse server.
      * xterm and similar programs such as rxvt.
      * Linux  console,  when  configured with gpm(1), Alessandro Rubini's
        mouse server.

+     * FreeBSD sysmouse (console)

      * OS/2 EMX
 
    The  mouse  interface  is  very  simple.  To  activate it, you use the
      * OS/2 EMX
 
    The  mouse  interface  is  very  simple.  To  activate it, you use the


@@ -610,7 +608,7 @@ Function Descriptions
           refresh()  will  clear the screen. If an error occurs a message
           is  written  to standard error and the program exits. Otherwise
           it  returns  a pointer to stdscr. A few functions may be called
           refresh()  will  clear the screen. If an error occurs a message
           is  written  to standard error and the program exits. Otherwise
           it  returns  a pointer to stdscr. A few functions may be called

-          before initscr (slk_init(), filter(), ripofflines(), use_env(),
+          before  initscr (slk_init(), filter(), ripoffline(), use_env(),

           and, if you are using multiple terminals, newterm().)
 
    endwin()
           and, if you are using multiple terminals, newterm().)
 
    endwin()


@@ -652,10 +650,9 @@ Function Descriptions
           the   terminal,   as  other  routines  merely  manipulate  data
           structures.  wrefresh() copies the named window to the physical
           terminal  screen,  taking into account what is already there in
           the   terminal,   as  other  routines  merely  manipulate  data
           structures.  wrefresh() copies the named window to the physical
           terminal  screen,  taking into account what is already there in

-          order   to  do  optimizations.  refresh()  does  a  refresh  of
-          stdscr().  Unless  leaveok()  has  been  enabled,  the physical
-          cursor  of the terminal is left at the location of the window's
-          cursor.
+          order  to do optimizations. refresh() does a refresh of stdscr.
+          Unless  leaveok()  has been enabled, the physical cursor of the
+          terminal is left at the location of the window's cursor.

 
    doupdate() and wnoutrefresh(win)
           These two functions allow multiple updates with more efficiency
 
    doupdate() and wnoutrefresh(win)
           These two functions allow multiple updates with more efficiency


@@ -801,15 +798,9 @@ Hints, Tips, and Tricks
   Using NCURSES under XTERM
 
    A  resize  operation  in  X  sends SIGWINCH to the application running
   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
 
    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


@@ -819,8 +810,13 @@ Hints, Tips, and Tricks
    limited  to  the new screen dimensions, and pads stdscr with blanks if
    the screen is larger.
 
    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
 
 
   Handling Multiple Terminal Screens
 


@@ -892,11 +888,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  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  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
 
    What  happens to the overlapping region depends on what wnoutrefresh()
    does  with  its  argument  --  what portions of the argument window it


@@ -930,7 +926,7 @@ Compatibility with Older Versions
 
    The  really clean way to handle this is to use the panels library. If,
    when  you want a screen update, you do update_panels(), it will do all
 
    The  really clean way to handle this is to use the panels library. If,
    when  you want a screen update, you do update_panels(), it will do all

-   the  necessary  wnoutrfresh()  calls for whatever panel stacking order
+   the  necessary  wnoutrefresh() calls for whatever panel stacking order

    you  have  defined. Then you can do one doupdate() and there will be a
    single burst of physical I/O that will do all your updates.
 
    you  have  defined. Then you can do one doupdate() and there will be a
    single burst of physical I/O that will do all your updates.
 


@@ -1116,10 +1112,10 @@ Overview of Menus
     1. Initialize curses.
     2. Create the menu items, using new_item().
     3. Create the menu using new_menu().
     1. Initialize curses.
     2. Create the menu items, using new_item().
     3. Create the menu using new_menu().

-    4. Post the menu using menu_post().
+    4. Post the menu using post_menu().

     5. Refresh the screen.
     6. Process user requests via an input loop.
     5. Refresh the screen.
     6. Process user requests via an input loop.

-    7. Unpost the menu using menu_unpost().
+    7. Unpost the menu using unpost_menu().

     8. Free the menu, using free_menu().
     9. Free the items using free_item().
    10. Terminate curses.
     8. Free the menu, using free_menu().
     9. Free the items using free_item().
    10. Terminate curses.


@@ -1199,8 +1195,8 @@ Menu Windows
    By  default,  both  windows  are  stdscr.  You  can  set them with the
    functions in menu_win(3x).
 
    By  default,  both  windows  are  stdscr.  You  can  set them with the
    functions in menu_win(3x).
 

-   When  you  call menu_post(), you write the menu to its subwindow. When
-   you  call  menu_unpost(), you erase the subwindow, However, neither of
+   When  you  call post_menu(), you write the menu to its subwindow. When
+   you  call  unpost_menu(), you erase the subwindow, However, neither of

    these  actually  modifies  the  screen. To do that, call wrefresh() or
    some equivalent.
 
    these  actually  modifies  the  screen. To do that, call wrefresh() or
    some equivalent.
 


@@ -1316,10 +1312,10 @@ Overview of Forms
     1. Initialize curses.
     2. Create the form fields, using new_field().
     3. Create the form using new_form().
     1. Initialize curses.
     2. Create the form fields, using new_field().
     3. Create the form using new_form().

-    4. Post the form using form_post().
+    4. Post the form using post_form().

     5. Refresh the screen.
     6. Process user requests via an input loop.
     5. Refresh the screen.
     6. Process user requests via an input loop.

-    7. Unpost the form using form_unpost().
+    7. Unpost the form using unpost_form().

     8. Free the form, using free_form().
     9. Free the fields using free_field().
    10. Terminate curses.
     8. Free the form, using free_form().
     9. Free the fields using free_field().
    10. Terminate curses.


@@ -1351,7 +1347,7 @@ FIELD *new_field(int height, int width,   /* new field size */
    the  screen  (the  third  and  fourth arguments, which must be zero or
    greater).  Note  that  these  coordinates  are  relative  to  the form
    subwindow,  which will coincide with stdscr by default but need not be
    the  screen  (the  third  and  fourth arguments, which must be zero or
    greater).  Note  that  these  coordinates  are  relative  to  the form
    subwindow,  which will coincide with stdscr by default but need not be

-   stdscr if you've done an explicit set_form_window() call.
+   stdscr if you've done an explicit set_form_win() call.

 
    The  fifth argument allows you to specify a number of off-screen rows.
    If  this  is zero, the entire field will always be displayed. If it is
 
    The  fifth argument allows you to specify a number of off-screen rows.
    If  this  is zero, the entire field will always be displayed. If it is