src - FreeBSD source tree

diff options


context:
space:
mode:

author	Rong-En Fan <rafan@FreeBSD.org>	2008-11-09 09:06:04 +0000
committer	Rong-En Fan <rafan@FreeBSD.org>	2008-11-09 09:06:04 +0000
commit	a388f199193767bacbb38b172ab89cb84369736c (patch)
tree	a1816f5667d2280b970ca44e407bac8cc4496c0a /doc/html
parent	aa59d4d4c5dda7e1c6f9dc0cc6edc58992a525c7 (diff)
download	src-a388f199193767bacbb38b172ab89cb84369736c.tar.gz src-a388f199193767bacbb38b172ab89cb84369736c.zip

- Flatten the vendor area

Notes

Notes: svn path=/vendor/ncurses/dist/; revision=184786

Diffstat (limited to 'doc/html')

-rw-r--r--

doc/html/NCURSES-Programming-HOWTO.html

6413

-rw-r--r--

doc/html/announce.html

600

-rw-r--r--

doc/html/hackguide.html

914

-rw-r--r--

doc/html/ncurses-intro.html

2722

4 files changed, 10649 insertions, 0 deletions

diff --git a/doc/html/NCURSES-Programming-HOWTO.html b/doc/html/NCURSES-Programming-HOWTO.html
new file mode 100644
index 000000000000..3a1010635ff0
--- /dev/null
+++ b/doc/html/NCURSES-Programming-HOWTO.html

@@ -0,0 +1,6413 @@

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

+<html>

+<head>

+<meta name="generator" content=

+"HTML Tidy for Linux/x86 (vers 1st December 2004), see www.w3.org">

+<title>NCURSES Programming HOWTO</title>

+<meta name="GENERATOR" content=

+"Modular DocBook HTML Stylesheet Version 1.7">

+</head>

+<body class="ARTICLE" bgcolor="#FFFFFF" text="#000000" link=

+"#0000FF" vlink="#840084" alink="#0000FF">

+<div class="ARTICLE">

+<div class="TITLEPAGE">

+<h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES Programming

+HOWTO</a></h1>

+<h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep Padala</a></h3>

+<div class="AFFILIATION">

+<div class="ADDRESS">

+<p class="ADDRESS"><code class="EMAIL"><<a href=

+"mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code></p>

+</div>

+<p class="PUBDATE">v1.9, 2005-06-20<br></p>

+<div class="REVHISTORY">

+<table width="100%" border="0">

+<tr>

+<th align="left" valign="top" colspan="3"><b>Revision

+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" colspan="3">The license has been changed to the

+MIT-style license used by NCURSES. Note that the programs are also

+re-licensed under this.</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" colspan="3">Lots of updates. Added references and

+perl examples. Changes to examples. Many grammatical and stylistic

+changes to the content. Changes to NCURSES history.</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" colspan="3">Added a README file for building and

+instructions for building from source.</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" colspan="3">Added "Other formats" section and made

+a lot of fancy changes to the programs. Inlining of programs is

+gone.</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" colspan="3">Removed the old Changelog section,

+cleaned the makefiles</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" colspan="3">Corrected a lot of spelling mistakes,

+added ACS variables section</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" colspan="3">Changed structure to present proper

+TOC</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" colspan="3">Corrected maintainers paragraph,

+Corrected stable release number</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" colspan="3">Added copyright notices to main

+document (LDP license) and programs (GPL), Corrected

+printw_example.</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" colspan="3">Incorporated ravi's changes. Mainly to

+introduction, menu, form, justforfun sections</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>

+<tr>

+<td align="left" colspan="3">Added "a word about window" section,

+Added scanw_example.</td>

+</tr>

+</table>

+</div>

+<div>

+<div class="ABSTRACT"><a name="AEN67" id="AEN67"></a>

+<p><em>This document is intended to be an "All in One" guide for

+programming with ncurses and its sister libraries. We graduate from

+a simple "Hello World" program to more complex form manipulation.

+No prior experience in ncurses is assumed. Send comments to

+<a href="mailto:ppadala@gmail.com" target="_top">this

+address</a></em></p>

+</div>

+<hr></div>

+<div class="TOC">

+<dl>

+<dt><b>Table of Contents</b></dt>

+<dt>1. <a href="#INTRO">Introduction</a></dt>

+<dd>

+<dl>

+<dt>1.1. <a href="#WHATIS">What is NCURSES?</a></dt>

+<dt>1.2. <a href="#WHATCANWEDO">What we can do with

+NCURSES</a></dt>

+<dt>1.3. <a href="#WHERETOGETIT">Where to get it</a></dt>

+<dt>1.4. <a href="#PURPOSE">Purpose/Scope of the document</a></dt>

+<dt>1.5. <a href="#ABOUTPROGRAMS">About the Programs</a></dt>

+<dt>1.6. <a href="#OTHERFORMATS">Other Formats of the

+document</a></dt>

+<dt>1.7. <a href="#CREDITS">Credits</a></dt>

+<dt>1.8. <a href="#WISHLIST">Wish List</a></dt>

+<dt>1.9. <a href="#COPYRIGHT">Copyright</a></dt>

+</dl>

+</dd>

+<dt>2. <a href="#HELLOWORLD">Hello World !!!</a></dt>

+<dd>

+<dl>

+<dt>2.1. <a href="#COMPILECURSES">Compiling With the NCURSES

+Library</a></dt>

+<dt>2.2. <a href="#DISSECTION">Dissection</a></dt>

+</dl>

+</dd>

+<dt>3. <a href="#GORY">The Gory Details</a></dt>

+<dt>4. <a href="#INIT">Initialization</a></dt>

+<dd>

+<dl>

+<dt>4.1. <a href="#ABOUTINIT">Initialization functions</a></dt>

+<dt>4.2. <a href="#RAWCBREAK">raw() and cbreak()</a></dt>

+<dt>4.3. <a href="#ECHONOECHO">echo() and noecho()</a></dt>

+<dt>4.4. <a href="#KEYPAD">keypad()</a></dt>

+<dt>4.5. <a href="#HALFDELAY">halfdelay()</a></dt>

+<dt>4.6. <a href="#MISCINIT">Miscellaneous Initialization

+functions</a></dt>

+<dt>4.7. <a href="#INITEX">An Example</a></dt>

+</dl>

+</dd>

+<dt>5. <a href="#AWORDWINDOWS">A Word about Windows</a></dt>

+<dt>6. <a href="#PRINTW">Output functions</a></dt>

+<dd>

+<dl>

+<dt>6.1. <a href="#ADDCHCLASS">addch() class of functions</a></dt>

+<dt>6.2. <a href="#AEN298">mvaddch(), waddch() and

+mvwaddch()</a></dt>

+<dt>6.3. <a href="#PRINTWCLASS">printw() class of

+functions</a></dt>

+<dt>6.4. <a href="#ADDSTRCLASS">addstr() class of

+functions</a></dt>

+<dt>6.5. <a href="#ACAUTION">A word of caution</a></dt>

+</dl>

+</dd>

+<dt>7. <a href="#SCANW">Input functions</a></dt>

+<dd>

+<dl>

+<dt>7.1. <a href="#GETCHCLASS">getch() class of functions</a></dt>

+<dt>7.2. <a href="#SCANWCLASS">scanw() class of functions</a></dt>

+<dt>7.3. <a href="#GETSTRCLASS">getstr() class of

+functions</a></dt>

+<dt>7.4. <a href="#GETSTREX">Some examples</a></dt>

+</dl>

+</dd>

+<dt>8. <a href="#ATTRIB">Attributes</a></dt>

+<dd>

+<dl>

+<dt>8.1. <a href="#ATTRIBDETAILS">The details</a></dt>

+<dt>8.2. <a href="#ATTRONVSATTRSET">attron() vs attrset()</a></dt>

+<dt>8.3. <a href="#ATTR_GET">attr_get()</a></dt>

+<dt>8.4. <a href="#ATTR_FUNCS">attr_ functions</a></dt>

+<dt>8.5. <a href="#WATTRFUNCS">wattr functions</a></dt>

+<dt>8.6. <a href="#CHGAT">chgat() functions</a></dt>

+</dl>

+</dd>

+<dt>9. <a href="#WINDOWS">Windows</a></dt>

+<dd>

+<dl>

+<dt>9.1. <a href="#WINDOWBASICS">The basics</a></dt>

+<dt>9.2. <a href="#LETBEWINDOW">Let there be a Window !!!</a></dt>

+<dt>9.3. <a href="#BORDEREXEXPL">Explanation</a></dt>

+<dt>9.4. <a href="#OTHERSTUFF">The other stuff in the

+example</a></dt>

+<dt>9.5. <a href="#OTHERBORDERFUNCS">Other Border

+functions</a></dt>

+</dl>

+</dd>

+<dt>10. <a href="#COLOR">Colors</a></dt>

+<dd>

+<dl>

+<dt>10.1. <a href="#COLORBASICS">The basics</a></dt>

+<dt>10.2. <a href="#CHANGECOLORDEFS">Changing Color

+Definitions</a></dt>

+<dt>10.3. <a href="#COLORCONTENT">Color Content</a></dt>

+</dl>

+</dd>

+<dt>11. <a href="#KEYS">Interfacing with the key board</a></dt>

+<dd>

+<dl>

+<dt>11.1. <a href="#KEYSBASICS">The Basics</a></dt>

+<dt>11.2. <a href="#SIMPLEKEYEX">A Simple Key Usage

+example</a></dt>

+</dl>

+</dd>

+<dt>12. <a href="#MOUSE">Interfacing with the mouse</a></dt>

+<dd>

+<dl>

+<dt>12.1. <a href="#MOUSEBASICS">The Basics</a></dt>

+<dt>12.2. <a href="#GETTINGEVENTS">Getting the events</a></dt>

+<dt>12.3. <a href="#MOUSETOGETHER">Putting it all Together</a></dt>

+<dt>12.4. <a href="#MISCMOUSEFUNCS">Miscellaneous

+Functions</a></dt>

+</dl>

+</dd>

+<dt>13. <a href="#SCREEN">Screen Manipulation</a></dt>

+<dd>

+<dl>

+<dt>13.1. <a href="#GETYX">getyx() functions</a></dt>

+<dt>13.2. <a href="#SCREENDUMP">Screen Dumping</a></dt>

+<dt>13.3. <a href="#WINDOWDUMP">Window Dumping</a></dt>

+</dl>

+</dd>

+<dt>14. <a href="#MISC">Miscellaneous features</a></dt>

+<dd>

+<dl>

+<dt>14.1. <a href="#CURSSET">curs_set()</a></dt>

+<dt>14.2. <a href="#TEMPLEAVE">Temporarily Leaving Curses

+mode</a></dt>

+<dt>14.3. <a href="#ACSVARS">ACS_ variables</a></dt>

+</dl>

+</dd>

+<dt>15. <a href="#OTHERLIB">Other libraries</a></dt>

+<dt>16. <a href="#PANELS">Panel Library</a></dt>

+<dd>

+<dl>

+<dt>16.1. <a href="#PANELBASICS">The Basics</a></dt>

+<dt>16.2. <a href="#COMPILEPANELS">Compiling With the Panels

+Library</a></dt>

+<dt>16.3. <a href="#PANELBROWSING">Panel Window Browsing</a></dt>

+<dt>16.4. <a href="#USERPTRUSING">Using User Pointers</a></dt>

+<dt>16.5. <a href="#PANELMOVERESIZE">Moving and Resizing

+Panels</a></dt>

+<dt>16.6. <a href="#PANELSHOWHIDE">Hiding and Showing

+Panels</a></dt>

+<dt>16.7. <a href="#PANELABOVE">panel_above() and panel_below()

+Functions</a></dt>

+</dl>

+</dd>

+<dt>17. <a href="#MENUS">Menus Library</a></dt>

+<dd>

+<dl>

+<dt>17.1. <a href="#MENUBASICS">The Basics</a></dt>

+<dt>17.2. <a href="#COMPILEMENUS">Compiling With the Menu

+Library</a></dt>

+<dt>17.3. <a href="#MENUDRIVER">Menu Driver: The work horse of the

+menu system</a></dt>

+<dt>17.4. <a href="#MENUWINDOWS">Menu Windows</a></dt>

+<dt>17.5. <a href="#SCROLLMENUS">Scrolling Menus</a></dt>

+<dt>17.6. <a href="#MULTICOLUMN">Multi Columnar Menus</a></dt>

+<dt>17.7. <a href="#MULTIVALUEMENUS">Multi Valued Menus</a></dt>

+<dt>17.8. <a href="#MENUOPT">Menu Options</a></dt>

+<dt>17.9. <a href="#MENUUSERPTR">The useful User Pointer</a></dt>

+</dl>

+</dd>

+<dt>18. <a href="#FORMS">Forms Library</a></dt>

+<dd>

+<dl>

+<dt>18.1. <a href="#FORMBASICS">The Basics</a></dt>

+<dt>18.2. <a href="#COMPILEFORMS">Compiling With the Forms

+Library</a></dt>

+<dt>18.3. <a href="#PLAYFIELDS">Playing with Fields</a></dt>

+<dt>18.4. <a href="#FORMWINDOWS">Form Windows</a></dt>

+<dt>18.5. <a href="#FILEDVALIDATE">Field Validation</a></dt>

+<dt>18.6. <a href="#FORMDRIVER">Form Driver: The work horse of the

+forms system</a></dt>

+</dl>

+</dd>

+<dt>19. <a href="#TOOLS">Tools and Widget Libraries</a></dt>

+<dd>

+<dl>

+<dt>19.1. <a href="#CDK">CDK (Curses Development Kit)</a></dt>

+<dt>19.2. <a href="#DIALOG">The dialog</a></dt>

+<dt>19.3. <a href="#PERLCURSES">Perl Curses Modules CURSES::FORM

+and CURSES::WIDGETS</a></dt>

+</dl>

+</dd>

+<dt>20. <a href="#JUSTFORFUN">Just For Fun !!!</a></dt>

+<dd>

+<dl>

+<dt>20.1. <a href="#GAMEOFLIFE">The Game of Life</a></dt>

+<dt>20.2. <a href="#MAGIC">Magic Square</a></dt>

+<dt>20.3. <a href="#HANOI">Towers of Hanoi</a></dt>

+<dt>20.4. <a href="#QUEENS">Queens Puzzle</a></dt>

+<dt>20.5. <a href="#SHUFFLE">Shuffle</a></dt>

+<dt>20.6. <a href="#TT">Typing Tutor</a></dt>

+</dl>

+</dd>

+<dt>21. <a href="#REF">References</a></dt>

+</dl>

+</div>

+<div class="SECT1">

+<h2 class="SECT1"><a name="INTRO" id="INTRO">1.

+Introduction</a></h2>

+<p>In the olden days of teletype terminals, terminals were away

+from computers and were connected to them through serial cables.

+The terminals could be configured by sending a series of bytes. All

+the capabilities (such as moving the cursor to a new location,

+erasing part of the screen, scrolling the screen, changing modes

+etc.) of terminals could be accessed through these series of bytes.

+These control seeuqnces are usually called escape sequences,

+because they start with an escape(0x1B) character. Even today, with

+proper emulation, we can send escape sequences to the emulator and

+achieve the same effect on a terminal window.</p>

+<p>Suppose you wanted to print a line in color. Try typing this on

+your console.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">echo "^[[0;31;40mIn Color"</font>

+</pre></td>

+</tr>

+</table>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">echo "^[[0;37;40m"</font>

+</pre></td>

+</tr>

+</table>

+<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 named <var class=

+"LITERAL">termcap</var>. It is a file that lists all the

+capabilities of a particular terminal, along with the escape

+sequences needed to achieve a particular effect. In the later

+years, this was replaced by <var class="LITERAL">terminfo</var>.

+Without delving too much into details, this mechanism allows

+application programs to query the terminfo database and obtain the

+control characters to be sent to a terminal or terminal

+emulator.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WHATIS" id="WHATIS">1.1. What is

+NCURSES?</a></h3>

+<p>You might be wondering, what the import of all this technical

+gibberish is. In the above scenario, every application program is

+supposed to query the terminfo and perform the necessary stuff

+(sending control characters etc.). It soon became difficult to

+manage this complexity and this gave birth to 'CURSES'. Curses is a

+pun on the name "cursor optimization". The Curses library forms a

+wrapper over working with raw terminal codes, and provides highly

+flexible and efficient API (Application Programming Interface). It

+provides functions to move the cursor, create windows, produce

+colors, play with mouse etc. The application programs need not

+worry about the underlying terminal capabilities.</p>

+<p>So what is NCURSES? NCURSES is a clone of the original System V

+Release 4.0 (SVr4) curses. It is a freely distributable library,

+fully compatible with older version of curses. In short, it is a

+library of functions that manages an application's display on

+character-cell terminals. In the remainder of the document, the

+terms curses and ncurses are used interchangeably.</p>

+<p>A detailed history of NCURSES can be found in the NEWS file from

+the source distribution. The current package is maintained by

+<a href="mailto:dickey@his.com" target="_top">Thomas Dickey</a>.

+You can contact the maintainers at <a href=

+"mailto:bug-ncurses@gnu.org" target=

+"_top">bug-ncurses@gnu.org</a>.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WHATCANWEDO" id="WHATCANWEDO">1.2. What

+we can do with NCURSES</a></h3>

+<p>NCURSES not only creates a wrapper over terminal capabilities,

+but also gives a robust framework to create nice looking UI (User

+Interface)s in text mode. It provides functions to create windows

+etc. Its sister libraries panel, menu and form provide an extension

+to the basic curses library. These libraries usually come along

+with curses. One can create applications that contain multiple

+windows, menus, panels and forms. Windows can be managed

+independently, can provide 'scrollability' and even can be

+hidden.</p>

+<p>Menus provide the user with an easy command selection option.

+Forms allow the creation of easy-to-use data entry and display

+windows. Panels extend the capabilities of ncurses to deal with

+overlapping and stacked windows.</p>

+<p>These are just some of the basic things we can do with ncurses.

+As we move along, We will see all the capabilities of these

+libraries.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WHERETOGETIT" id="WHERETOGETIT">1.3.

+Where to get it</a></h3>

+<p>All right, now that you know what you can do with ncurses, you

+must be rearing to get started. NCURSES is usually shipped with

+your installation. In case you don't have the library or want to

+compile it on your own, read on.</p>

+<p><em>Compiling the package</em></p>

+<p>NCURSES can be obtained from <a href=

+"ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz" target=

+"_top">ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz</a> or any

+of the ftp sites mentioned in <a href=

+"http://www.gnu.org/order/ftp.html" target=

+"_top">http://www.gnu.org/order/ftp.html</a>.</p>

+<p>Read the README and INSTALL files for details on to how to

+install it. It usually involves the following operations.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> tar zxvf ncurses<version>.tar.gz # unzip and untar the archive

+ cd ncurses<version> # cd to the directory

+ ./configure # configure the build according to your

+ # environment

+ make # make it

+ su root # become root

+ make install # install it</font>

+</pre></td>

+</tr>

+</table>

+<p><em>Using the RPM</em></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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> rpm -i <downloaded rpm></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PURPOSE" id="PURPOSE">1.4. Purpose/Scope

+of the document</a></h3>

+<p>This document is intended to be a "All in One" guide for

+programming with ncurses and its sister libraries. We graduate from

+a simple "Hello World" program to more complex form manipulation.

+No prior experience in ncurses is assumed. The writing is informal,

+but a lot of detail is provided for each of the examples.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ABOUTPROGRAMS" id="ABOUTPROGRAMS">1.5.

+About the Programs</a></h3>

+<p>All the programs in the document are available in zipped form

+<a href=

+"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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">ncurses

+ |

+ |----> JustForFun -- just for fun programs

+ |----> basics -- basic programs

+ |----> demo -- output files go into this directory after make

+ | |

+ | |----> exe -- exe files of all example programs

+ |----> forms -- programs related to form library

+ |----> menus -- programs related to menus library

+ |----> panels -- programs related to panels library

+ |----> perl -- perl equivalents of the examples (contributed

+ | by Anuradha Ratnaweera)

+ |----> Makefile -- the top level Makefile

+ |----> README -- the top level README file. contains instructions

+ |----> COPYING -- copyright notice</font>

+</pre></td>

+</tr>

+</table>

+<p>The individual directories contain the following files.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">Description of files in each directory

+--------------------------------------

+JustForFun

+ |

+ |----> hanoi.c -- The Towers of Hanoi Solver

+ |----> life.c -- The Game of Life demo

+ |----> magic.c -- An Odd Order Magic Square builder

+ |----> queens.c -- The famous N-Queens Solver

+ |----> shuffle.c -- A fun game, if you have time to kill

+ |----> tt.c -- A very trivial typing tutor

+ basics

+ |

+ |----> acs_vars.c -- ACS_ variables example

+ |----> hello_world.c -- Simple "Hello World" Program

+ |----> init_func_example.c -- Initialization functions example

+ |----> key_code.c -- Shows the scan code of the key pressed

+ |----> mouse_menu.c -- A menu accessible by mouse

+ |----> other_border.c -- Shows usage of other border functions apa

+ | -- rt from box()

+ |----> printw_example.c -- A very simple printw() example

+ |----> scanw_example.c -- A very simple getstr() example

+ |----> simple_attr.c -- A program that can print a c file with

+ | -- comments in attribute

+ |----> simple_color.c -- A simple example demonstrating colors

+ |----> simple_key.c -- A menu accessible with keyboard UP, DOWN

+ | -- arrows

+ |----> temp_leave.c -- Demonstrates temporarily leaving curses mode

+ |----> win_border.c -- Shows Creation of windows and borders

+ |----> with_chgat.c -- chgat() usage example

+ forms

+ |

+ |----> form_attrib.c -- Usage of field attributes

+ |----> form_options.c -- Usage of field options

+ |----> form_simple.c -- A simple form example

+ |----> form_win.c -- Demo of windows associated with forms

+ menus

+ |

+ |----> menu_attrib.c -- Usage of menu attributes

+ |----> menu_item_data.c -- Usage of item_name() etc.. functions

+ |----> menu_multi_column.c -- Creates multi columnar menus

+ |----> menu_scroll.c -- Demonstrates scrolling capability of menus

+ |----> menu_simple.c -- A simple menu accessed by arrow keys

+ |----> menu_toggle.c -- Creates multi valued menus and explains

+ | -- REQ_TOGGLE_ITEM

+ |----> menu_userptr.c -- Usage of user pointer

+ |----> menu_win.c -- Demo of windows associated with menus

+ panels

+ |

+ |----> panel_browse.c -- Panel browsing through tab. Usage of user

+ | -- pointer

+ |----> panel_hide.c -- Hiding and Un hiding of panels

+ |----> panel_resize.c -- Moving and resizing of panels

+ |----> panel_simple.c -- A simple panel example

+ perl

+ |----> 01-10.pl -- Perl equivalents of first ten example programs</font>

+</pre></td>

+</tr>

+</table>

+<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 selective make by going into the

+corresponding directory. Each directory contains a README file

+explaining the purpose of each c file in the directory.</p>

+<p>For every example, I have included path name for the file

+relative to the examples directory.</p>

+<p>If you prefer browsing individual programs, point your browser

+to <a href=

+"http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/"

+target=

+"_top">http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/</a></p>

+<p>All the programs are released under the same license that is

+used by ncurses (MIT-style). This gives you the ability to do

+pretty much anything other than claiming them as yours. Feel free

+to use them in your programs as appropriate.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="OTHERFORMATS" id="OTHERFORMATS">1.6.

+Other Formats of the document</a></h3>

+<p>This howto is also availabe in various other formats on the

+tldp.org site. Here are the links to other formats of this

+document.</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="LISTFORMATS" id="LISTFORMATS">1.6.1.

+Readily available formats from tldp.org</a></h4>

+<ul>

+<li>

+<p><a href=

+"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf"

+target="_top">Acrobat PDF Format</a></p>

+</li>

+<li>

+<p><a href=

+"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz"

+target="_top">PostScript Format</a></p>

+</li>

+<li>

+<p><a href=

+"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz"

+target="_top">In Multiple HTML pages</a></p>

+</li>

+<li>

+<p><a href=

+"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html"

+target="_top">In One big HTML format</a></p>

+</li>

+</ul>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="BUILDSOURCE" id="BUILDSOURCE">1.6.2.

+Building from source</a></h4>

+<p>If above links are broken or if you want to experiment with sgml

+read on.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> Get both the source and the tar,gzipped programs, available at

+ http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/

+ NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml

+ http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/

+ NCURSES-HOWTO/ncurses_programs.tar.gz

+ Unzip ncurses_programs.tar.gz with

+ tar zxvf ncurses_programs.tar.gz

+ Use jade to create various formats. For example if you just want to create

+ the multiple html files, you would use

+ jade -t sgml -i html -d <path to docbook html stylesheet>

+ NCURSES-Programming-HOWTO.sgml

+ to get pdf, first create a single html file of the HOWTO with

+ jade -t sgml -i html -d <path to docbook html stylesheet> -V nochunks

+ NCURSES-Programming-HOWTO.sgml > NCURSES-ONE-BIG-FILE.html

+ then use htmldoc to get pdf file with

+ htmldoc --size universal -t pdf --firstpage p1 -f <output file name.pdf>

+ NCURSES-ONE-BIG-FILE.html

+ for ps, you would use

+ htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps>

+ NCURSES-ONE-BIG-FILE.html</font>

+</pre></td>

+</tr>

+</table>

+<p>See <a href="http://www.tldp.org/LDP/LDP-Author-Guide/" target=

+"_top">LDP Author guide</a> for more details. If all else failes,

+mail me at <a href="ppadala@gmail.com" target=

+"_top">ppadala@gmail.com</a></p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="CREDITS" id="CREDITS">1.7.

+Credits</a></h3>

+<p>I thank <a href="mailto:sharath_1@usa.net" target=

+"_top">Sharath</a> and Emre Akbas for helping me with few sections.

+The introduction was initially written by sharath. I rewrote it

+with few excerpts taken from his initial work. Emre helped in

+writing printw and scanw sections.</p>

+<p>Perl equivalents of the example programs are contributed by

+<a href="mailto:Aratnaweera@virtusa.com" target="_top">Anuradha

+Ratnaweera</a>.</p>

+<p>Then comes <a href="mailto:parimi@ece.arizona.edu" target=

+"_top">Ravi Parimi</a>, my dearest friend, who has been on this

+project before even one line was written. He constantly bombarded

+me with suggestions and patiently reviewed the whole text. He also

+checked each program on Linux and Solaris.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WISHLIST" id="WISHLIST">1.8. Wish

+List</a></h3>

+<p>This is the wish list, in the order of priority. If you have a

+wish or you want to work on completing the wish, mail <a href=

+"mailto:ppadala@gmail.com" target="_top">me</a>.</p>

+<ul>

+<li>

+<p>Add examples to last parts of forms section.</p>

+</li>

+<li>

+<p>Prepare a Demo showing all the programs and allow the user to

+browse through description of each program. Let the user compile

+and see the program in action. A dialog based interface is

+preferred.</p>

+</li>

+<li>

+<p>Add debug info. _tracef, _tracemouse stuff.</p>

+</li>

+<li>

+<p>Accessing termcap, terminfo using functions provided by ncurses

+package.</p>

+</li>

+<li>

+<p>Working on two terminals simultaneously.</p>

+</li>

+<li>

+<p>Add more stuff to miscellaneous section.</p>

+</li>

+</ul>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="COPYRIGHT" id="COPYRIGHT">1.9.

+Copyright</a></h3>

+<p>Permission is hereby granted, free of charge, to any person

+obtaining a copy of this software and associated documentation

+files (the "Software"), to deal in the Software without

+restriction, including without limitation the rights to use, copy,

+modify, merge, publish, distribute, distribute with modifications,

+sublicense, and/or sell copies of the Software, and to permit

+persons to whom the Software is furnished to do so, subject to the

+following conditions:</p>

+<p>The above copyright notice and this permission notice shall be

+included in all copies or substantial portions of the Software.</p>

+<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

+NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE

+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN

+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

+SOFTWARE.</p>

+<p>Except as contained in this notice, the name(s) of the above

+copyright holders shall not be used in advertising or otherwise to

+promote the sale, use or other dealings in this Software without

+prior written authorization.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="HELLOWORLD" id="HELLOWORLD">2. Hello

+World !!!</a></h2>

+<p>Welcome to the world of curses. Before we plunge into the

+library and look into its various features, let's write a simple

+program and say hello to the world.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="COMPILECURSES" id="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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> #include <ncurses.h>

+ .

+ compile and link: gcc <program file> -lncurses</font>

+</pre></td>

+</tr>

+</table>

+<div class="EXAMPLE"><a name="BHW" id="BHW"></a>

+<p><b>Example 1. The Hello World !!! Program</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+int main()

+ initscr(); /* Start curses mode */

+ printw("Hello World !!!"); /* Print Hello World */

+ refresh(); /* Print it on to the real screen */

+ getch(); /* Wait for user input */

+ endwin(); /* End curses mode */

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="DISSECTION" id="DISSECTION">2.2.

+Dissection</a></h3>

+<p>The above program prints "Hello World !!!" to the screen and

+exits. This program shows how to initialize curses and do screen

+manipulation and end curses mode. Let's dissect it line by

+line.</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="ABOUT-INITSCR" id="ABOUT-INITSCR">2.2.1.

+About initscr()</a></h4>

+<p>The function initscr() initializes the terminal in curses mode.

+In some implementations, it clears the screen and presents a blank

+screen. To do any screen manipulation using curses package this has

+to be called first. This function initializes the curses system and

+allocates memory for our present window (called <var class=

+"LITERAL">stdscr</var>) and some other data-structures. Under

+extreme cases this function might fail due to insufficient memory

+to allocate memory for curses library's data structures.</p>

+<p>After this is done, we can do a variety of initializations to

+customize our curses settings. These details will be explained

+<a href="#INIT">later</a> .</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="MYST-REFRESH" id="MYST-REFRESH">2.2.2.

+The mysterious refresh()</a></h4>

+<p>The next line printw prints the string "Hello World !!!" on to

+the screen. This function is analogous to normal printf in all

+respects except that it prints the data on a window called stdscr

+at the current (y,x) co-ordinates. Since our present co-ordinates

+are at 0,0 the string is printed at the left hand corner of the

+window.</p>

+<p>This brings us to that mysterious refresh(). Well, when we

+called printw the data is actually written to an imaginary window,

+which is not updated on the screen yet. The job of printw is to

+update a few flags and data structures and write the data to a

+buffer corresponding to stdscr. In order to show it on the screen,

+we need to call refresh() and tell the curses system to dump the

+contents on the screen.</p>

+<p>The philosophy behind all this is to allow the programmer to do

+multiple updates on the imaginary screen or windows and do a

+refresh once all his screen update is done. refresh() checks the

+window and updates only the portion which has been changed. This

+improves performance and offers greater flexibility too. But, it is

+sometimes frustrating to beginners. A common mistake committed by

+beginners is to forget to call refresh() after they did some update

+through printw() class of functions. I still forget to add it

+sometimes :-)</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="ABOUT-ENDWIN" id="ABOUT-ENDWIN">2.2.3.

+About endwin()</a></h4>

+<p>And finally don't forget to end the curses mode. Otherwise your

+terminal might behave strangely after the program quits. endwin()

+frees the memory taken by curses sub-system and its data structures

+and puts the terminal in normal mode. This function must be called

+after you are done with the curses mode.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="GORY" id="GORY">3. The Gory

+Details</a></h2>

+<p>Now that we have seen how to write a simple curses program let's

+get into the details. There are many functions that help customize

+what you see on screen and many features which can be put to full

+use.</p>

+<p>Here we go...</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="INIT" id="INIT">4.

+Initialization</a></h2>

+<p>We now know that to initialize curses system the function

+initscr() has to be called. There are functions which can be called

+after this initialization to customize our curses session. We may

+ask the curses system to set the terminal in raw mode or initialize

+color or initialize the mouse etc.. Let's discuss some of the

+functions that are normally called immediately after initscr();</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ABOUTINIT" id="ABOUTINIT">4.1.

+Initialization functions</a></h3>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="RAWCBREAK" id="RAWCBREAK">4.2. raw() and

+cbreak()</a></h3>

+<p>Normally the terminal driver buffers the characters a user types

+until a new line or carriage return is encountered. But most

+programs require that the characters be available as soon as the

+user types them. The above two functions are used to disable line

+buffering. The difference between these two functions is in the way

+control characters like suspend (CTRL-Z), interrupt and quit

+(CTRL-C) are passed to the program. In the raw() mode these

+characters are directly passed to the program without generating a

+signal. In the <var class="LITERAL">cbreak()</var> mode these

+control characters are interpreted as any other character by the

+terminal driver. I personally prefer to use raw() as I can exercise

+greater control over what the user does.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ECHONOECHO" id="ECHONOECHO">4.3. echo()

+and noecho()</a></h3>

+<p>These functions control the echoing of characters typed by the

+user to the terminal. <var class="LITERAL">noecho()</var> switches

+off echoing. The reason you might want to do this is to gain more

+control over echoing or to suppress unnecessary echoing while

+taking input from the user through the getch() etc. functions. Most

+of the interactive programs call <var class=

+"LITERAL">noecho()</var> at initialization and do the echoing of

+characters in a controlled manner. It gives the programmer the

+flexibility of echoing characters at any place in the window

+without updating current (y,x) co-ordinates.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="KEYPAD" id="KEYPAD">4.4.

+keypad()</a></h3>

+<p>This is my favorite initialization function. It enables the

+reading of function keys like F1, F2, arrow keys etc. Almost every

+interactive program enables this, as arrow keys are a major part of

+any User Interface. Do <var class="LITERAL">keypad(stdscr,

+TRUE)</var> to enable this feature for the regular screen (stdscr).

+You will learn more about key management in later sections of this

+document.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="HALFDELAY" id="HALFDELAY">4.5.

+halfdelay()</a></h3>

+<p>This function, though not used very often, is a useful one at

+times. halfdelay()is called to enable the half-delay mode, which is

+similar to the cbreak() mode in that characters typed are

+immediately available to program. However, it waits for 'X' tenths

+of a second for input and then returns ERR, if no input is

+available. 'X' is the timeout value passed to the function

+halfdelay(). This function is useful when you want to ask the user

+for input, and if he doesn't respond with in certain time, we can

+do some thing else. One possible example is a timeout at the

+password prompt.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MISCINIT" id="MISCINIT">4.6.

+Miscellaneous Initialization functions</a></h3>

+<p>There are few more functions which are called at initialization

+to customize curses behavior. They are not used as extensively as

+those mentioned above. Some of them are explained where

+appropriate.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="INITEX" id="INITEX">4.7. An

+Example</a></h3>

+<p>Let's write a program which will clarify the usage of these

+functions.</p>

+<div class="EXAMPLE"><a name="BINFU" id="BINFU"></a>

+<p><b>Example 2. Initialization Function Usage example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+int main()

+{ int ch;

+ initscr(); /* Start curses mode */

+ raw(); /* Line buffering disabled */

+ keypad(stdscr, TRUE); /* We get F1, F2 etc.. */

+ noecho(); /* Don't echo() while we do getch */

+ printw("Type any character to see it in bold\n");

+ ch = getch(); /* If raw() hadn't been called

+ * we have to press enter before it

+ * gets to the program */

+ if(ch == KEY_F(1)) /* Without keypad enabled this will */

+ printw("F1 Key pressed");/* not get to us either */

+ /* Without noecho() some ugly escape

+ * charachters might have been printed

+ * on screen */

+ else

+ { printw("The pressed key is ");

+ attron(A_BOLD);

+ printw("%c", ch);

+ attroff(A_BOLD);

+ }

+ refresh(); /* Print it on to the real screen */

+ getch(); /* Wait for user input */

+ endwin(); /* End curses mode */

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>This program is self-explanatory. But I used functions which

+aren't explained yet. The function <var class=

+"LITERAL">getch()</var> is used to get a character from user. It is

+equivalent to normal <var class="LITERAL">getchar()</var> except

+that we can disable the line buffering to avoid <enter> after

+input. Look for more about <var class="LITERAL">getch()</var>and

+reading keys in the <a href="#KEYS">key management section</a> .

+The functions attron and attroff are used to switch some attributes

+on and off respectively. In the example I used them to print the

+character in bold. These functions are explained in detail

+later.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="AWORDWINDOWS" id="AWORDWINDOWS">5. A

+Word about Windows</a></h2>

+<p>Before we plunge into the myriad ncurses functions, let me clear

+few things about windows. Windows are explained in detail in

+following <a href="#WINDOWS">sections</a></p>

+<p>A Window is an imaginary screen defined by curses system. A

+window does not mean a bordered window which you usually see on

+Win9X platforms. When curses is initialized, it creates a default

+window named <var class="LITERAL">stdscr</var> which represents

+your 80x25 (or the size of window in which you are running) screen.

+If you are doing simple tasks like printing few strings, reading

+input etc., you can safely use this single window for all of your

+purposes. You can also create windows and call functions which

+explicitly work on the specified window.</p>

+<p>For example, if you call</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> printw("Hi There !!!");

+ refresh();</font>

+</pre></td>

+</tr>

+</table>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> wprintw(win, "Hi There !!!");

+ wrefresh(win);</font>

+</pre></td>

+</tr>

+</table>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> printw(string); /* Print on stdscr at present cursor position */

+ mvprintw(y, x, string);/* Move to (y, x) then print string */

+ wprintw(win, string); /* Print on window win at present cursor position */

+ /* in the window */

+ mvwprintw(win, y, x, string); /* Move to (y, x) relative to window */

+ /* co-ordinates and then print */</font>

+</pre></td>

+</tr>

+</table>

+<p>Usually the w-less functions are macros which expand to

+corresponding w-function with stdscr as the window parameter.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="PRINTW" id="PRINTW">6. Output

+functions</a></h2>

+<p>I guess you can't wait any more to see some action. Back to our

+odyssey of curses functions. Now that curses is initialized, let's

+interact with world.</p>

+<p>There are three classes of functions which you can use to do

+output on screen.</p>

+<ol type="1">

+<li>

+<p>addch() class: Print single character with attributes</p>

+</li>

+<li>

+<p>printw() class: Print formatted output similar to printf()</p>

+</li>

+<li>

+<p>addstr() class: Print strings</p>

+</li>

+</ol>

+<p>These functions can be used interchangeably and it's a matter of

+style as to which class is used. Let's see each one in detail.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ADDCHCLASS" id="ADDCHCLASS">6.1. addch()

+class of functions</a></h3>

+<p>These functions put a single character into the current cursor

+location and advance the position of the cursor. You can give the

+character to be printed but they usually are used to print a

+character with some attributes. Attributes are explained in detail

+in later <a href="#ATTRIB">sections</a> of the document. If a

+character is associated with an attribute(bold, reverse video

+etc.), when curses prints the character, it is printed in that

+attribute.</p>

+<p>In order to combine a character with some attributes, you have

+two options:</p>

+<ul>

+<li>

+<p>By OR'ing a single character with the desired attribute macros.

+These attribute macros could be found in the header file

+<var class="LITERAL">ncurses.h</var>. For example, you want to

+print a character ch(of type char) bold and underlined, you would

+call addch() as below.</p>

+<table border="0" bgcolor="#E0E0E0" width="90%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> addch(ch | A_BOLD | A_UNDERLINE);</font>

+</pre></td>

+</tr>

+</table>

+</li>

+<li>

+<p>By using functions like <var class=

+"LITERAL">attrset(),attron(),attroff()</var>. These functions are

+explained in the <a href="#ATTRIB">Attributes</a> section. Briefly,

+they manipulate the current attributes of the given window. Once

+set, the character printed in the window are associated with the

+attributes until it is turned off.</p>

+</li>

+</ul>

+<p>Additionally, <var class="LITERAL">curses</var> provides some

+special characters for character-based graphics. You can draw

+tables, horizontal or vertical lines, etc. You can find all

+avaliable characters in the header file <var class=

+"LITERAL">ncurses.h</var>. Try looking for macros beginning with

+<var class="LITERAL">ACS_</var> in this file.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="AEN298" id="AEN298">6.2. mvaddch(),

+waddch() and mvwaddch()</a></h3>

+<p><var class="LITERAL">mvaddch()</var> is used to move the cursor

+to a given point, and then print. Thus, the calls:</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> move(row,col); /* moves the cursor to row<em>th</em> row and col<em>th</em> column */

+ addch(ch);</font>

+</pre></td>

+</tr>

+</table>

+can be replaced by

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> mvaddch(row,col,ch);</font>

+</pre></td>

+</tr>

+</table>

+<p><var class="LITERAL">waddch()</var> is similar to <var class=

+"LITERAL">addch()</var>, except that it adds a character into the

+given window. (Note that <var class="LITERAL">addch()</var> adds a

+character into the window <var class="LITERAL">stdscr</var>.)</p>

+<p>In a similar fashion <var class="LITERAL">mvwaddch()</var>

+function is used to add a character into the given window at the

+given coordinates.</p>

+<p>Now, we are familiar with the basic output function <var class=

+"LITERAL">addch()</var>. But, if we want to print a string, it

+would be very annoying to print it character by character.

+Fortunately, <var class="LITERAL">ncurses</var> provides

+<var class="LITERAL">printf</var><em>-like</em> or <var class=

+"LITERAL">puts</var><em>-like</em> functions.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PRINTWCLASS" id="PRINTWCLASS">6.3.

+printw() class of functions</a></h3>

+<p>These functions are similar to <var class=

+"LITERAL">printf()</var> with the added capability of printing at

+any position on the screen.</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="PRINTWMVPRINTW" id=

+"PRINTWMVPRINTW">6.3.1. printw() and mvprintw</a></h4>

+<p>These two functions work much like <var class=

+"LITERAL">printf()</var>. <var class="LITERAL">mvprintw()</var> can

+be used to move the cursor to a position and then print. If you

+want to move the cursor first and then print using <var class=

+"LITERAL">printw()</var> function, use <var class=

+"LITERAL">move()</var> first and then use <var class=

+"LITERAL">printw()</var> though I see no point why one should avoid

+using <var class="LITERAL">mvprintw()</var>, you have the

+flexibility to manipulate.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="WPRINTWMVWPRINTW" id=

+"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 argument.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="VWPRINTW" id="VWPRINTW">6.3.3.

+vwprintw()</a></h4>

+<p>This function is similar to <var class=

+"LITERAL">vprintf()</var>. This can be used when variable number of

+arguments are to be printed.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="SIMPLEPRINTWEX" id=

+"SIMPLEPRINTWEX">6.3.4. A Simple printw example</a></h4>

+<div class="EXAMPLE"><a name="BPREX" id="BPREX"></a>

+<p><b>Example 3. A Simple printw example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */

+#include <string.h>

+int main()

+ char mesg[]="Just a string"; /* message to be appeared on the screen */

+ int row,col; /* to store the number of rows and *

+ * the number of colums of the screen */

+ initscr(); /* start the curses mode */

+ getmaxyx(stdscr,row,col); /* get the number of rows and columns */

+ mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);

+ /* print the message at the center of the screen */

+ mvprintw(row-2,0,"This screen has %d rows and %d columns\n",row,col);

+ printw("Try resizing your window(if possible) and then run this program again");

+ refresh();

+ getch();

+ endwin();

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Above program demonstrates how easy it is to use <var class=

+"LITERAL">printw</var>. You just feed the coordinates and the

+message to be appeared on the screen, then it does what you

+want.</p>

+<p>The above program introduces us to a new function <var class=

+"LITERAL">getmaxyx()</var>, a macro defined in <var class=

+"LITERAL">ncurses.h</var>. It gives the number of columns and the

+number of rows in a given window. <var class=

+"LITERAL">getmaxyx()</var> does this by updating the variables

+given to it. Since <var class="LITERAL">getmaxyx()</var> is not a

+function we don't pass pointers to it, we just give two integer

+variables.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ADDSTRCLASS" id="ADDSTRCLASS">6.4.

+addstr() class of functions</a></h3>

+<p><var class="LITERAL">addstr()</var> is used to put a character

+string into a given window. This function is similar to calling

+<var class="LITERAL">addch()</var> once for each character in a

+given string. This is true for all output functions. There are

+other functions from this family such as <var class=

+"LITERAL">mvaddstr(),mvwaddstr()</var> and <var class=

+"LITERAL">waddstr()</var>, which obey the naming convention of

+curses.(e.g. mvaddstr() is similar to the respective calls move()

+and then addstr().) Another function of this family is addnstr(),

+which takes an integer parameter(say n) additionally. This function

+puts at most n characters into the screen. If n is negative, then

+the entire string will be added.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ACAUTION" id="ACAUTION">6.5. A word of

+caution</a></h3>

+<p>All these functions take y co-ordinate first and then x in their

+arguments. A common mistake by beginners is to pass x,y in that

+order. If you are doing too many manipulations of (y,x)

+co-ordinates, think of dividing the screen into windows and

+manipulate each one separately. Windows are explained in the

+<a href="#WINDOWS">windows</a> section.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="SCANW" id="SCANW">7. Input

+functions</a></h2>

+<p>Well, printing without taking input, is boring. Let's see

+functions which allow us to get input from user. These functions

+also can be divided into three categories.</p>

+<ol type="1">

+<li>

+<p>getch() class: Get a character</p>

+</li>

+<li>

+<p>scanw() class: Get formatted input</p>

+</li>

+<li>

+<p>getstr() class: Get strings</p>

+</li>

+</ol>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="GETCHCLASS" id="GETCHCLASS">7.1. getch()

+class of functions</a></h3>

+<p>These functions read a single character from the terminal. But

+there are several subtle facts to consider. For example if you

+don't use the function cbreak(), curses will not read your input

+characters contiguously but will begin read them only after a new

+line or an EOF is encountered. In order to avoid this, the cbreak()

+function must used so that characters are immediately available to

+your program. Another widely used function is noecho(). As the name

+suggests, when this function is set (used), the characters that are

+keyed in by the user will not show up on the screen. The two

+functions cbreak() and noecho() are typical examples of key

+management. Functions of this genre are explained in the <a href=

+"#KEYS">key management section</a> .</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="SCANWCLASS" id="SCANWCLASS">7.2. scanw()

+class of functions</a></h3>

+<p>These functions are similar to <var class=

+"LITERAL">scanf()</var> with the added capability of getting the

+input from any location on the screen.</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="SCANWMVSCANW" id="SCANWMVSCANW">7.2.1.

+scanw() and mvscanw</a></h4>

+<p>The usage of these functions is similar to that of <var class=

+"LITERAL">sscanf()</var>, where the line to be scanned is provided

+by <var class="LITERAL">wgetstr()</var> function. That is, these

+functions call to <var class="LITERAL">wgetstr()</var>

+function(explained below) and uses the resulting line for a

+scan.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="WSCANWMVWSCANW" id=

+"WSCANWMVWSCANW">7.2.2. wscanw() and mvwscanw()</a></h4>

+<p>These are similar to above two functions except that they read

+from a window, which is supplied as one of the arguments to these

+functions.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="VWSCANW" id="VWSCANW">7.2.3.

+vwscanw()</a></h4>

+<p>This function is similar to <var class="LITERAL">vscanf()</var>.

+This can be used when a variable number of arguments are to be

+scanned.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="GETSTRCLASS" id="GETSTRCLASS">7.3.

+getstr() class of functions</a></h3>

+<p>These functions are used to get strings from the terminal. In

+essence, this function performs the same task as would be achieved

+by a series of calls to <var class="LITERAL">getch()</var> until a

+newline, carriage return, or end-of-file is received. The resulting

+string of characters are pointed to by <var class=

+"LITERAL">str</var>, which is a character pointer provided by the

+user.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="GETSTREX" id="GETSTREX">7.4. Some

+examples</a></h3>

+<div class="EXAMPLE"><a name="BSCEX" id="BSCEX"></a>

+<p><b>Example 4. A Simple scanw example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */

+#include <string.h>

+int main()

+ char mesg[]="Enter a string: "; /* message to be appeared on the screen */

+ char str[80];

+ int row,col; /* to store the number of rows and *

+ * the number of colums of the screen */

+ initscr(); /* start the curses mode */

+ getmaxyx(stdscr,row,col); /* get the number of rows and columns */

+ mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);

+ /* print the message at the center of the screen */

+ getstr(str);

+ mvprintw(LINES - 2, 0, "You Entered: %s", str);

+ getch();

+ endwin();

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="ATTRIB" id="ATTRIB">8.

+Attributes</a></h2>

+<p>We have seen an example of how attributes can be used to print

+characters with some special effects. Attributes, when set

+prudently, can present information in an easy, understandable

+manner. The following program takes a C file as input and prints

+the file with comments in bold. Scan through the code.</p>

+<div class="EXAMPLE"><a name="BSIAT" id="BSIAT"></a>

+<p><b>Example 5. A Simple Attributes example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">/* pager functionality by Joseph Spainhour" <spainhou@bellsouth.net> */

+#include <ncurses.h>

+#include <stdlib.h>

+int main(int argc, char *argv[])

+ int ch, prev, row, col;

+ prev = EOF;

+ FILE *fp;

+ int y, x;

+ if(argc != 2)

+ {

+ printf("Usage: %s <a c file name>\n", argv[0]);

+ exit(1);

+ }

+ fp = fopen(argv[1], "r");

+ if(fp == NULL)

+ {

+ perror("Cannot open input file");

+ exit(1);

+ }

+ initscr(); /* Start curses mode */

+ getmaxyx(stdscr, row, col); /* find the boundaries of the screeen */

+ while((ch = fgetc(fp)) != EOF) /* read the file till we reach the end */

+ {

+ getyx(stdscr, y, x); /* get the current curser position */

+ if(y == (row - 1)) /* are we are at the end of the screen */

+ {

+ printw("<-Press Any Key->"); /* tell the user to press a key */

+ getch();

+ clear(); /* clear the screen */

+ move(0, 0); /* start at the beginning of the screen */

+ }

+ if(prev == '/' && ch == '*') /* If it is / and * then only

+ * switch bold on */

+ {

+ attron(A_BOLD); /* cut bold on */

+ getyx(stdscr, y, x); /* get the current curser position */

+ move(y, x - 1); /* back up one space */

+ printw("%c%c", '/', ch); /* The actual printing is done here */

+ }

+ else

+ printw("%c", ch);

+ refresh();

+ if(prev == '*' && ch == '/')

+ attroff(A_BOLD); /* Switch it off once we got *

+ * and then / */

+ prev = ch;

+ }

+ endwin(); /* End curses mode */

+ fclose(fp);

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Don't worry about all those initialization and other crap.

+Concentrate on the while loop. It reads each character in the file

+and searches for the pattern /*. Once it spots the pattern, it

+switches the BOLD attribute on with <var class=

+"LITERAL">attron()</var> . When we get the pattern */ it is

+switched off by <var class="LITERAL">attroff()</var> .</p>

+<p>The above program also introduces us to two useful functions

+<var class="LITERAL">getyx()</var> and <var class=

+"LITERAL">move()</var>. The first function gets the co-ordinates of

+the present cursor into the variables y, x. Since getyx() is a

+macro we don't have to pass pointers to variables. The function

+<var class="LITERAL">move()</var> moves the cursor to the

+co-ordinates given to it.</p>

+<p>The above program is really a simple one which doesn't do much.

+On these lines one could write a more useful program which reads a

+C file, parses it and prints it in different colors. One could even

+extend it to other languages as well.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ATTRIBDETAILS" id="ATTRIBDETAILS">8.1.

+The details</a></h3>

+<p>Let's get into more details of attributes. The functions

+<var class="LITERAL">attron(), attroff(), attrset()</var> , and

+their sister functions <var class="LITERAL">attr_get()</var> etc..

+can be used to switch attributes on/off , get attributes and

+produce a colorful display.</p>

+<p>The functions attron and attroff take a bit-mask of 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">

+ A_NORMAL Normal display (no highlight)

+ A_STANDOUT Best highlighting mode of the terminal.

+ A_UNDERLINE Underlining

+ A_REVERSE Reverse video

+ A_BLINK Blinking

+ A_DIM Half bright

+ A_BOLD Extra bright or bold

+ A_PROTECT Protected mode

+ A_INVIS Invisible or blank mode

+ A_ALTCHARSET Alternate character set

+ A_CHARTEXT Bit-mask to extract a character

+ COLOR_PAIR(n) Color-pair number n

+ </font>

+</pre></td>

+</tr>

+</table>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> attron(A_REVERSE | A_BLINK);</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ATTRONVSATTRSET" id=

+"ATTRONVSATTRSET">8.2. attron() vs attrset()</a></h3>

+<p>Then what is the difference between attron() and attrset()?

+attrset sets the attributes of window whereas attron just switches

+on the attribute given to it. So attrset() fully overrides whatever

+attributes the window previously had and sets it to the new

+attribute(s). Similarly attroff() just switches off the

+attribute(s) given to it as an argument. This gives us the

+flexibility of managing attributes easily.But if you use them

+carelessly you may loose track of what attributes the window has

+and garble the display. This is especially true while managing

+menus with colors and highlighting. So decide on a consistent

+policy and stick to it. You can always use <var class=

+"LITERAL">standend()</var> which is equivalent to <var class=

+"LITERAL">attrset(A_NORMAL)</var> which turns off all attributes

+and brings you to normal mode.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ATTR_GET" id="ATTR_GET">8.3.

+attr_get()</a></h3>

+<p>The function attr_get() gets the current attributes and color

+pair of the window. Though we might not use this as often as the

+above functions, this is useful in scanning areas of screen. Say we

+wanted to do some complex update on screen and we are not sure what

+attribute each character is associated with. Then this function can

+be used with either attrset or attron to produce the desired

+effect.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ATTR_FUNCS" id="ATTR_FUNCS">8.4. attr_

+functions</a></h3>

+<p>There are series of functions like attr_set(), attr_on etc..

+These are similar to above functions except that they take

+parameters of type <var class="LITERAL">attr_t</var>.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WATTRFUNCS" id="WATTRFUNCS">8.5. wattr

+functions</a></h3>

+<p>For each of the above functions we have a corresponding function

+with 'w' which operates on a particular window. The above functions

+operate on stdscr.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="CHGAT" id="CHGAT">8.6. chgat()

+functions</a></h3>

+<p>The function chgat() is listed in the end of the man page

+curs_attr. It actually is a useful one. This function can be used

+to set attributes for a group of characters without moving. I mean

+it !!! without moving the cursor :-) It changes the attributes of a

+given number of characters starting at the current cursor

+location.</p>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> chgat(-1, A_REVERSE, 0, NULL);</font>

+</pre></td>

+</tr>

+</table>

+<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 attribute.</p>

+<p>Other functions wchgat(), mvchgat(), wchgat() behave similarly

+except that the w functions operate on the particular window. The

+mv functions first move the cursor then perform the work given to

+them. Actually chgat is a macro which is replaced by a wchgat()

+with stdscr as the window. Most of the "w-less" functions are

+macros.</p>

+<div class="EXAMPLE"><a name="BWICH" id="BWICH"></a>

+<p><b>Example 6. Chgat() Usage example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+int main(int argc, char *argv[])

+{ initscr(); /* Start curses mode */

+ start_color(); /* Start color functionality */

+ init_pair(1, COLOR_CYAN, COLOR_BLACK);

+ printw("A Big string which i didn't care to type fully ");

+ mvchgat(0, 0, -1, A_BLINK, 1, NULL);

+ /*

+ * First two parameters specify the position at which to start

+ * Third parameter number of characters to update. -1 means till

+ * end of line

+ * Forth parameter is the normal attribute you wanted to give

+ * to the charcter

+ * Fifth is the color index. It is the index given during init_pair()

+ * use 0 if you didn't want color

+ * Sixth one is always NULL

+ */

+ refresh();

+ getch();

+ endwin(); /* End curses mode */

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>This example also introduces us to the color world of curses.

+Colors will be explained in detail later. Use 0 for no color.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="WINDOWS" id="WINDOWS">9.

+Windows</a></h2>

+<p>Windows form the most important concept in curses. You have seen

+the standard window stdscr above where all the functions implicitly

+operated on this window. Now to make design even a simplest GUI,

+you need to resort to windows. The main reason you may want to use

+windows is to manipulate parts of the screen separately, for better

+efficiency, by updating only the windows that need to be changed

+and for a better design. I would say the last reason is the most

+important in going for windows. You should always strive for a

+better and easy-to-manage design in your programs. If you are

+writing big, complex GUIs this is of pivotal importance before you

+start doing anything.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WINDOWBASICS" id="WINDOWBASICS">9.1. The

+basics</a></h3>

+<p>A Window can be created by calling the function <var class=

+"LITERAL">newwin()</var>. It doesn't create any thing on the screen

+actually. It allocates memory for a structure to manipulate the

+window and updates the structure with data regarding the window

+like it's size, beginy, beginx etc.. Hence in curses, a window is

+just an abstraction of an imaginary window, which can be

+manipulated independent of other parts of screen. The function

+newwin() returns a pointer to structure WINDOW, which can be passed

+to window related functions like wprintw() etc.. Finally the window

+can be destroyed with delwin(). It will deallocate the memory

+associated with the window structure.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="LETBEWINDOW" id="LETBEWINDOW">9.2. Let

+there be a Window !!!</a></h3>

+<p>What fun is it, if a window is created and we can't see it. So

+the fun part begins by displaying the window. The function

+<var class="LITERAL">box()</var> can be used to draw a border

+around the window. Let's explore these functions in more detail in

+this example.</p>

+<div class="EXAMPLE"><a name="BWIBO" id="BWIBO"></a>

+<p><b>Example 7. Window Border example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+WINDOW *create_newwin(int height, int width, int starty, int startx);

+void destroy_win(WINDOW *local_win);

+int main(int argc, char *argv[])

+{ WINDOW *my_win;

+ int startx, starty, width, height;

+ int ch;

+ initscr(); /* Start curses mode */

+ cbreak(); /* Line buffering disabled, Pass on

+ * everty thing to me */

+ keypad(stdscr, TRUE); /* I need that nifty F1 */

+ height = 3;

+ width = 10;

+ starty = (LINES - height) / 2; /* Calculating for a center placement */

+ startx = (COLS - width) / 2; /* of the window */

+ printw("Press F1 to exit");

+ refresh();

+ my_win = create_newwin(height, width, starty, startx);

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case KEY_LEFT:

+ destroy_win(my_win);

+ my_win = create_newwin(height, width, starty,--startx);

+ break;

+ case KEY_RIGHT:

+ destroy_win(my_win);

+ my_win = create_newwin(height, width, starty,++startx);

+ break;

+ case KEY_UP:

+ destroy_win(my_win);

+ my_win = create_newwin(height, width, --starty,startx);

+ break;

+ case KEY_DOWN:

+ destroy_win(my_win);

+ my_win = create_newwin(height, width, ++starty,startx);

+ break;

+ }

+ endwin(); /* End curses mode */

+ return 0;

+WINDOW *create_newwin(int height, int width, int starty, int startx)

+{ WINDOW *local_win;

+ local_win = newwin(height, width, starty, startx);

+ box(local_win, 0 , 0); /* 0, 0 gives default characters

+ * for the vertical and horizontal

+ * lines */

+ wrefresh(local_win); /* Show that box */

+ return local_win;

+void destroy_win(WINDOW *local_win)

+ /* box(local_win, ' ', ' '); : This won't produce the desired

+ * result of erasing the window. It will leave it's four corners

+ * and so an ugly remnant of window.

+ */

+ wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' ');

+ /* The parameters taken are

+ * 1. win: the window on which to operate

+ * 2. ls: character to be used for the left side of the window

+ * 3. rs: character to be used for the right side of the window

+ * 4. ts: character to be used for the top side of the window

+ * 5. bs: character to be used for the bottom side of the window

+ * 6. tl: character to be used for the top left corner of the window

+ * 7. tr: character to be used for the top right corner of the window

+ * 8. bl: character to be used for the bottom left corner of the window

+ * 9. br: character to be used for the bottom right corner of the window

+ */

+ wrefresh(local_win);

+ delwin(local_win);

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="BORDEREXEXPL" id="BORDEREXEXPL">9.3.

+Explanation</a></h3>

+<p>Don't scream. I know it's a big example. But I have to explain

+some important things here :-). This program creates a rectangular

+window that can be moved with left, right, up, down arrow keys. It

+repeatedly creates and destroys windows as user press a key. Don't

+go beyond the screen limits. Checking for those limits is left as

+an exercise for the reader. Let's dissect it by line by line.</p>

+<p>The <var class="LITERAL">create_newwin()</var> function creates

+a window with <var class="LITERAL">newwin()</var> and displays a

+border around it with box. The function <var class=

+"LITERAL">destroy_win()</var> first erases the window from screen

+by painting a border with ' ' character and then calling

+<var class="LITERAL">delwin()</var> to deallocate memory related to

+it. Depending on the key the user presses, starty or startx is

+changed and a new window is created.</p>

+<p>In the destroy_win, as you can see, I used wborder instead of

+box. The reason is written in the comments (You missed it. I know.

+Read the code :-)). wborder draws a 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');</font>

+</pre></td>

+</tr>

+</table>

+<p>it produces some thing like</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> +------------+

+ | |

+ +------------+</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="OTHERSTUFF" id="OTHERSTUFF">9.4. The

+other stuff in the example</a></h3>

+<p>You can also see in the above examples, that I have used the

+variables COLS, LINES which are initialized to the screen sizes

+after initscr(). They can be useful in finding screen dimensions

+and finding the center co-ordinate of the screen as above. The

+function <var class="LITERAL">getch()</var> as usual gets the key

+from keyboard and according to the key it does the corresponding

+work. This type of switch- case is very common in any GUI based

+programs.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="OTHERBORDERFUNCS" id=

+"OTHERBORDERFUNCS">9.5. Other Border functions</a></h3>

+<p>Above program is grossly inefficient in that with each press of

+a key, a window is destroyed and another is created. So let's write

+a more efficient program which uses other border related

+functions.</p>

+<p>The following program uses <var class="LITERAL">mvhline()</var>

+and <var class="LITERAL">mvvline()</var> to achieve similar effect.

+These two functions are simple. They create a horizontal or

+vertical line of the specified length at the specified

+position.</p>

+<div class="EXAMPLE"><a name="BOTBO" id="BOTBO"></a>

+<p><b>Example 8. More border functions</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+typedef struct _win_border_struct {

+ chtype ls, rs, ts, bs,

+ tl, tr, bl, br;

+}WIN_BORDER;

+typedef struct _WIN_struct {

+ int startx, starty;

+ int height, width;

+ WIN_BORDER border;

+}WIN;

+void init_win_params(WIN *p_win);

+void print_win_params(WIN *p_win);

+void create_box(WIN *win, bool flag);

+int main(int argc, char *argv[])

+{ WIN win;

+ int ch;

+ initscr(); /* Start curses mode */

+ start_color(); /* Start the color functionality */

+ cbreak(); /* Line buffering disabled, Pass on

+ * everty thing to me */

+ keypad(stdscr, TRUE); /* I need that nifty F1 */

+ noecho();

+ init_pair(1, COLOR_CYAN, COLOR_BLACK);

+ /* Initialize the window parameters */

+ init_win_params(&win);

+ print_win_params(&win);

+ attron(COLOR_PAIR(1));

+ printw("Press F1 to exit");

+ refresh();

+ attroff(COLOR_PAIR(1));

+ create_box(&win, TRUE);

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case KEY_LEFT:

+ create_box(&win, FALSE);

+ --win.startx;

+ create_box(&win, TRUE);

+ break;

+ case KEY_RIGHT:

+ create_box(&win, FALSE);

+ ++win.startx;

+ create_box(&win, TRUE);

+ break;

+ case KEY_UP:

+ create_box(&win, FALSE);

+ --win.starty;

+ create_box(&win, TRUE);

+ break;

+ case KEY_DOWN:

+ create_box(&win, FALSE);

+ ++win.starty;

+ create_box(&win, TRUE);

+ break;

+ }

+ endwin(); /* End curses mode */

+ return 0;

+void init_win_params(WIN *p_win)

+ p_win->height = 3;

+ p_win->width = 10;

+ p_win->starty = (LINES - p_win->height)/2;

+ p_win->startx = (COLS - p_win->width)/2;

+ p_win->border.ls = '|';

+ p_win->border.rs = '|';

+ p_win->border.ts = '-';

+ p_win->border.bs = '-';

+ p_win->border.tl = '+';

+ p_win->border.tr = '+';

+ p_win->border.bl = '+';

+ p_win->border.br = '+';

+void print_win_params(WIN *p_win)

+#ifdef _DEBUG

+ mvprintw(25, 0, "%d %d %d %d", p_win->startx, p_win->starty,

+ p_win->width, p_win->height);

+ refresh();

+#endif

+void create_box(WIN *p_win, bool flag)

+{ int i, j;

+ int x, y, w, h;

+ x = p_win->startx;

+ y = p_win->starty;

+ w = p_win->width;

+ h = p_win->height;

+ if(flag == TRUE)

+ { mvaddch(y, x, p_win->border.tl);

+ mvaddch(y, x + w, p_win->border.tr);

+ mvaddch(y + h, x, p_win->border.bl);

+ mvaddch(y + h, x + w, p_win->border.br);

+ mvhline(y, x + 1, p_win->border.ts, w - 1);

+ mvhline(y + h, x + 1, p_win->border.bs, w - 1);

+ mvvline(y + 1, x, p_win->border.ls, h - 1);

+ mvvline(y + 1, x + w, p_win->border.rs, h - 1);

+ }

+ else

+ for(j = y; j <= y + h; ++j)

+ for(i = x; i <= x + w; ++i)

+ mvaddch(j, i, ' ');

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="COLOR" id="COLOR">10. Colors</a></h2>

+<div class="SECT2">

+<h3 class="SECT2"><a name="COLORBASICS" id="COLORBASICS">10.1. The

+basics</a></h3>

+<p>Life seems dull with no colors. Curses has a nice mechanism to

+handle colors. Let's get into the thick of the things with a small

+program.</p>

+<div class="EXAMPLE"><a name="BSICO" id="BSICO"></a>

+<p><b>Example 9. A Simple Color example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string);

+int main(int argc, char *argv[])

+{ initscr(); /* Start curses mode */

+ if(has_colors() == FALSE)

+ { endwin();

+ printf("Your terminal does not support color\n");

+ exit(1);

+ }

+ start_color(); /* Start color */

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ attron(COLOR_PAIR(1));

+ print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ...");

+ attroff(COLOR_PAIR(1));

+ getch();

+ endwin();

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ mvwprintw(win, y, x, "%s", string);

+ refresh();

+</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>As you can see, to start using color, you should first call the

+function <var class="LITERAL">start_color()</var>. After that, you

+can use color capabilities of your terminals using various

+functions. To find out whether a terminal has color capabilities or

+not, you can use <var class="LITERAL">has_colors()</var> function,

+which returns FALSE if the terminal does not support color.</p>

+<p>Curses initializes all the colors supported by terminal when

+start_color() is called. These can be accessed by the define

+constants like <var class="LITERAL">COLOR_BLACK</var> etc. Now to

+actually start using colors, you have to define pairs. Colors are

+always used in pairs. That means you have to use the function

+<var class="LITERAL">init_pair()</var> to define the foreground and

+background for the pair number you give. After that that pair

+number can be used as a normal attribute with <var class=

+"LITERAL">COLOR_PAIR()</var>function. This may seem to be

+cumbersome at first. But this elegant solution allows us to manage

+color pairs very easily. To appreciate it, you have to look into

+the the source code of "dialog", a utility for displaying dialog

+boxes from shell scripts. The developers have defined foreground

+and background combinations for all the colors they might need and

+initialized at the beginning. This makes it very easy to set

+attributes just by accessing a pair which we already have defined

+as a constant.</p>

+<p>The following colors are defined in <var class=

+"LITERAL">curses.h</var>. You can use these as parameters for

+various color functions.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> COLOR_BLACK 0

+ COLOR_RED 1

+ COLOR_GREEN 2

+ COLOR_YELLOW 3

+ COLOR_BLUE 4

+ COLOR_MAGENTA 5

+ COLOR_CYAN 6

+ COLOR_WHITE 7</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="CHANGECOLORDEFS" id=

+"CHANGECOLORDEFS">10.2. Changing Color Definitions</a></h3>

+<p>The function <var class="LITERAL">init_color()</var>can be used

+to change the rgb values for the colors defined by curses

+initially. Say you wanted to lighten the intensity of red color by

+a minuscule. Then you can use this function as</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> init_color(COLOR_RED, 700, 0, 0);

+ /* param 1 : color name

+ * param 2, 3, 4 : rgb content min = 0, max = 1000 */</font>

+</pre></td>

+</tr>

+</table>

+<p>If your terminal cannot change the color definitions, the

+function returns ERR. The function <var class=

+"LITERAL">can_change_color()</var> can be used to find out whether

+the terminal has the capability of changing color content or not.

+The rgb content is scaled from 0 to 1000. Initially RED color is

+defined with content 1000(r), 0(g), 0(b).</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="COLORCONTENT" id="COLORCONTENT">10.3.

+Color Content</a></h3>

+<p>The functions <var class="LITERAL">color_content()</var> and

+<var class="LITERAL">pair_content()</var> can be used to find the

+color content and foreground, background combination for the

+pair.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="KEYS" id="KEYS">11. Interfacing with the

+key board</a></h2>

+<div class="SECT2">

+<h3 class="SECT2"><a name="KEYSBASICS" id="KEYSBASICS">11.1. The

+Basics</a></h3>

+<p>No GUI is complete without a strong user interface and to

+interact with the user, a curses program should be 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's very

+easy to get key input from the user. A simple way of getting key

+presses is to use <var class="LITERAL">getch()</var> function. The

+cbreak mode should be enabled to read keys when you are interested

+in reading individual key hits rather than complete lines of text

+(which usually end with a carriage return). keypad should be

+enabled to get the Functions keys, arrow keys etc. See the

+initialization section for details.</p>

+<p><var class="LITERAL">getch()</var> returns an integer

+corresponding to the key pressed. If it is a normal character, the

+integer value will be equivalent to the character. Otherwise it

+returns a number which can be matched with the constants defined in

+<var class="LITERAL">curses.h</var>. For example if the user

+presses F1, the integer returned is 265. This can be checked using

+the macro KEY_F() defined in curses.h. This makes reading keys

+portable and easy to manage.</p>

+<p>For example, if you call getch() like this</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> int ch;

+ ch = getch();</font>

+</pre></td>

+</tr>

+</table>

+<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 value returned with the

+constants defined in curses.h to match against the keys you

+want.</p>

+<p>The following code piece will do that job.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> if(ch == KEY_LEFT)

+ printw("Left arrow is pressed\n");</font>

+</pre></td>

+</tr>

+</table>

+<p>Let's write a small program which creates a menu which can be

+navigated by up and down arrows.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="SIMPLEKEYEX" id="SIMPLEKEYEX">11.2. A

+Simple Key Usage example</a></h3>

+<div class="EXAMPLE"><a name="BSIKE" id="BSIKE"></a>

+<p><b>Example 10. A Simple Key Usage example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <stdio.h>

+#include <ncurses.h>

+#define WIDTH 30

+#define HEIGHT 10

+int startx = 0;

+int starty = 0;

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Exit",

+ };

+int n_choices = sizeof(choices) / sizeof(char *);

+void print_menu(WINDOW *menu_win, int highlight);

+int main()

+{ WINDOW *menu_win;

+ int highlight = 1;

+ int choice = 0;

+ int c;

+ initscr();

+ clear();

+ noecho();

+ cbreak(); /* Line buffering disabled. pass on everything */

+ startx = (80 - WIDTH) / 2;

+ starty = (24 - HEIGHT) / 2;

+ menu_win = newwin(HEIGHT, WIDTH, starty, startx);

+ keypad(menu_win, TRUE);

+ mvprintw(0, 0, "Use arrow keys to go up and down, Press enter to select a choice");

+ refresh();

+ print_menu(menu_win, highlight);

+ while(1)

+ { c = wgetch(menu_win);

+ switch(c)

+ { case KEY_UP:

+ if(highlight == 1)

+ highlight = n_choices;

+ else

+ --highlight;

+ break;

+ case KEY_DOWN:

+ if(highlight == n_choices)

+ highlight = 1;

+ else

+ ++highlight;

+ break;

+ case 10:

+ choice = highlight;

+ break;

+ default:

+ mvprintw(24, 0, "Charcter pressed is = %3d Hopefully it can be printed as '%c'", c, c);

+ refresh();

+ break;

+ }

+ print_menu(menu_win, highlight);

+ if(choice != 0) /* User did a choice come out of the infinite loop */

+ break;

+ }

+ mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, choices[choice - 1]);

+ clrtoeol();

+ refresh();

+ endwin();

+ return 0;

+void print_menu(WINDOW *menu_win, int highlight)

+ int x, y, i;

+ x = 2;

+ y = 2;

+ box(menu_win, 0, 0);

+ for(i = 0; i < n_choices; ++i)

+ { if(highlight == i + 1) /* High light the present choice */

+ { wattron(menu_win, A_REVERSE);

+ mvwprintw(menu_win, y, x, "%s", choices[i]);

+ wattroff(menu_win, A_REVERSE);

+ }

+ else

+ mvwprintw(menu_win, y, x, "%s", choices[i]);

+ ++y;

+ }

+ wrefresh(menu_win);

+</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="MOUSE" id="MOUSE">12. Interfacing with

+the mouse</a></h2>

+<p>Now that you have seen how to get keys, lets do the same thing

+from mouse. Usually each UI allows the user to interact with both

+keyboard and mouse.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MOUSEBASICS" id="MOUSEBASICS">12.1. The

+Basics</a></h3>

+<p>Before you do any thing else, the events you want to receive

+have to be enabled with <var class="LITERAL">mousemask()</var>.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> mousemask( mmask_t newmask, /* The events you want to listen to */

+ mmask_t *oldmask) /* The old events mask */</font>

+</pre></td>

+</tr>

+</table>

+<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 <var class="LITERAL">ALL_MOUSE_EVENTS</var> can

+be used to get all the events.</p>

+<p>The following are all the event masks:</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> Name Description

+ ---------------------------------------------------------------------

+ BUTTON1_PRESSED mouse button 1 down

+ BUTTON1_RELEASED mouse button 1 up

+ BUTTON1_CLICKED mouse button 1 clicked

+ BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked

+ BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked

+ BUTTON2_PRESSED mouse button 2 down

+ BUTTON2_RELEASED mouse button 2 up

+ BUTTON2_CLICKED mouse button 2 clicked

+ BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked

+ BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked

+ BUTTON3_PRESSED mouse button 3 down

+ BUTTON3_RELEASED mouse button 3 up

+ BUTTON3_CLICKED mouse button 3 clicked

+ BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked

+ BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked

+ BUTTON4_PRESSED mouse button 4 down

+ BUTTON4_RELEASED mouse button 4 up

+ BUTTON4_CLICKED mouse button 4 clicked

+ BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked

+ BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked

+ BUTTON_SHIFT shift was down during button state change

+ BUTTON_CTRL control was down during button state change

+ BUTTON_ALT alt was down during button state change

+ ALL_MOUSE_EVENTS report all button state changes

+ REPORT_MOUSE_POSITION report mouse movement</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="GETTINGEVENTS" id="GETTINGEVENTS">12.2.

+Getting the events</a></h3>

+<p>Once a class of mouse events have been enabled, getch() class of

+functions return KEY_MOUSE every time some mouse event happens.

+Then the mouse event can be retrieved with <var class=

+"LITERAL">getmouse()</var>.</p>

+<p>The code approximately looks like this:</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> MEVENT event;

+ ch = getch();

+ if(ch == KEY_MOUSE)

+ if(getmouse(&event) == OK)

+ . /* Do some thing with the event */

+ .

+ .</font>

+</pre></td>

+</tr>

+</table>

+<p>getmouse() returns the event into the pointer given to it. It's

+a structure which contains</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> typedef struct

+ {

+ short id; /* ID to distinguish multiple devices */

+ int x, y, z; /* event coordinates */

+ mmask_t bstate; /* button state bits */

+ } </font>

+</pre></td>

+</tr>

+</table>

+<p>The <var class="LITERAL">bstate</var> 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> if(event.bstate & BUTTON1_PRESSED)

+ printw("Left Button Pressed");</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MOUSETOGETHER" id="MOUSETOGETHER">12.3.

+Putting it all Together</a></h3>

+<p>That's pretty much interfacing with mouse. Let's create the same

+menu and enable mouse interaction. To make things simpler, key

+handling is removed.</p>

+<div class="EXAMPLE"><a name="BMOME" id="BMOME"></a>

+<p><b>Example 11. Access the menu with mouse !!!</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+#define WIDTH 30

+#define HEIGHT 10

+int startx = 0;

+int starty = 0;

+char *choices[] = { "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Exit",

+ };

+int n_choices = sizeof(choices) / sizeof(char *);

+void print_menu(WINDOW *menu_win, int highlight);

+void report_choice(int mouse_x, int mouse_y, int *p_choice);

+int main()

+{ int c, choice = 0;

+ WINDOW *menu_win;

+ MEVENT event;

+ /* Initialize curses */

+ initscr();

+ clear();

+ noecho();

+ cbreak(); //Line buffering disabled. pass on everything

+ /* Try to put the window in the middle of screen */

+ startx = (80 - WIDTH) / 2;

+ starty = (24 - HEIGHT) / 2;

+ attron(A_REVERSE);

+ mvprintw(23, 1, "Click on Exit to quit (Works best in a virtual console)");

+ refresh();

+ attroff(A_REVERSE);

+ /* Print the menu for the first time */

+ menu_win = newwin(HEIGHT, WIDTH, starty, startx);

+ print_menu(menu_win, 1);

+ /* Get all the mouse events */

+ mousemask(ALL_MOUSE_EVENTS, NULL);

+ while(1)

+ { c = wgetch(menu_win);

+ switch(c)

+ { case KEY_MOUSE:

+ if(getmouse(&event) == OK)

+ { /* When the user clicks left mouse button */

+ if(event.bstate & BUTTON1_PRESSED)

+ { report_choice(event.x + 1, event.y + 1, &choice);

+ if(choice == -1) //Exit chosen

+ goto end;

+ mvprintw(22, 1, "Choice made is : %d String Chosen is \"%10s\"", choice, choices[choice - 1]);

+ refresh();

+ }

+ print_menu(menu_win, choice);

+ break;

+ }

+end:

+ endwin();

+ return 0;

+void print_menu(WINDOW *menu_win, int highlight)

+ int x, y, i;

+ x = 2;

+ y = 2;

+ box(menu_win, 0, 0);

+ for(i = 0; i < n_choices; ++i)

+ { if(highlight == i + 1)

+ { wattron(menu_win, A_REVERSE);

+ mvwprintw(menu_win, y, x, "%s", choices[i]);

+ wattroff(menu_win, A_REVERSE);

+ }

+ else

+ mvwprintw(menu_win, y, x, "%s", choices[i]);

+ ++y;

+ }

+ wrefresh(menu_win);

+/* Report the choice according to mouse position */

+void report_choice(int mouse_x, int mouse_y, int *p_choice)

+{ int i,j, choice;

+ i = startx + 2;

+ j = starty + 3;

+ for(choice = 0; choice < n_choices; ++choice)

+ if(mouse_y == j + choice && mouse_x >= i && mouse_x <= i + strlen(choices[choice]))

+ { if(choice == n_choices - 1)

+ *p_choice = -1;

+ else

+ *p_choice = choice + 1;

+ break;

+ }

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MISCMOUSEFUNCS" id=

+"MISCMOUSEFUNCS">12.4. Miscellaneous Functions</a></h3>

+<p>The functions mouse_trafo() and wmouse_trafo() can be used to

+convert to mouse co-ordinates to screen relative co-ordinates. See

+curs_mouse(3X) man page for details.</p>

+<p>The mouseinterval function sets the maximum time (in thousands

+of a second) that can elapse between press and release events in

+order for them to be recognized as a click. This function returns

+the previous interval value. The default is one fifth of a

+second.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="SCREEN" id="SCREEN">13. Screen

+Manipulation</a></h2>

+<p>In this section, we will look into some functions, which allow

+us to manage the screen efficiently and to write some fancy

+programs. This is especially important in writing games.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="GETYX" id="GETYX">13.1. getyx()

+functions</a></h3>

+<p>The function <var class="LITERAL">getyx()</var> can be used to

+find out the present cursor co-ordinates. It will 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> getyx(win, y, x);

+ /* win: window pointer

+ * y, x: y, x co-ordinates will be put into this variables

+ */</font>

+</pre></td>

+</tr>

+</table>

+<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 stuff like writing

+multiple menus, it becomes difficult to store the menu positions,

+their first option co-ordinates etc. A simple solution to this

+problem, is to create menus in sub windows and later find the

+starting co-ordinates of the menus by using getparyx().</p>

+<p>The functions getbegyx() and getmaxyx() store current window's

+beginning and maximum co-ordinates. These functions are useful in

+the same way as above in managing the windows and sub windows

+effectively.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="SCREENDUMP" id="SCREENDUMP">13.2. Screen

+Dumping</a></h3>

+<p>While writing games, some times it becomes necessary to store

+the state of the screen and restore it back to the same state. The

+function scr_dump() can be used to dump the screen contents to a

+file given as an argument. Later it can be restored by scr_restore

+function. These two simple functions can be used effectively to

+maintain a fast moving game with changing scenarios.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="WINDOWDUMP" id="WINDOWDUMP">13.3. Window

+Dumping</a></h3>

+<p>To store and restore windows, the functions <var class=

+"LITERAL">putwin()</var> and <var class="LITERAL">getwin()</var>

+can be used. <var class="LITERAL">putwin()</var> puts the present

+window state into a file, which can be later restored by

+<var class="LITERAL">getwin()</var>.</p>

+<p>The function <var class="LITERAL">copywin()</var> can be used to

+copy a window completely onto another window. It takes the source

+and destination windows as parameters and according to the

+rectangle specified, it copies the rectangular region from source

+to destination window. It's last parameter specifies whether to

+overwrite or just overlay the contents on to the destination

+window. If this argument is true, then the copying is

+non-destructive.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="MISC" id="MISC">14. Miscellaneous

+features</a></h2>

+<p>Now you know enough features to write a good curses program,

+with all bells and whistles. There are some miscellaneous functions

+which are useful in various cases. Let's go headlong into some of

+those.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="CURSSET" id="CURSSET">14.1.

+curs_set()</a></h3>

+<p>This function can be used to make the cursor invisible. The

+parameter to this function should be</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> 0 : invisible or

+ 1 : normal or

+ 2 : very visible.</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="TEMPLEAVE" id="TEMPLEAVE">14.2.

+Temporarily Leaving Curses mode</a></h3>

+<p>Some times you may want to get back to cooked mode (normal line

+buffering mode) temporarily. In such a case you will first need to

+save the tty modes with a call to <var class=

+"LITERAL">def_prog_mode()</var> and then call <var class=

+"LITERAL">endwin()</var> to end the curses mode. This will leave

+you in the original tty mode. To get back to curses once you are

+done, call <var class="LITERAL">reset_prog_mode()</var> . This

+function returns the tty to the state stored by <var class=

+"LITERAL">def_prog_mode()</var>. Then do refresh(), and you are

+back to the curses mode. Here is an example showing the sequence of

+things to be done.</p>

+<div class="EXAMPLE"><a name="BTELE" id="BTELE"></a>

+<p><b>Example 12. Temporarily Leaving Curses Mode</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+int main()

+ initscr(); /* Start curses mode */

+ printw("Hello World !!!\n"); /* Print Hello World */

+ refresh(); /* Print it on to the real screen */

+ def_prog_mode(); /* Save the tty modes */

+ endwin(); /* End curses mode temporarily */

+ system("/bin/sh"); /* Do whatever you like in cooked mode */

+ reset_prog_mode(); /* Return to the previous tty mode*/

+ /* stored by def_prog_mode() */

+ refresh(); /* Do refresh() to restore the */

+ /* Screen contents */

+ printw("Another String\n"); /* Back to curses use the full */

+ refresh(); /* capabilities of curses */

+ endwin(); /* End curses mode */

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="ACSVARS" id="ACSVARS">14.3. ACS_

+variables</a></h3>

+<p>If you have ever programmed in DOS, you know about those nifty

+characters in extended character set. They are printable only on

+some terminals. NCURSES functions like <var class=

+"LITERAL">box()</var> use these characters. All these variables

+start with ACS meaning alternative character set. You might have

+noticed me using these characters in some of the programs above.

+Here's an example showing all the characters.</p>

+<div class="EXAMPLE"><a name="BACSVARS" id="BACSVARS"></a>

+<p><b>Example 13. ACS Variables Example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <ncurses.h>

+int main()

+ initscr();

+ printw("Upper left corner "); addch(ACS_ULCORNER); printw("\n");

+ printw("Lower left corner "); addch(ACS_LLCORNER); printw("\n");

+ printw("Lower right corner "); addch(ACS_LRCORNER); printw("\n");

+ printw("Tee pointing right "); addch(ACS_LTEE); printw("\n");

+ printw("Tee pointing left "); addch(ACS_RTEE); printw("\n");

+ printw("Tee pointing up "); addch(ACS_BTEE); printw("\n");

+ printw("Tee pointing down "); addch(ACS_TTEE); printw("\n");

+ printw("Horizontal line "); addch(ACS_HLINE); printw("\n");

+ printw("Vertical line "); addch(ACS_VLINE); printw("\n");

+ printw("Large Plus or cross over "); addch(ACS_PLUS); printw("\n");

+ printw("Scan Line 1 "); addch(ACS_S1); printw("\n");

+ printw("Scan Line 3 "); addch(ACS_S3); printw("\n");

+ printw("Scan Line 7 "); addch(ACS_S7); printw("\n");

+ printw("Scan Line 9 "); addch(ACS_S9); printw("\n");

+ printw("Diamond "); addch(ACS_DIAMOND); printw("\n");

+ printw("Checker board (stipple) "); addch(ACS_CKBOARD); printw("\n");

+ printw("Degree Symbol "); addch(ACS_DEGREE); printw("\n");

+ printw("Plus/Minus Symbol "); addch(ACS_PLMINUS); printw("\n");

+ printw("Bullet "); addch(ACS_BULLET); printw("\n");

+ printw("Arrow Pointing Left "); addch(ACS_LARROW); printw("\n");

+ printw("Arrow Pointing Right "); addch(ACS_RARROW); printw("\n");

+ printw("Arrow Pointing Down "); addch(ACS_DARROW); printw("\n");

+ printw("Arrow Pointing Up "); addch(ACS_UARROW); printw("\n");

+ printw("Board of squares "); addch(ACS_BOARD); printw("\n");

+ printw("Lantern Symbol "); addch(ACS_LANTERN); printw("\n");

+ printw("Solid Square Block "); addch(ACS_BLOCK); printw("\n");

+ printw("Less/Equal sign "); addch(ACS_LEQUAL); printw("\n");

+ printw("Greater/Equal sign "); addch(ACS_GEQUAL); printw("\n");

+ printw("Pi "); addch(ACS_PI); printw("\n");

+ printw("Not equal "); addch(ACS_NEQUAL); printw("\n");

+ printw("UK pound sign "); addch(ACS_STERLING); printw("\n");

+ refresh();

+ getch();

+ endwin();

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="OTHERLIB" id="OTHERLIB">15. Other

+libraries</a></h2>

+<p>Apart from the curses library, there are few text mode

+libraries, which provide more functionality and a lot of features.

+The following sections explain three standard libraries which are

+usually distributed along with curses.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="PANELS" id="PANELS">16. Panel

+Library</a></h2>

+<p>Now that you are proficient in curses, you wanted to do some

+thing big. You created a lot of overlapping windows to give a

+professional windows-type look. Unfortunately, it soon becomes

+difficult to manage these. The multiple refreshes, updates plunge

+you into a nightmare. The overlapping windows create blotches,

+whenever you forget to refresh the windows in the proper order.</p>

+<p>Don't despair. There's an elegant solution provided in panels

+library. In the words of developers of ncurses</p>

+<p><em>When your 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.</em></p>

+<p>If you have lot of overlapping windows, then panels library is

+the way to go. It obviates the need of doing series of

+wnoutrefresh(), doupdate() and relieves the burden of doing it

+correctly(bottom up). The library maintains information about the

+order of windows, their overlapping and update the screen properly.

+So why wait? Let's take a close peek into panels.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PANELBASICS" id="PANELBASICS">16.1. The

+Basics</a></h3>

+<p>Panel object is a window that is implicitly treated as part of a

+deck including all other panel objects. The deck is treated as a

+stack with the top panel being completely visible and the other

+panels may or may not be obscured according to their positions. So

+the basic idea is to create a stack of overlapping panels and use

+panels library to display them correctly. There is a function

+similar to refresh() which, when called , displays panels in the

+correct order. Functions are provided to hide or show panels, move

+panels, change its size etc.. The overlapping problem is managed by

+the panels library during all the calls to these functions.</p>

+<p>The general flow of a panel program goes like this:</p>

+<ol type="1">

+<li>

+<p>Create the windows (with newwin()) to be attached to the

+panels.</p>

+</li>

+<li>

+<p>Create panels with the chosen visibility order. Stack them up

+according to the desired visibility. The function new_panel() is

+used to created panels.</p>

+</li>

+<li>

+<p>Call update_panels() to write the panels to the virtual screen

+in correct visibility order. Do a doupdate() to show it on the

+screen.</p>

+</li>

+<li>

+<p>Mainpulate the panels with show_panel(), hide_panel(),

+move_panel() etc. Make use of helper functions like panel_hidden()

+and panel_window(). Make use of user pointer to store custom data

+for a panel. Use the functions set_panel_userptr() and

+panel_userptr() to set and get the user pointer for a panel.</p>

+</li>

+<li>

+<p>When you are done with the panel use del_panel() to delete the

+panel.</p>

+</li>

+</ol>

+<p>Let's make the concepts clear, with some programs. The following

+is a simple program which creates 3 overlapping panels and shows

+them on the screen.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="COMPILEPANELS" id="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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> #include <panel.h>

+ .

+ compile and link: gcc <program file> -lpanel -lncurses</font>

+</pre></td>

+</tr>

+</table>

+<div class="EXAMPLE"><a name="PPASI" id="PPASI"></a>

+<p><b>Example 14. Panel basics</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <panel.h>

+int main()

+{ WINDOW *my_wins[3];

+ PANEL *my_panels[3];

+ int lines = 10, cols = 40, y = 2, x = 4, i;

+ initscr();

+ cbreak();

+ noecho();

+ /* Create windows for the panels */

+ my_wins[0] = newwin(lines, cols, y, x);

+ my_wins[1] = newwin(lines, cols, y + 1, x + 5);

+ my_wins[2] = newwin(lines, cols, y + 2, x + 10);

+ /*

+ * Create borders around the windows so that you can see the effect

+ * of panels

+ */

+ for(i = 0; i < 3; ++i)

+ box(my_wins[i], 0, 0);

+ /* Attach a panel to each window */ /* Order is bottom up */

+ my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */

+ my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */

+ my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */

+ /* Update the stacking order. 2nd panel will be on top */

+ update_panels();

+ /* Show it on the screen */

+ doupdate();

+ getch();

+ endwin();

+</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>As you can see, above program follows a simple flow as

+explained. The windows are created with newwin() and then they are

+attached to panels with new_panel(). As we attach one panel after

+another, the stack of panels gets updated. To put them on screen

+update_panels() and doupdate() are called.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PANELBROWSING" id="PANELBROWSING">16.3.

+Panel Window Browsing</a></h3>

+<p>A slightly complicated example is given below. This program

+creates 3 windows which can be cycled through using tab. Have a

+look at the code.</p>

+<div class="EXAMPLE"><a name="PPABR" id="PPABR"></a>

+<p><b>Example 15. Panel Window Browsing Example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <panel.h>

+#define NLINES 10

+#define NCOLS 40

+void init_wins(WINDOW **wins, int n);

+void win_show(WINDOW *win, char *label, int label_color);

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);

+int main()

+{ WINDOW *my_wins[3];

+ PANEL *my_panels[3];

+ PANEL *top;

+ int ch;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize all the colors */

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_GREEN, COLOR_BLACK);

+ init_pair(3, COLOR_BLUE, COLOR_BLACK);

+ init_pair(4, COLOR_CYAN, COLOR_BLACK);

+ init_wins(my_wins, 3);

+ /* Attach a panel to each window */ /* Order is bottom up */

+ my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */

+ my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */

+ my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */

+ /* Set up the user pointers to the next panel */

+ set_panel_userptr(my_panels[0], my_panels[1]);

+ set_panel_userptr(my_panels[1], my_panels[2]);

+ set_panel_userptr(my_panels[2], my_panels[0]);

+ /* Update the stacking order. 2nd panel will be on top */

+ update_panels();

+ /* Show it on the screen */

+ attron(COLOR_PAIR(4));

+ mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");

+ attroff(COLOR_PAIR(4));

+ doupdate();

+ top = my_panels[2];

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case 9:

+ top = (PANEL *)panel_userptr(top);

+ top_panel(top);

+ break;

+ }

+ update_panels();

+ doupdate();

+ }

+ endwin();

+ return 0;

+/* Put all the windows */

+void init_wins(WINDOW **wins, int n)

+{ int x, y, i;

+ char label[80];

+ y = 2;

+ x = 10;

+ for(i = 0; i < n; ++i)

+ { wins[i] = newwin(NLINES, NCOLS, y, x);

+ sprintf(label, "Window Number %d", i + 1);

+ win_show(wins[i], label, i + 1);

+ y += 3;

+ x += 7;

+ }

+/* Show the window with a border and a label */

+void win_show(WINDOW *win, char *label, int label_color)

+{ int startx, starty, height, width;

+ getbegyx(win, starty, startx);

+ getmaxyx(win, height, width);

+ box(win, 0, 0);

+ mvwaddch(win, 2, 0, ACS_LTEE);

+ mvwhline(win, 2, 1, ACS_HLINE, width - 2);

+ mvwaddch(win, 2, width - 1, ACS_RTEE);

+ print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ wattron(win, color);

+ mvwprintw(win, y, x, "%s", string);

+ wattroff(win, color);

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="USERPTRUSING" id="USERPTRUSING">16.4.

+Using User Pointers</a></h3>

+<p>In the above example I used user pointers to find out the next

+window in the cycle. We can attach custom information to the panel

+by specifying a user pointer, which can point to any information

+you want to store. In this case I stored the pointer to the next

+panel in the cycle. User pointer for a panel can be set with the

+function <var class="LITERAL">set_panel_userptr()</var>. It can be

+accessed using the function <var class=

+"LITERAL">panel_userptr()</var> which will return the user pointer

+for the panel given as argument. After finding the next panel in

+the cycle It's brought to the top by the function top_panel(). This

+function brings the panel given as argument to the top of the panel

+stack.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PANELMOVERESIZE" id=

+"PANELMOVERESIZE">16.5. Moving and Resizing Panels</a></h3>

+<p>The function <var class="LITERAL">move_panel()</var> can be used

+to move a panel to the desired location. It does not change the

+position of the panel in the stack. Make sure that you use

+move_panel() instead mvwin() on the window associated with the

+panel.</p>

+<p>Resizing a panel is slightly complex. There is no straight

+forward function just to resize the window associated with a panel.

+A solution to resize a panel is to create a new window with the

+desired sizes, change the window associated with the panel using

+replace_panel(). Don't forget to delete the old window. The window

+associated with a panel can be found by using the function

+panel_window().</p>

+<p>The following program shows these concepts, in supposedly simple

+program. You can cycle through the window with <TAB> as

+usual. To resize or move the active panel press 'r' for resize 'm'

+for moving. Then use arrow keys to resize or move it to the desired

+way and press enter to end your resizing or moving. This example

+makes use of user data to get the required data to do the

+operations.</p>

+<div class="EXAMPLE"><a name="PPARE" id="PPARE"></a>

+<p><b>Example 16. Panel Moving and Resizing example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <panel.h>

+typedef struct _PANEL_DATA {

+ int x, y, w, h;

+ char label[80];

+ int label_color;

+ PANEL *next;

+}PANEL_DATA;

+#define NLINES 10

+#define NCOLS 40

+void init_wins(WINDOW **wins, int n);

+void win_show(WINDOW *win, char *label, int label_color);

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);

+void set_user_ptrs(PANEL **panels, int n);

+int main()

+{ WINDOW *my_wins[3];

+ PANEL *my_panels[3];

+ PANEL_DATA *top;

+ PANEL *stack_top;

+ WINDOW *temp_win, *old_win;

+ int ch;

+ int newx, newy, neww, newh;

+ int size = FALSE, move = FALSE;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize all the colors */

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_GREEN, COLOR_BLACK);

+ init_pair(3, COLOR_BLUE, COLOR_BLACK);

+ init_pair(4, COLOR_CYAN, COLOR_BLACK);

+ init_wins(my_wins, 3);

+ /* Attach a panel to each window */ /* Order is bottom up */

+ my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */

+ my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */

+ my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */

+ set_user_ptrs(my_panels, 3);

+ /* Update the stacking order. 2nd panel will be on top */

+ update_panels();

+ /* Show it on the screen */

+ attron(COLOR_PAIR(4));

+ mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing");

+ mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");

+ attroff(COLOR_PAIR(4));

+ doupdate();

+ stack_top = my_panels[2];

+ top = (PANEL_DATA *)panel_userptr(stack_top);

+ newx = top->x;

+ newy = top->y;

+ neww = top->w;

+ newh = top->h;

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case 9: /* Tab */

+ top = (PANEL_DATA *)panel_userptr(stack_top);

+ top_panel(top->next);

+ stack_top = top->next;

+ top = (PANEL_DATA *)panel_userptr(stack_top);

+ newx = top->x;

+ newy = top->y;

+ neww = top->w;

+ newh = top->h;

+ break;

+ case 'r': /* Re-Size*/

+ size = TRUE;

+ attron(COLOR_PAIR(4));

+ mvprintw(LINES - 4, 0, "Entered Resizing :Use Arrow Keys to resize and press <ENTER> to end resizing");

+ refresh();

+ attroff(COLOR_PAIR(4));

+ break;

+ case 'm': /* Move */

+ attron(COLOR_PAIR(4));

+ mvprintw(LINES - 4, 0, "Entered Moving: Use Arrow Keys to Move and press <ENTER> to end moving");

+ refresh();

+ attroff(COLOR_PAIR(4));

+ move = TRUE;

+ break;

+ case KEY_LEFT:

+ if(size == TRUE)

+ { --newx;

+ ++neww;

+ }

+ if(move == TRUE)

+ --newx;

+ break;

+ case KEY_RIGHT:

+ if(size == TRUE)

+ { ++newx;

+ --neww;

+ }

+ if(move == TRUE)

+ ++newx;

+ break;

+ case KEY_UP:

+ if(size == TRUE)

+ { --newy;

+ ++newh;

+ }

+ if(move == TRUE)

+ --newy;

+ break;

+ case KEY_DOWN:

+ if(size == TRUE)

+ { ++newy;

+ --newh;

+ }

+ if(move == TRUE)

+ ++newy;

+ break;

+ case 10: /* Enter */

+ move(LINES - 4, 0);

+ clrtoeol();

+ refresh();

+ if(size == TRUE)

+ { old_win = panel_window(stack_top);

+ temp_win = newwin(newh, neww, newy, newx);

+ replace_panel(stack_top, temp_win);

+ win_show(temp_win, top->label, top->label_color);

+ delwin(old_win);

+ size = FALSE;

+ }

+ if(move == TRUE)

+ { move_panel(stack_top, newy, newx);

+ move = FALSE;

+ }

+ break;

+ }

+ attron(COLOR_PAIR(4));

+ mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing");

+ mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");

+ attroff(COLOR_PAIR(4));

+ refresh();

+ update_panels();

+ doupdate();

+ }

+ endwin();

+ return 0;

+/* Put all the windows */

+void init_wins(WINDOW **wins, int n)

+{ int x, y, i;

+ char label[80];

+ y = 2;

+ x = 10;

+ for(i = 0; i < n; ++i)

+ { wins[i] = newwin(NLINES, NCOLS, y, x);

+ sprintf(label, "Window Number %d", i + 1);

+ win_show(wins[i], label, i + 1);

+ y += 3;

+ x += 7;

+ }

+/* Set the PANEL_DATA structures for individual panels */

+void set_user_ptrs(PANEL **panels, int n)

+{ PANEL_DATA *ptrs;

+ WINDOW *win;

+ int x, y, w, h, i;

+ char temp[80];

+ ptrs = (PANEL_DATA *)calloc(n, sizeof(PANEL_DATA));

+ for(i = 0;i < n; ++i)

+ { win = panel_window(panels[i]);

+ getbegyx(win, y, x);

+ getmaxyx(win, h, w);

+ ptrs[i].x = x;

+ ptrs[i].y = y;

+ ptrs[i].w = w;

+ ptrs[i].h = h;

+ sprintf(temp, "Window Number %d", i + 1);

+ strcpy(ptrs[i].label, temp);

+ ptrs[i].label_color = i + 1;

+ if(i + 1 == n)

+ ptrs[i].next = panels[0];

+ else

+ ptrs[i].next = panels[i + 1];

+ set_panel_userptr(panels[i], &ptrs[i]);

+ }

+/* Show the window with a border and a label */

+void win_show(WINDOW *win, char *label, int label_color)

+{ int startx, starty, height, width;

+ getbegyx(win, starty, startx);

+ getmaxyx(win, height, width);

+ box(win, 0, 0);

+ mvwaddch(win, 2, 0, ACS_LTEE);

+ mvwhline(win, 2, 1, ACS_HLINE, width - 2);

+ mvwaddch(win, 2, width - 1, ACS_RTEE);

+ print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ wattron(win, color);

+ mvwprintw(win, y, x, "%s", string);

+ wattroff(win, color);

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Concentrate on the main while loop. Once it finds out the type

+of key pressed, it takes appropriate action. If 'r' is pressed

+resizing mode is started. After this the new sizes are updated as

+the user presses the arrow keys. When the user presses

+<ENTER> present selection ends and panel is resized by using

+the concept explained. While in resizing mode the program doesn't

+show how the window is getting resized. It's left as an exercise to

+the reader to print a dotted border while it gets resized to a new

+position.</p>

+<p>When the user presses 'm' the move mode starts. This is a bit

+simpler than resizing. As the arrow keys are pressed the new

+position is updated and pressing of <ENTER> causes the panel

+to be moved by calling the function move_panel().</p>

+<p>In this program the user data which is represented as

+PANEL_DATA, plays very important role in finding the associated

+information with a panel. As written in the comments, the

+PANEL_DATA stores the panel sizes, label, label color and a pointer

+to the next panel in the cycle.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PANELSHOWHIDE" id="PANELSHOWHIDE">16.6.

+Hiding and Showing Panels</a></h3>

+<p>A Panel can be hidden by using the function hide_panel(). This

+function merely removes it form the stack of panels, thus hiding it

+on the screen once you do update_panels() and doupdate(). It

+doesn't destroy the PANEL structure associated with the hidden

+panel. It can be shown again by using the show_panel()

+function.</p>

+<p>The following program shows the hiding of panels. Press 'a' or

+'b' or 'c' to show or hide first, second and third windows

+respectively. It uses a user data with a small variable hide, which

+keeps track of whether the window is hidden or not. For some reason

+the function <var class="LITERAL">panel_hidden()</var> which tells

+whether a panel is hidden or not is not working. A bug report was

+also presented by Michael Andres <a href=

+"http://www.geocrawler.com/archives/3/344/1999/9/0/2643549/"

+target="_top">here</a></p>

+<div class="EXAMPLE"><a name="PPAHI" id="PPAHI"></a>

+<p><b>Example 17. Panel Hiding and Showing example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <panel.h>

+typedef struct _PANEL_DATA {

+ int hide; /* TRUE if panel is hidden */

+}PANEL_DATA;

+#define NLINES 10

+#define NCOLS 40

+void init_wins(WINDOW **wins, int n);

+void win_show(WINDOW *win, char *label, int label_color);

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);

+int main()

+{ WINDOW *my_wins[3];

+ PANEL *my_panels[3];

+ PANEL_DATA panel_datas[3];

+ PANEL_DATA *temp;

+ int ch;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize all the colors */

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_GREEN, COLOR_BLACK);

+ init_pair(3, COLOR_BLUE, COLOR_BLACK);

+ init_pair(4, COLOR_CYAN, COLOR_BLACK);

+ init_wins(my_wins, 3);

+ /* Attach a panel to each window */ /* Order is bottom up */

+ my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */

+ my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */

+ my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */

+ /* Initialize panel datas saying that nothing is hidden */

+ panel_datas[0].hide = FALSE;

+ panel_datas[1].hide = FALSE;

+ panel_datas[2].hide = FALSE;

+ set_panel_userptr(my_panels[0], &panel_datas[0]);

+ set_panel_userptr(my_panels[1], &panel_datas[1]);

+ set_panel_userptr(my_panels[2], &panel_datas[2]);

+ /* Update the stacking order. 2nd panel will be on top */

+ update_panels();

+ /* Show it on the screen */

+ attron(COLOR_PAIR(4));

+ mvprintw(LINES - 3, 0, "Show or Hide a window with 'a'(first window) 'b'(Second Window) 'c'(Third Window)");

+ mvprintw(LINES - 2, 0, "F1 to Exit");

+ attroff(COLOR_PAIR(4));

+ doupdate();

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case 'a':

+ temp = (PANEL_DATA *)panel_userptr(my_panels[0]);

+ if(temp->hide == FALSE)

+ { hide_panel(my_panels[0]);

+ temp->hide = TRUE;

+ }

+ else

+ { show_panel(my_panels[0]);

+ temp->hide = FALSE;

+ }

+ break;

+ case 'b':

+ temp = (PANEL_DATA *)panel_userptr(my_panels[1]);

+ if(temp->hide == FALSE)

+ { hide_panel(my_panels[1]);

+ temp->hide = TRUE;

+ }

+ else

+ { show_panel(my_panels[1]);

+ temp->hide = FALSE;

+ }

+ break;

+ case 'c':

+ temp = (PANEL_DATA *)panel_userptr(my_panels[2]);

+ if(temp->hide == FALSE)

+ { hide_panel(my_panels[2]);

+ temp->hide = TRUE;

+ }

+ else

+ { show_panel(my_panels[2]);

+ temp->hide = FALSE;

+ }

+ break;

+ }

+ update_panels();

+ doupdate();

+ }

+ endwin();

+ return 0;

+/* Put all the windows */

+void init_wins(WINDOW **wins, int n)

+{ int x, y, i;

+ char label[80];

+ y = 2;

+ x = 10;

+ for(i = 0; i < n; ++i)

+ { wins[i] = newwin(NLINES, NCOLS, y, x);

+ sprintf(label, "Window Number %d", i + 1);

+ win_show(wins[i], label, i + 1);

+ y += 3;

+ x += 7;

+ }

+/* Show the window with a border and a label */

+void win_show(WINDOW *win, char *label, int label_color)

+{ int startx, starty, height, width;

+ getbegyx(win, starty, startx);

+ getmaxyx(win, height, width);

+ box(win, 0, 0);

+ mvwaddch(win, 2, 0, ACS_LTEE);

+ mvwhline(win, 2, 1, ACS_HLINE, width - 2);

+ mvwaddch(win, 2, width - 1, ACS_RTEE);

+ print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ wattron(win, color);

+ mvwprintw(win, y, x, "%s", string);

+ wattroff(win, color);

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PANELABOVE" id="PANELABOVE">16.7.

+panel_above() and panel_below() Functions</a></h3>

+<p>The functions <var class="LITERAL">panel_above()</var> and

+<var class="LITERAL">panel_below()</var> can be used to find out

+the panel above and below a panel. If the argument to these

+functions is NULL, then they return a pointer to bottom panel and

+top panel respectively.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="MENUS" id="MENUS">17. Menus

+Library</a></h2>

+<p>The menus library provides a nice extension to basic curses,

+through which you can create menus. It provides a set of functions

+to create menus. But they have to be customized to give a nicer

+look, with colors etc. Let's get into the details.</p>

+<p>A menu is a screen display that assists the user to choose some

+subset of a given set of items. To put it simple, a menu is a

+collection of items from which one or more items can be chosen.

+Some readers might not be aware of multiple item selection

+capability. Menu library provides functionality to write menus from

+which the user can chose more than one item as the preferred

+choice. This is dealt with in a later section. Now it is time for

+some rudiments.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MENUBASICS" id="MENUBASICS">17.1. The

+Basics</a></h3>

+<p>To create menus, you first create items, and then post the menu

+to the display. After that, all the processing of user responses is

+done in an elegant function menu_driver() which is the work horse

+of any menu program.</p>

+<p>The general flow of control of a menu program looks like

+this.</p>

+<ol type="1">

+<li>

+<p>Initialize curses</p>

+</li>

+<li>

+<p>Create items using new_item(). You can specify a name and

+description for the items.</p>

+</li>

+<li>

+<p>Create the menu with new_menu() by specifying the items to be

+attached with.</p>

+</li>

+<li>

+<p>Post the menu with menu_post() and refresh the screen.</p>

+</li>

+<li>

+<p>Process the user requests with a loop and do necessary updates

+to menu with menu_driver.</p>

+</li>

+<li>

+<p>Unpost the menu with menu_unpost()</p>

+</li>

+<li>

+<p>Free the memory allocated to menu by free_menu()</p>

+</li>

+<li>

+<p>Free the memory allocated to the items with free_item()</p>

+</li>

+<li>

+<p>End curses</p>

+</li>

+</ol>

+<p>Let's see a program which prints a simple menu and updates the

+current selection with up, down arrows.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="COMPILEMENUS" id="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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> #include <menu.h>

+ .

+ compile and link: gcc <program file> -lmenu -lncurses</font>

+</pre></td>

+</tr>

+</table>

+<div class="EXAMPLE"><a name="MMESI" id="MMESI"></a>

+<p><b>Example 18. Menu Basics</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <curses.h>

+#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Exit",

+ };

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ int n_choices, i;

+ ITEM *cur_item;

+ initscr();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ my_items[i] = new_item(choices[i], choices[i]);

+ my_items[n_choices] = (ITEM *)NULL;

+ my_menu = new_menu((ITEM **)my_items);

+ mvprintw(LINES - 2, 0, "F1 to Exit");

+ post_menu(my_menu);

+ refresh();

+ while((c = getch()) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ }

+ free_item(my_items[0]);

+ free_item(my_items[1]);

+ free_menu(my_menu);

+ endwin();

+ </span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>This program demonstrates the basic concepts involved in

+creating a menu using menus library. First we create the items

+using new_item() and then attach them to the menu with new_menu()

+function. After posting the menu and refreshing the screen, the

+main processing loop starts. It reads user input and takes

+corresponding action. The function menu_driver() is the main work

+horse of the menu system. The second parameter to this function

+tells what's to be done with the menu. According to the parameter,

+menu_driver() does the corresponding task. The value can be either

+a menu navigational request, an ascii character, or a KEY_MOUSE

+special key associated with a mouse event.</p>

+<p>The menu_driver accepts following navigational requests.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> REQ_LEFT_ITEM Move left to an item.

+ REQ_RIGHT_ITEM Move right to an item.

+ REQ_UP_ITEM Move up to an item.

+ REQ_DOWN_ITEM Move down to an item.

+ REQ_SCR_ULINE Scroll up a line.

+ REQ_SCR_DLINE Scroll down a line.

+ REQ_SCR_DPAGE Scroll down a page.

+ REQ_SCR_UPAGE Scroll up a page.

+ REQ_FIRST_ITEM Move to the first item.

+ REQ_LAST_ITEM Move to the last item.

+ REQ_NEXT_ITEM Move to the next item.

+ REQ_PREV_ITEM Move to the previous item.

+ REQ_TOGGLE_ITEM Select/deselect an item.

+ REQ_CLEAR_PATTERN Clear the menu pattern buffer.

+ REQ_BACK_PATTERN Delete the previous character from the pattern buffer.

+ REQ_NEXT_MATCH Move to the next item matching the pattern match.

+ REQ_PREV_MATCH Move to the previous item matching the pattern match.</font>

+</pre></td>

+</tr>

+</table>

+<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 two options when passed to

+menu_driver, menu driver updates the current item to one item up or

+down respectively.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MENUDRIVER" id="MENUDRIVER">17.3. Menu

+Driver: The work horse of the menu system</a></h3>

+<p>As you have seen in the above example, menu_driver plays an

+important role in updating the menu. It is very important to

+understand various options it takes and what they do. As explained

+above, the second parameter to menu_driver() can be either a

+navigational request, a printable character or a KEY_MOUSE key.

+Let's dissect the different navigational requests.</p>

+<ul>

+<li>

+<p><em>REQ_LEFT_ITEM and REQ_RIGHT_ITEM</em></p>

+<p>A Menu can be displayed with multiple columns for more than one

+item. This can be done by using the <var class=

+"LITERAL">menu_format()</var>function. When a multi columnar menu

+is displayed these requests cause the menu driver to move the

+current selection to left or right.</p>

+</li>

+<li>

+<p><em>REQ_UP_ITEM and REQ_DOWN_ITEM</em></p>

+<p>These two options you have seen in the above example. These

+options when given, makes the menu_driver to move the current

+selection to an item up or down.</p>

+</li>

+<li>

+<p><em>REQ_SCR_* options</em></p>

+<p>The four options REQ_SCR_ULINE, REQ_SCR_DLINE, REQ_SCR_DPAGE,

+REQ_SCR_UPAGE are related to scrolling. If all the items in the

+menu cannot be displayed in the menu sub window, then the menu is

+scrollable. These requests can be given to the menu_driver to do

+the scrolling either one line up, down or one page down or up

+respectively.</p>

+</li>

+<li>

+<p><em>REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM and

+REQ_PREV_ITEM</em></p>

+<p>These requests are self explanatory.</p>

+</li>

+<li>

+<p><em>REQ_TOGGLE_ITEM</em></p>

+<p>This request when given, toggles the present selection. This

+option is to be used only in a multi valued menu. So to use this

+request the option O_ONEVALUE must be off. This option can be made

+off or on with set_menu_opts().</p>

+</li>

+<li>

+<p><em>Pattern Requests</em></p>

+<p>Every menu has an associated pattern buffer, which is used to

+find the nearest match to the ascii characters entered by the user.

+Whenever ascii characters are given to menu_driver, it puts in to

+the pattern buffer. It also tries to find the nearest match to the

+pattern in the items list and moves current selection to that item.

+The request REQ_CLEAR_PATTERN clears the pattern buffer. The

+request REQ_BACK_PATTERN deletes the previous character in the

+pattern buffer. In case the pattern matches more than one item then

+the matched items can be cycled through REQ_NEXT_MATCH and

+REQ_PREV_MATCH which move the current selection to the next and

+previous matches respectively.</p>

+</li>

+<li>

+<p><em>Mouse Requests</em></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>

+<table border="0" bgcolor="#E0E0E0" width="90%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"><em> If the second argument is the KEY_MOUSE special key, the

+ associated mouse event is translated into one of the above

+ pre-defined requests. Currently only clicks in the user

+ window (e.g. inside the menu display area or the decora

+ tion window) are handled. If you click above the display

+ region of the menu, a REQ_SCR_ULINE is generated, if you

+ doubleclick a REQ_SCR_UPAGE is generated and if you

+ tripleclick a REQ_FIRST_ITEM is generated. If you click

+ below the display region of the menu, a REQ_SCR_DLINE is

+ generated, if you doubleclick a REQ_SCR_DPAGE is generated

+ and if you tripleclick a REQ_LAST_ITEM is generated. If

+ you click at an item inside the display area of the menu,

+ the menu cursor is positioned to that item.</em></font>

+</pre></td>

+</tr>

+</table>

+</li>

+</ul>

+<p>Each of the above requests will be explained in the following

+lines with several examples whenever appropriate.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MENUWINDOWS" id="MENUWINDOWS">17.4. Menu

+Windows</a></h3>

+<p>Every menu created is associated with a window and a sub window.

+The menu window displays any title or border associated with the

+menu. The menu sub window displays the menu items currently

+available for selection. But we didn't specify any window or sub

+window in the simple example. When a window is not specified,

+stdscr is taken as the main window, and then menu system calculates

+the sub window size required for the display of items. Then items

+are displayed in the calculated sub window. So let's play with

+these windows and display a menu with a border and a title.</p>

+<div class="EXAMPLE"><a name="MMEWI" id="MMEWI"></a>

+<p><b>Example 19. Menu Windows Usage example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Exit",

+ (char *)NULL,

+ };

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ WINDOW *my_menu_win;

+ int n_choices, i;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ /* Create items */

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ my_items[i] = new_item(choices[i], choices[i]);

+ /* Crate menu */

+ my_menu = new_menu((ITEM **)my_items);

+ /* Create the window to be associated with the menu */

+ my_menu_win = newwin(10, 40, 4, 4);

+ keypad(my_menu_win, TRUE);

+ /* Set main window and sub window */

+ set_menu_win(my_menu, my_menu_win);

+ set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1));

+ /* Set menu mark to the string " * " */

+ set_menu_mark(my_menu, " * ");

+ /* Print a border around the main window and print a title */

+ box(my_menu_win, 0, 0);

+ print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1));

+ mvwaddch(my_menu_win, 2, 0, ACS_LTEE);

+ mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38);

+ mvwaddch(my_menu_win, 2, 39, ACS_RTEE);

+ mvprintw(LINES - 2, 0, "F1 to exit");

+ refresh();

+ /* Post the menu */

+ post_menu(my_menu);

+ wrefresh(my_menu_win);

+ while((c = wgetch(my_menu_win)) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ }

+ wrefresh(my_menu_win);

+ }

+ /* Unpost and free all the memory taken up */

+ unpost_menu(my_menu);

+ free_menu(my_menu);

+ for(i = 0; i < n_choices; ++i)

+ free_item(my_items[i]);

+ endwin();

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ wattron(win, color);

+ mvwprintw(win, y, x, "%s", string);

+ wattroff(win, color);

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>This example creates a menu with a title, border, a fancy line

+separating title and the items. As you can see, in order to attach

+a window to a menu the function set_menu_win() has to be used. Then

+we attach the sub window also. This displays the items in the sub

+window. You can also set the mark string which gets displayed to

+the left of the selected item with set_menu_mark().</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="SCROLLMENUS" id="SCROLLMENUS">17.5.

+Scrolling Menus</a></h3>

+<p>If the sub window given for a window is not big enough to show

+all the items, then the menu will be scrollable. When you are on

+the last item in the present list, if you send REQ_DOWN_ITEM, it

+gets translated into REQ_SCR_DLINE and the menu scrolls by one

+item. You can manually give REQ_SCR_ operations to do scrolling.

+Let's see how it can be done.</p>

+<div class="EXAMPLE"><a name="MMESC" id="MMESC"></a>

+<p><b>Example 20. Scrolling Menus example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <curses.h>

+#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Choice 5",

+ "Choice 6",

+ "Choice 7",

+ "Choice 8",

+ "Choice 9",

+ "Choice 10",

+ "Exit",

+ (char *)NULL,

+ };

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ WINDOW *my_menu_win;

+ int n_choices, i;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_CYAN, COLOR_BLACK);

+ /* Create items */

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ my_items[i] = new_item(choices[i], choices[i]);

+ /* Crate menu */

+ my_menu = new_menu((ITEM **)my_items);

+ /* Create the window to be associated with the menu */

+ my_menu_win = newwin(10, 40, 4, 4);

+ keypad(my_menu_win, TRUE);

+ /* Set main window and sub window */

+ set_menu_win(my_menu, my_menu_win);

+ set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1));

+ set_menu_format(my_menu, 5, 1);

+ /* Set menu mark to the string " * " */

+ set_menu_mark(my_menu, " * ");

+ /* Print a border around the main window and print a title */

+ box(my_menu_win, 0, 0);

+ print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1));

+ mvwaddch(my_menu_win, 2, 0, ACS_LTEE);

+ mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38);

+ mvwaddch(my_menu_win, 2, 39, ACS_RTEE);

+ /* Post the menu */

+ post_menu(my_menu);

+ wrefresh(my_menu_win);

+ attron(COLOR_PAIR(2));

+ mvprintw(LINES - 2, 0, "Use PageUp and PageDown to scoll down or up a page of items");

+ mvprintw(LINES - 1, 0, "Arrow Keys to navigate (F1 to Exit)");

+ attroff(COLOR_PAIR(2));

+ refresh();

+ while((c = wgetch(my_menu_win)) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ case KEY_NPAGE:

+ menu_driver(my_menu, REQ_SCR_DPAGE);

+ break;

+ case KEY_PPAGE:

+ menu_driver(my_menu, REQ_SCR_UPAGE);

+ break;

+ }

+ wrefresh(my_menu_win);

+ }

+ /* Unpost and free all the memory taken up */

+ unpost_menu(my_menu);

+ free_menu(my_menu);

+ for(i = 0; i < n_choices; ++i)

+ free_item(my_items[i]);

+ endwin();

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ wattron(win, color);

+ mvwprintw(win, y, x, "%s", string);

+ wattroff(win, color);

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>This program is self-explanatory. In this example the number of

+choices has been increased to ten, which is larger than our sub

+window size which can hold 6 items. This message has to be

+explicitly conveyed to the menu system with the function

+set_menu_format(). In here we specify the number of rows and

+columns we want to be displayed for a single page. We can specify

+any number of items to be shown, in the rows variables, if it is

+less than the height of the sub window. If the key pressed by the

+user is a PAGE UP or PAGE DOWN, the menu is scrolled a page due to

+the requests (REQ_SCR_DPAGE and REQ_SCR_UPAGE) given to

+menu_driver().</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MULTICOLUMN" id="MULTICOLUMN">17.6.

+Multi Columnar Menus</a></h3>

+<p>In the above example you have seen how to use the function

+set_menu_format(). I didn't mention what the cols variable (third

+parameter) does. Well, If your sub window is wide enough, you can

+opt to display more than one item per row. This can be specified in

+the cols variable. To make things simpler, the following example

+doesn't show descriptions for the items.</p>

+<div class="EXAMPLE"><a name="MMEMUCO" id="MMEMUCO"></a>

+<p><b>Example 21. Milt Columnar Menus Example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <curses.h>

+#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5",

+ "Choice 6", "Choice 7", "Choice 8", "Choice 9", "Choice 10",

+ "Choice 11", "Choice 12", "Choice 13", "Choice 14", "Choice 15",

+ "Choice 16", "Choice 17", "Choice 18", "Choice 19", "Choice 20",

+ "Exit",

+ (char *)NULL,

+ };

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ WINDOW *my_menu_win;

+ int n_choices, i;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_CYAN, COLOR_BLACK);

+ /* Create items */

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ my_items[i] = new_item(choices[i], choices[i]);

+ /* Crate menu */

+ my_menu = new_menu((ITEM **)my_items);

+ /* Set menu option not to show the description */

+ menu_opts_off(my_menu, O_SHOWDESC);

+ /* Create the window to be associated with the menu */

+ my_menu_win = newwin(10, 70, 4, 4);

+ keypad(my_menu_win, TRUE);

+ /* Set main window and sub window */

+ set_menu_win(my_menu, my_menu_win);

+ set_menu_sub(my_menu, derwin(my_menu_win, 6, 68, 3, 1));

+ set_menu_format(my_menu, 5, 3);

+ set_menu_mark(my_menu, " * ");

+ /* Print a border around the main window and print a title */

+ box(my_menu_win, 0, 0);

+ attron(COLOR_PAIR(2));

+ mvprintw(LINES - 3, 0, "Use PageUp and PageDown to scroll");

+ mvprintw(LINES - 2, 0, "Use Arrow Keys to navigate (F1 to Exit)");

+ attroff(COLOR_PAIR(2));

+ refresh();

+ /* Post the menu */

+ post_menu(my_menu);

+ wrefresh(my_menu_win);

+ while((c = wgetch(my_menu_win)) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ case KEY_LEFT:

+ menu_driver(my_menu, REQ_LEFT_ITEM);

+ break;

+ case KEY_RIGHT:

+ menu_driver(my_menu, REQ_RIGHT_ITEM);

+ break;

+ case KEY_NPAGE:

+ menu_driver(my_menu, REQ_SCR_DPAGE);

+ break;

+ case KEY_PPAGE:

+ menu_driver(my_menu, REQ_SCR_UPAGE);

+ break;

+ }

+ wrefresh(my_menu_win);

+ }

+ /* Unpost and free all the memory taken up */

+ unpost_menu(my_menu);

+ free_menu(my_menu);

+ for(i = 0; i < n_choices; ++i)

+ free_item(my_items[i]);

+ endwin();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Watch the function call to set_menu_format(). It specifies the

+number of columns to be 3, thus displaying 3 items per row. We have

+also switched off the showing descriptions with the function

+menu_opts_off(). There are 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> O_ONEVALUE

+ Only one item can be selected for this menu.

+ O_SHOWDESC

+ Display the item descriptions when the menu is

+ posted.

+ O_ROWMAJOR

+ Display the menu in row-major order.

+ O_IGNORECASE

+ Ignore the case when pattern-matching.

+ O_SHOWMATCH

+ Move the cursor to within the item name while pat

+ tern-matching.

+ O_NONCYCLIC

+ Don't wrap around next-item and previous-item,

+ requests to the other end of the menu.</font>

+</pre></td>

+</tr>

+</table>

+<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() to directly specify the

+options. The argument to this function should be a OR ed value of

+some of those above constants. The function menu_opts() can be used

+to find out a menu's present options.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MULTIVALUEMENUS" id=

+"MULTIVALUEMENUS">17.7. Multi Valued Menus</a></h3>

+<p>You might be wondering what if you switch off the option

+O_ONEVALUE. Then the menu becomes multi-valued. That means you can

+select more than one item. This brings us to the request

+REQ_TOGGLE_ITEM. Let's see it in action.</p>

+<div class="EXAMPLE"><a name="MMETO" id="MMETO"></a>

+<p><b>Example 22. Multi Valued Menus example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <curses.h>

+#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Choice 5",

+ "Choice 6",

+ "Choice 7",

+ "Exit",

+ };

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ int n_choices, i;

+ ITEM *cur_item;

+ /* Initialize curses */

+ initscr();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize items */

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ my_items[i] = new_item(choices[i], choices[i]);

+ my_items[n_choices] = (ITEM *)NULL;

+ my_menu = new_menu((ITEM **)my_items);

+ /* Make the menu multi valued */

+ menu_opts_off(my_menu, O_ONEVALUE);

+ mvprintw(LINES - 3, 0, "Use <SPACE> to select or unselect an item.");

+ mvprintw(LINES - 2, 0, "<ENTER> to see presently selected items(F1 to Exit)");

+ post_menu(my_menu);

+ refresh();

+ while((c = getch()) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ case ' ':

+ menu_driver(my_menu, REQ_TOGGLE_ITEM);

+ break;

+ case 10: /* Enter */

+ { char temp[200];

+ ITEM **items;

+ items = menu_items(my_menu);

+ temp[0] = '\0';

+ for(i = 0; i < item_count(my_menu); ++i)

+ if(item_value(items[i]) == TRUE)

+ { strcat(temp, item_name(items[i]));

+ strcat(temp, " ");

+ }

+ move(20, 0);

+ clrtoeol();

+ mvprintw(20, 0, temp);

+ refresh();

+ }

+ break;

+ }

+ free_item(my_items[0]);

+ free_item(my_items[1]);

+ free_menu(my_menu);

+ endwin();

+ </span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Whew, A lot of new functions. Let's take them one after another.

+Firstly, the REQ_TOGGLE_ITEM. In a multi-valued menu, the user

+should be allowed to select or un select more than one item. The

+request REQ_TOGGLE_ITEM toggles the present selection. In this case

+when space is pressed REQ_TOGGLE_ITEM request is sent to

+menu_driver to achieve the result.</p>

+<p>Now when the user presses <ENTER> we show the items he

+presently selected. First we find out the items associated with the

+menu using the function menu_items(). Then we loop through the

+items to find out if the item is selected or not. The function

+item_value() returns TRUE if an item is selected. The function

+item_count() returns the number of items in the menu. The item name

+can be found with item_name(). You can also find the description

+associated with an item using item_description().</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MENUOPT" id="MENUOPT">17.8. Menu

+Options</a></h3>

+<p>Well, by this time you must be itching for some difference in

+your menu, with lots of functionality. I know. You want Colors !!!.

+You want to create nice menus similar to those text mode <a href=

+"http://www.jersey.net/~debinjoe/games/" target="_top">dos

+games</a>. The functions set_menu_fore() and set_menu_back() can be

+used to change the attribute of the selected item and unselected

+item. The names are misleading. They don't change menu's foreground

+or background which would have been useless.</p>

+<p>The function set_menu_grey() can be used to set the display

+attribute for the non-selectable items in the menu. This brings us

+to the interesting option for an item the one and only

+O_SELECTABLE. We can turn it off by the function item_opts_off()

+and after that that item is not selectable. It's like a grayed item

+in those fancy windows menus. Let's put these concepts in practice

+with this example</p>

+<div class="EXAMPLE"><a name="MMEAT" id="MMEAT"></a>

+<p><b>Example 23. Menu Options example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Choice 5",

+ "Choice 6",

+ "Choice 7",

+ "Exit",

+ };

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ int n_choices, i;

+ ITEM *cur_item;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_GREEN, COLOR_BLACK);

+ init_pair(3, COLOR_MAGENTA, COLOR_BLACK);

+ /* Initialize items */

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ my_items[i] = new_item(choices[i], choices[i]);

+ my_items[n_choices] = (ITEM *)NULL;

+ item_opts_off(my_items[3], O_SELECTABLE);

+ item_opts_off(my_items[6], O_SELECTABLE);

+ /* Create menu */

+ my_menu = new_menu((ITEM **)my_items);

+ /* Set fore ground and back ground of the menu */

+ set_menu_fore(my_menu, COLOR_PAIR(1) | A_REVERSE);

+ set_menu_back(my_menu, COLOR_PAIR(2));

+ set_menu_grey(my_menu, COLOR_PAIR(3));

+ /* Post the menu */

+ mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected");

+ mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)");

+ post_menu(my_menu);

+ refresh();

+ while((c = getch()) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ case 10: /* Enter */

+ move(20, 0);

+ clrtoeol();

+ mvprintw(20, 0, "Item selected is : %s",

+ item_name(current_item(my_menu)));

+ pos_menu_cursor(my_menu);

+ break;

+ }

+ unpost_menu(my_menu);

+ for(i = 0; i < n_choices; ++i)

+ free_item(my_items[i]);

+ free_menu(my_menu);

+ endwin();

+ </span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MENUUSERPTR" id="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's 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's 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <curses.h>

+#include <menu.h>

+#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))

+#define CTRLD 4

+char *choices[] = {

+ "Choice 1",

+ "Choice 2",

+ "Choice 3",

+ "Choice 4",

+ "Choice 5",

+ "Choice 6",

+ "Choice 7",

+ "Exit",

+ };

+void func(char *name);

+int main()

+{ ITEM **my_items;

+ int c;

+ MENU *my_menu;

+ int n_choices, i;

+ ITEM *cur_item;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_GREEN, COLOR_BLACK);

+ init_pair(3, COLOR_MAGENTA, COLOR_BLACK);

+ /* Initialize items */

+ n_choices = ARRAY_SIZE(choices);

+ my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));

+ for(i = 0; i < n_choices; ++i)

+ { my_items[i] = new_item(choices[i], choices[i]);

+ /* Set the user pointer */

+ set_item_userptr(my_items[i], func);

+ }

+ my_items[n_choices] = (ITEM *)NULL;

+ /* Create menu */

+ my_menu = new_menu((ITEM **)my_items);

+ /* Post the menu */

+ mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected");

+ mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)");

+ post_menu(my_menu);

+ refresh();

+ while((c = getch()) != KEY_F(1))

+ { switch(c)

+ { case KEY_DOWN:

+ menu_driver(my_menu, REQ_DOWN_ITEM);

+ break;

+ case KEY_UP:

+ menu_driver(my_menu, REQ_UP_ITEM);

+ break;

+ case 10: /* Enter */

+ { ITEM *cur;

+ void (*p)(char *);

+ cur = current_item(my_menu);

+ p = item_userptr(cur);

+ p((char *)item_name(cur));

+ pos_menu_cursor(my_menu);

+ break;

+ }

+ break;

+ }

+ unpost_menu(my_menu);

+ for(i = 0; i < n_choices; ++i)

+ free_item(my_items[i]);

+ free_menu(my_menu);

+ endwin();

+void func(char *name)

+{ move(20, 0);

+ clrtoeol();

+ mvprintw(20, 0, "Item selected is : %s", name);

+} </span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="FORMS" id="FORMS">18. Forms

+Library</a></h2>

+<p>Well. If you have seen those forms on web pages which take input

+from users and do various kinds of things, you might be wondering

+how would any one create such forms in text mode display. It's

+quite difficult to write those nifty forms in plain ncurses. Forms

+library tries to provide a basic frame work to build and maintain

+forms with ease. It has lot of features(functions) which manage

+validation, dynamic expansion of fields etc.. Let's see it in full

+flow.</p>

+<p>A form is a collection of fields; each field can be either a

+label(static text) or a data-entry location. The forms also library

+provides functions to divide forms into multiple pages.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="FORMBASICS" id="FORMBASICS">18.1. The

+Basics</a></h3>

+<p>Forms are created in much the same way as menus. First the

+fields related to the form are created with new_field(). You can

+set options for the fields, so that they can be displayed with some

+fancy attributes, validated before the field looses focus etc..

+Then the fields are attached to form. After this, the form can be

+posted to display and is ready to receive inputs. On the similar

+lines to menu_driver(), the form is manipulated with form_driver().

+We can send requests to form_driver to move focus to a certain

+field, move cursor to end of the field etc.. After the user enters

+values in the fields and validation done, form can be unposted and

+memory allocated can be freed.</p>

+<p>The general flow of control of a forms program looks like

+this.</p>

+<ol type="1">

+<li>

+<p>Initialize curses</p>

+</li>

+<li>

+<p>Create fields using new_field(). You can specify the height and

+width of the field, and its position on the form.</p>

+</li>

+<li>

+<p>Create the forms with new_form() by specifying the fields to be

+attached with.</p>

+</li>

+<li>

+<p>Post the form with form_post() and refresh the screen.</p>

+</li>

+<li>

+<p>Process the user requests with a loop and do necessary updates

+to form with form_driver.</p>

+</li>

+<li>

+<p>Unpost the menu with form_unpost()</p>

+</li>

+<li>

+<p>Free the memory allocated to menu by free_form()</p>

+</li>

+<li>

+<p>Free the memory allocated to the items with free_field()</p>

+</li>

+<li>

+<p>End curses</p>

+</li>

+</ol>

+<p>As you can see, working with forms library is much similar to

+handling menu library. The following examples will explore various

+aspects of form processing. Let's start the journey with a simple

+example. first.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="COMPILEFORMS" id="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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"> #include <form.h>

+ .

+ compile and link: gcc <program file> -lform -lncurses</font>

+</pre></td>

+</tr>

+</table>

+<div class="EXAMPLE"><a name="FFOSI" id="FFOSI"></a>

+<p><b>Example 25. Forms Basics</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <form.h>

+int main()

+{ FIELD *field[3];

+ FORM *my_form;

+ int ch;

+ /* Initialize curses */

+ initscr();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize the fields */

+ field[0] = new_field(1, 10, 4, 18, 0, 0);

+ field[1] = new_field(1, 10, 6, 18, 0, 0);

+ field[2] = NULL;

+ /* Set field options */

+ set_field_back(field[0], A_UNDERLINE); /* Print a line for the option */

+ field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */

+ /* Field is filled up */

+ set_field_back(field[1], A_UNDERLINE);

+ field_opts_off(field[1], O_AUTOSKIP);

+ /* Create the form and post it */

+ my_form = new_form(field);

+ post_form(my_form);

+ refresh();

+ mvprintw(4, 10, "Value 1:");

+ mvprintw(6, 10, "Value 2:");

+ refresh();

+ /* Loop through to get user requests */

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case KEY_DOWN:

+ /* Go to next field */

+ form_driver(my_form, REQ_NEXT_FIELD);

+ /* Go to the end of the present buffer */

+ /* Leaves nicely at the last character */

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ case KEY_UP:

+ /* Go to previous field */

+ form_driver(my_form, REQ_PREV_FIELD);

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ default:

+ /* If this is a normal character, it gets */

+ /* Printed */

+ form_driver(my_form, ch);

+ break;

+ }

+ /* Un post form and free the memory */

+ unpost_form(my_form);

+ free_form(my_form);

+ free_field(field[0]);

+ free_field(field[1]);

+ endwin();

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Above example is pretty straight forward. It creates two fields

+with <var class="LITERAL">new_field()</var>. new_field() takes

+height, width, starty, startx, number of offscreen rows and number

+of additional working buffers. The fifth argument number of

+offscreen rows specifies how much of the field to be shown. If it

+is zero, the entire field is always displayed otherwise the form

+will be scrollable when the user accesses not displayed parts of

+the field. The forms library allocates one buffer per field to

+store the data user enters. Using the last parameter to new_field()

+we can specify it to allocate some additional buffers. These can be

+used for any purpose you like.</p>

+<p>After creating the fields, back ground attribute of both of them

+is set to an underscore with set_field_back(). The AUTOSKIP option

+is turned off using field_opts_off(). If this option is turned on,

+focus will move to the next field in the form once the active field

+is filled up completely.</p>

+<p>After attaching the fields to the form, it is posted. Here on,

+user inputs are processed in the while loop, by making

+corresponding requests to form_driver. The details of all the

+requests to the form_driver() are explained later.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PLAYFIELDS" id="PLAYFIELDS">18.3.

+Playing with Fields</a></h3>

+<p>Each form field is associated with a lot of attributes. They can

+be manipulated to get the required effect and to have fun !!!. So

+why wait?</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="FETCHINFO" id="FETCHINFO">18.3.1.

+Fetching Size and Location of Field</a></h4>

+<p>The parameters we have given at the time of creation of a field

+can be retrieved with field_info(). It returns 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">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 */</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="MOVEFIELD" id="MOVEFIELD">18.3.2. Moving

+the field</a></h4>

+<p>The location of the field can be moved to a different position

+with move_field().</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int move_field( FIELD *field, /* field to alter */

+ int top, int left); /* new upper-left corner */</font>

+</pre></td>

+</tr>

+</table>

+<p>As usual, the changed position can be queried with

+field_infor().</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="JUSTIFYFIELD" id="JUSTIFYFIELD">18.3.3.

+Field Justification</a></h4>

+<p>The justification to be done for the field can be fixed using

+the function set_field_just().</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> int set_field_just(FIELD *field, /* field to alter */

+ int justmode); /* mode to set */

+ int field_just(FIELD *field); /* fetch justify mode of field */</font>

+</pre></td>

+</tr>

+</table>

+<p>The justification mode valued accepted and returned by these

+functions are NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or

+JUSTIFY_CENTER.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="FIELDDISPATTRIB" id=

+"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() and setfield_back().

+These functions set foreground and background attribute of the

+fields. You can also specify a pad character which will be filled

+in the unfilled portion of the field. The pad character is set with

+a call to set_field_pad(). Default pad value is a space. The

+functions field_fore(), field_back, field_pad() can be used to

+query the present foreground, background attributes and pad

+character for the field. The following list gives the usage of

+functions.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_fore(FIELD *field, /* field to alter */

+ chtype attr); /* attribute to set */

+chtype field_fore(FIELD *field); /* field to query */

+ /* returns foreground attribute */

+int set_field_back(FIELD *field, /* field to alter */

+ chtype attr); /* attribute to set */

+chtype field_back(FIELD *field); /* field to query */

+ /* returns background attribute */

+int set_field_pad(FIELD *field, /* field to alter */

+ int pad); /* pad character to set */

+chtype field_pad(FIELD *field); /* field to query */

+ /* returns present pad character */</font>

+</pre></td>

+</tr>

+</table>

+<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 background attributes of a field. The

+foreground attribute is associated with the character. That means a

+character in the field is printed with the attribute you have set

+with set_field_fore(). Background attribute is the attribute used

+to fill background of field, whether any character is there or not.

+So what about colors? Since colors are always defined in pairs,

+what is the right way to display colored fields? Here's an example

+clarifying color attributes.</p>

+<div class="EXAMPLE"><a name="FFOAT" id="FFOAT"></a>

+<p><b>Example 26. Form Attributes example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <form.h>

+int main()

+{ FIELD *field[3];

+ FORM *my_form;

+ int ch;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize few color pairs */

+ init_pair(1, COLOR_WHITE, COLOR_BLUE);

+ init_pair(2, COLOR_WHITE, COLOR_BLUE);

+ /* Initialize the fields */

+ field[0] = new_field(1, 10, 4, 18, 0, 0);

+ field[1] = new_field(1, 10, 6, 18, 0, 0);

+ field[2] = NULL;

+ /* Set field options */

+ set_field_fore(field[0], COLOR_PAIR(1));/* Put the field with blue background */

+ set_field_back(field[0], COLOR_PAIR(2));/* and white foreground (characters */

+ /* are printed in white */

+ field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */

+ /* Field is filled up */

+ set_field_back(field[1], A_UNDERLINE);

+ field_opts_off(field[1], O_AUTOSKIP);

+ /* Create the form and post it */

+ my_form = new_form(field);

+ post_form(my_form);

+ refresh();

+ set_current_field(my_form, field[0]); /* Set focus to the colored field */

+ mvprintw(4, 10, "Value 1:");

+ mvprintw(6, 10, "Value 2:");

+ mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields");

+ refresh();

+ /* Loop through to get user requests */

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case KEY_DOWN:

+ /* Go to next field */

+ form_driver(my_form, REQ_NEXT_FIELD);

+ /* Go to the end of the present buffer */

+ /* Leaves nicely at the last character */

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ case KEY_UP:

+ /* Go to previous field */

+ form_driver(my_form, REQ_PREV_FIELD);

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ default:

+ /* If this is a normal character, it gets */

+ /* Printed */

+ form_driver(my_form, ch);

+ break;

+ }

+ /* Un post form and free the memory */

+ unpost_form(my_form);

+ free_form(my_form);

+ free_field(field[0]);

+ free_field(field[1]);

+ endwin();

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>Play with the color pairs and try to understand the foreground

+and background attributes. In my programs using color attributes, I

+usually set only the background with set_field_back(). Curses

+simply doesn't allow defining individual color attributes.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="FIELDOPTIONBITS" id=

+"FIELDOPTIONBITS">18.3.5. 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_opts(FIELD *field, /* field to alter */

+ int attr); /* attribute to set */

+int field_opts_on(FIELD *field, /* field to alter */

+ int attr); /* attributes to turn on */

+int field_opts_off(FIELD *field, /* field to alter */

+ int attr); /* attributes to turn off */

+int field_opts(FIELD *field); /* field to query */ </font>

+</pre></td>

+</tr>

+</table>

+<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 field_opts_off() selectively.

+Anytime you can query the attributes of a field with field_opts().

+The following is the list of available options. By default, all

+options are on.</p>

+<div class="VARIABLELIST">

+<dl>

+<dt>O_VISIBLE</dt>

+<dd>

+<p>Controls whether the field is visible on the screen. Can be used

+during form processing to hide or pop up fields depending on the

+value of parent fields.</p>

+</dd>

+<dt>O_ACTIVE</dt>

+<dd>

+<p>Controls whether the field is active during forms processing

+(i.e. visited by form navigation keys). Can be used to make labels

+or derived fields with buffer values alterable by the forms

+application, not the user.</p>

+</dd>

+<dt>O_PUBLIC</dt>

+<dd>

+<p>Controls whether data is displayed during field entry. If this

+option is turned off on a field, the library will accept and edit

+data in that field, but it will not be displayed and the visible

+field cursor will not move. You can turn off the O_PUBLIC bit to

+define password fields.</p>

+</dd>

+<dt>O_EDIT</dt>

+<dd>

+<p>Controls whether the field's data can be modified. When this

+option is off, all editing requests except <var class=

+"LITERAL">REQ_PREV_CHOICE</var> and <var class=

+"LITERAL">REQ_NEXT_CHOICE</var>will fail. Such read-only fields may

+be useful for help messages.</p>

+</dd>

+<dt>O_WRAP</dt>

+<dd>

+<p>Controls word-wrapping in multi-line fields. Normally, when any

+character of a (blank-separated) word reaches the end of the

+current line, the entire word is wrapped to the next line (assuming

+there is one). When this option is off, the word will be split

+across the line break.</p>

+</dd>

+<dt>O_BLANK</dt>

+<dd>

+<p>Controls field blanking. When this option is on, entering a

+character at the first field position erases the entire field

+(except for the just-entered character).</p>

+</dd>

+<dt>O_AUTOSKIP</dt>

+<dd>

+<p>Controls automatic skip to next field when this one fills.

+Normally, when the forms user tries to type more data into a field

+than will fit, the editing location jumps to next field. When this

+option is off, the user's cursor will hang at the end of the field.

+This option is ignored in dynamic fields that have not reached

+their size limit.</p>

+</dd>

+<dt>O_NULLOK</dt>

+<dd>

+<p>Controls whether validation is applied to blank fields.

+Normally, it is not; the user can leave a field blank without

+invoking the usual validation check on exit. If this option is off

+on a field, exit from it will invoke a validation check.</p>

+</dd>

+<dt>O_PASSOK</dt>

+<dd>

+<p>Controls whether validation occurs on every exit, or only after

+the field is modified. Normally the latter is true. Setting

+O_PASSOK may be useful if your field's validation function may

+change during forms processing.</p>

+</dd>

+<dt>O_STATIC</dt>

+<dd>

+<p>Controls whether the field is fixed to its initial dimensions.

+If you turn this off, the field becomes dynamic and will stretch to

+fit entered data.</p>

+</dd>

+</dl>

+</div>

+<p>A field's options cannot be changed while the field is currently

+selected. However, options may be changed on posted fields that are

+not current.</p>

+<p>The option values are bit-masks and can be composed with

+logical-or in the obvious way. You have seen the usage of switching

+off O_AUTOSKIP option. The following example clarifies usage of

+some more options. Other options are explained where

+appropriate.</p>

+<div class="EXAMPLE"><a name="FFOOP" id="FFOOP"></a>

+<p><b>Example 27. Field Options Usage example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <form.h>

+#define STARTX 15

+#define STARTY 4

+#define WIDTH 25

+#define N_FIELDS 3

+int main()

+{ FIELD *field[N_FIELDS];

+ FORM *my_form;

+ int ch, i;

+ /* Initialize curses */

+ initscr();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize the fields */

+ for(i = 0; i < N_FIELDS - 1; ++i)

+ field[i] = new_field(1, WIDTH, STARTY + i * 2, STARTX, 0, 0);

+ field[N_FIELDS - 1] = NULL;

+ /* Set field options */

+ set_field_back(field[1], A_UNDERLINE); /* Print a line for the option */

+ field_opts_off(field[0], O_ACTIVE); /* This field is a static label */

+ field_opts_off(field[1], O_PUBLIC); /* This filed is like a password field*/

+ field_opts_off(field[1], O_AUTOSKIP); /* To avoid entering the same field */

+ /* after last character is entered */

+ /* Create the form and post it */

+ my_form = new_form(field);

+ post_form(my_form);

+ refresh();

+ set_field_just(field[0], JUSTIFY_CENTER); /* Center Justification */

+ set_field_buffer(field[0], 0, "This is a static Field");

+ /* Initialize the field */

+ mvprintw(STARTY, STARTX - 10, "Field 1:");

+ mvprintw(STARTY + 2, STARTX - 10, "Field 2:");

+ refresh();

+ /* Loop through to get user requests */

+ while((ch = getch()) != KEY_F(1))

+ { switch(ch)

+ { case KEY_DOWN:

+ /* Go to next field */

+ form_driver(my_form, REQ_NEXT_FIELD);

+ /* Go to the end of the present buffer */

+ /* Leaves nicely at the last character */

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ case KEY_UP:

+ /* Go to previous field */

+ form_driver(my_form, REQ_PREV_FIELD);

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ default:

+ /* If this is a normal character, it gets */

+ /* Printed */

+ form_driver(my_form, ch);

+ break;

+ }

+ /* Un post form and free the memory */

+ unpost_form(my_form);

+ free_form(my_form);

+ free_field(field[0]);

+ free_field(field[1]);

+ endwin();

+ return 0;

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<p>This example, though useless, shows the usage of options. If

+used properly, they can present information very effectively in a

+form. The second field being not O_PUBLIC, does not show the

+characters you are typing.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="FIELDSTATUS" id="FIELDSTATUS">18.3.6.

+Field Status</a></h4>

+<p>The field status specifies whether the field has got edited or

+not. It is initially set to FALSE and when user enters something

+and the data buffer gets modified it 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_status(FIELD *field, /* field to alter */

+ int status); /* status to set */

+int field_status(FIELD *field); /* fetch status of field */</font>

+</pre></td>

+</tr>

+</table>

+<p>It's 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 guarantee that right status is

+returned, call field_status() either (1) in the field's exit

+validation check routine, (2) from the field's or form's

+initialization or termination hooks, or (3) just after a

+REQ_VALIDATION request has been processed by the forms driver</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="FIELDUSERPTR" id="FIELDUSERPTR">18.3.7.

+Field User Pointer</a></h4>

+<p>Every field structure contains one pointer that can be used by

+the user for various purposes. It is not touched by forms library

+and can be used for any purpose by the user. The following

+functions set and fetch user pointer.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">int set_field_userptr(FIELD *field,

+ char *userptr); /* the user pointer you wish to associate */

+ /* with the field */

+char *field_userptr(FIELD *field); /* fetch user pointer of the field */</font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="VARIABLESIZEFIELDS" id=

+"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. This will allow

+the user to enter more data than the original size of the field and

+let the field grow. According to the field orientation it will

+scroll horizontally or vertically to incorporate the new data.</p>

+<p>To make a field dynamically growable, the option O_STATIC should

+be turned off. This can be done with a</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"> field_opts_off(field_pointer, O_STATIC);</font>

+</pre></td>

+</tr>

+</table>

+<p>But it's usually not advisable to allow a field to grow

+infinitely. You can set a maximum limit to the growth of the field

+with</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_max_field(FIELD *field, /* Field on which to operate */

+ int max_growth); /* maximum growth allowed for the field */</font>

+</pre></td>

+</tr>

+</table>

+<p>The field info for a dynamically growable field can be retrieved

+by</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int dynamic_field_info( FIELD *field, /* Field on which to operate */

+ int *prows, /* number of rows will be filled in this */

+ int *pcols, /* number of columns will be filled in this*/

+ int *pmax) /* maximum allowable growth will be filled */

+ /* in this */</font>

+</pre></td>

+</tr>

+</table>

+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 than one will be defined to be a

+multi line field.</p>

+<p>A one line field with O_STATIC turned off (dynamically growable

+field) will contain a single fixed row, but the number of columns

+can increase if the user enters more data than the initial field

+will hold. The number of columns displayed will remain fixed and

+the additional data will scroll horizontally.</p>

+<p>A multi line field with O_STATIC turned off (dynamically

+growable field) will contain a fixed number of columns, but the

+number of rows can increase if the user enters more data than the

+initial field will hold. The number of rows displayed will remain

+fixed and the additional data will scroll vertically.</p>

+<p>The above two paragraphs pretty much describe a dynamically

+growable field's behavior. The way other parts of forms library

+behaves is described below:</p>

+<ol type="1">

+<li>

+<p>The field option O_AUTOSKIP will be ignored if the option

+O_STATIC is off and there is no maximum growth specified for the

+field. Currently, O_AUTOSKIP generates an automatic REQ_NEXT_FIELD

+form driver request when the user types in the last character

+position of a field. On a growable field with no maximum growth

+specified, there is no last character position. If a maximum growth

+is specified, the O_AUTOSKIP option will work as normal if the

+field has grown to its maximum size.</p>

+</li>

+<li>

+<p>The field justification will be ignored if the option O_STATIC

+is off. Currently, set_field_just can be used to JUSTIFY_LEFT,

+JUSTIFY_RIGHT, JUSTIFY_CENTER the contents of a one line field. A

+growable one line field will, by definition, grow and scroll

+horizontally and may contain more data than can be justified. The

+return from field_just will be unchanged.</p>

+</li>

+<li>

+<p>The overloaded form driver request REQ_NEW_LINE will operate the

+same way regardless of the O_NL_OVERLOAD form option if the field

+option O_STATIC is off and there is no maximum growth specified for

+the field. Currently, if the form option O_NL_OVERLOAD is on,

+REQ_NEW_LINE implicitly generates a REQ_NEXT_FIELD if called from

+the last line of a field. If a field can grow without bound, there

+is no last line, so REQ_NEW_LINE will never implicitly generate a

+REQ_NEXT_FIELD. If a maximum growth limit is specified and the

+O_NL_OVERLOAD form option is on, REQ_NEW_LINE will only implicitly

+generate REQ_NEXT_FIELD if the field has grown to its maximum size

+and the user is on the last line.</p>

+</li>

+<li>

+<p>The library call dup_field will work as usual; it will duplicate

+the field, including the current buffer size and contents of the

+field being duplicated. Any specified maximum growth will also be

+duplicated.</p>

+</li>

+<li>

+<p>The library call link_field will work as usual; it will

+duplicate all field attributes and share buffers with the field

+being linked. If the O_STATIC field option is subsequently changed

+by a field sharing buffers, how the system reacts to an attempt to

+enter more data into the field than the buffer will currently hold

+will depend on the setting of the option in the current field.</p>

+</li>

+<li>

+<p>The library call field_info will work as usual; the variable

+nrow will contain the value of the original call to new_field. The

+user should use dynamic_field_info, described above, to query the

+current size of the buffer.</p>

+</li>

+</ol>

+<p>Some of the above points make sense only after explaining form

+driver. We will be looking into that in next few sections.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="FORMWINDOWS" id="FORMWINDOWS">18.4. Form

+Windows</a></h3>

+<p>The form windows concept is pretty much similar to menu windows.

+Every form is associated with a main window and a sub window. The

+form main window displays any title or border associated or

+whatever the user wishes. Then the sub window contains all the

+fields and displays them according to their position. This gives

+the flexibility of manipulating fancy form displaying very

+easily.</p>

+<p>Since this is pretty much similar to menu windows, I am

+providing an example with out much explanation. The functions are

+similar and they work the same way.</p>

+<div class="EXAMPLE"><a name="FFOWI" id="FFOWI"></a>

+<p><b>Example 28. Form Windows Example</b></p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000"><span class=

+"INLINEMEDIAOBJECT">#include <form.h>

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);

+int main()

+ FIELD *field[3];

+ FORM *my_form;

+ WINDOW *my_form_win;

+ int ch, rows, cols;

+ /* Initialize curses */

+ initscr();

+ start_color();

+ cbreak();

+ noecho();

+ keypad(stdscr, TRUE);

+ /* Initialize few color pairs */

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ /* Initialize the fields */

+ field[0] = new_field(1, 10, 6, 1, 0, 0);

+ field[1] = new_field(1, 10, 8, 1, 0, 0);

+ field[2] = NULL;

+ /* Set field options */

+ set_field_back(field[0], A_UNDERLINE);

+ field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */

+ /* Field is filled up */

+ set_field_back(field[1], A_UNDERLINE);

+ field_opts_off(field[1], O_AUTOSKIP);

+ /* Create the form and post it */

+ my_form = new_form(field);

+ /* Calculate the area required for the form */

+ scale_form(my_form, &rows, &cols);

+ /* Create the window to be associated with the form */

+ my_form_win = newwin(rows + 4, cols + 4, 4, 4);

+ keypad(my_form_win, TRUE);

+ /* Set main window and sub window */

+ set_form_win(my_form, my_form_win);

+ set_form_sub(my_form, derwin(my_form_win, rows, cols, 2, 2));

+ /* Print a border around the main window and print a title */

+ box(my_form_win, 0, 0);

+ print_in_middle(my_form_win, 1, 0, cols + 4, "My Form", COLOR_PAIR(1));

+ post_form(my_form);

+ wrefresh(my_form_win);

+ mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields");

+ refresh();

+ /* Loop through to get user requests */

+ while((ch = wgetch(my_form_win)) != KEY_F(1))

+ { switch(ch)

+ { case KEY_DOWN:

+ /* Go to next field */

+ form_driver(my_form, REQ_NEXT_FIELD);

+ /* Go to the end of the present buffer */

+ /* Leaves nicely at the last character */

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ case KEY_UP:

+ /* Go to previous field */

+ form_driver(my_form, REQ_PREV_FIELD);

+ form_driver(my_form, REQ_END_LINE);

+ break;

+ default:

+ /* If this is a normal character, it gets */

+ /* Printed */

+ form_driver(my_form, ch);

+ break;

+ }

+ /* Un post form and free the memory */

+ unpost_form(my_form);

+ free_form(my_form);

+ free_field(field[0]);

+ free_field(field[1]);

+ endwin();

+ return 0;

+void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)

+{ int length, x, y;

+ float temp;

+ if(win == NULL)

+ win = stdscr;

+ getyx(win, y, x);

+ if(startx != 0)

+ x = startx;

+ if(starty != 0)

+ y = starty;

+ if(width == 0)

+ width = 80;

+ length = strlen(string);

+ temp = (width - length)/ 2;

+ x = startx + (int)temp;

+ wattron(win, color);

+ mvwprintw(win, y, x, "%s", string);

+ wattroff(win, color);

+ refresh();

+}</span></font>

+</pre></td>

+</tr>

+</table>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="FILEDVALIDATE" id="FILEDVALIDATE">18.5.

+Field Validation</a></h3>

+<p>By default, a field will accept any data input by the user. It

+is possible to attach validation to the field. Then any attempt by

+the user to leave the field, while it contains data that doesn't

+match the validation type will fail. Some validation types also

+have a character-validity check for each time a character is

+entered in the field.</p>

+<p>Validation can be attached to a field with the following

+function.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_type(FIELD *field, /* field to alter */

+ FIELDTYPE *ftype, /* type to associate */

+ ...); /* additional arguments*/</font>

+</pre></td>

+</tr>

+</table>

+Once set, the validation type for a field can be queried with

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">FIELDTYPE *field_type(FIELD *field); /* field to query */</font>

+</pre></td>

+</tr>

+</table>

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

+<ul>

+<li>

+<p>the application program changes the field value by calling

+set_field_buffer.</p>

+</li>

+<li>

+<p>linked field values are changed indirectly -- by changing the

+field to which they are linked</p>

+</li>

+</ul>

+<p>The following are the pre-defined validation types. You can also

+specify custom validation, though it's a bit tricky and

+cumbersome.</p>

+<h1 class="BRIDGEHEAD"><a name="AEN1069" id=

+"AEN1069"></a>TYPE_ALPHA</h1>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_type(FIELD *field, /* field to alter */

+ TYPE_ALPHA, /* type to associate */

+ int width); /* maximum width of field */</font>

+</pre></td>

+</tr>

+</table>

+<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 this to the field width; if

+it's 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="AEN1073" id=

+"AEN1073"></a>TYPE_ALNUM</h1>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_type(FIELD *field, /* field to alter */

+ TYPE_ALNUM, /* type to associate */

+ int width); /* maximum width of field */</font>

+</pre></td>

+</tr>

+</table>

+<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's 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>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">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? */</font>

+</pre></td>

+</tr>

+</table>

+<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>When the user exits a TYPE_ENUM field, the validation procedure

+tries to complete the data in the buffer to a valid entry. If a

+complete choice string has been entered, it is of course valid. But

+it is also possible to enter a prefix of a valid string and have it

+completed for you.</p>

+<p>By default, if you enter such a prefix and it matches more than

+one value in the string list, the prefix will be completed to the

+first matching value. But the checkunique argument, if true,

+requires prefix matches to be unique in order to be valid.</p>

+<p>The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be

+particularly useful with these fields.</p>

+<h1 class="BRIDGEHEAD"><a name="AEN1084" id=

+"AEN1084"></a>TYPE_INTEGER</h1>

+<p>This field type accepts an integer. It is set up as follows:</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">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 */</font>

+</pre></td>

+</tr>

+</table>

+<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 ignored.</p>

+<p>If the value passes its range check, it is padded with as many

+leading zero digits as necessary to meet the padding argument.</p>

+<p>A TYPE_INTEGER value buffer can conveniently be interpreted with

+the C library function atoi(3).</p>

+<h1 class="BRIDGEHEAD"><a name="AEN1090" id=

+"AEN1090"></a>TYPE_NUMERIC</h1>

+<p>This field type accepts a decimal number. It is set up as

+follows:</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">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 */</font>

+</pre></td>

+</tr>

+</table>

+<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 than or equal to

+the minimum, the range is ignored.</p>

+<p>If the value passes its range check, it is padded with as many

+trailing zero digits as necessary to meet the padding argument.</p>

+<p>A TYPE_NUMERIC value buffer can conveniently be interpreted with

+the C library function atof(3).</p>

+<h1 class="BRIDGEHEAD"><a name="AEN1096" id=

+"AEN1096"></a>TYPE_REGEXP</h1>

+<p>This field type accepts data matching a regular expression. It

+is set up as follows:</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int set_field_type(FIELD *field, /* field to alter */

+ TYPE_REGEXP, /* type to associate */

+ char *regexp); /* expression to match */</font>

+</pre></td>

+</tr>

+</table>

+<p>The syntax for regular expressions is that of regcomp(3). The

+check for regular-expression match is performed on exit.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="FORMDRIVER" id="FORMDRIVER">18.6. Form

+Driver: The work horse of the forms system</a></h3>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">int form_driver(FORM *form, /* form on which to operate */

+ int request) /* form request code */</font>

+</pre></td>

+</tr>

+</table>

+<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's a field

+data or a form request. The form requests are then passed to

+form_driver() to do the work.</p>

+<p>The requests roughly can be divided into following categories.

+Different requests and their usage is explained below:</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="PAGENAVREQ" id="PAGENAVREQ">18.6.1. Page

+Navigation Requests</a></h4>

+<p>These requests cause page-level moves through the form,

+triggering display of a new form screen. A form can be made of

+multiple pages. If you have a big form with 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>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">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 */</font>

+</pre></td>

+</tr>

+</table>

+<p>The following requests allow you to move to different pages</p>

+<ul>

+<li>

+<p><em>REQ_NEXT_PAGE</em> Move to the next form page.</p>

+</li>

+<li>

+<p><em>REQ_PREV_PAGE</em> Move to the previous form page.</p>

+</li>

+<li>

+<p><em>REQ_FIRST_PAGE</em> Move to the first form page.</p>

+</li>

+<li>

+<p><em>REQ_LAST_PAGE</em> Move to the last form page.</p>

+</li>

+</ul>

+<p>These requests treat the list as cyclic; that is, REQ_NEXT_PAGE

+from the last page goes to the first, and REQ_PREV_PAGE from the

+first page goes to the last.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="INTERFIELDNAVREQ" id=

+"INTERFIELDNAVREQ">18.6.2. Inter-Field Navigation Requests</a></h4>

+<p>These requests handle navigation between fields on the same

+page.</p>

+<ul>

+<li>

+<p><em>REQ_NEXT_FIELD</em> Move to next field.</p>

+</li>

+<li>

+<p><em>REQ_PREV_FIELD</em> Move to previous field.</p>

+</li>

+<li>

+<p><em>REQ_FIRST_FIELD</em> Move to the first field.</p>

+</li>

+<li>

+<p><em>REQ_LAST_FIELD</em> Move to the last field.</p>

+</li>

+<li>

+<p><em>REQ_SNEXT_FIELD</em> Move to sorted next field.</p>

+</li>

+<li>

+<p><em>REQ_SPREV_FIELD</em> Move to sorted previous field.</p>

+</li>

+<li>

+<p><em>REQ_SFIRST_FIELD</em> Move to the sorted first field.</p>

+</li>

+<li>

+<p><em>REQ_SLAST_FIELD</em> Move to the sorted last field.</p>

+</li>

+<li>

+<p><em>REQ_LEFT_FIELD</em> Move left to field.</p>

+</li>

+<li>

+<p><em>REQ_RIGHT_FIELD</em> Move right to field.</p>

+</li>

+<li>

+<p><em>REQ_UP_FIELD</em> Move up to field.</p>

+</li>

+<li>

+<p><em>REQ_DOWN_FIELD</em> Move down to field.</p>

+</li>

+</ul>

+<p>These requests treat the list of fields on a page as cyclic;

+that is, REQ_NEXT_FIELD from the last field goes to the first, and

+REQ_PREV_FIELD from the first field goes to the last. The order of

+the fields for these (and the REQ_FIRST_FIELD and REQ_LAST_FIELD

+requests) is simply the order of the field pointers in the form

+array (as set up by new_form() or set_form_fields()</p>

+<p>It is also possible to traverse the fields as if they had been

+sorted in screen-position order, so the sequence goes left-to-right

+and top-to-bottom. To do this, use the second group of four

+sorted-movement requests.</p>

+<p>Finally, it is possible to move between fields using visual

+directions up, down, right, and left. To accomplish this, use the

+third group of four requests. Note, however, that the position of a

+form for purposes of these requests is its upper-left corner.</p>

+<p>For example, suppose you have a multi-line field B, and two

+single-line fields A and C on the same line with B, with A to the

+left of B and C to the right of B. A REQ_MOVE_RIGHT 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.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="INTRAFIELDNAVREQ" id=

+"INTRAFIELDNAVREQ">18.6.3. Intra-Field Navigation Requests</a></h4>

+<p>These requests drive movement of the edit cursor within the

+currently selected field.</p>

+<ul>

+<li>

+<p><em>REQ_NEXT_CHAR</em> Move to next character.</p>

+</li>

+<li>

+<p><em>REQ_PREV_CHAR</em> Move to previous character.</p>

+</li>

+<li>

+<p><em>REQ_NEXT_LINE</em> Move to next line.</p>

+</li>

+<li>

+<p><em>REQ_PREV_LINE</em> Move to previous line.</p>

+</li>

+<li>

+<p><em>REQ_NEXT_WORD</em> Move to next word.</p>

+</li>

+<li>

+<p><em>REQ_PREV_WORD</em> Move to previous word.</p>

+</li>

+<li>

+<p><em>REQ_BEG_FIELD</em> Move to beginning of field.</p>

+</li>

+<li>

+<p><em>REQ_END_FIELD</em> Move to end of field.</p>

+</li>

+<li>

+<p><em>REQ_BEG_LINE</em> Move to beginning of line.</p>

+</li>

+<li>

+<p><em>REQ_END_LINE</em> Move to end of line.</p>

+</li>

+<li>

+<p><em>REQ_LEFT_CHAR</em> Move left in field.</p>

+</li>

+<li>

+<p><em>REQ_RIGHT_CHAR</em> Move right in field.</p>

+</li>

+<li>

+<p><em>REQ_UP_CHAR</em> Move up in field.</p>

+</li>

+<li>

+<p><em>REQ_DOWN_CHAR</em> Move down in field.</p>

+</li>

+</ul>

+<p>Each word is separated from the previous and next characters by

+whitespace. The commands to move to beginning and end of line or

+field look for the first or last non-pad character in their

+ranges.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="SCROLLREQ" id="SCROLLREQ">18.6.4.

+Scrolling Requests</a></h4>

+<p>Fields that are dynamic and have grown and fields explicitly

+created with offscreen rows are scrollable. One-line fields scroll

+horizontally; multi-line fields scroll vertically. Most scrolling

+is triggered by editing and intra-field movement (the library

+scrolls the field to keep the cursor visible). It is possible to

+explicitly request scrolling with the following requests:</p>

+<ul>

+<li>

+<p><em>REQ_SCR_FLINE</em> Scroll vertically forward a line.</p>

+</li>

+<li>

+<p><em>REQ_SCR_BLINE</em> Scroll vertically backward a line.</p>

+</li>

+<li>

+<p><em>REQ_SCR_FPAGE</em> Scroll vertically forward a page.</p>

+</li>

+<li>

+<p><em>REQ_SCR_BPAGE</em> Scroll vertically backward a page.</p>

+</li>

+<li>

+<p><em>REQ_SCR_FHPAGE</em> Scroll vertically forward half a

+page.</p>

+</li>

+<li>

+<p><em>REQ_SCR_BHPAGE</em> Scroll vertically backward half a

+page.</p>

+</li>

+<li>

+<p><em>REQ_SCR_FCHAR</em> Scroll horizontally forward a

+character.</p>

+</li>

+<li>

+<p><em>REQ_SCR_BCHAR</em> Scroll horizontally backward a

+character.</p>

+</li>

+<li>

+<p><em>REQ_SCR_HFLINE</em> Scroll horizontally one field width

+forward.</p>

+</li>

+<li>

+<p><em>REQ_SCR_HBLINE</em> Scroll horizontally one field width

+backward.</p>

+</li>

+<li>

+<p><em>REQ_SCR_HFHALF</em> Scroll horizontally one half field width

+forward.</p>

+</li>

+<li>

+<p><em>REQ_SCR_HBHALF</em> Scroll horizontally one half field width

+backward.</p>

+</li>

+</ul>

+<p>For scrolling purposes, a page of a field is the height of its

+visible part.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="EDITREQ" id="EDITREQ">18.6.5. 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 buffer.

+Whether this is an insertion or a replacement depends on the

+field's edit mode (insertion is the default.</p>

+<p>The following requests support editing the field and changing

+the edit mode:</p>

+<ul>

+<li>

+<p><em>REQ_INS_MODE</em> Set insertion mode.</p>

+</li>

+<li>

+<p><em>REQ_OVL_MODE</em> Set overlay mode.</p>

+</li>

+<li>

+<p><em>REQ_NEW_LINE</em> New line request (see below for

+explanation).</p>

+</li>

+<li>

+<p><em>REQ_INS_CHAR</em> Insert space at character location.</p>

+</li>

+<li>

+<p><em>REQ_INS_LINE</em> Insert blank line at character

+location.</p>

+</li>

+<li>

+<p><em>REQ_DEL_CHAR</em> Delete character at cursor.</p>

+</li>

+<li>

+<p><em>REQ_DEL_PREV</em> Delete previous word at cursor.</p>

+</li>

+<li>

+<p><em>REQ_DEL_LINE</em> Delete line at cursor.</p>

+</li>

+<li>

+<p><em>REQ_DEL_WORD</em> Delete word at cursor.</p>

+</li>

+<li>

+<p><em>REQ_CLR_EOL</em> Clear to end of line.</p>

+</li>

+<li>

+<p><em>REQ_CLR_EOF</em> Clear to end of field.</p>

+</li>

+<li>

+<p><em>REQ_CLR_FIELD</em> Clear entire field.</p>

+</li>

+</ul>

+<p>The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is

+complicated and partly controlled by a pair of forms options. The

+special cases are triggered when the cursor is at the beginning of

+a field, or on the last line of the field.</p>

+<p>First, we consider REQ_NEW_LINE:</p>

+<p>The normal behavior of REQ_NEW_LINE in insert mode is to break

+the current line at the position of the edit cursor, inserting the

+portion of the current line after the cursor as a new line

+following the current and moving the cursor to the beginning of

+that new line (you may think of this as inserting a newline in the

+field buffer).</p>

+<p>The normal behavior of REQ_NEW_LINE in overlay mode is to clear

+the current line from the position of the edit cursor to end of

+line. The cursor is then moved to the beginning of the next

+line.</p>

+<p>However, REQ_NEW_LINE at the beginning of a field, or on the

+last line of a field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD

+option is off, this special action is disabled.</p>

+<p>Now, let us consider REQ_DEL_PREV:</p>

+<p>The normal behavior of REQ_DEL_PREV is to delete the previous

+character. If insert mode is on, and the cursor is at the start of

+a line, and the text on that line will fit on the previous one, it

+instead appends the contents of the current line to the previous

+one and deletes the current line (you may think of this as deleting

+a newline from the field buffer).</p>

+<p>However, REQ_DEL_PREV at the beginning of a field is instead

+treated as a REQ_PREV_FIELD.</p>

+<p>If the O_BS_OVERLOAD option is off, this special action is

+disabled and the forms driver just returns E_REQUEST_DENIED.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="ORDERREQ" id="ORDERREQ">18.6.6. 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 from

+a given value, there are requests that can fetch that value into

+the field buffer:</p>

+<ul>

+<li>

+<p><em>REQ_NEXT_CHOICE</em> Place the successor value of the

+current value in the buffer.</p>

+</li>

+<li>

+<p><em>REQ_PREV_CHOICE</em> Place the predecessor value of the

+current value in the buffer.</p>

+</li>

+</ul>

+<p>Of the built-in field types, only TYPE_ENUM has built-in

+successor and predecessor functions. When you define a field type

+of your own (see Custom Validation Types), you can associate our

+own ordering functions.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="APPLICCOMMANDS" id=

+"APPLICCOMMANDS">18.6.7. Application Commands</a></h4>

+<p>Form requests are represented as integers above the curses value

+greater than KEY_MAX and less than or equal to the constant

+MAX_COMMAND. A value within this range gets ignored by

+form_driver(). So this can be used for any purpose by the

+application. It can be treated as an application specific action

+and take corresponding action.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="TOOLS" id="TOOLS">19. Tools and Widget

+Libraries</a></h2>

+<p>Now that you have seen the capabilities of ncurses and its

+sister libraries, you are rolling your sleeves up and gearing for a

+project that heavily manipulates screen. But wait.. It can be

+pretty difficult to write and maintain complex GUI widgets in plain

+ncurses or even with the additional libraries. There are some

+ready-to-use tools and widget libraries that can be used instead of

+writing your own widgets. You can use some of them, get ideas from

+the code, or even extend them.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="CDK" id="CDK">19.1. CDK (Curses

+Development Kit)</a></h3>

+<p>In the author's words</p>

+<p><em>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.</em></p>

+<p>The kit provides some useful widgets, which can be used in your

+programs directly. It's 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="http://invisible-island.net/cdk/" target=

+"_top">http://invisible-island.net/cdk/</a> . Follow the

+instructions in README file to install it.</p>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="WIDGETLIST" id="WIDGETLIST">19.1.1.

+Widget List</a></h4>

+<p>The following is the list of widgets provided with cdk and their

+description.</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color="#000000">Widget Type Quick Description

+===========================================================================

+Alphalist Allows a user to select from a list of words, with

+ the ability to narrow the search list by typing in a

+ few characters of the desired word.

+Buttonbox This creates a multiple button widget.

+Calendar Creates a little simple calendar widget.

+Dialog Prompts the user with a message, and the user

+ can pick an answer from the buttons provided.

+Entry Allows the user to enter various types of information.

+File Selector A file selector built from Cdk base widgets. This

+ example shows how to create more complicated widgets

+ using the Cdk widget library.

+Graph Draws a graph.

+Histogram Draws a histogram.

+Item List Creates a pop up field which allows the user to select

+ one of several choices in a small field. Very useful

+ for things like days of the week or month names.

+Label Displays messages in a pop up box, or the label can be

+ considered part of the screen.

+Marquee Displays a message in a scrolling marquee.

+Matrix Creates a complex matrix with lots of options.

+Menu Creates a pull-down menu interface.

+Multiple Line Entry A multiple line entry field. Very useful

+ for long fields. (like a description

+ field)

+Radio List Creates a radio button list.

+Scale Creates a numeric scale. Used for allowing a user to

+ pick a numeric value and restrict them to a range of

+ values.

+Scrolling List Creates a scrolling list/menu list.

+Scrolling Window Creates a scrolling log file viewer. Can add

+ information into the window while its running.

+ A good widget for displaying the progress of

+ something. (akin to a console window)

+Selection List Creates a multiple option selection list.

+Slider Akin to the scale widget, this widget provides a

+ visual slide bar to represent the numeric value.

+Template Creates a entry field with character sensitive

+ positions. Used for pre-formatted fields like

+ dates and phone numbers.

+Viewer This is a file/information viewer. Very useful

+ when you need to display loads of information.

+===========================================================================</font>

+</pre></td>

+</tr>

+</table>

+<p>A few of the widgets are modified by Thomas Dickey in recent

+versions.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="CDKATTRACT" id="CDKATTRACT">19.1.2. Some

+Attractive Features</a></h4>

+<p>Apart from making our life easier with readily usable widgets,

+cdk solves one frustrating problem with printing multi colored

+strings, justified strings elegantly. Special formatting tags can

+be embedded in the strings which are passed to CDK functions. For

+Example</p>

+<p>If the string</p>

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000">"</B/1>This line should have a yellow foreground and a blue

+background.<!1>"</font>

+</pre></td>

+</tr>

+</table>

+<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 special drawing

+characters etc.. Please refer to the man page cdk_display(3X) for

+details. The man page explains the usage with nice examples.</p>

+</div>

+<div class="SECT3">

+<hr>

+<h4 class="SECT3"><a name="CDKCONCLUSION" id=

+"CDKCONCLUSION">19.1.3. Conclusion</a></h4>

+<p>All in all, CDK is a well-written package of widgets, which if

+used properly can form a strong frame work for developing complex

+GUI.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="DIALOG" id="DIALOG">19.2. The

+dialog</a></h3>

+<p>Long long ago, in September 1994, when few people knew linux,

+Jeff Tranter wrote an <a href=

+"http://www2.linuxjournal.com/lj-issues/issue5/2807.html" target=

+"_top">article</a> on dialog in Linux Journal. He starts the

+article with these words..</p>

+<p><em>Linux is based on the Unix operating system, but also

+features a number of unique and useful kernel features and

+application programs that often go beyond what is available under

+Unix. One little-known gem is "dialog", a utility for creating

+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</em></p>

+<p>As he explains, dialog is a real gem in making

+professional-looking dialog boxes with ease. It creates a variety

+of dialog boxes, menus, check lists etc.. It is usually installed

+by default. If not, you can download it from <a href=

+"http://invisible-island.net/dialog/" target="_top">Thomas

+Dickey</a>'s site.</p>

+<p>The above-mentioned article gives a very good overview of its

+uses and capabilites. The man page has more details. It can be used

+in variety of situations. One good example is building of linux

+kernel in text mode. Linux kernel uses a modified version of dialog

+tailored for its needs.</p>

+<p>dialog was initially designed to be used with shell scripts. If

+you want to use its functionality in a c program, then you can use

+libdialog. The documentation regarding this is sparse. Definitive

+reference is the dialog.h header file which comes with the library.

+You may need to hack here and there to get the required output. The

+source is easily customizable. I have used it on a number of

+occasions by modifying the code.</p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="PERLCURSES" id="PERLCURSES">19.3. Perl

+Curses Modules CURSES::FORM and CURSES::WIDGETS</a></h3>

+<p>The perl module Curses, Curses::Form and Curses::Widgets give

+access to curses from perl. If you have curses and basic perl is

+installed, you can get these modules from <a href=

+"http://www.cpan.org/modules/01modules.index.html" target=

+"_top">CPAN All Modules page</a>. Get the three zipped modules in

+the Curses category. Once installed you can use these modules from

+perl scripts like any other module. For more information on perl

+modules see perlmod man page. The above modules come with good

+documentation and they have some demo scripts to test the

+functionality. Though the widgets provided are very rudimentary,

+these modules provide good access to curses library from perl.</p>

+<p>Some of my code examples are converted to perl by Anuradha

+Ratnaweera and they are available in the <var class=

+"LITERAL">perl</var> directory.</p>

+<p>For more information see man pages Curses(3) , Curses::Form(3)

+and Curses::Widgets(3). These pages are installed only when the

+above modules are acquired and installed.</p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="JUSTFORFUN" id="JUSTFORFUN">20. Just For

+Fun !!!</a></h2>

+<p>This section contains few programs written by me just for fun.

+They don't signify a better programming practice or the best way of

+using ncurses. They are provided here so as to allow beginners to

+get ideas and add more programs to this section. If you have

+written a couple of nice, simple programs in curses and want them

+to included here, contact <a href="mailto:ppadala@gmail.com"

+target="_top">me</a>.</p>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="GAMEOFLIFE" id="GAMEOFLIFE">20.1. The

+Game of Life</a></h3>

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

+<table border="0" bgcolor="#E0E0E0" width="100%">

+<tr>

+<td>

+<pre class="PROGRAMLISTING">

+<font color=

+"#000000"><em>The Game of Life (or simply Life) is not a game in the conventional sense. There

+are no players, and no winning or losing. Once the "pieces" are placed in the

+starting position, the rules determine everything that happens later.

+Nevertheless, Life is full of surprises! In most cases, it is impossible to look

+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.</em></font>

+</pre></td>

+</tr>

+</table>

+<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 pattern of his choice or

+even take input from a file. You can also change rules and play

+with a lot of variations. Search on <a href="http://www.google.com"

+target="_top">google</a> for interesting information on game of

+life.</p>

+<p><em>File Path: JustForFun/life.c</em></p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="MAGIC" id="MAGIC">20.2. Magic

+Square</a></h3>

+<p>Magic Square, another wonder of math, is very simple to

+understand but very difficult to make. In a magic square sum of the

+numbers in each row, each column is equal. Even diagnol sum can be

+equal. There are many variations which have special properties.</p>

+<p>This program creates a simple magic square of odd order.</p>

+<p><em>File Path: JustForFun/magic.c</em></p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="HANOI" id="HANOI">20.3. Towers of

+Hanoi</a></h3>

+<p>The famous towers of hanoi solver. The aim of the game is to

+move the disks on the first peg to last peg, using middle peg as a

+temporary stay. The catch is not to place a larger disk over a

+small disk at any time.</p>

+<p><em>File Path: JustForFun/hanoi.c</em></p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="QUEENS" id="QUEENS">20.4. Queens

+Puzzle</a></h3>

+<p>The objective of the famous N-Queen puzzle is to put N queens on

+a N X N chess board without attacking each other.</p>

+<p>This program solves it with a simple backtracking technique.</p>

+<p><em>File Path: JustForFun/queens.c</em></p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="SHUFFLE" id="SHUFFLE">20.5.

+Shuffle</a></h3>

+<p>A fun game, if you have time to kill.</p>

+<p><em>File Path: JustForFun/shuffle.c</em></p>

+</div>

+<div class="SECT2">

+<hr>

+<h3 class="SECT2"><a name="TT" id="TT">20.6. Typing Tutor</a></h3>

+<p>A simple typing tutor, I created more out of need than for ease

+of use. If you know how to put your fingers correctly on the

+keyboard, but lack practice, this can be helpful.</p>

+<p><em>File Path: JustForFun/tt.c</em></p>

+</div>

+<div class="SECT1">

+<hr>

+<h2 class="SECT1"><a name="REF" id="REF">21. References</a></h2>

+<ul>

+<li>

+<p>NCURSES man pages</p>

+</li>

+<li>

+<p>NCURSES FAQ at <a href=

+"http://invisible-island.net/ncurses/ncurses.faq.html" target=

+"_top">http://invisible-island.net/ncurses/ncurses.faq.html</a></p>

+</li>

+<li>

+<p>Writing programs with NCURSES by Eric Raymond and Zeyd M.

+Ben-Halim at <a href=

+"http://invisible-island.net/ncurses/ncurses-intro.html" target=

+"_top">http://invisible-island.net/ncurses/ncurses-intro.html</a> -

+somewhat obsolete. I was inspired by this document and the

+structure of this HOWTO follows from the original document</p>

+</li>

+</ul>

+</div>

+</body>

+</html>

diff --git a/doc/html/announce.html b/doc/html/announce.html
new file mode 100644
index 000000000000..f9dae07e5d9a
--- /dev/null
+++ b/doc/html/announce.html

@@ -0,0 +1,600 @@

+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">

+<!--

+ $Id: announce.html,v 1.51 2006/12/17 23:32:42 tom Exp $

+ ****************************************************************************

+ * *

+ * Permission is hereby granted, free of charge, to any person obtaining a *

+ * copy of this software and associated documentation files (the *

+ * "Software"), to deal in the Software without restriction, including *

+ * without limitation the rights to use, copy, modify, merge, publish, *

+ * distribute, distribute with modifications, sublicense, and/or sell *

+ * copies of the Software, and to permit persons to whom the Software is *

+ * furnished to do so, subject to the following conditions: *

+ * *

+ * The above copyright notice and this permission notice shall be included *

+ * in all copies or substantial portions of the Software. *

+ * *

+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

+ * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

+ * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

+ * *

+ * Except as contained in this notice, the name(s) of the above copyright *

+ * holders shall not be used in advertising or otherwise to promote the *

+ * sale, use or other dealings in this Software without prior written *

+ * authorization. *

+ ****************************************************************************

+-->

+<HTML>

+<HEAD>

+<TITLE>Announcing ncurses 5.6</TITLE>

+<link rev=made href="mailto:bug-ncurses@gnu.org">

+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

+</HEAD>

+<BODY>

+<H1>Announcing ncurses 5.6</H1>

+The ncurses (new curses) library is a free software emulation of

+curses in System V Release 4.0, and more. It uses terminfo format,

+supports pads and color

+and multiple highlights and forms characters and function-key mapping,

+and has all the other SYSV-curses enhancements over BSD curses.<P>

+In mid-June 1995, the maintainer of 4.4BSD curses declared that he

+considered 4.4BSD curses obsolete, and encouraged the keepers of

+Unix releases such as BSD/OS, FreeBSD and NetBSD to switch over to

+ncurses.<P>

+The ncurses code was developed under GNU/Linux.

+It has been in use for some time with OpenBSD as the system curses library,

+and on FreeBSD and NetBSD as an external package.

+It should port easily to any ANSI/POSIX-conforming UNIX.

+It has even been ported to OS/2 Warp!<P>

+The distribution includes the library and support utilities, including a

+terminfo compiler tic(1), a decompiler infocmp(1), clear(1), tput(1), tset(1),

+and a termcap conversion tool captoinfo(1). Full manual pages are provided for

+the library and tools.<P>

+The ncurses distribution is available via anonymous FTP at

+the GNU distribution site

+<A HREF="ftp://ftp.gnu.org/gnu/ncurses/">ftp://ftp.gnu.org/gnu/ncurses/</A> .

+<br>It is also available at

+<A HREF="ftp://invisible-island.net/ncurses/">ftp://invisible-island.net/ncurses/</A> .

+<H1>Release Notes</H1>

+This release is designed to be upward compatible from ncurses 5.0 through 5.5;

+very few applications will require recompilation, depending on the platform.

+These are the highlights from the change-log since ncurses 5.5 release.

+<p>

+Interface changes:

+<ul>

+ <li>generate linkable stubs for some macros:

+ <br>

+ getbegx, getbegy, getcurx, getcury, getmaxx, getmaxy, getparx,

+ getpary, getpary,

+ <br>

+ and (for libncursesw)

+ <br>

+ wgetbkgrnd

+</ul>

+New features and improvements:

+<ul>

+ <li>library

+ <ul>

+ <li>support hashed databases for the terminal descriptions.

+ This uses the Berkeley database, has been tested for

+ several versions on different platforms.

+ <li>add <code>use_legacy_coding()</code> function to support

+ lynx's font-switching feature.

+ <li>add extension <code>nofilter()</code>, to cancel a prior

+ <code>filter()</code> call.

+ <li>add/install a package config script, e.g.,

+ <code>ncurses5-config</code> or

+ <code>ncursesw5-config</code>, according to

+ configuration options.

+ <li>provide ifdef for <code>NCURSES_NOMACROS</code> which

+ suppresses most macro definitions from curses.h, i.e.,

+ where a macro is defined to override a function to improve

+ performance.

+ <li>make ifdef's consistent in <code>curses.h</code> for the

+ extended colors so the header file can be used for the

+ normal curses library. The header file installed for

+ extended colors is a variation of the wide-character

+ configuration.

+ <li>improve <code>tgetstr()</code> by making the return value

+ point into the user's buffer, if provided.

+ <li>add ifdef's allowing ncurses to be built with

+ <code>tparm()</code> using either varargs (the existing

+ status), or using a fixed-parameter list (to match X/Open).

+ <li>widen the test for xterm <code>kmous</code> a little to

+ <code>allow</code> for other

+ strings than "\E[M", e.g., for <code>xterm-sco</code>

+ functionality in xterm.

+ <li>modify <code>wgetnstr()</code> to return

+ <code>KEY_RESIZE</code> if a sigwinch occurs.

+ <li>move prototypes for wide-character trace functions from

+ curses.tail to curses.wide to avoid accidental reference to

+ those if <code>_XOPEN_SOURCE_EXTENDED</code> is defined

+ without ensuring that <wchar.h> is included.

+ <li>change the way shared libraries (other than libtool) are

+ installed. Rather than copying the build-tree's libraries,

+ link the shared objects into the install directory. This

+ makes the <code>--with-rpath</code> option work except with

+ <code>$(DESTDIR)</code>.

+ <li>several improvements for rendering in hpterm. These are

+ only available if the library is configured using

+ <code>--enable-xmc-glitch</code>.

+ <li>Add <code>NCURSES_NO_HARD_TABS</code> and

+ <code>NCURSES_NO_MAGIC_COOKIE</code> environment variables

+ to allow runtime suppression of the related hard-tabs and

+ xmc-glitch features.

+ </ul>

+ <li>programs:

+ <ul>

+ <li>add new test programs: chgat.c, demo_altkeys.c,

+ echochar.c, foldkeys.c, movewindow.c, redraw.c, (noting

+ that existing test programs also were modified to test

+ additional features).

+ <li>modify tack to test extended capability function-key

+ strings.

+ <li>modify toe to access termcap data, e.g., via <code>cgetent()</code>

+ functions, or as a text file if those are not available.

+ <li>improve infocmp/tic <code>-f</code> option formatting.

+ <li>add <code>toe -a</code> option, to show all databases.

+ This uses new private interfaces in the ncurses library for

+ iterating through the list of databases.

+ <li>modify <code>MKfallback.sh</code> to use

+ <code>tic -x</code> when constructing fallback tables to

+ allow extended capabilities to be retrieved from a fallback entry.

+ </ul>

+ <li>terminal database

+ <ul>

+ <li>add terminfo entries for xfce terminal (xfce) and multi gnome terminal (mgt)

+ <li>add nsterm-16color entry

+ <li>updated mlterm terminfo entry

+ <li>add kon, kon2 and jfbterm terminfo entry

+ <li>remove invis capability from klone+sgr, mainly used by linux entry, since it does not really do this

+ <li>add ka2, kb1, kb3, kc2 to vt220-keypad as an extension

+ <li>add shifted up/down arrow codes to xterm-new as kind/kri strings

+ <li>add hpterm-color terminfo entry

+ <li>add 256color variants of terminfo entries for programs which are reported to implement this feature

+ <li>correct order of use-clauses in rxvt-basic entry which made codes for f1-f4 vt100-style rather than vt220-style.

+ </ul>

+</ul>

+Major bug fixes:

+<ul>

+ <li>correct a typo in configure <code>--with-bool</code> option for the

+ case where <code>--without-cxx</code> is used.

+ <li>move assignment from environment variable <code>ESCDELAY</code>

+ from <code>initscr()</code> down to <code>newterm()</code> so the

+ environment variable affects timeouts for terminals opened with

+ newterm() as well.

+ <li>modify <code>werase</code> to clear multicolumn characters that

+ extend into a derived window.

+ <li>modify <code>wchgat()</code> to mark updated cells as changed so a

+ refresh will repaint those cells.

+ <li>correct logic in <code>wadd_wch()</code> and

+ <code>wecho_wch()</code>, which did not guard against passing the

+ multi-column attribute into a call on <code>waddch()</code>, e.g.,

+ using data returned by <code>win_wch()</code>

+ <li>fix redrawing of windows other than <code>stdscr</code> using

+ <code>wredrawln()</code> by touching the corresponding rows in

+ <code>curscr</code>.

+ <li>reduce memory leaks in repeated calls to <code>tgetent()</code> by

+ remembering the last <code>TERMINAL*</code> value allocated to hold

+ the corresponding data and freeing that if the

+ <code>tgetent()</code> result buffer is the same as the previous

+ call.

+ <li>modify <code>read_termtype()</code> so the <code>term_names</code>

+ data is always allocated as part of the <code>str_table</code>, a

+ better fix for a memory leak.

+ <li>fix <code>wins_nwstr(),</code> which did not handle single-column

+ non-8bit codes.

+ <li>modify <code>wbkgrnd()</code> to avoid clearing the

+ <code>A_CHARTEXT</code> attribute bits since those record the state

+ of multicolumn characters.

+ <li>improve <code>SIGWINCH</code> handling by postponing its effect

+ during <code>newterm()</code>, etc., when allocating screens.

+ <li>remove 970913 feature for copying subwindows as they are moved in

+ <code>mvwin()</code>.

+ <li>add checks in <code>waddchnstr()</code> and

+ <code>wadd_wchnstr()</code> to stop copying when a null character

+ is found.

+ <li>add some checks to ensure current position is within scrolling

+ region before scrolling on a new line.

+ <li>add a workaround to ACS mapping to allow applications such as

+ test/blue.c to use the "PC ROM" characters by masking them with

+ A_ALTCHARSET. This worked up til 5.5, but was lost in the revision

+ of legacy coding.

+</ul>

+Portability:

+<ul>

+ <li>configure script:

+ <ul>

+ <li>new options:

+ <dl>

+ <dt>--with-hashed-db

+ <dd>Use Berkeley hashed database for storing terminfo data rather than storing

+ each compiled entry in a separate binary file within a directory

+ tree.

+ <dt>--without-dlsym

+ <dd>Do not use <code>dlsym()</code> to load GPM dynamically.

+ <dt>--with-valgrind

+ <dd>Simplify building for testing with valgrind.

+ <dt>--enable-wgetch-events

+ <dd>Compile with experimental wgetch-events code.

+ <dt>--enable-signed-char

+ <dd>Store booleans in "signed char" rather than "char".

+ </dl>

+ <li>improved options:

+ <dl>

+ <dt>--disable-largefile

+ <dd>make the option work both ways.

+ <dt>--with-gpm

+ <dd>The option now accepts a parameter,

+ i.e., the name of the dynamic GPM library to load via

+ <code>dlopen()</code>

+ <dt>--disable-symlinks

+ <dd>The option now allows one to

+ disable <code>symlink()</code> in <code>tic</code> even when

+ <code>link()</code> does not work.

+ </dl>

+ </ul>

+ <li>other configure/build issues: <ul> <li>remove special case for

+ Darwin in <code>CF_XOPEN_SOURCE</code> configure macro.

+ <li>add configure check to ensure that <code>SIGWINCH</code> is

+ defined on platforms such as OS X which exclude that when

+ <code>_XOPEN_SOURCE,</code> etc., are defined

+ <li>use ld's <code>-search_paths_first</code> option on Darwin

+ to work around odd search rules on that platform.

+ <li>improve ifdef's for <code>_POSIX_VDISABLE</code> in tset to

+ work with Mac OS X.

+ <li>modify configure script to ensure that if the C compiler is

+ used rather than the loader in making shared libraries, the

+ <code>$(CFLAGS)</code> variable is also used.

+ <li>use <code>${CC}</code> rather than <code>${LD}</code> in

+ shared library rules for IRIX64, Solaris to help ensure

+ that initialization sections are provided for extra linkage

+ requirements, e.g., of C++ applications.

+ <li>improve some shared-library configure scripting for Linux,

+ FreeBSD and NetBSD to make

+ <code>--with-shlib-version</code> work.

+ <li>split up dependency of <code>names.c</code> and

+ <code>codes.c</code> in <code>ncurses/Makefile</code> to

+ work with parallel make.

+ <li>modify <code>MKlib_gen.sh</code> to change

+ preprocessor-expanded <code>_Bool</code> back to <code>bool</code>.

+ <li>modify <code>progs/Makefile.in</code> to make

+ <code>tput init</code> work properly with cygwin,

+ i.e., do not pass a <code>.exe</code> in the reference

+ string used in check_aliases.

+ </ul>

+ <li>library:

+ <ul>

+ <li>ignore wide-acs line-drawing characters that

+ <code>wcwidth()</code> claims are not one-column. This is

+ a workaround for Solaris' broken locale support.

+ <li>reduce name-pollution in <code>term.h</code> by removing

+ <code>#define</code>'s for HAVE_xxx symbols.

+ <li>fix <code>#ifdef</code> in <code>c++/internal.h</code> for

+ QNX 6.1

+ </ul>

+ <li>test programs: <ul> <li>modify <code>test/configure</code> script

+ to allow building test programs with PDCurses/X11.

+ <li>modified test programs to allow some to work with NetBSD

+ curses. Several do not because NetBSD curses implements a

+ subset of X/Open curses, and also lacks much of SVr4

+ additions. But it is enough for comparison.

+ <li>improved <code>test/configure</code> to build test/ncurses

+ on HPUX 11 using the vendor curses.

+ <li>change configure script to produce

+ <code>test/Makefile</code> from data file.

+ </ul>

+</ul>

+<H1>Features of Ncurses</H1>

+The ncurses package is fully compatible with SVr4 (System V Release 4) curses:

+<UL>

+<LI>All 257 of the SVr4 calls have been implemented (and are documented).

+<LI>Full support for SVr4 curses features including keyboard mapping, color,

+forms-drawing with ACS characters, and automatic recognition of keypad

+and function keys.

+<LI>An emulation of the SVr4 panels library, supporting

+a stack of windows with backing store, is included.

+<LI>An emulation of the SVr4 menus library, supporting

+a uniform but flexible interface for menu programming, is included.

+<LI>An emulation of the SVr4 form library, supporting

+data collection through on-screen forms, is included.

+<LI>Binary terminfo entries generated by the ncurses tic(1) implementation

+are bit-for-bit-compatible with the entry format SVr4 curses uses.

+<LI>The utilities have options to allow you to filter terminfo

+entries for use with less capable <STRONG>curses</STRONG>/<STRONG>terminfo</STRONG>

+versions such as the HP/UX and AIX ports.</UL>

+The ncurses package also has many useful extensions over SVr4:

+<UL>

+<LI>The API is 8-bit clean and base-level conformant with the X/OPEN curses

+specification, XSI curses (that is, it implements all BASE level features,

+and most EXTENDED features).

+It includes many function calls not supported under SVr4 curses

+(but portability of all

+calls is documented so you can use the SVr4 subset only).

+<LI>Unlike SVr3 curses, ncurses can write to the rightmost-bottommost corner

+of the screen if your terminal has an insert-character capability.

+<LI>Ada95 and C++ bindings.

+<LI>Support for mouse event reporting with X Window xterm

+and FreeBSD and OS/2 console windows.

+<LI>Extended mouse support via Alessandro Rubini's gpm package.

+<LI>The function <CODE>wresize()</CODE> allows you to resize windows, preserving

+their data.

+<LI>The function <CODE>use_default_colors()</CODE> allows you to

+use the terminal's default colors for the default color pair,

+achieving the effect of transparent colors.

+<LI>The functions <CODE>keyok()</CODE>

+and <CODE>define_key()</CODE> allow

+you to better control the use of function keys,

+e.g., disabling the ncurses KEY_MOUSE,

+or by defining more than one control sequence to map to a given key code.

+<LI>Support for 16-color terminals, such as aixterm and modern xterm.

+<LI>Better cursor-movement optimization. The package now features a

+cursor-local-movement computation more efficient than either BSD's

+or System V's.

+<LI>Super hardware scrolling support. The screen-update code incorporates

+a novel, simple, and cheap algorithm that enables it to make optimal

+use of hardware scrolling, line-insertion, and line-deletion

+for screen-line movements. This algorithm is more powerful than

+the 4.4BSD curses quickch() routine.

+<LI>Real support for terminals with the magic-cookie glitch. The

+screen-update code will refrain from drawing a highlight if the magic-

+cookie unattributed spaces required just before the beginning and

+after the end would step on a non-space character. It will

+automatically shift highlight boundaries when doing so would make it

+possible to draw the highlight without changing the visual appearance

+of the screen.

+<LI>It is possible to generate the library with a list of pre-loaded

+fallback entries linked to it so that it can serve those terminal types even

+when no terminfo tree or termcap file is accessible (this may be useful

+for support of screen-oriented programs that must run in single-user mode).

+<LI>The tic(1)/captoinfo utility provided with ncurses has the

+ability to translate many termcaps from the XENIX, IBM and

+AT&T extension sets.

+<LI>A BSD-like tset(1) utility is provided.

+<LI>The ncurses library and utilities will automatically read terminfo

+entries from $HOME/.terminfo if it exists, and compile to that directory

+if it exists and the user has no write access to the system directory.

+This feature makes it easier for users to have personal terminfo entries

+without giving up access to the system terminfo directory.

+<LI>You may specify a path of directories to search for compiled

+descriptions with the environment variable TERMINFO_DIRS (this

+generalizes the feature provided by TERMINFO under stock System V.)

+<LI>In terminfo source files, use capabilities may refer not just to

+other entries in the same source file (as in System V) but also to

+compiled entries in either the system terminfo directory or the user's

+$HOME/.terminfo directory.

+<LI>A script (<STRONG>capconvert</STRONG>) is provided to help BSD users

+transition from termcap to terminfo. It gathers the information in a

+TERMCAP environment variable and/or a ~/.termcap local entries file

+and converts it to an equivalent local terminfo tree under $HOME/.terminfo.

+<LI>Automatic fallback to the /etc/termcap file can be compiled in

+when it is not possible to build a terminfo tree. This feature is neither

+fast nor cheap, you don't want to use it unless you have to,

+but it's there.

+<LI>The table-of-entries utility <STRONG>toe</STRONG> makes it easy for users to

+see exactly what terminal types are available on the system.

+<LI>The library meets the XSI requirement that every macro entry

+point have a corresponding function which may be linked (and will be

+prototype-checked) if the macro definition is disabled with

+<CODE>#undef</CODE>.

+<LI>An HTML "Introduction to Programming with NCURSES" document provides

+a narrative introduction to the curses programming interface.

+</UL>

+<H1>State of the Package</H1>

+Numerous bugs present in earlier versions have been fixed; the

+library is far more reliable than it used to be. Bounds checking in many

+`dangerous' entry points has been improved. The code is now type-safe

+according to gcc -Wall. The library has been checked for malloc leaks and

+arena corruption by the Purify memory-allocation tester.<P>

+The ncurses code has been tested with a wide variety of applications

+including (versions starting with those noted):

+<DL>

+<DT> cdk

+<DD> Curses Development Kit

+<br>

+<A HREF="http://invisible-island.net/cdk/">http://invisible-island.net/cdk/</A>

+<br>

+<A HREF="http://www.vexus.ca/products/CDK/">http://www.vexus.ca/products/CDK/</a>

+<DT> ded

+<DD> directory-editor

+<br>

+<A HREF="http://invisible-island.net/ded/">http://invisible-island.net/ded/</A>

+<DT> dialog

+<DD> the underlying application used in Slackware's setup, and the basis

+for similar applications on GNU/Linux.

+<br>

+<A HREF="http://invisible-island.net/dialog/">http://invisible-island.net/dialog/</A>

+<DT> lynx

+<DD> the character-screen WWW browser

+<br>

+<A HREF="http://lynx.isc.org/release/">http://lynx.isc.org/release/</A>

+<DT> Midnight Commander

+<DD> file manager

+<br>

+<A HREF="http://www.ibiblio.org/mc/">http://www.ibiblio.org/mc/</A>

+<DT> mutt

+<DD> mail utility

+<br>

+<A HREF="http://www.mutt.org/">http://www.mutt.org/</A>

+<DT> ncftp

+<DD> file-transfer utility

+<br>

+<A HREF="http://www.ncftp.com/">http://www.ncftp.com/</A>

+<DT> nvi

+<DD> New vi versions 1.50 are able to use ncurses versions 1.9.7 and later.

+<br>

+<A HREF="http://www.bostic.com/vi/">http://www.bostic.com/vi/</A>

+<br>

+<DT> pinfo

+<DD> Lynx-like info browser.

+<A HREF="http://dione.ids.pl/~pborys/software/pinfo/">http://dione.ids.pl/~pborys/software/pinfo/</A>

+<DT> tin

+<DD> newsreader, supporting color, MIME

+<A HREF="http://www.tin.org/">http://www.tin.org/</A>

+<DT> vh-1.6

+<DD> Volks-Hypertext browser for the Jargon File

+<br>

+<A HREF="http://www.debian.org/Packages/unstable/text/vh.html">http://www.debian.org/Packages/unstable/text/vh.html</A>

+</DL>

+as well as some that use ncurses for the terminfo support alone:

+<DL>

+<DT> minicom

+<DD> terminal emulator

+<br>

+<A HREF="http://alioth.debian.org/projects/minicom/">

+http://alioth.debian.org/projects/minicom/</A>

+<DT> vile

+<DD> vi-like-emacs

+<br>

+<A HREF="http://invisible-island.net/vile/">http://invisible-island.net/vile/</A>

+</DL>

+<P>

+The ncurses distribution includes a selection of test programs (including

+a few games).

+<H2>Who's Who and What's What</H2>

+Zeyd Ben-Halim

+started it from a previous package pcurses, written by Pavel Curtis.

+Eric S. Raymond

+continued development.

+Jürgen Pfeifer wrote most of the form and menu libraries.

+Ongoing work is being done by

+<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A>.

+Thomas Dickey

+acts as the maintainer for the Free Software Foundation,

+which holds the copyright on ncurses.

+Contact the current maintainers at

+<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.

+<P>

+To join the ncurses mailing list, please write email to

+<CODE>bug-ncurses-request@gnu.org</CODE> containing the line:

+<PRE>

+ subscribe <name>@<host.domain>

+</PRE>

+This list is open to anyone interested in helping with the development and

+testing of this package.<P>

+Beta versions of ncurses and patches to the current release are made available at

+<A HREF="ftp://invisible-island.net/ncurses/">ftp://invisible-island.net/ncurses/</A> .

+<H2>Future Plans</H2>

+<UL>

+<LI>Extended-level XPG4 conformance, with internationalization support.

+<LI>Ports to more systems, including DOS and Windows.

+</UL>

+We need people to help with these projects. If you are interested in working

+on them, please join the ncurses list.

+<H2>Other Related Resources</H2>

+The distribution provides a newer version of the terminfo-format

+terminal description file once maintained by

+<A HREF="http://www.catb.org/~esr/terminfo/">Eric Raymond</A> .

+Unlike the older version, the termcap and terminfo data are provided

+in the same file, and provides several user-definable extensions

+beyond the X/Open specification.<P>

+You can find lots of information on terminal-related topics

+not covered in the terminfo file at

+<A HREF="http://www.cs.utk.edu/~shuford/terminal_index.html">Richard Shuford's

+archive</A> .

+</BODY>

+</HTML>

+<!--

+# The following sets edit modes for GNU EMACS

+# Local Variables:

+# mode:html

+# case-fold-search:nil

+# fill-column:70

+# End:

+-->

diff --git a/doc/html/hackguide.html b/doc/html/hackguide.html
new file mode 100644
index 000000000000..97d1369170c1
--- /dev/null
+++ b/doc/html/hackguide.html

@@ -0,0 +1,914 @@

+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">

+<!--

+ $Id: hackguide.html,v 1.27 2005/12/24 15:37:13 tom Exp $

+ ****************************************************************************

+ * *

+ * Permission is hereby granted, free of charge, to any person obtaining a *

+ * copy of this software and associated documentation files (the *

+ * "Software"), to deal in the Software without restriction, including *

+ * without limitation the rights to use, copy, modify, merge, publish, *

+ * distribute, distribute with modifications, sublicense, and/or sell *

+ * copies of the Software, and to permit persons to whom the Software is *

+ * furnished to do so, subject to the following conditions: *

+ * *

+ * The above copyright notice and this permission notice shall be included *

+ * in all copies or substantial portions of the Software. *

+ * *

+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

+ * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

+ * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

+ * *

+ * Except as contained in this notice, the name(s) of the above copyright *

+ * holders shall not be used in advertising or otherwise to promote the *

+ * sale, use or other dealings in this Software without prior written *

+ * authorization. *

+ ****************************************************************************

+-->

+<HTML>

+<HEAD>

+<TITLE>A Hacker's Guide to Ncurses Internals</TITLE>

+<link rev="made" href="mailto:bugs-ncurses@gnu.org">

+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

+<!--

+This document is self-contained, *except* that there is one relative link to

+the ncurses-intro.html document, expected to be in the same directory with

+this one.

+-->

+</HEAD>

+<BODY>

+<H1>A Hacker's Guide to NCURSES</H1>

+<H1>Contents</H1>

+<UL>

+<LI><A HREF="#abstract">Abstract</A>

+<LI><A HREF="#objective">Objective of the Package</A>

+<UL>

+<LI><A HREF="#whysvr4">Why System V Curses?</A>

+<LI><A HREF="#extensions">How to Design Extensions</A>

+</UL>

+<LI><A HREF="#portability">Portability and Configuration</A>

+<LI><A HREF="#documentation">Documentation Conventions</A>

+<LI><A HREF="#bugtrack">How to Report Bugs</A>

+<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A>

+<UL>

+<LI><A HREF="#loverview">Library Overview</A>

+<LI><A HREF="#engine">The Engine Room</A>

+<LI><A HREF="#input">Keyboard Input</A>

+<LI><A HREF="#mouse">Mouse Events</A>

+<LI><A HREF="#output">Output and Screen Updating</A>

+</UL>

+<LI><A HREF="#fmnote">The Forms and Menu Libraries</A>

+<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><A HREF="#uses">Use Capability Resolution</A>

+<LI><A HREF="#translation">Source-Form Translation</A>

+</UL>

+<LI><A HREF="#utils">Other Utilities</A>

+<LI><A HREF="#style">Style Tips for Developers</A>

+<LI><A HREF="#port">Porting Hints</A>

+</UL>

+<H1><A NAME="abstract">Abstract</A></H1>

+This document is a hacker's tour of the <STRONG>ncurses</STRONG> library and utilities.

+It discusses design philosophy, implementation methods, and the

+conventions used for coding and documentation. It is recommended

+reading for anyone who is interested in porting, extending or improving the

+package.

+<H1><A NAME="objective">Objective of the Package</A></H1>

+The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for

+character-cell terminals and terminal emulators with the following

+characteristics:

+<UL>

+<LI>Source-compatible with historical curses implementations (including

+ the original BSD curses and System V curses.

+<LI>Conformant with the XSI Curses standard issued as part of XPG4 by

+ X/Open.

+<LI>High-quality -- stable and reliable code, wide portability, good

+ packaging, superior documentation.

+<LI>Featureful -- should eliminate as much of the drudgery of C interface

+ programming as possible, freeing programmers to think at a higher

+ level of design.

+</UL>

+These objectives are in priority order. So, for example, source

+compatibility with older version must trump featurefulness -- we cannot

+add features if it means breaking the portion of the API corresponding

+to historical curses versions.

+<H2><A NAME="whysvr4">Why System V Curses?</A></H2>

+We used System V curses as a model, reverse-engineering their API, in

+order to fulfill the first two objectives. <P>

+System V curses implementations can support BSD curses programs with

+just a recompilation, so by capturing the System V API we also

+capture BSD's. <P>

+More importantly for the future, the XSI Curses standard issued by X/Open

+is explicitly and closely modeled on System V. So conformance with

+System V took us most of the way to base-level XSI conformance.

+<H2><A NAME="extensions">How to Design Extensions</A></H2>

+The third objective (standards conformance) requires that it be easy to

+condition source code using <STRONG>ncurses</STRONG> so that the absence of nonstandard

+extensions does not break the code. <P>

+Accordingly, we have a policy of associating with each nonstandard extension

+a feature macro, so that ncurses client code can use this macro to condition

+in or out the code that requires the <STRONG>ncurses</STRONG> extension. <P>

+For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses

+does not define, but which is defined in the <STRONG>ncurses</STRONG> library header.

+You can use this to condition the calls to the mouse API calls.

+<H1><A NAME="portability">Portability and Configuration</A></H1>

+Code written for <STRONG>ncurses</STRONG> may assume an ANSI-standard C compiler and

+POSIX-compatible OS interface. It may also assume the presence of a

+System-V-compatible <EM>select(2)</EM> call. <P>

+We encourage (but do not require) developers to make the code friendly

+to less-capable UNIX environments wherever possible. <P>

+We encourage developers to support OS-specific optimizations and methods

+not available under POSIX/ANSI, provided only that:

+<UL>

+<LI>All such code is properly conditioned so the build process does not

+ attempt to compile it under a plain ANSI/POSIX environment.

+<LI>Adding such implementation methods does not introduce incompatibilities

+ in the <STRONG>ncurses</STRONG> API between platforms.

+</UL>

+We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues.

+The right way to leverage an OS-specific feature is to modify the autoconf

+specification files (configure.in and aclocal.m4) to set up a new feature

+macro, which you then use to condition your code.

+<H1><A NAME="documentation">Documentation Conventions</A></H1>

+There are three kinds of documentation associated with this package. Each

+has a different preferred format:

+<UL>

+<LI>Package-internal files (README, INSTALL, TO-DO etc.)

+<LI>Manual pages.

+<LI>Everything else (i.e., narrative documentation).

+</UL>

+Our conventions are simple:

+<OL>

+<LI><STRONG>Maintain package-internal files in plain text.</STRONG>

+ The expected viewer for them <EM>more(1)</EM> or an editor window; there's

+ no point in elaborate mark-up.

+<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable

+ through traditional <EM>man(1)</EM> programs.

+<LI><STRONG>Write everything else in HTML.</STRONG>

+</OL>

+When in doubt, HTMLize a master and use <EM>lynx(1)</EM> to generate

+plain ASCII (as we do for the announcement document). <P>

+The reason for choosing HTML is that it's (a) well-adapted for on-line

+browsing through viewers that are everywhere; (b) more easily readable

+as plain text than most other mark-ups, if you don't have a viewer; and (c)

+carries enough information that you can generate a nice-looking printed

+version from it. Also, of course, it make exporting things like the

+announcement document to WWW pretty trivial.

+<H1><A NAME="bugtrack">How to Report Bugs</A></H1>

+The <A NAME="bugreport">reporting address for bugs</A> is

+<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.

+This is a majordomo list; to join, write

+to <CODE>bug-ncurses-request@gnu.org</CODE> with a message containing the line:

+<PRE>

+ subscribe <name>@<host.domain>

+</PRE>

+The <CODE>ncurses</CODE> code is maintained by a small group of

+volunteers. While we try our best to fix bugs promptly, we simply

+don't have a lot of hours to spend on elementary hand-holding. We rely

+on intelligent cooperation from our users. If you think you have

+found a bug in <CODE>ncurses</CODE>, there are some steps you can take

+before contacting us that will help get the bug fixed quickly. <P>

+In order to use our bug-fixing time efficiently, we put people who

+show us they've taken these steps at the head of our queue. This

+means that if you don't, you'll probably end up at the tail end and

+have to wait a while.

+<OL>

+<LI>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 behavior --

+ideally, by giving us source for a small, portable test program that

+breaks the library. (Even better is a keystroke recipe using one of

+the test programs provided with the distribution.)

+<LI>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're using a traditional

+asynchronous terminal or PC-based terminal emulator, rather than xterm

+or a UNIX console entry. <P>

+It's therefore extremely helpful if you can tell us whether or not your

+problem reproduces on other terminal types. Usually you'll have both

+a console type and xterm available; please tell us whether or not your

+bug reproduces on both. <P>

+If you have xterm available, it is also good to collect xterm reports for

+different window sizes. This is especially true if you normally use an

+unusual xterm window size -- a surprising number of the bugs we've seen

+are either triggered or masked by these.

+<LI>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="ncurses-intro.html#debugging">"Writing Programs with

+NCURSES"</A> for details on trace levels.)

+Reproduce your bug, then look at the trace file to see what the library

+was actually doing. <P>

+Another frequent cause of apparent bugs is application coding errors

+that cause the wrong things to be put on the virtual screen. Looking

+at the virtual-screen dumps in the trace file will tell you immediately if

+this is happening, and save you from the possible embarrassment of being

+told that the bug is in your code and is your problem rather than ours. <P>

+If the virtual-screen dumps look correct but the bug persists, it's

+possible to crank up the trace level to give more and more information

+about the library's update actions and the control sequences it issues

+to perform them. The test directory of the distribution contains a

+tool for digesting these logs to make them less tedious to wade

+through. <P>

+Often you'll find terminfo problems at this stage by noticing that the

+escape sequences put out for various capabilities are wrong. If not,

+you're likely to learn enough to be able to characterize any bug in

+the screen-update logic quite exactly.

+<LI>Report details and symptoms, not just interpretations. <P>

+If you do the preceding two steps, it is very likely that you'll discover

+the nature of the problem yourself and be able to send us a fix. This

+will create happy feelings all around and earn you good karma for the first

+time you run into a bug you really can't characterize and fix yourself. <P>

+If you're still stuck, at least you'll know what to tell us. Remember, we

+need details. If you guess about what is safe to leave out, you are too

+likely to be wrong. <P>

+If your bug produces a bad update, include a trace file. Try to make

+the trace at the <EM>least</EM> voluminous level that pins down the

+bug. Logs that have been through tracemunch are OK, it doesn't throw

+away any information (actually they're better than un-munched ones because

+they're easier to read). <P>

+If your bug produces a core-dump, please include a symbolic stack trace

+generated by gdb(1) or your local equivalent. <P>

+Tell us about every terminal on which you've reproduced the bug -- and

+every terminal on which you can't. Ideally, sent us terminfo sources

+for all of these (yours might differ from ours). <P>

+Include your ncurses version and your OS/machine type, of course! You can

+find your ncurses version in the <CODE>curses.h</CODE> file.

+</OL>

+If your problem smells like a logic error or in cursor movement or

+scrolling or a bad capability, there are a couple of tiny test frames

+for the library algorithms in the progs directory that may help you

+isolate it. These are not part of the normal build, but do have their

+own make productions. <P>

+The most important of these is <CODE>mvcur</CODE>, a test frame for the

+cursor-movement optimization code. With this program, you can see

+directly what control sequences will be emitted for any given cursor

+movement or scroll/insert/delete operations. If you think you've got

+a bad capability identified, you can disable it and test again. The

+program is command-driven and has on-line help. <P>

+If you think the vertical-scroll optimization is broken, or just want to

+understand how it works better, build <CODE>hashmap</CODE> and read the

+header comments of <CODE>hardscroll.c</CODE> and <CODE>hashmap.c</CODE>; then try

+it out. You can also test the hardware-scrolling optimization separately

+with <CODE>hardscroll</CODE>. <P>

+<H1><A NAME="ncurslib">A Tour of the Ncurses Library</A></H1>

+<H2><A NAME="loverview">Library Overview</A></H2>

+Most of the library is superstructure -- fairly trivial convenience

+interfaces to a small set of basic functions and data structures used

+to manipulate the virtual screen (in particular, none of this code

+does any I/O except through calls to more fundamental modules

+described below). The files

+<blockquote>

+<CODE>

+lib_addch.c

+lib_bkgd.c

+lib_box.c

+lib_chgat.c

+lib_clear.c

+lib_clearok.c

+lib_clrbot.c

+lib_clreol.c

+lib_colorset.c

+lib_data.c

+lib_delch.c

+lib_delwin.c

+lib_echo.c

+lib_erase.c

+lib_gen.c

+lib_getstr.c

+lib_hline.c

+lib_immedok.c

+lib_inchstr.c

+lib_insch.c

+lib_insdel.c

+lib_insstr.c

+lib_instr.c

+lib_isendwin.c

+lib_keyname.c

+lib_leaveok.c

+lib_move.c

+lib_mvwin.c

+lib_overlay.c

+lib_pad.c

+lib_printw.c

+lib_redrawln.c

+lib_scanw.c

+lib_screen.c

+lib_scroll.c

+lib_scrollok.c

+lib_scrreg.c

+lib_set_term.c

+lib_slk.c

+lib_slkatr_set.c

+lib_slkatrof.c

+lib_slkatron.c

+lib_slkatrset.c

+lib_slkattr.c

+lib_slkclear.c

+lib_slkcolor.c

+lib_slkinit.c

+lib_slklab.c

+lib_slkrefr.c

+lib_slkset.c

+lib_slktouch.c

+lib_touch.c

+lib_unctrl.c

+lib_vline.c

+lib_wattroff.c

+lib_wattron.c

+lib_window.c

+</CODE>

+</blockquote>

+are all in this category. They are very

+unlikely to need change, barring bugs or some fundamental

+reorganization in the underlying data structures. <P>

+These files are used only for debugging support:

+<blockquote>

+<code>

+lib_trace.c

+lib_traceatr.c

+lib_tracebits.c

+lib_tracechr.c

+lib_tracedmp.c

+lib_tracemse.c

+trace_buf.c

+</code>

+</blockquote>

+It is rather unlikely you will ever need to change these, unless

+you want to introduce a new debug trace level for some reason.<P>

+There is another group of files that do direct I/O via <EM>tputs()</EM>,

+computations on the terminal capabilities, or queries to the OS

+environment, but nevertheless have only fairly low complexity. These

+include:

+<blockquote>

+<code>

+lib_acs.c

+lib_beep.c

+lib_color.c

+lib_endwin.c

+lib_initscr.c

+lib_longname.c

+lib_newterm.c

+lib_options.c

+lib_termcap.c

+lib_ti.c

+lib_tparm.c

+lib_tputs.c

+lib_vidattr.c

+read_entry.c.

+</code>

+</blockquote>

+They are likely to need revision only if

+ncurses is being ported to an environment without an underlying

+terminfo capability representation. <P>

+These files

+have serious hooks into

+the tty driver and signal facilities:

+<blockquote>

+<code>

+lib_kernel.c

+lib_baudrate.c

+lib_raw.c

+lib_tstp.c

+lib_twait.c

+</code>

+</blockquote>

+If you run into porting snafus

+moving the package to another UNIX, the problem is likely to be in one

+of these files.

+The file <CODE>lib_print.c</CODE> uses sleep(2) and also

+falls in this category.<P>

+Almost all of the real work is done in the files

+<blockquote>

+<code>

+hardscroll.c

+hashmap.c

+lib_addch.c

+lib_doupdate.c

+lib_getch.c

+lib_mouse.c

+lib_mvcur.c

+lib_refresh.c

+lib_setup.c

+lib_vidattr.c

+</code>

+</blockquote>

+Most of the algorithmic complexity in the

+library lives in these files.

+If there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here.

+We'll tour some of these files in detail

+below (see <A HREF="#engine">The Engine Room</A>). <P>

+Finally, there is a group of files that is actually most of the

+terminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG>

+library is to support fallback to /etc/termcap. These files include

+<blockquote>

+<code>

+alloc_entry.c

+captoinfo.c

+comp_captab.c

+comp_error.c

+comp_hash.c

+comp_parse.c

+comp_scan.c

+parse_entry.c

+read_termcap.c

+write_entry.c

+</code>

+</blockquote>

+We'll discuss these in the compiler tour.

+<H2><A NAME="engine">The Engine Room</A></H2>

+<H3><A NAME="input">Keyboard Input</A></H3>

+All <CODE>ncurses</CODE> input funnels through the function

+<CODE>wgetch()</CODE>, defined in <CODE>lib_getch.c</CODE>. This function is

+tricky; it has to poll for keyboard and mouse events and do a running

+match of incoming input against the set of defined special keys. <P>

+The central data structure in this module is a FIFO queue, used to

+match multiple-character input sequences against special-key

+capabilities; also to implement pushback via <CODE>ungetch()</CODE>. <P>

+The <CODE>wgetch()</CODE> code distinguishes between function key

+sequences and the same sequences typed manually by doing a timed wait

+after each input character that could lead a function key sequence.

+If the entire sequence takes less than 1 second, it is assumed to have

+been generated by a function key press. <P>

+Hackers bruised by previous encounters with variant <CODE>select(2)</CODE>

+calls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals

+with the problem that some BSD selects don't return a reliable

+time-left value. The function <CODE>timed_wait()</CODE> effectively

+simulates a System V select.

+<H3><A NAME="mouse">Mouse Events</A></H3>

+If the mouse interface is active, <CODE>wgetch()</CODE> polls for mouse

+events each call, before it goes to the keyboard for input. It is

+up to <CODE>lib_mouse.c</CODE> how the polling is accomplished; it may vary

+for different devices. <P>

+Under xterm, however, mouse event notifications come in via the keyboard

+input stream. They are recognized by having the <STRONG>kmous</STRONG> capability

+as a prefix. This is kind of klugey, but trying to wire in recognition of

+a mouse key prefix without going through the function-key machinery would

+be just too painful, and this turns out to imply having the prefix somewhere

+in the function-key capabilities at terminal-type initialization. <P>

+This kluge only works because <STRONG>kmous</STRONG> isn't actually used by any

+historic terminal type or curses implementation we know of. Best

+guess is it's a relic of some forgotten experiment in-house at Bell

+Labs that didn't leave any traces in the publicly-distributed System V

+terminfo files. If System V or XPG4 ever gets serious about using it

+again, this kluge may have to change. <P>

+Here are some more details about mouse event handling: <P>

+The <CODE>lib_mouse()</CODE>code is logically split into a lower level that

+accepts event reports in a device-dependent format and an upper level that

+parses mouse gestures and filters events. The mediating data structure is a

+circular queue of event structures. <P>

+Functionally, the lower level's job is to pick up primitive events and

+put them on the circular queue. This can happen in one of two ways:

+either (a) <CODE>_nc_mouse_event()</CODE> detects a series of incoming

+mouse reports and queues them, or (b) code in <CODE>lib_getch.c</CODE> detects the

+<STRONG>kmous</STRONG> prefix in the keyboard input stream and calls _nc_mouse_inline

+to queue up a series of adjacent mouse reports. <P>

+In either case, <CODE>_nc_mouse_parse()</CODE> should be called after the

+series is accepted to parse the digested mouse reports (low-level

+events) into a gesture (a high-level or composite event).

+<H3><A NAME="output">Output and Screen Updating</A></H3>

+With the single exception of character echoes during a <CODE>wgetnstr()</CODE>

+call (which simulates cooked-mode line editing in an ncurses window),

+the library normally does all its output at refresh time. <P>

+The main job is to go from the current state of the screen (as represented

+in the <CODE>curscr</CODE> window structure) to the desired new state (as

+represented in the <CODE>newscr</CODE> window structure), while doing as

+little I/O as possible. <P>

+The brains of this operation are the modules <CODE>hashmap.c</CODE>,

+<CODE>hardscroll.c</CODE> and <CODE>lib_doupdate.c</CODE>; the latter two use

+<CODE>lib_mvcur.c</CODE>. Essentially, what happens looks like this: <P>

+The <CODE>hashmap.c</CODE> module tries to detect vertical motion

+changes between the real and virtual screens. This information

+is represented by the oldindex members in the newscr structure.

+These are modified by vertical-motion and clear operations, and both are

+re-initialized after each update. To this change-journalling

+information, the hashmap code adds deductions made using a modified Heckel

+algorithm on hash values generated from the line contents. <P>

+The <CODE>hardscroll.c</CODE> module computes an optimum set of scroll,

+insertion, and deletion operations to make the indices match. It calls

+<CODE>_nc_mvcur_scrolln()</CODE> in <CODE>lib_mvcur.c</CODE> to do those motions. <P>

+Then <CODE>lib_doupdate.c</CODE> goes to work. Its job is to do line-by-line

+transformations of <CODE>curscr</CODE> lines to <CODE>newscr</CODE> lines. Its main

+tool is the routine <CODE>mvcur()</CODE> in <CODE>lib_mvcur.c</CODE>. This routine

+does cursor-movement optimization, attempting to get from given screen

+location A to given location B in the fewest output characters possible. <P>

+If you want to work on screen optimizations, you should use the fact

+that (in the trace-enabled version of the library) enabling the

+<CODE>TRACE_TIMES</CODE> trace level causes a report to be emitted after

+each screen update giving the elapsed time and a count of characters

+emitted during the update. You can use this to tell when an update

+optimization improves efficiency. <P>

+In the trace-enabled version of the library, it is also possible to disable

+and re-enable various optimizations at runtime by tweaking the variable

+<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE>

+for mask values, near the end.

+<H1><A NAME="fmnote">The Forms and Menu Libraries</A></H1>

+The forms and menu libraries should work reliably in any environment you

+can port ncurses to. The only portability issue anywhere in them is what

+flavor of regular expressions the built-in form field type TYPE_REGEXP

+will recognize. <P>

+The configuration code prefers the POSIX regex facility, modeled on

+System V's, but will settle for BSD regexps if the former isn't available. <P>

+Historical note: the panels code was written primarily to assist in

+porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking

+panels support; u386mon 2.10 and beyond use it. This version has been

+slightly cleaned up for <CODE>ncurses</CODE>.

+<H1><A NAME="tic">A Tour of the Terminfo Compiler</A></H1>

+The <STRONG>ncurses</STRONG> implementation of <STRONG>tic</STRONG> is rather complex

+internally; it has to do a trying combination of missions. This starts

+with the fact that, in addition to its normal duty of compiling

+terminfo sources into loadable terminfo binaries, it has to be able to

+handle termcap syntax and compile that too into terminfo entries. <P>

+The implementation therefore starts with a table-driven, dual-mode

+lexical analyzer (in <CODE>comp_scan.c</CODE>). The lexer chooses its

+mode (termcap or terminfo) based on the first `,' or `:' it finds in

+each entry. The lexer does all the work of recognizing capability

+names and values; the grammar above it is trivial, just "parse entries

+till you run out of file".

+<H2><A NAME="nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A></H2>

+Translation of most things besides <STRONG>use</STRONG> capabilities is pretty

+straightforward. The lexical analyzer's tokenizer hands each capability

+name to a hash function, which drives a table lookup. The table entry

+yields an index which is used to look up the token type in another table,

+and controls interpretation of the value. <P>

+One possibly interesting aspect of the implementation is the way the

+compiler tables are initialized. All the tables are generated by various

+awk/sed/sh scripts from a master table <CODE>include/Caps</CODE>; these

+scripts actually write C initializers which are linked to the compiler.

+Furthermore, the hash table is generated in the same way, so it doesn't

+have to be generated at compiler startup time (another benefit of this

+organization is that the hash table can be in shareable text space). <P>

+Thus, adding a new capability is usually pretty trivial, just a matter

+of adding one line to the <CODE>include/Caps</CODE> file. We'll have more

+to say about this in the section on <A HREF="#translation">Source-Form

+Translation</A>.

+<H2><A NAME="uses">Use Capability Resolution</A></H2>

+The background problem that makes <STRONG>tic</STRONG> tricky isn't the capability

+translation itself, it's the resolution of <STRONG>use</STRONG> capabilities. Older

+versions would not handle forward <STRONG>use</STRONG> references for this reason

+(that is, a using terminal always had to follow its use target in the

+source file). By doing this, they got away with a simple implementation

+tactic; compile everything as it blows by, then resolve uses from compiled

+entries. <P>

+This won't do for <STRONG>ncurses</STRONG>. The problem is that that the whole

+compilation process has to be embeddable in the <STRONG>ncurses</STRONG> library

+so that it can be called by the startup code to translate termcap

+entries on the fly. The embedded version can't go promiscuously writing

+everything it translates out to disk -- for one thing, it will typically

+be running with non-root permissions. <P>

+So our <STRONG>tic</STRONG> is designed to parse an entire terminfo file into a

+doubly-linked circular list of entry structures in-core, and then do

+<STRONG>use</STRONG> resolution in-memory before writing everything out. This

+design has other advantages: it makes forward and back use-references

+equally easy (so we get the latter for free), and it makes checking for

+name collisions before they're written out easy to do. <P>

+And this is exactly how the embedded version works. But the stand-alone

+user-accessible version of <STRONG>tic</STRONG> partly reverts to the historical

+strategy; it writes to disk (not keeping in core) any entry with no

+<STRONG>use</STRONG> references. <P>

+This is strictly a core-economy kluge, implemented because the

+terminfo master file is large enough that some core-poor systems swap

+like crazy when you compile it all in memory...there have been reports of

+this process taking <STRONG>three hours</STRONG>, rather than the twenty seconds

+or less typical on the author's development box. <P>

+So. The executable <STRONG>tic</STRONG> passes the entry-parser a hook that

+<EM>immediately</EM> writes out the referenced entry if it has no use

+capabilities. The compiler main loop refrains from adding the entry

+to the in-core list when this hook fires. If some other entry later

+needs to reference an entry that got written immediately, that's OK;

+the resolution code will fetch it off disk when it can't find it in

+core. <P>

+Name collisions will still be detected, just not as cleanly. The

+<CODE>write_entry()</CODE> code complains before overwriting an entry that

+postdates the time of <STRONG>tic</STRONG>'s first call to

+<CODE>write_entry()</CODE>, Thus it will complain about overwriting

+entries newly made during the <STRONG>tic</STRONG> run, but not about

+overwriting ones that predate it.

+<H2><A NAME="translation">Source-Form Translation</A></H2>

+Another use of <STRONG>tic</STRONG> is to do source translation between various termcap

+and terminfo formats. There are more variants out there than you might

+think; the ones we know about are described in the <STRONG>captoinfo(1)</STRONG>

+manual page. <P>

+The translation output code (<CODE>dump_entry()</CODE> in

+<CODE>ncurses/dump_entry.c</CODE>) is shared with the <STRONG>infocmp(1)</STRONG>

+utility. It takes the same internal representation used to generate

+the binary form and dumps it to standard output in a specified

+format. <P>

+The <CODE>include/Caps</CODE> file has a header comment describing ways you

+can specify source translations for nonstandard capabilities just by

+altering the master table. It's possible to set up capability aliasing

+or tell the compiler to plain ignore a given capability without writing

+any C code at all. <P>

+For circumstances where you need to do algorithmic translation, there

+are functions in <CODE>parse_entry.c</CODE> called after the parse of each

+entry that are specifically intended to encapsulate such

+translations. This, for example, is where the AIX <STRONG>box1</STRONG> capability

+get translated to an <STRONG>acsc</STRONG> string.

+<H1><A NAME="utils">Other Utilities</A></H1>

+The <STRONG>infocmp</STRONG> utility is just a wrapper around the same

+entry-dumping code used by <STRONG>tic</STRONG> for source translation. Perhaps

+the one interesting aspect of the code is the use of a predicate

+function passed in to <CODE>dump_entry()</CODE> to control which

+capabilities are dumped. This is necessary in order to handle both

+the ordinary De-compilation case and entry difference reporting. <P>

+The <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load

+followed by a <CODE>tputs()</CODE> of a selected capability.

+<H1><A NAME="style">Style Tips for Developers</A></H1>

+See the TO-DO file in the top-level directory of the source distribution

+for additions that would be particularly useful. <P>

+The prefix <CODE>_nc_</CODE> should be used on library public functions that are

+not part of the curses API in order to prevent pollution of the

+application namespace.

+If you have to add to or modify the function prototypes in curses.h.in,

+read ncurses/MKlib_gen.sh first so you can avoid breaking XSI conformance.

+Please join the ncurses mailing list. See the INSTALL file in the

+top level of the distribution for details on the list. <P>

+Look for the string <CODE>FIXME</CODE> in source files to tag minor bugs

+and potential problems that could use fixing. <P>

+Don't try to auto-detect OS features in the main body of the C code.

+That's the job of the configuration system. <P>

+To hold down complexity, do make your code data-driven. Especially,

+if you can drive logic from a table filtered out of

+<CODE>include/Caps</CODE>, do it. If you find you need to augment the

+data in that file in order to generate the proper table, that's still

+preferable to ad-hoc code -- that's why the fifth field (flags) is

+there. <P>

+Have fun!

+<H1><A NAME="port">Porting Hints</A></H1>

+The following notes are intended to be a first step towards DOS and Macintosh

+ports of the ncurses libraries. <P>

+The following library modules are `pure curses'; they operate only on

+the curses internal structures, do all output through other curses

+calls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not

+call any other UNIX routines such as signal(2) or the stdio library.

+Thus, they should not need to be modified for single-terminal

+ports.

+<blockquote>

+<code>

+lib_addch.c

+lib_addstr.c

+lib_bkgd.c

+lib_box.c

+lib_clear.c

+lib_clrbot.c

+lib_clreol.c

+lib_delch.c

+lib_delwin.c

+lib_erase.c

+lib_inchstr.c

+lib_insch.c

+lib_insdel.c

+lib_insstr.c

+lib_keyname.c

+lib_move.c

+lib_mvwin.c

+lib_newwin.c

+lib_overlay.c

+lib_pad.c

+lib_printw.c

+lib_refresh.c

+lib_scanw.c

+lib_scroll.c

+lib_scrreg.c

+lib_set_term.c

+lib_touch.c

+lib_tparm.c

+lib_tputs.c

+lib_unctrl.c

+lib_window.c

+panel.c

+</code>

+</blockquote>

+<P>

+This module is pure curses, but calls outstr():

+<blockquote>

+<code>

+lib_getstr.c

+</code>

+</blockquote>

+<P>

+These modules are pure curses, except that they use <CODE>tputs()</CODE>

+and <CODE>putp()</CODE>:

+<blockquote>

+<code>

+lib_beep.c

+lib_color.c

+lib_endwin.c

+lib_options.c

+lib_slk.c

+lib_vidattr.c

+</code>

+</blockquote>

+<P>

+This modules assist in POSIX emulation on non-POSIX systems:

+<DL>

+<DT> sigaction.c

+<DD> signal calls

+</DL>

+The following source files will not be needed for a

+single-terminal-type port.

+<blockquote>

+<code>

+alloc_entry.c

+captoinfo.c

+clear.c

+comp_captab.c

+comp_error.c

+comp_hash.c

+comp_main.c

+comp_parse.c

+comp_scan.c

+dump_entry.c

+infocmp.c

+parse_entry.c

+read_entry.c

+tput.c

+write_entry.c

+</code>

+</blockquote>

+<P>

+The following modules will use open()/read()/write()/close()/lseek() on files,

+but no other OS calls.

+<DL>

+<DT>lib_screen.c

+<DD>used to read/write screen dumps

+<DT>lib_trace.c

+<DD>used to write trace data to the logfile

+</DL>

+Modules that would have to be modified for a port start here: <P>

+The following modules are `pure curses' but contain assumptions inappropriate

+for a memory-mapped port.

+<dl>

+<dt>lib_longname.c<dd>assumes there may be multiple terminals

+<dt>lib_acs.c<dd>assumes acs_map as a double indirection

+<dt>lib_mvcur.c<dd>assumes cursor moves have variable cost

+<dt>lib_termcap.c<dd>assumes there may be multiple terminals

+<dt>lib_ti.c<dd>assumes there may be multiple terminals

+</dl>

+The following modules use UNIX-specific calls:

+<dl>

+<dt>lib_doupdate.c<dd>input checking

+<dt>lib_getch.c<dd>read()

+<dt>lib_initscr.c<dd>getenv()

+<dt>lib_newterm.c

+<dt>lib_baudrate.c

+<dt>lib_kernel.c<dd>various tty-manipulation and system calls

+<dt>lib_raw.c<dd>various tty-manipulation calls

+<dt>lib_setup.c<dd>various tty-manipulation calls

+<dt>lib_restart.c<dd>various tty-manipulation calls

+<dt>lib_tstp.c<dd>signal-manipulation calls

+<dt>lib_twait.c<dd>gettimeofday(), select().

+</dl>

+<HR>

+<ADDRESS>Eric S. Raymond <esr@snark.thyrsus.com></ADDRESS>

+(Note: This is <EM>not</EM> the <A HREF="#bugtrack">bug address</A>!)

+</BODY>

+</HTML>

diff --git a/doc/html/ncurses-intro.html b/doc/html/ncurses-intro.html
new file mode 100644
index 000000000000..451e7ab4d32d
--- /dev/null
+++ b/doc/html/ncurses-intro.html

@@ -0,0 +1,2722 @@

+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">

+<!--

+ $Id: ncurses-intro.html,v 1.43 2007/03/03 19:31:50 tom Exp $

+ ****************************************************************************

+ * *

+ * Permission is hereby granted, free of charge, to any person obtaining a *

+ * copy of this software and associated documentation files (the *

+ * "Software"), to deal in the Software without restriction, including *

+ * without limitation the rights to use, copy, modify, merge, publish, *

+ * distribute, distribute with modifications, sublicense, and/or sell *

+ * copies of the Software, and to permit persons to whom the Software is *

+ * furnished to do so, subject to the following conditions: *

+ * *

+ * The above copyright notice and this permission notice shall be included *

+ * in all copies or substantial portions of the Software. *

+ * *

+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

+ * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

+ * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

+ * *

+ * Except as contained in this notice, the name(s) of the above copyright *

+ * holders shall not be used in advertising or otherwise to promote the *

+ * sale, use or other dealings in this Software without prior written *

+ * authorization. *

+ ****************************************************************************

+-->

+<HTML>

+<HEAD>

+<TITLE>Writing Programs with NCURSES</TITLE>

+<link rev="made" href="mailto:bugs-ncurses@gnu.org">

+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

+</HEAD>

+<BODY>

+<H1>Writing Programs with NCURSES</H1>

+<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><A HREF="#scope">Scope of This Document</A>

+<LI><A HREF="#terminology">Terminology</A>

+</UL>

+<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><A HREF="#updating">Updating the Screen</A>

+<LI><A HREF="#stdscr">Standard Windows and Function Naming Conventions</A>

+<LI><A HREF="#variables">Variables</A>

+</UL>

+<LI><A HREF="#using">Using the Library</A>

+<UL>

+<LI><A HREF="#starting">Starting up</A>

+<LI><A HREF="#output">Output</A>

+<LI><A HREF="#input">Input</A>

+<LI><A HREF="#formschars">Using Forms Characters</A>

+<LI><A HREF="#attributes">Character Attributes and Color</A>

+<LI><A HREF="#mouse">Mouse Interfacing</A>

+<LI><A HREF="#finishing">Finishing Up</A>

+</UL>

+<LI><A HREF="#functions">Function Descriptions</A>

+<UL>

+<LI><A HREF="#init">Initialization and Wrapup</A>

+<LI><A HREF="#flush">Causing Output to the Terminal</A>

+<LI><A HREF="#lowlevel">Low-Level Capability Access</A>

+<LI><A HREF="#debugging">Debugging</A>

+</UL>

+<LI><A HREF="#hints">Hints, Tips, and Tricks</A>

+<UL>

+<LI><A HREF="#caution">Some Notes of Caution</A>

+<LI><A HREF="#leaving">Temporarily Leaving ncurses Mode</A>

+<LI><A HREF="#xterm">Using <CODE>ncurses</CODE> under <CODE>xterm</CODE></A>

+<LI><A HREF="#screens">Handling Multiple Terminal Screens</A>

+<LI><A HREF="#testing">Testing for Terminal Capabilities</A>

+<LI><A HREF="#tuning">Tuning for Speed</A>

+<LI><A HREF="#special">Special Features of <CODE>ncurses</CODE></A>

+</UL>

+<LI><A HREF="#compat">Compatibility with Older Versions</A>

+<UL>

+<LI><A HREF="#refbug">Refresh of Overlapping Windows</A>

+<LI><A HREF="#backbug">Background Erase</A>

+</UL>

+<LI><A HREF="#xsifuncs">XSI Curses Conformance</A>

+</UL>

+<LI><A HREF="#panels">The Panels Library</A>

+<UL>

+<LI><A HREF="#pcompile">Compiling With the Panels Library</A>

+<LI><A HREF="#poverview">Overview of Panels</A>

+<LI><A HREF="#pstdscr">Panels, Input, and the Standard Screen</A>

+<LI><A HREF="#hiding">Hiding Panels</A>

+<LI><A HREF="#pmisc">Miscellaneous Other Facilities</A>

+</UL>

+<LI><A HREF="#menu">The Menu Library</A>

+<UL>

+<LI><A HREF="#mcompile">Compiling with the menu Library</A>

+<LI><A HREF="#moverview">Overview of Menus</A>

+<LI><A HREF="#mselect">Selecting items</A>

+<LI><A HREF="#mdisplay">Menu Display</A>

+<LI><A HREF="#mwindows">Menu Windows</A>

+<LI><A HREF="#minput">Processing Menu Input</A>

+<LI><A HREF="#mmisc">Miscellaneous Other Features</A>

+</UL>

+<LI><A HREF="#form">The Forms Library</A>

+<UL>

+<LI><A HREF="#fcompile">Compiling with the forms Library</A>

+<LI><A HREF="#foverview">Overview of Forms</A>

+<LI><A HREF="#fcreate">Creating and Freeing Fields and Forms</A>

+<LI><A HREF="#fattributes">Fetching and Changing Field Attributes</A>

+<UL>

+<LI><A HREF="#fsizes">Fetching Size and Location Data</A>

+<LI><A HREF="#flocation">Changing the Field Location</A>

+<LI><A HREF="#fjust">The Justification Attribute</A>

+<LI><A HREF="#fdispatts">Field Display Attributes</A>

+<LI><A HREF="#foptions">Field Option Bits</A>

+<LI><A HREF="#fstatus">Field Status</A>

+<LI><A HREF="#fuser">Field User Pointer</A>

+</UL>

+<LI><A HREF="#fdynamic">Variable-Sized Fields</A>

+<LI><A HREF="#fvalidation">Field Validation</A>

+<UL>

+<LI><A HREF="#ftype_alpha">TYPE_ALPHA</A>

+<LI><A HREF="#ftype_alnum">TYPE_ALNUM</A>

+<LI><A HREF="#ftype_enum">TYPE_ENUM</A>

+<LI><A HREF="#ftype_integer">TYPE_INTEGER</A>

+<LI><A HREF="#ftype_numeric">TYPE_NUMERIC</A>

+<LI><A HREF="#ftype_regexp">TYPE_REGEXP</A>

+</UL>

+<LI><A HREF="#fbuffer">Direct Field Buffer Manipulation</A>

+<LI><A HREF="#formattrs">Attributes of Forms</A>

+<LI><A HREF="#fdisplay">Control of Form Display</A>

+<LI><A HREF="#fdriver">Input Processing in the Forms Driver</A>

+<UL>

+<LI><A HREF="#fpage">Page Navigation Requests</A>

+<LI><A HREF="#ffield">Inter-Field Navigation Requests</A>

+<LI><A HREF="#fifield">Intra-Field Navigation Requests</A>

+<LI><A HREF="#fscroll">Scrolling Requests</A>

+<LI><A HREF="#fedit">Field Editing Requests</A>

+<LI><A HREF="#forder">Order Requests</A>

+<LI><A HREF="#fappcmds">Application Commands</A>

+</UL>

+<LI><A HREF="#fhooks">Field Change Hooks</A>

+<LI><A HREF="#ffocus">Field Change Commands</A>

+<LI><A HREF="#frmoptions">Form Options</A>

+<LI><A HREF="#fcustom">Custom Validation Types</A>

+<UL>

+<LI><A HREF="#flinktypes">Union Types</A>

+<LI><A HREF="#fnewtypes">New Field Types</A>

+<LI><A HREF="#fcheckargs">Validation Function Arguments</A>

+<LI><A HREF="#fcustorder">Order Functions For Custom Types</A>

+<LI><A HREF="#fcustprobs">Avoiding Problems</A>

+</UL>

+<HR>

+<H1><A NAME="introduction">Introduction</A></H1>

+This document is an introduction to programming with <CODE>curses</CODE>. It is

+not an exhaustive reference for the curses Application Programming Interface

+(API); that role is filled by the <CODE>curses</CODE> manual pages. Rather, it

+is intended to help C programmers ease into using the package. <P>

+This document is aimed at C applications programmers not yet specifically

+familiar with ncurses. If you are already an experienced <CODE>curses</CODE>

+programmer, you should nevertheless read the sections on

+<A HREF="#mouse">Mouse Interfacing</A>, <A HREF="#debugging">Debugging</A>,

+<A HREF="#compat">Compatibility with Older Versions</A>,

+and <A HREF="#hints">Hints, Tips, and Tricks</A>. These will bring you up

+to speed on the special features and quirks of the <CODE>ncurses</CODE>

+implementation. If you are not so experienced, keep reading. <P>

+The <CODE>curses</CODE> package is a subroutine library for

+terminal-independent screen-painting and input-event handling which

+presents a high level screen model to the programmer, hiding differences

+between terminal types and doing automatic optimization of output to change

+one screen full of text into another. <CODE>Curses</CODE> uses terminfo, which

+is a database format that can describe the capabilities of thousands of

+different terminals. <P>

+The <CODE>curses</CODE> API may seem something of an archaism on UNIX desktops

+increasingly dominated by X, Motif, and Tcl/Tk. Nevertheless, UNIX still

+supports tty lines and X supports <EM>xterm(1)</EM>; the <CODE>curses</CODE>

+API has the advantage of (a) back-portability to character-cell terminals,

+and (b) simplicity. For an application that does not require bit-mapped

+graphics and multiple fonts, an interface implementation using <CODE>curses</CODE>

+will typically be a great deal simpler and less expensive than one using an

+X toolkit.

+<H2><A NAME="history">A Brief History of Curses</A></H2>

+Historically, the first ancestor of <CODE>curses</CODE> was the routines written to

+provide screen-handling for the game <CODE>rogue</CODE>; these used the

+already-existing <CODE>termcap</CODE> database facility for describing terminal

+capabilities. These routines were abstracted into a documented library and

+first released with the early BSD UNIX versions. <P>

+System III UNIX from Bell Labs featured a rewritten and much-improved

+<CODE>curses</CODE> library. It introduced the terminfo format. Terminfo is based

+on Berkeley's termcap database, but contains a number of improvements and

+extensions. Parameterized capabilities strings were introduced, making it

+possible to describe multiple video attributes, and colors and to handle far

+more unusual terminals than possible with termcap. In the later AT&T

+System V releases, <CODE>curses</CODE> evolved to use more facilities and offer

+more capabilities, going far beyond BSD curses in power and flexibility.

+<H2><A NAME="scope">Scope of This Document</A></H2>

+This document describes <CODE>ncurses</CODE>, a free implementation of

+the System V <CODE>curses</CODE> API with some clearly marked extensions.

+It includes the following System V curses features:

+<UL>

+<LI>Support for multiple screen highlights (BSD curses could only

+handle one `standout' highlight, usually reverse-video).

+<LI>Support for line- and box-drawing using forms characters.

+<LI>Recognition of function keys on input.

+<LI>Color support.

+<LI>Support for pads (windows of larger than screen size on which the

+screen or a subwindow defines a viewport).

+</UL>

+Also, this package makes use of the insert and delete line and character

+features of terminals so equipped, and determines how to optimally use these

+features with no help from the programmer. It allows arbitrary combinations of

+video attributes to be displayed, even on terminals that leave ``magic

+cookies'' on the screen to mark changes in attributes. <P>

+The <CODE>ncurses</CODE> package can also capture and use event reports from a

+mouse in some environments (notably, xterm under the X window system). This

+document includes tips for using the mouse. <P>

+The <CODE>ncurses</CODE> package was originated by Pavel Curtis. The original

+maintainer of this package is

+<A HREF="mailto:zmbenhal@netcom.com">Zeyd Ben-Halim</A>

+<zmbenhal@netcom.com>.

+<A HREF="mailto:esr@snark.thyrsus.com">Eric S. Raymond</A>

+<esr@snark.thyrsus.com>

+wrote many of the new features in versions after 1.8.1

+and wrote most of this introduction.

+Jürgen Pfeifer

+wrote all of the menu and forms code as well as the

+<A HREF="http://www.adahome.com">Ada95</A> binding.

+Ongoing work is being done by

+<A HREF="mailto:dickey@invisible-island.net">Thomas Dickey</A> (maintainer).

+Contact the current maintainers at

+<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>.

+<P>

+This document also describes the <A HREF="#panels">panels</A> extension library,

+similarly modeled on the SVr4 panels facility. This library allows you to

+associate backing store with each of a stack or deck of overlapping windows,

+and provides operations for moving windows around in the stack that change

+their visibility in the natural way (handling window overlaps). <P>

+Finally, this document describes in detail the <A HREF="#menu">menus</A> and <A

+HREF="#form">forms</A> extension libraries, also cloned from System V,

+which support easy construction and sequences of menus and fill-in

+forms.

+<H2><A NAME="terminology">Terminology</A></H2>

+In this document, the following terminology is used with reasonable

+consistency:

+<DL>

+<DT> window

+<DD>

+A data structure describing a sub-rectangle of the screen (possibly the

+entire screen). You can write to a window as though it were a miniature

+screen, scrolling independently of other windows on the physical screen.

+<DT> screens

+<DD>

+A subset of windows which are as large as the terminal screen, i.e., they start

+at the upper left hand corner and encompass the lower right hand corner. One

+of these, <CODE>stdscr</CODE>, is automatically provided for the programmer.

+<DT> terminal screen

+<DD>

+The package's idea of what the terminal display currently looks like, i.e.,

+what the user sees now. This is a special screen.

+</DL>

+<H1><A NAME="curses">The Curses Library</A></H1>

+<H2><A NAME="overview">An Overview of Curses</A></H2>

+<H3><A NAME="compiling">Compiling Programs using Curses</A></H3>

+In order to use the library, it is necessary to have certain types and

+variables defined. Therefore, the programmer must have a line:

+<PRE>

+ #include <curses.h>

+</PRE>

+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 includes

+<CODE><termios.h></CODE>, <CODE><termio.h></CODE>, or

+<CODE><sgtty.h></CODE> depending on your system. It is redundant (but

+harmless) for the programmer to do these includes, too. In linking with

+<CODE>curses</CODE> you need to have <CODE>-lncurses</CODE> in your LDFLAGS or on the

+command line. There is no need for any other libraries.

+<H3><A NAME="updating">Updating the Screen</A></H3>

+In order to update the screen optimally, it is necessary for the routines to

+know what the screen currently looks like and what the programmer wants it to

+look like next. For this purpose, a data type (structure) named WINDOW is

+defined which describes a window image to the routines, including its starting

+position on the screen (the (y, x) coordinates of the upper left hand corner)

+and its size. One of these (called <CODE>curscr</CODE>, for current screen) is a

+screen image of what the terminal currently looks like. Another screen (called

+<CODE>stdscr</CODE>, for standard screen) is provided by default to make changes

+on. <P>

+A window is a purely internal representation. It is used to build and store a

+potential image of a portion of the terminal. It doesn't bear any necessary

+relation to what is really on the terminal screen; it's more like a

+scratchpad or write buffer. <P>

+To make the section of physical screen corresponding to a window reflect the

+contents of the window structure, the routine <CODE>refresh()</CODE> (or

+<CODE>wrefresh()</CODE> if the window is not <CODE>stdscr</CODE>) is called. <P>

+A given physical screen section may be within the scope of any number of

+overlapping windows. Also, changes can be made to windows in any order,

+without regard to motion efficiency. Then, at will, the programmer can

+effectively say ``make it look like this,'' and let the package implementation

+determine the most efficient way to repaint the screen.

+<H3><A NAME="stdscr">Standard Windows and Function Naming Conventions</A></H3>

+As hinted above, the routines can use several windows, but two are

+automatically given: <CODE>curscr</CODE>, which knows what the terminal looks like,

+and <CODE>stdscr</CODE>, which is what the programmer wants the terminal to look

+like next. The user should never actually access <CODE>curscr</CODE> directly.

+Changes should be made to through the API, and then the routine

+<CODE>refresh()</CODE> (or <CODE>wrefresh()</CODE>) called. <P>

+Many functions are defined to use <CODE>stdscr</CODE> as a default screen. For

+example, to add a character to <CODE>stdscr</CODE>, one calls <CODE>addch()</CODE> with

+the desired character as argument. To write to a different window. use the

+routine <CODE>waddch()</CODE> (for `w'indow-specific addch()) is provided. This

+convention of prepending function names with a `w' when they are to be

+applied to specific windows is consistent. The only routines which do not

+follow it are those for which a window must always be specified. <P>

+In order to move the current (y, x) coordinates from one point to another, the

+routines <CODE>move()</CODE> and <CODE>wmove()</CODE> are provided. However, it is

+often desirable to first move and then perform some I/O operation. In order to

+avoid clumsiness, most I/O routines can be preceded by the prefix 'mv' and

+the desired (y, x) coordinates prepended to the arguments to the function. For

+example, the calls

+<PRE>

+ move(y, x);

+ addch(ch);

+</PRE>

+can be replaced by

+<PRE>

+ mvaddch(y, x, ch);

+</PRE>

+and

+<PRE>

+ wmove(win, y, x);

+ waddch(win, ch);

+</PRE>

+can be replaced by

+<PRE>

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

+</PRE>

+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.

+<H3><A NAME="variables">Variables</A></H3>

+The <CODE>curses</CODE> library sets some variables describing the terminal

+capabilities.

+<PRE>

+ type name description

+ ------------------------------------------------------------------

+ int LINES number of lines on the terminal

+ int COLS number of columns on the terminal

+</PRE>

+The <CODE>curses.h</CODE> also introduces some <CODE>#define</CODE> constants and types

+of general usefulness:

+<DL>

+<DT> <CODE>bool</CODE>

+<DD> boolean type, actually a `char' (e.g., <CODE>bool doneit;</CODE>)

+<DT> <CODE>TRUE</CODE>

+<DD> boolean `true' flag (1).

+<DT> <CODE>FALSE</CODE>

+<DD> boolean `false' flag (0).

+<DT> <CODE>ERR</CODE>

+<DD> error flag returned by routines on a failure (-1).

+<DT> <CODE>OK</CODE>

+<DD> error flag returned by routines when things go right.

+</DL>

+<H2><A NAME="using">Using the Library</A></H2>

+Now we describe how to actually use the screen package. In it, we assume all

+updating, reading, etc. is applied to <CODE>stdscr</CODE>. These instructions will

+work on any window, providing you change the function names and parameters as

+mentioned above. <P>

+Here is a sample program to motivate the discussion:

+<PRE>

+#include <curses.h>

+#include <signal.h>

+static void finish(int sig);

+int

+main(int argc, char *argv[])

+ int num = 0;

+ /* initialize your non-curses data structures here */

+ (void) signal(SIGINT, finish); /* arrange interrupts to terminate */

+ (void) initscr(); /* initialize the curses library */

+ keypad(stdscr, TRUE); /* enable keyboard mapping */

+ (void) nonl(); /* tell curses not to do NL->CR/NL on output */

+ (void) cbreak(); /* take input chars one at a time, no wait for \n */

+ (void) echo(); /* echo input - in color */

+ if (has_colors())

+ {

+ start_color();

+ /*

+ * Simple color assignment, often all we need. Color pair 0 cannot

+ * be redefined. This example uses the same value for the color

+ * pair as for the foreground color, though of course that is not

+ * necessary:

+ */

+ init_pair(1, COLOR_RED, COLOR_BLACK);

+ init_pair(2, COLOR_GREEN, COLOR_BLACK);

+ init_pair(3, COLOR_YELLOW, COLOR_BLACK);

+ init_pair(4, COLOR_BLUE, COLOR_BLACK);

+ init_pair(5, COLOR_CYAN, COLOR_BLACK);

+ init_pair(6, COLOR_MAGENTA, COLOR_BLACK);

+ init_pair(7, COLOR_WHITE, COLOR_BLACK);

+ }

+ for (;;)

+ {

+ int c = getch(); /* refresh, accept single keystroke of input */

+ attrset(COLOR_PAIR(num % 8));

+ num++;

+ /* process the command keystroke */

+ }

+ finish(0); /* we're done */

+static void finish(int sig)

+ endwin();

+ /* do your non-curses wrapup here */

+ exit(0);

+</PRE>

+<H3><A NAME="starting">Starting up</A></H3>

+In order to use the screen package, the routines must know about terminal

+characteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be

+allocated. These function <CODE>initscr()</CODE> does both these things. Since it

+must allocate space for the windows, it can overflow memory when attempting to

+do so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate

+the program with an error message. <CODE>initscr()</CODE> must always be called

+before any of the routines which affect windows are used. If it is not, the

+program will core dump as soon as either <CODE>curscr</CODE> or <CODE>stdscr</CODE> are

+referenced. However, it is usually best to wait to call it until after you are

+sure you will need it, like after checking for startup errors. Terminal status

+changing routines like <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called

+after <CODE>initscr()</CODE>. <P>

+Once the screen windows have been allocated, you can set them up for

+your program. If you want to, say, allow a screen to scroll, use

+<CODE>scrollok()</CODE>. If you want the cursor to be left in place after

+the last change, use <CODE>leaveok()</CODE>. If this isn't done,

+<CODE>refresh()</CODE> will move the cursor to the window's current (y, x)

+coordinates after updating it. <P>

+You can create new windows of your own using the functions <CODE>newwin()</CODE>,

+<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>. The routine <CODE>delwin()</CODE> will

+allow you to get rid of old windows. All the options described above can be

+applied to any window.

+<H3><A NAME="output">Output</A></H3>

+Now that we have set things up, we will want to actually update the terminal.

+The basic functions used to change what will go on a window are

+<CODE>addch()</CODE> and <CODE>move()</CODE>. <CODE>addch()</CODE> adds a character at the

+current (y, x) coordinates. <CODE>move()</CODE> changes the current (y, x)

+coordinates to whatever you want them to be. It returns <CODE>ERR</CODE> if you

+try to move off the window. As mentioned above, you can combine the two into

+<CODE>mvaddch()</CODE> to do both things at once. <P>

+The other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>,

+all call <CODE>addch()</CODE> to add characters to the window. <P>

+After you have put on the window what you want there, when you want the portion

+of the terminal covered by the window to be made to look like it, you must call

+<CODE>refresh()</CODE>. In order to optimize finding changes, <CODE>refresh()</CODE>

+assumes that any part of the window not changed since the last

+<CODE>refresh()</CODE> of that window has not been changed on the terminal, i.e.,

+that you have not refreshed a portion of the terminal with an overlapping

+window. If this is not the case, the routine <CODE>touchwin()</CODE> is provided

+to make it look like the entire window has been changed, thus making

+<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P>

+If you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will

+make the screen look like <CODE>curscr</CODE> thinks it looks like. This is useful

+for implementing a command which would redraw the screen in case it get messed

+up.

+<H3><A NAME="input">Input</A></H3>

+The complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if

+echo is set, will call <CODE>addch()</CODE> to echo the character. Since the

+screen package needs to know what is on the terminal at all times, if

+characters are to be echoed, the tty must be in raw or cbreak mode. Since

+initially the terminal has echoing enabled and is in ordinary ``cooked'' mode,

+one or the other has to changed before calling <CODE>getch()</CODE>; otherwise,

+the program's output will be unpredictable. <P>

+When you need to accept line-oriented input in a window, the functions

+<CODE>wgetstr()</CODE> and friends are available. There is even a <CODE>wscanw()</CODE>

+function that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window

+input. These pseudo-line-oriented functions turn on echoing while they

+execute. <P>

+The example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable

+support for function-key mapping. With this feature, the <CODE>getch()</CODE> code

+watches the input stream for character sequences that correspond to arrow and

+function keys. These sequences are returned as pseudo-character values. The

+<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The

+mapping from sequences to <CODE>#define</CODE> values is determined by

+<CODE>key_</CODE> capabilities in the terminal's terminfo entry.

+<H3><A NAME="formschars">Using Forms Characters</A></H3>

+The <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and

+<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially

+defined by <CODE>ncurses</CODE>. These are <CODE>#define</CODE> values set up in

+the <CODE>curses.h</CODE> header; see there for a complete list (look for

+the prefix <CODE>ACS_</CODE>). <P>

+The most useful of the ACS defines are the forms-drawing characters. You can

+use these to draw boxes and simple graphs on the screen. If the terminal

+does not have such characters, <CODE>curses.h</CODE> will map them to a

+recognizable (though ugly) set of ASCII defaults.

+<H3><A NAME="attributes">Character Attributes and Color</A></H3>

+The <CODE>ncurses</CODE> package supports screen highlights including standout,

+reverse-video, underline, and blink. It also supports color, which is treated

+as another kind of highlight. <P>

+Highlights are encoded, internally, as high bits of the pseudo-character type

+(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a

+screen cell. See the <CODE>curses.h</CODE> header file for a complete list of

+highlight mask values (look for the prefix <CODE>A_</CODE>).<P>

+There are two ways to make highlights. One is to logical-or the value of the

+highlights you want into the character argument of an <CODE>addch()</CODE> call,

+or any other output call that takes a <CODE>chtype</CODE> argument. <P>

+The other is to set the current-highlight value. This is logical-or'ed with

+any highlight you specify the first way. You do this with the functions

+<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual

+pages for details.

+Color is a special kind of highlight. The package actually thinks in terms

+of color pairs, combinations of foreground and background colors. The sample

+code above sets up eight color pairs, all of the guaranteed-available colors

+on black. Note that each color pair is, in effect, given the name of its

+foreground color. Any other range of eight non-conflicting values could

+have been used as the first arguments of the <CODE>init_pair()</CODE> values. <P>

+Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can

+use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular

+color combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N,

+is itself a compile-time constant and can be used in initializers.

+<H3><A NAME="mouse">Mouse Interfacing</A></H3>

+The <CODE>ncurses</CODE> library also provides a mouse interface.

+

+<blockquote>

+<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, it is not part of either

+the XSI Curses standard, nor of System V Release 4, nor BSD curses.

+System V Release 4 curses contains code with similar interface definitions,

+however it is not documented. Other than by disassembling the library, we

+have no way to determine exactly how that mouse code works.

+Thus, we recommend that you wrap mouse-related code in an #ifdef using the

+feature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked

+on non-ncurses systems.

+</blockquote>

+Presently, mouse event reporting works in the following environments:

+<ul>

+<li>xterm and similar programs such as rxvt.

+<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro

+Rubini's mouse server.

+<li>FreeBSD sysmouse (console)

+<li>OS/2 EMX

+</ul>

+<P>

+The mouse interface is very simple. To activate it, you use the function

+<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies

+what kinds of events you want your program to be able to see. It will

+return the bit-mask of events that actually become visible, which may differ

+from the argument if the mouse device is not capable of reporting some of

+the event types you specify. <P>

+Once the mouse is active, your application's command loop should watch

+for a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>. When

+you see this, a mouse event report has been queued. To pick it off

+the queue, use the function <CODE>getmouse()</CODE> (you must do this before

+the next <CODE>wgetch()</CODE>, otherwise another mouse event might come

+in and make the first one inaccessible). <P>

+Each call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll

+pass it) with mouse event data. The event data includes zero-origin,

+screen-relative character-cell coordinates of the mouse pointer. It also

+includes an event mask. Bits in this mask will be set, corresponding

+to the event type being reported. <P>

+The mouse structure contains two additional fields which may be

+significant in the future as ncurses interfaces to new kinds of

+pointing device. In addition to x and y coordinates, there is a slot

+for a z coordinate; this might be useful with touch-screens that can

+return a pressure or duration parameter. There is also a device ID

+field, which could be used to distinguish between multiple pointing

+devices. <P>

+The class of visible events may be changed at any time via <CODE>mousemask()</CODE>.

+Events that can be reported include presses, releases, single-, double- and

+triple-clicks (you can set the maximum button-down time for clicks). If

+you don't make clicks visible, they will be reported as press-release

+pairs. In some environments, the event mask may include bits reporting

+the state of shift, alt, and ctrl keys on the keyboard during the event. <P>

+A function to check whether a mouse event fell within a given window is

+also supplied. You can use this to see whether a given window should

+consider a mouse event relevant to it. <P>

+Because mouse event reporting will not be available in all

+environments, it would be unwise to build <CODE>ncurses</CODE>

+applications that <EM>require</EM> the use of a mouse. Rather, you should

+use the mouse as a shortcut for point-and-shoot commands your application

+would normally accept from the keyboard. Two of the test games in the

+<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain

+code that illustrates how this can be done. <P>

+See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the

+mouse-interface functions.

+<H3><A NAME="finishing">Finishing Up</A></H3>

+In order to clean up after the <CODE>ncurses</CODE> routines, the routine

+<CODE>endwin()</CODE> is provided. It restores tty modes to what they were when

+<CODE>initscr()</CODE> was first called, and moves the cursor down to the

+lower-left corner. Thus, anytime after the call to initscr, <CODE>endwin()</CODE>

+should be called before exiting.

+<H2><A NAME="functions">Function Descriptions</A></H2>

+We describe the detailed behavior of some important curses functions here, as a

+supplement to the manual page descriptions.

+<H3><A NAME="init">Initialization and Wrapup</A></H3>

+<DL>

+<DT> <CODE>initscr()</CODE>

+<DD> The first function called should almost always be <CODE>initscr()</CODE>.

+This will determine the terminal type and

+initialize curses data structures. <CODE>initscr()</CODE> also arranges that

+the first call to <CODE>refresh()</CODE> 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 (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>,

+<CODE>ripoffline()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple

+terminals, <CODE>newterm()</CODE>.)

+<DT> <CODE>endwin()</CODE>

+<DD> Your program should always call <CODE>endwin()</CODE> before exiting or

+shelling out of the program. This function will restore tty modes,

+move the cursor to the lower left corner of the screen, reset the

+terminal into the proper non-visual mode. Calling <CODE>refresh()</CODE>

+or <CODE>doupdate()</CODE> after a temporary escape from the program will

+restore the ncurses screen from before the escape.

+<DT> <CODE>newterm(type, ofp, ifp)</CODE>

+<DD> A program which outputs to more than one terminal should use

+<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should

+be called once for each terminal. It returns a variable of type

+<CODE>SCREEN *</CODE> which should be saved as a reference to that

+terminal.

+(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we

+are describing in this introduction, but a collection of

+parameters used to assist in optimizing the display.)

+The arguments are the type of the terminal (a string) and

+<CODE>FILE</CODE> pointers for the output and input of the terminal. If

+type is NULL then the environment variable <CODE>$TERM</CODE> is used.

+<CODE>endwin()</CODE> should called once at wrapup time for each terminal

+opened using this function.

+<DT> <CODE>set_term(new)</CODE>

+<DD> This function is used to switch to a different terminal previously

+opened by <CODE>newterm()</CODE>. The screen reference for the new terminal

+is passed as the parameter. The previous terminal is returned by the

+function. All other calls affect only the current terminal.

+<DT> <CODE>delscreen(sp)</CODE>

+<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures

+associated with a given <CODE>SCREEN</CODE> reference.

+</DL>

+<H3><A NAME="flush">Causing Output to the Terminal</A></H3>

+<DL>

+<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE>

+<DD> These functions must be called to actually get any output on

+the terminal, as other routines merely manipulate data

+structures. <CODE>wrefresh()</CODE> copies the named window to the physical

+terminal screen, taking into account what is already

+there in order to do optimizations. <CODE>refresh()</CODE> does a

+refresh of <CODE>stdscr</CODE>. Unless <CODE>leaveok()</CODE> has been

+enabled, the physical cursor of the terminal is left at the

+location of the window's cursor.

+<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE>

+<DD> These two functions allow multiple updates with more efficiency

+than wrefresh. To use them, it is important to understand how curses

+works. In addition to all the window structures, curses keeps two

+data structures representing the terminal screen: a physical screen,

+describing what is actually on the screen, and a virtual screen,

+describing what the programmer wants to have on the screen. wrefresh

+works by first copying the named window to the virtual screen

+(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the

+screen (<CODE>doupdate()</CODE>). If the programmer wishes to output

+several windows at once, a series of calls to <CODE>wrefresh</CODE> will result

+in alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>,

+causing several bursts of output to the screen. By calling

+<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call

+<CODE>doupdate()</CODE> once, resulting in only one burst of output, with

+fewer total characters transmitted (this also avoids a visually annoying

+flicker at each update).

+</DL>

+<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3>

+<DL>

+<DT> <CODE>setupterm(term, filenum, errret)</CODE>

+<DD> This routine is called to initialize a terminal's description, without setting

+up the curses screen structures or changing the tty-driver mode bits.

+<CODE>term</CODE> is the character string representing the name of the terminal

+being used. <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to

+be used for output. <CODE>errret</CODE> is a pointer to an integer, in which a

+success or failure 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 as NULL, meaning no error code is wanted. If <CODE>errret</CODE> is

+defaulted, and something goes wrong, <CODE>setupterm()</CODE> will print an

+appropriate error message and exit, rather than returning. Thus, a simple

+program can call setupterm(0, 1, 0) and not worry about initialization

+errors. <P>

+After the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is

+set to point to the current structure of terminal capabilities. By calling

+<CODE>setupterm()</CODE> for each terminal, and saving and restoring

+<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at

+once. <CODE>Setupterm()</CODE> also stores the names section of the terminal

+description in the global character array <CODE>ttytype[]</CODE>. Subsequent calls

+to <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it

+yourself if need be.

+</DL>

+<H3><A NAME="debugging">Debugging</A></H3>

+

+<blockquote>

+<strong>NOTE:</strong> These functions are not part of the standard curses API!

+</blockquote>

+<DL>

+<DT> <CODE>trace()</CODE>

+<DD>

+This function can be used to explicitly set a trace level. If the

+trace level is nonzero, execution of your program will generate a file

+called `trace' in the current working directory containing a report on

+the library's actions. Higher trace levels enable more detailed (and

+verbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines

+in the <CODE>curses.h</CODE> file for details. (It is also possible to set

+a trace level by assigning a trace level value to the environment variable

+<CODE>NCURSES_TRACE</CODE>).

+<DT> <CODE>_tracef()</CODE>

+<DD>

+This function can be used to output your own debugging information. It is only

+available only if you link with -lncurses_g. It can be used the same way as

+<CODE>printf()</CODE>, only it outputs a newline after the end of arguments.

+The output goes to a file called <CODE>trace</CODE> in the current directory.

+</DL>

+Trace logs can be difficult to interpret due to the sheer volume of

+data dumped in them. There is a script called <STRONG>tracemunch</STRONG>

+included with the <CODE>ncurses</CODE> distribution that can alleviate

+this problem somewhat; it compacts long sequences of similar operations into

+more succinct single-line pseudo-operations. These pseudo-ops can be

+distinguished by the fact that they are named in capital letters.

+<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2>

+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.

+<H3><A NAME="caution">Some Notes of Caution</A></H3>

+If you find yourself thinking you need to use <CODE>noraw()</CODE> or

+<CODE>nocbreak()</CODE>, think again and move carefully. It's probably

+better design to use <CODE>getstr()</CODE> or one of its relatives to

+simulate cooked mode. The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE>

+functions try to restore cooked mode, but they may end up clobbering

+some control bits set before you started your application. Also, they

+have always been poorly documented, and are likely to hurt your

+application's usability with other curses libraries. <P>

+Bear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>.

+Don't try to mix use of <CODE>stdscr</CODE> with use of windows declared

+by <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the

+screen. The right way to handle this is to use <CODE>subwin()</CODE>, or

+not touch <CODE>stdscr</CODE> at all and tile your screen with declared

+windows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program

+event loop, with a single <CODE>doupdate()</CODE> call to trigger actual

+repainting. <P>

+You are much less likely to run into problems if you design your screen

+layouts to use tiled rather than overlapping windows. Historically,

+curses support for overlapping windows has been weak, fragile, and poorly

+documented. The <CODE>ncurses</CODE> library is not yet an exception to this

+rule. <P>

+There is a panels library included in the <CODE>ncurses</CODE>

+distribution that does a pretty good job of strengthening the

+overlapping-windows facilities. <P>

+Try to avoid using the global variables LINES and COLS. Use

+<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> context instead. Reason:

+your code may be ported to run in an environment with window resizes,

+in which case several screens could be open with different sizes.

+<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3>

+Sometimes you will want to write a program that spends most of its time in

+screen mode, but occasionally returns to ordinary `cooked' mode. A common

+reason for this is to support shell-out. This behavior is simple to arrange

+in <CODE>ncurses</CODE>. <P>

+To leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you

+were intending to terminate the program. This will take the screen back to

+cooked mode; you can do your shell-out. When you want to return to

+<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>.

+This will repaint the screen. <P>

+There is a boolean function, <CODE>isendwin()</CODE>, which code can use to

+test whether <CODE>ncurses</CODE> screen mode is active. It returns <CODE>TRUE</CODE>

+in the interval between an <CODE>endwin()</CODE> call and the following

+<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise. <P>

+Here is some sample code for shellout:

+<PRE>

+ addstr("Shelling out...");

+ def_prog_mode(); /* save current tty modes */

+ endwin(); /* restore original tty modes */

+ system("sh"); /* run shell */

+ addstr("returned.\n"); /* prepare return message */

+ refresh(); /* restore save modes, repaint screen */

+</PRE>

+<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3>

+A resize operation in X sends <CODE>SIGWINCH</CODE> to the application running

+under xterm.

+The easiest way to handle <CODE>SIGWINCH</CODE>

+is to do an <CODE>endwin</CODE>,

+followed by an <CODE>refresh</CODE> and a screen repaint you code

+yourself.

+The <CODE>refresh</CODE> will pick up the new screen size from the

+xterm's environment. <P>

+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 reinitialize the display, and does

+not resize subwindows which must be shrunk.

+<CODE>Ncurses</CODE> provides an extension which works better, the

+<CODE>resizeterm</CODE> function. That function ensures that all windows

+are limited to the new screen dimensions, and pads <CODE>stdscr</CODE>

+with blanks if the screen is larger. <P>

+The <CODE>ncurses</CODE> library provides a SIGWINCH signal handler,

+which pushes a <CODE>KEY_RESIZE</CODE> via the wgetch() calls.

+When <CODE>ncurses</CODE> returns that code,

+it calls <code>resizeterm</CODE>

+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

+<CODE>KEY_RESIZE</CODE> yourself.

+<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3>

+The <CODE>initscr()</CODE> function actually calls a function named

+<CODE>newterm()</CODE> to do most of its work. If you are writing a program that

+opens multiple terminals, use <CODE>newterm()</CODE> directly. <P>

+For each call, you will have to specify a terminal type and a pair of file

+pointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be

+set to the last one allocated. You will switch between screens with the

+<CODE>set_term</CODE> call. Note that you will also have to call

+<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself.

+<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3>

+Sometimes you may want to write programs that test for the presence of various

+capabilities before deciding whether to go into <CODE>ncurses</CODE> mode. An easy

+way to do this is to call <CODE>setupterm()</CODE>, then use the functions

+<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your

+testing. <P>

+A particularly useful case of this often comes up when you want to

+test whether a given terminal type should be treated as `smart'

+(cursor-addressable) or `stupid'. The right way to test this is to see

+if the return value of <CODE>tigetstr("cup")</CODE> is non-NULL. Alternatively,

+you can include the <CODE>term.h</CODE> file and test the value of the

+macro <CODE>cursor_address</CODE>.

+<H3><A NAME="tuning">Tuning for Speed</A></H3>

+Use the <CODE>addchstr()</CODE> family of functions for fast

+screen-painting of text when you know the text doesn't contain any

+control characters. Try to make attribute changes infrequent on your

+screens. Don't use the <CODE>immedok()</CODE> option!

+<H3><A NAME="special">Special Features of NCURSES</A></H3>

+The <CODE>wresize()</CODE> function allows you to resize a window in place.

+The associated <CODE>resizeterm()</CODE> function simplifies the construction

+of <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows. <P>

+The <CODE>define_key()</CODE> function allows you

+to define at runtime function-key control sequences which are not in the

+terminal description.

+The <CODE>keyok()</CODE> function allows you to temporarily

+enable or disable interpretation of any function-key control sequence. <P>

+The <CODE>use_default_colors()</CODE> function allows you to construct

+applications which can use the terminal's default foreground and

+background colors as an additional "default" color.

+Several terminal emulators support this feature, which is based on ISO 6429. <P>

+Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8.

+While most terminals which provide color allow only 8 colors, about

+a quarter (including XFree86 xterm) support 16 colors.

+<H2><A NAME="compat">Compatibility with Older Versions</A></H2>

+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.

+<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3>

+If you define two windows A and B that overlap, and then alternately scribble

+on and refresh them, the changes made to the overlapping region under historic

+<CODE>curses</CODE> versions were often not documented precisely. <P>

+To understand why this is a problem, remember that screen updates are

+calculated between two representations of the <EM>entire</EM> 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. <P>

+What happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE>

+does with its argument -- what portions of the argument window it copies to the

+virtual screen. Some implementations do "change copy", copying down only

+locations in the window that have changed (or been marked changed with

+<CODE>wtouchln()</CODE> and friends). Some implementations do "entire copy",

+copying <EM>all</EM> window locations to the virtual screen whether or not

+they have changed. <P>

+The <CODE>ncurses</CODE> library itself has not always been consistent on this

+score. Due to a bug, versions 1.8.7 to 1.9.8a did entire copy. Versions

+1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P>

+For most commercial curses implementations, it is not documented and not known

+for sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do

+change copy or entire copy. We know that System V release 3 curses has logic

+in it that looks like an attempt to do change copy, but the surrounding logic

+and data representations are sufficiently complex, and our knowledge

+sufficiently indirect, that it's hard to know whether this is reliable.

+It is not clear what the SVr4 documentation and XSI standard intend. The XSI

+Curses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be

+describing entire-copy, but it is possible with some effort and straining to

+read them the other way. <P>

+It might therefore be unwise to rely on either behavior in programs that might

+have to be linked with other curses implementations. Instead, you can do an

+explicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to

+guarantee an entire-contents copy anywhere. <P>

+The really clean way to handle this is to use the panels library. If,

+when you want a screen update, you do <CODE>update_panels()</CODE>, it will

+do all the necessary <CODE>wnoutrefresh()</CODE> calls for whatever panel

+stacking order you have defined. Then you can do one <CODE>doupdate()</CODE>

+and there will be a <EM>single</EM> burst of physical I/O that will do

+all your updates.

+<H3><A NAME="backbug">Background Erase</A></H3>

+If you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or

+older) you may be surprised by the behavior of the erase functions. In older

+versions, erased areas of a window were filled with a blank modified by the

+window's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>,

+<STRONG>wattroff()</STRONG> and friends). <P>

+In newer versions, this is not so. Instead, the attribute of erased blanks

+is normal unless and until it is modified by the functions <CODE>bkgdset()</CODE>

+or <CODE>wbkgdset()</CODE>. <P>

+This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and

+the XSI Curses standard.

+<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2>

+The <CODE>ncurses</CODE> library is intended to be base-level conformant with the

+XSI Curses standard from X/Open. Many extended-level features (in fact, almost

+all features not directly concerned with wide characters and

+internationalization) are also supported. <P>

+One effect of XSI conformance is the change in behavior described under

+<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P>

+Also, <CODE>ncurses</CODE> meets the XSI requirement that every macro

+entry point have a corresponding function which may be linked (and

+will be prototype-checked) if the macro definition is disabled with

+<CODE>#undef</CODE>.

+<H1><A NAME="panels">The Panels Library</A></H1>

+The <CODE>ncurses</CODE> library by itself provides good support for screen

+displays in which the windows are tiled (non-overlapping). In the more

+general case that windows may overlap, you have to use a series of

+<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be

+careful about the order you do the window refreshes in. It has to be

+bottom-upwards, otherwise parts of windows that should be obscured will

+show through. <P>

+When your 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. <P>

+The <CODE>panel</CODE> library first appeared in AT&T System V. The

+version documented here is the <CODE>panel</CODE> code distributed

+with <CODE>ncurses</CODE>.

+<H2><A NAME="pcompile">Compiling With the Panels Library</A></H2>

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

+<PRE>

+ #include <panel.h>

+</PRE>

+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 linkers

+are two-pass and will accept either order, but it is still good practice

+to put <CODE>-lpanel</CODE> first and <CODE>-lncurses</CODE> second.

+<H2><A NAME="poverview">Overview of Panels</A></H2>

+A panel object is a window that is implicitly treated as part of a

+<DFN>deck</DFN> including all other panel objects. The deck has an implicit

+bottom-to-top visibility order. The panels library includes an update

+function (analogous to <CODE>refresh()</CODE>) that displays all panels in the

+deck in the proper order to resolve overlaps. The standard window,

+<CODE>stdscr</CODE>, is considered below all panels. <P>

+Details on the panels functions are available in the man pages. We'll just

+hit the highlights here. <P>

+You create a panel from a window by calling <CODE>new_panel()</CODE> on a

+window pointer. It then becomes the top of the deck. The panel's window

+is available as the value of <CODE>panel_window()</CODE> called with the

+panel pointer as argument.<P>

+You can delete a panel (removing it from the deck) with <CODE>del_panel</CODE>.

+This will not deallocate the associated window; you have to do that yourself.

+You can replace a panel's window with a different window by calling

+<CODE>replace_window</CODE>. The new window may be of different size;

+the panel code will re-compute all overlaps. This operation doesn't

+change the panel's position in the deck. <P>

+To move a panel's window, use <CODE>move_panel()</CODE>. The

+<CODE>mvwin()</CODE> function on the panel's window isn't sufficient because it

+doesn't update the panels library's representation of where the windows are.

+This operation leaves the panel's depth, contents, and size unchanged. <P>

+Two functions (<CODE>top_panel()</CODE>, <CODE>bottom_panel()</CODE>) are

+provided for rearranging the deck. The first pops its argument window to the

+top of the deck; the second sends it to the bottom. Either operation leaves

+the panel's screen location, contents, and size unchanged. <P>

+The function <CODE>update_panels()</CODE> does all the

+<CODE>wnoutrefresh()</CODE> calls needed to prepare for

+<CODE>doupdate()</CODE> (which you must call yourself, afterwards). <P>

+Typically, you will want to call <CODE>update_panels()</CODE> and

+<CODE>doupdate()</CODE> just before accepting command input, once in each cycle

+of interaction with the user. If you call <CODE>update_panels()</CODE> after

+each and every panel write, you'll generate a lot of unnecessary refresh

+activity and screen flicker.

+<H2><A NAME="pstdscr">Panels, Input, and the Standard Screen</A></H2>

+You shouldn't mix <CODE>wnoutrefresh()</CODE> or <CODE>wrefresh()</CODE>

+operations with panels code; this will work only if the argument window

+is either in the top panel or unobscured by any other panels. <P>

+The <CODE>stsdcr</CODE> window is a special case. It is considered below all

+panels. Because changes to panels may obscure parts of <CODE>stdscr</CODE>,

+though, you should call <CODE>update_panels()</CODE> before

+<CODE>doupdate()</CODE> even when you only change <CODE>stdscr</CODE>. <P>

+Note that <CODE>wgetch</CODE> automatically calls <CODE>wrefresh</CODE>.

+Therefore, before requesting input from a panel window, you need to be sure

+that the panel is totally unobscured. <P>

+There is presently no way to display changes to one obscured panel without

+repainting all panels.

+<H2><A NAME="hiding">Hiding Panels</A></H2>

+It's possible to remove a panel from the deck temporarily; use

+<CODE>hide_panel</CODE> for this. Use <CODE>show_panel()</CODE> to render it

+visible again. The predicate function <CODE>panel_hidden</CODE>

+tests whether or not a panel is hidden. <P>

+The <CODE>panel_update</CODE> code ignores hidden panels. You cannot do

+<CODE>top_panel()</CODE> or <CODE>bottom_panel</CODE> on a hidden panel().

+Other panels operations are applicable.

+<H2><A NAME="pmisc">Miscellaneous Other Facilities</A></H2>

+It's possible to navigate the deck using the functions

+<CODE>panel_above()</CODE> and <CODE>panel_below</CODE>. Handed a panel

+pointer, they return the panel above or below that panel. Handed

+<CODE>NULL</CODE>, they return the bottom-most or top-most panel. <P>

+Every panel has an associated user pointer, not used by the panel code, to

+which you can attach application data. See the man page documentation

+of <CODE>set_panel_userptr()</CODE> and <CODE>panel_userptr</CODE> for

+details.

+<H1><A NAME="menu">The Menu Library</A></H1>

+A menu is a screen display that assists the user to choose some subset

+of a given set of items. The <CODE>menu</CODE> library is a curses

+extension that supports easy programming of menu hierarchies with a

+uniform but flexible interface. <P>

+The <CODE>menu</CODE> library first appeared in AT&T System V. The

+version documented here is the <CODE>menu</CODE> code distributed

+with <CODE>ncurses</CODE>.

+<H2><A NAME="mcompile">Compiling With the menu Library</A></H2>

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

+<PRE>

+ #include <menu.h>

+</PRE>

+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 linkers

+are two-pass and will accept either order, but it is still good practice

+to put <CODE>-lmenu</CODE> first and <CODE>-lncurses</CODE> second.

+<H2><A NAME="moverview">Overview of Menus</A></H2>

+The menus created by this library consist of collections of

+<DFN>items</DFN> including a name string part and a description string

+part. To make menus, you create groups of these items and connect

+them with menu frame objects. <P>

+The menu can then by <DFN>posted</DFN>, that is written to an

+associated window. Actually, each menu has two associated windows; a

+containing window in which the programmer can scribble titles or

+borders, and a subwindow in which the menu items proper are displayed.

+If this subwindow is too small to display all the items, it will be a

+scrollable viewport on the collection of items. <P>

+A menu may also be <DFN>unposted</DFN> (that is, undisplayed), and finally

+freed to make the storage associated with it and its items available for

+re-use. <P>

+The general flow of control of a menu program looks like this:

+<OL>

+<LI>Initialize <CODE>curses</CODE>.

+<LI>Create the menu items, using <CODE>new_item()</CODE>.

+<LI>Create the menu using <CODE>new_menu()</CODE>.

+<LI>Post the menu using <CODE>post_menu()</CODE>.

+<LI>Refresh the screen.

+<LI>Process user requests via an input loop.

+<LI>Unpost the menu using <CODE>unpost_menu()</CODE>.

+<LI>Free the menu, using <CODE>free_menu()</CODE>.

+<LI>Free the items using <CODE>free_item()</CODE>.

+<LI>Terminate <CODE>curses</CODE>.

+</OL>

+<H2><A NAME="mselect">Selecting items</A></H2>

+Menus may be multi-valued or (the default) single-valued (see the manual

+page <CODE>menu_opts(3x)</CODE> to see how to change the default).

+Both types always have a <DFN>current item</DFN>. <P>

+From a single-valued menu you can read the selected value simply by looking

+at the current item. From a multi-valued menu, you get the selected set

+by looping through the items applying the <CODE>item_value()</CODE>

+predicate function. Your menu-processing code can use the function

+<CODE>set_item_value()</CODE> to flag the items in the select set. <P>

+Menu items can be made unselectable using <CODE>set_item_opts()</CODE>

+or <CODE>item_opts_off()</CODE> with the <CODE>O_SELECTABLE</CODE>

+argument. This is the only option so far defined for menus, but it

+is good practice to code as though other option bits might be on.

+<H2><A NAME="mdisplay">Menu Display</A></H2>

+The menu library calculates a minimum display size for your window, based

+on the following variables:

+<UL>

+<LI>The number and maximum length of the menu items

+<LI>Whether the O_ROWMAJOR option is enabled

+<LI>Whether display of descriptions is enabled

+<LI>Whatever menu format may have been set by the programmer

+<LI>The length of the menu mark string used for highlighting selected items

+</UL>

+The function <CODE>set_menu_format()</CODE> allows you to set the

+maximum size of the viewport or <DFN>menu page</DFN> that will be used

+to display menu items. You can retrieve any format associated with a

+menu with <CODE>menu_format()</CODE>. The default format is rows=16,

+columns=1. <P>

+The actual menu page may be smaller than the format size. This depends

+on the item number and size and whether O_ROWMAJOR is on. This option

+(on by default) causes menu items to be displayed in a `raster-scan'

+pattern, so that if more than one item will fit horizontally the first

+couple of items are side-by-side in the top row. The alternative is

+column-major display, which tries to put the first several items in

+the first column. <P>

+As mentioned above, a menu format not large enough to allow all items to fit

+on-screen will result in a menu display that is vertically scrollable. <P>

+You can scroll it with requests to the menu driver, which will be described

+in the section on <A HREF="#minput">menu input handling</A>. <P>

+Each menu has a <DFN>mark string</DFN> used to visually tag selected items;

+see the <CODE>menu_mark(3x)</CODE> manual page for details. The mark

+string length also influences the menu page size. <P>

+The function <CODE>scale_menu()</CODE> returns the minimum display size

+that the menu code computes from all these factors.

+There are other menu display attributes including a select attribute,

+an attribute for selectable items, an attribute for unselectable items,

+and a pad character used to separate item name text from description

+text. These have reasonable defaults which the library allows you to

+change (see the <CODE>menu_attribs(3x)</CODE> manual page.

+<H2><A NAME="mwindows">Menu Windows</A></H2>

+Each menu has, as mentioned previously, a pair of associated windows.

+Both these windows are painted when the menu is posted and erased when

+the menu is unposted. <P>

+The outer or frame window is not otherwise touched by the menu

+routines. It exists so the programmer can associate a title, a

+border, or perhaps help text with the menu and have it properly

+refreshed or erased at post/unpost time. The inner window or

+<DFN>subwindow</DFN> is where the current menu page is displayed. <P>

+By default, both windows are <CODE>stdscr</CODE>. You can set them with the

+functions in <CODE>menu_win(3x)</CODE>. <P>

+When you call <CODE>post_menu()</CODE>, you write the menu to its

+subwindow. When you call <CODE>unpost_menu()</CODE>, you erase the

+subwindow, However, neither of these actually modifies the screen. To

+do that, call <CODE>wrefresh()</CODE> or some equivalent.

+<H2><A NAME="minput">Processing Menu Input</A></H2>

+The main loop of your menu-processing code should call

+<CODE>menu_driver()</CODE> repeatedly. The first argument of this routine

+is a menu pointer; the second is a menu command code. You should write an

+input-fetching routine that maps input characters to menu command codes, and

+pass its output to <CODE>menu_driver()</CODE>. The menu command codes are

+fully documented in <CODE>menu_driver(3x)</CODE>. <P>

+The simplest group of command codes is <CODE>REQ_NEXT_ITEM</CODE>,

+<CODE>REQ_PREV_ITEM</CODE>, <CODE>REQ_FIRST_ITEM</CODE>,

+<CODE>REQ_LAST_ITEM</CODE>, <CODE>REQ_UP_ITEM</CODE>,

+<CODE>REQ_DOWN_ITEM</CODE>, <CODE>REQ_LEFT_ITEM</CODE>,

+<CODE>REQ_RIGHT_ITEM</CODE>. These change the currently selected

+item. These requests may cause scrolling of the menu page if it only

+partially displayed. <P>

+There are explicit requests for scrolling which also change the

+current item (because the select location does not change, but the

+item there does). These are <CODE>REQ_SCR_DLINE</CODE>,

+<CODE>REQ_SCR_ULINE</CODE>, <CODE>REQ_SCR_DPAGE</CODE>, and

+<CODE>REQ_SCR_UPAGE</CODE>. <P>

+The <CODE>REQ_TOGGLE_ITEM</CODE> selects or deselects the current item.

+It is for use in multi-valued menus; if you use it with <CODE>O_ONEVALUE</CODE>

+on, you'll get an error return (<CODE>E_REQUEST_DENIED</CODE>). <P>

+Each menu has an associated pattern buffer. The

+<CODE>menu_driver()</CODE> logic tries to accumulate printable ASCII

+characters passed in in that buffer; when it matches a prefix of an

+item name, that item (or the next matching item) is selected. If

+appending a character yields no new match, that character is deleted

+from the pattern buffer, and <CODE>menu_driver()</CODE> returns

+<CODE>E_NO_MATCH</CODE>. <P>

+Some requests change the pattern buffer directly:

+<CODE>REQ_CLEAR_PATTERN</CODE>, <CODE>REQ_BACK_PATTERN</CODE>,

+<CODE>REQ_NEXT_MATCH</CODE>, <CODE>REQ_PREV_MATCH</CODE>. The latter

+two are useful when pattern buffer input matches more than one item

+in a multi-valued menu. <P>

+Each successful scroll or item navigation request clears the pattern

+buffer. It is also possible to set the pattern buffer explicitly

+with <CODE>set_menu_pattern()</CODE>. <P>

+Finally, menu driver requests above the constant <CODE>MAX_COMMAND</CODE>

+are considered application-specific commands. The <CODE>menu_driver()</CODE>

+code ignores them and returns <CODE>E_UNKNOWN_COMMAND</CODE>.

+<H2><A NAME="mmisc">Miscellaneous Other Features</A></H2>

+Various menu options can affect the processing and visual appearance

+and input processing of menus. See <CODE>menu_opts(3x) for

+details.</CODE> <P>

+It is possible to change the current item from application code; this

+is useful if you want to write your own navigation requests. It is

+also possible to explicitly set the top row of the menu display. See

+<CODE>mitem_current(3x)</CODE>.

+If your application needs to change the menu subwindow cursor for

+any reason, <CODE>pos_menu_cursor()</CODE> will restore it to the

+correct location for continuing menu driver processing. <P>

+It is possible to set hooks to be called at menu initialization and

+wrapup time, and whenever the selected item changes. See

+<CODE>menu_hook(3x)</CODE>. <P>

+Each item, and each menu, has an associated user pointer on which you

+can hang application data. See <CODE>mitem_userptr(3x)</CODE> and

+<CODE>menu_userptr(3x)</CODE>.

+<H1><A NAME="form">The Forms Library</A></H1>

+The <CODE>form</CODE> library is a curses extension that supports easy

+programming of on-screen forms for data entry and program control. <P>

+The <CODE>form</CODE> library first appeared in AT&T System V. The

+version documented here is the <CODE>form</CODE> code distributed

+with <CODE>ncurses</CODE>.

+<H2><A NAME="fcompile">Compiling With the form Library</A></H2>

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

+<PRE>

+ #include <form.h>

+</PRE>

+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 linkers

+are two-pass and will accept either order, but it is still good practice

+to put <CODE>-lform</CODE> first and <CODE>-lncurses</CODE> second.

+<H2><A NAME="foverview">Overview of Forms</A></H2>

+A form is a collection of fields; each field may be either a label

+(explanatory text) or a data-entry location. Long forms may be

+segmented into pages; each entry to a new page clears the screen. <P>

+To make forms, you create groups of fields and connect them with form

+frame objects; the form library makes this relatively simple. <P>

+Once defined, a form can be <DFN>posted</DFN>, that is written to an

+associated window. Actually, each form has two associated windows; a

+containing window in which the programmer can scribble titles or

+borders, and a subwindow in which the form fields proper are displayed. <P>

+As the form user fills out the posted form, navigation and editing

+keys support movement between fields, editing keys support modifying

+field, and plain text adds to or changes data in a current field. The

+form library allows you (the forms designer) to bind each navigation

+and editing key to any keystroke accepted by <CODE>curses</CODE>

+Fields may have validation conditions on them, so that they check input

+data for type and value. The form library supplies a rich set of

+pre-defined field types, and makes it relatively easy to define new ones. <P>

+Once its transaction is completed (or aborted), a form may be

+<DFN>unposted</DFN> (that is, undisplayed), and finally freed to make

+the storage associated with it and its items available for re-use. <P>

+The general flow of control of a form program looks like this:

+<OL>

+<LI>Initialize <CODE>curses</CODE>.

+<LI>Create the form fields, using <CODE>new_field()</CODE>.

+<LI>Create the form using <CODE>new_form()</CODE>.

+<LI>Post the form using <CODE>post_form()</CODE>.

+<LI>Refresh the screen.

+<LI>Process user requests via an input loop.

+<LI>Unpost the form using <CODE>unpost_form()</CODE>.

+<LI>Free the form, using <CODE>free_form()</CODE>.

+<LI>Free the fields using <CODE>free_field()</CODE>.

+<LI>Terminate <CODE>curses</CODE>.

+</OL>

+Note that this looks much like a menu program; the form library handles

+tasks which are in many ways similar, and its interface was obviously

+designed to resemble that of the <A HREF="#menu">menu library</A>

+wherever possible. <P>

+In forms programs, however, the `process user requests' is somewhat more

+complicated than for menus. Besides menu-like navigation operations,

+the menu driver loop has to support field editing and data validation.

+<H2><A NAME="fcreate">Creating and Freeing Fields and Forms</A></H2>

+The basic function for creating fields is <CODE>new_field()</CODE>:

+<PRE>

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

+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 both be greater

+than zero). <P>

+You must also specify the location of the field's upper left corner on

+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 <CODE>stdscr</CODE> by default but

+need not be <CODE>stdscr</CODE> if you've done an explicit

+<CODE>set_form_win()</CODE> call. <P>

+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

+nonzero, the form will be scrollable, with only one screen-full (initially

+the top part) displayed at any given time. If you make a field dynamic

+and grow it so it will no longer fit on the screen, the form will become

+scrollable even if the <CODE>offscreen</CODE> argument was initially zero. <P>

+The forms library allocates one working buffer per field; the size of

+each buffer is <CODE>((height + offscreen)*width + 1</CODE>, one character

+for each position in the field plus a NUL terminator. The sixth

+argument is the number of additional data buffers to allocate for the

+field; your application can use them for its own purposes.

+<PRE>

+FIELD *dup_field(FIELD *field, /* field to copy */

+ int top, int left); /* location of new copy */

+</PRE>

+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).

+<PRE>

+FIELD *link_field(FIELD *field, /* field to copy */

+ int top, int left); /* location of new copy */

+</PRE>

+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 buffer to be shared with the old one. <P>

+Besides the obvious use in making a field editable from two different

+form pages, linked fields give you a way to hack in dynamic labels. If

+you declare several fields linked to an original, and then make them

+inactive, changes from the original will still be propagated to the

+linked fields. <P>

+As with duplicated fields, linked fields have attribute bits separate

+from the original. <P>

+As you might guess, all these field-allocations return <CODE>NULL</CODE> if

+the field allocation is not possible due to an out-of-memory error or

+out-of-bounds arguments. <P>

+To connect fields to a form, use

+<PRE>

+FORM *new_form(FIELD **fields);

+</PRE>

+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 fails). <P>

+Note that <CODE>new_field()</CODE> does <EM>not</EM> copy the pointer array

+into private storage; if you modify the contents of the pointer array

+during forms processing, all manner of bizarre things might happen. Also

+note that any given field may only be connected to one form. <P>

+The functions <CODE>free_field()</CODE> and <CODE>free_form</CODE> are available

+to free field and form objects. It is an error to attempt to free a field

+connected to a form, but not vice-versa; thus, you will generally free

+your form objects first.

+<H2><A NAME="fattributes">Fetching and Changing Field Attributes</A></H2>

+Each form field has a number of location and size attributes

+associated with it. There are other field attributes used to control

+display and editing of the field. Some (for example, the <CODE>O_STATIC</CODE> bit)

+involve sufficient complications to be covered in sections of their own

+later on. We cover the functions used to get and set several basic

+attributes here. <P>

+When a field is created, the attributes not specified by the

+<CODE>new_field</CODE> function are copied from an invisible system

+default field. In attribute-setting and -fetching functions, the

+argument NULL is taken to mean this field. Changes to it persist

+as defaults until your forms application terminates.

+<H3><A NAME="fsizes">Fetching Size and Location Data</A></H3>

+You can retrieve field sizes and locations through:

+<PRE>

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

+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.

+<H3><A NAME="flocation">Changing the Field Location</A></H3>

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

+<PRE>

+int move_field(FIELD *field, /* field to alter */

+ int top, int left); /* new upper-left corner */

+</PRE>

+You can, of course. query the current location through <CODE>field_info()</CODE>.

+<H3><A NAME="fjust">The Justification Attribute</A></H3>

+One-line fields may be unjustified, justified right, justified left,

+or centered. Here is how you manipulate this attribute:

+<PRE>

+int set_field_just(FIELD *field, /* field to alter */

+ int justmode); /* mode to set */

+int field_just(FIELD *field); /* fetch mode of field */

+</PRE>

+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>.

+<H3><A NAME="fdispatts">Field Display Attributes</A></H3>

+For each field, you can set a foreground attribute for entered

+characters, a background attribute for the entire field, and a pad

+character for the unfilled portion of the field. You can also

+control pagination of the form. <P>

+This group of four field attributes controls the visual appearance

+of the field on the screen, without affecting in any way the data

+in the field buffer.

+<PRE>

+int set_field_fore(FIELD *field, /* field to alter */

+ chtype attr); /* attribute to set */

+chtype field_fore(FIELD *field); /* field to query */

+int set_field_back(FIELD *field, /* field to alter */

+ chtype attr); /* attribute to set */

+chtype field_back(FIELD *field); /* field to query */

+int set_field_pad(FIELD *field, /* field to alter */

+ int pad); /* pad character to set */

+chtype field_pad(FIELD *field);

+int set_new_page(FIELD *field, /* field to alter */

+ int flag); /* TRUE to force new page */

+chtype new_page(FIELD *field); /* field to query */

+</PRE>

+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.

+<H3><A NAME="foptions">Field Option Bits</A></H3>

+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:

+<PRE>

+int set_field_opts(FIELD *field, /* field to alter */

+ int attr); /* attribute to set */

+int field_opts_on(FIELD *field, /* field to alter */

+ int attr); /* attributes to turn on */

+int field_opts_off(FIELD *field, /* field to alter */

+ int attr); /* attributes to turn off */

+int field_opts(FIELD *field); /* field to query */

+</PRE>

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

+<DL>

+<DT> O_VISIBLE

+<DD> Controls whether the field is visible on the screen. Can be used

+during form processing to hide or pop up fields depending on the value

+of parent fields.

+<DT> O_ACTIVE

+<DD> Controls whether the field is active during forms processing (i.e.

+visited by form navigation keys). Can be used to make labels or derived

+fields with buffer values alterable by the forms application, not the user.

+<DT> O_PUBLIC

+<DD> Controls whether data is displayed during field entry. If this option is

+turned off on a field, the library will accept and edit data in that field,

+but it will not be displayed and the visible field cursor will not move.

+You can turn off the O_PUBLIC bit to define password fields.

+<DT> O_EDIT

+<DD> Controls whether the field's data can be modified. When this option is

+off, all editing requests except <CODE>REQ_PREV_CHOICE</CODE> and

+<CODE>REQ_NEXT_CHOICE</CODE> will fail. Such read-only fields may be useful for

+help messages.

+<DT> O_WRAP

+<DD> Controls word-wrapping in multi-line fields. Normally, when any

+character of a (blank-separated) word reaches the end of the current line, the

+entire word is wrapped to the next line (assuming there is one). When this

+option is off, the word will be split across the line break.

+<DT> O_BLANK

+<DD> Controls field blanking. When this option is on, entering a character at

+the first field position erases the entire field (except for the just-entered

+character).

+<DT> O_AUTOSKIP

+<DD> Controls automatic skip to next field when this one fills. Normally,

+when the forms user tries to type more data into a field than will fit,

+the editing location jumps to next field. When this option is off, the

+user's cursor will hang at the end of the field. This option is ignored

+in dynamic fields that have not reached their size limit.

+<DT> O_NULLOK

+<DD> Controls whether <A HREF="#fvalidation">validation</A> is applied to

+blank fields. Normally, it is not; the user can leave a field blank

+without invoking the usual validation check on exit. If this option is

+off on a field, exit from it will invoke a validation check.

+<DT> O_PASSOK

+<DD> Controls whether validation occurs on every exit, or only after

+the field is modified. Normally the latter is true. Setting O_PASSOK

+may be useful if your field's validation function may change during

+forms processing.

+<DT> O_STATIC

+<DD> Controls whether the field is fixed to its initial dimensions. If you

+turn this off, the field becomes <A HREF="#fdynamic">dynamic</A> and will

+stretch to fit entered data.

+</DL>

+A field's options cannot be changed while the field is currently selected.

+However, options may be changed on posted fields that are not current. <P>

+The option values are bit-masks and can be composed with logical-or in

+the obvious way.

+<H2><A NAME="fstatus">Field Status</A></H2>

+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:

+<PRE>

+int set_field_status(FIELD *field, /* field to alter */

+ int status); /* mode to set */

+int field_status(FIELD *field); /* fetch mode of field */

+</PRE>

+Setting this flag under program control can be useful if you use the same

+form repeatedly, looking for modified fields each time. <P>

+Calling <CODE>field_status()</CODE> on a field not currently selected

+for input will return a correct value. Calling <CODE>field_status()</CODE> on a

+field that is currently selected for input may not necessarily give a

+correct field status value, because entered data isn't necessarily copied to

+buffer zero before the exit validation check.

+To guarantee that the returned status value reflects reality, call

+<CODE>field_status()</CODE> either (1) in the field's exit validation check

+routine, (2) from the field's or form's initialization or termination

+hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been

+processed by the forms driver.

+<H2><A NAME="fuser">Field User Pointer</A></H2>

+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:

+<PRE>

+int set_field_userptr(FIELD *field, /* field to alter */

+ char *userptr); /* mode to set */

+char *field_userptr(FIELD *field); /* fetch mode of field */

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

+<H2><A NAME="fdynamic">Variable-Sized Fields</A></H2>

+Normally, a field is fixed at the size specified for it at creation

+time. If, however, you turn off its O_STATIC bit, it becomes

+<DFN>dynamic</DFN> and will automatically resize itself to accommodate

+data as it is entered. If the field has extra buffers associated with it,

+they will grow right along with the main input buffer. <P>

+A one-line dynamic field will have a fixed height (1) but variable

+width, scrolling horizontally to display data within the field area as

+originally dimensioned and located. A multi-line dynamic field will

+have a fixed width, but variable height (number of rows), scrolling

+vertically to display data within the field area as originally

+dimensioned and located. <P>

+Normally, a dynamic field is allowed to grow without limit. But it is

+possible to set an upper limit on the size of a dynamic field. You do

+it with this function:

+<PRE>

+int set_max_field(FIELD *field, /* field to alter (may not be NULL) */

+ int max_size); /* upper limit on field size */

+</PRE>

+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. The growth limit can be changed whether

+or not the O_STATIC bit is on, but has no effect until it is. <P>

+The following properties of a field change when it becomes dynamic:

+<UL>

+<LI>If there is no growth limit, there is no final position of the field;

+therefore <CODE>O_AUTOSKIP</CODE> and <CODE>O_NL_OVERLOAD</CODE> are ignored.

+<LI>Field justification will be ignored (though whatever justification is

+set up will be retained internally and can be queried).

+<LI>The <CODE>dup_field()</CODE> and <CODE>link_field()</CODE> calls copy

+dynamic-buffer sizes. If the <CODE>O_STATIC</CODE> option is set on one of a

+collection of links, buffer resizing will occur only when the field is

+edited through that link.

+<LI>The call <CODE>field_info()</CODE> will retrieve the original static size of

+the field; use <CODE>dynamic_field_info()</CODE> to get the actual dynamic size.

+</UL>

+<H2><A NAME="fvalidation">Field Validation</A></H2>

+By default, a field will accept any data that will fit in its input buffer.

+However, it is possible to attach a validation type to a field. If you do

+this, any attempt to leave the field while it contains data that doesn't

+match the validation type will fail. Some validation types also have a

+character-validity check for each time a character is entered in the field. <P>

+A field's validation check (if any) is not called when

+<CODE>set_field_buffer()</CODE> modifies the input buffer, nor when that buffer

+is changed through a linked field. <P>

+The <CODE>form</CODE> library provides a rich set of pre-defined validation

+types, and gives you the capability to define custom ones of your own. You

+can examine and change field validation attributes with the following

+functions:

+<PRE>

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

+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 default will change the system default for validation of

+newly-created fields. <P>

+Here are the pre-defined validation types:

+<H3><A NAME="ftype_alpha">TYPE_ALPHA</A></H3>

+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:

+<PRE>

+int set_field_type(FIELD *field, /* field to alter */

+ TYPE_ALPHA, /* type to associate */

+ int width); /* maximum width of field */

+</PRE>

+The <CODE>width</CODE> argument sets a minimum width of data. Typically

+you'll want to set this to the field width; if it's greater than the

+field width, the validation check will always fail. A minimum width

+of zero makes field completion optional.

+<H3><A NAME="ftype_alnum">TYPE_ALNUM</A></H3>

+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:

+<PRE>

+int set_field_type(FIELD *field, /* field to alter */

+ TYPE_ALNUM, /* type to associate */

+ int width); /* maximum width of field */

+</PRE>

+The <CODE>width</CODE> argument sets a minimum width of data. As with

+TYPE_ALPHA, typically you'll want to set this to the field width; if it's

+greater than the field width, the validation check will always fail. A

+minimum width of zero makes field completion optional.

+<H3><A NAME="ftype_enum">TYPE_ENUM</A></H3>

+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:

+<PRE>

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

+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 case-sensitive. <P>

+When the user exits a TYPE_ENUM field, the validation procedure tries to

+complete the data in the buffer to a valid entry. If a complete choice string

+has been entered, it is of course valid. But it is also possible to enter a

+prefix of a valid string and have it completed for you. <P>

+By default, if you enter such a prefix and it matches more than one value

+in the string list, the prefix will be completed to the first matching

+value. But the <CODE>checkunique</CODE> argument, if true, requires prefix

+matches to be unique in order to be valid. <P>

+The <CODE>REQ_NEXT_CHOICE</CODE> and <CODE>REQ_PREV_CHOICE</CODE> input requests

+can be particularly useful with these fields.

+<H3><A NAME="ftype_integer">TYPE_INTEGER</A></H3>

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

+<PRE>

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

+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 ignored. <P>

+If the value passes its range check, it is padded with as many leading

+zero digits as necessary to meet the padding argument. <P>

+A <CODE>TYPE_INTEGER</CODE> value buffer can conveniently be interpreted

+with the C library function <CODE>atoi(3)</CODE>.

+<H3><A NAME="ftype_numeric">TYPE_NUMERIC</A></H3>

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

+<PRE>

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

+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 one defined by your locale. The range check is

+performed on exit. If the range maximum is less than or equal to the minimum,

+the range is ignored. <P>

+If the value passes its range check, it is padded with as many trailing

+zero digits as necessary to meet the padding argument. <P>

+A <CODE>TYPE_NUMERIC</CODE> value buffer can conveniently be interpreted

+with the C library function <CODE>atof(3)</CODE>.

+<H3><A NAME="ftype_regexp">TYPE_REGEXP</A></H3>

+This field type accepts data matching a regular expression. It is set up

+as follows:

+<PRE>

+int set_field_type(FIELD *field, /* field to alter */

+ TYPE_REGEXP, /* type to associate */

+ char *regexp); /* expression to match */

+</PRE>

+The syntax for regular expressions is that of <CODE>regcomp(3)</CODE>.

+The check for regular-expression match is performed on exit.

+<H2><A NAME="fbuffer">Direct Field Buffer Manipulation</A></H2>

+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:

+<PRE>

+char *field_buffer(FIELD *field, /* field to query */

+ int bufindex); /* number of buffer to query */

+</PRE>

+Normally, the state of the zero-numbered buffer for each field is set by

+the user's editing actions on that field. It's sometimes useful to be able

+to set the value of the zero-numbered (or some other) buffer from your

+application:

+<PRE>

+int set_field_buffer(FIELD *field, /* field to alter */

+ int bufindex, /* number of buffer to alter */

+ char *value); /* string value to set */

+</PRE>

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

+Calling <CODE>field_buffer()</CODE> with a null field pointer will raise an

+error. Calling <CODE>field_buffer()</CODE> on a field not currently selected

+for input will return a correct value. Calling <CODE>field_buffer()</CODE> on a

+field that is currently selected for input may not necessarily give a

+correct field buffer value, because entered data isn't necessarily copied to

+buffer zero before the exit validation check.

+To guarantee that the returned buffer value reflects on-screen reality,

+call <CODE>field_buffer()</CODE> either (1) in the field's exit validation

+check routine, (2) from the field's or form's initialization or termination

+hooks, or (3) just after a <CODE>REQ_VALIDATION</CODE> request has been processed

+by the forms driver.

+<H2><A NAME="formattrs">Attributes of Forms</A></H2>

+As with field attributes, form attributes inherit a default from a

+system default form structure. These defaults can be queried or set by

+of these functions using a form-pointer argument of <CODE>NULL</CODE>. <P>

+The principal attribute of a form is its field list. You can query

+and change this list with:

+<PRE>

+int set_form_fields(FORM *form, /* form to alter */

+ FIELD **fields); /* fields to connect */

+char *form_fields(FORM *form); /* fetch fields of form */

+int field_count(FORM *form); /* count connect fields */

+</PRE>

+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 are

+disconnected but not freed (and eligible to be connected to other

+forms), then the new fields are connected. <P>

+It may also be null, in which case the old fields are disconnected

+(and not freed) but no new ones are connected. <P>

+The <CODE>field_count()</CODE> function simply counts the number of fields

+connected to a given from. It returns -1 if the form-pointer argument

+is NULL.

+<H2><A NAME="fdisplay">Control of Form Display</A></H2>

+In the overview section, you saw that to display a form you normally

+start by defining its size (and fields), posting it, and refreshing

+the screen. There is an hidden step before posting, which is the

+association of the form with a frame window (actually, a pair of

+windows) within which it will be displayed. By default, the forms

+library associates every form with the full-screen window

+<CODE>stdscr</CODE>. <P>

+By making this step explicit, you can associate a form with a declared

+frame window on your screen display. This can be useful if you want to

+adapt the form display to different screen sizes, dynamically tile

+forms on the screen, or use a form as part of an interface layout

+managed by <A HREF="#panels">panels</A>. <P>

+The two windows associated with each form have the same functions as

+their analogues in the <A HREF="#menu">menu library</A>. Both these

+windows are painted when the form is posted and erased when the form

+is unposted. <P>

+The outer or frame window is not otherwise touched by the form

+routines. It exists so the programmer can associate a title, a

+border, or perhaps help text with the form and have it properly

+refreshed or erased at post/unpost time. The inner window or subwindow

+is where the current form page is actually displayed. <P>

+In order to declare your own frame window for a form, you'll need to

+know the size of the form's bounding rectangle. You can get this

+information with:

+<PRE>

+int scale_form(FORM *form, /* form to query */

+ int *rows, /* form rows */

+ int *cols); /* form cols */

+</PRE>

+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:

+<PRE>

+int set_form_win(FORM *form, /* form to alter */

+ WINDOW *win); /* frame window to connect */

+WINDOW *form_win(FORM *form); /* fetch frame window of form */

+int set_form_sub(FORM *form, /* form to alter */

+ WINDOW *win); /* form subwindow to connect */

+WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */

+</PRE>

+Note that curses operations, including <CODE>refresh()</CODE>, on the form,

+should be done on the frame window, not the form subwindow. <P>

+It is possible to check from your application whether all of a

+scrollable field is actually displayed within the menu subwindow. Use

+these functions:

+<PRE>

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

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

+</PRE>

+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 off-screen below it. <P>

+The function <CODE>data_behind()</CODE> returns TRUE if the first (upper

+left hand) character position is off-screen (not being displayed). <P>

+Finally, there is a function to restore the form window's cursor to the

+value expected by the forms driver:

+<PRE>

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

+</PRE>

+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.

+<H2><A NAME="fdriver">Input Processing in the Forms Driver</A></H2>

+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>).

+<PRE>

+int form_driver(FORM *form, /* form to pass input to */

+ int request); /* form request code */

+</PRE>

+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), or a forms processing request. <P>

+The forms driver provides hooks (through input-validation and

+field-termination functions) with which your application code can check

+that the input taken by the driver matched what was expected.

+<H3><A NAME="fpage">Page Navigation Requests</A></H3>

+These requests cause page-level moves through the form,

+triggering display of a new form screen.

+<DL>

+<DT> <CODE>REQ_NEXT_PAGE</CODE>

+<DD> Move to the next form page.

+<DT> <CODE>REQ_PREV_PAGE</CODE>

+<DD> Move to the previous form page.

+<DT> <CODE>REQ_FIRST_PAGE</CODE>

+<DD> Move to the first form page.

+<DT> <CODE>REQ_LAST_PAGE</CODE>

+<DD> Move to the last form page.

+</DL>

+These requests treat the list as cyclic; that is, <CODE>REQ_NEXT_PAGE</CODE>

+from the last page goes to the first, and <CODE>REQ_PREV_PAGE</CODE> from

+the first page goes to the last.

+<H3><A NAME="ffield">Inter-Field Navigation Requests</A></H3>

+These requests handle navigation between fields on the same page.

+<DL>

+<DT> <CODE>REQ_NEXT_FIELD</CODE>

+<DD> Move to next field.

+<DT> <CODE>REQ_PREV_FIELD</CODE>

+<DD> Move to previous field.

+<DT> <CODE>REQ_FIRST_FIELD</CODE>

+<DD> Move to the first field.

+<DT> <CODE>REQ_LAST_FIELD</CODE>

+<DD> Move to the last field.

+<DT> <CODE>REQ_SNEXT_FIELD</CODE>

+<DD> Move to sorted next field.

+<DT> <CODE>REQ_SPREV_FIELD</CODE>

+<DD> Move to sorted previous field.

+<DT> <CODE>REQ_SFIRST_FIELD</CODE>

+<DD> Move to the sorted first field.

+<DT> <CODE>REQ_SLAST_FIELD</CODE>

+<DD> Move to the sorted last field.

+<DT> <CODE>REQ_LEFT_FIELD</CODE>

+<DD> Move left to field.

+<DT> <CODE>REQ_RIGHT_FIELD</CODE>

+<DD> Move right to field.

+<DT> <CODE>REQ_UP_FIELD</CODE>

+<DD> Move up to field.

+<DT> <CODE>REQ_DOWN_FIELD</CODE>

+<DD> Move down to field.

+</DL>

+These requests treat the list of fields on a page as cyclic; that is,

+<CODE>REQ_NEXT_FIELD</CODE> from the last field goes to the first, and

+<CODE>REQ_PREV_FIELD</CODE> from the first field goes to the last. The

+order of the fields for these (and the <CODE>REQ_FIRST_FIELD</CODE> and

+<CODE>REQ_LAST_FIELD</CODE> requests) is simply the order of the field

+pointers in the form array (as set up by <CODE>new_form()</CODE> or

+<CODE>set_form_fields()</CODE> <P>

+It is also possible to traverse the fields as if they had been sorted in

+screen-position order, so the sequence goes left-to-right and top-to-bottom.

+To do this, use the second group of four sorted-movement requests. <P>

+Finally, it is possible to move between fields using visual directions up,

+down, right, and left. To accomplish this, use the third group of four

+requests. Note, however, that the position of a form for purposes of these

+requests is its upper-left corner. <P>

+For example, suppose you have a multi-line field B, and two

+single-line fields A and C on the same line with B, with A to the left

+of B and C to the right of B. A <CODE>REQ_MOVE_RIGHT</CODE> 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.

+<H3><A NAME="fifield">Intra-Field Navigation Requests</A></H3>

+These requests drive movement of the edit cursor within the currently

+selected field.

+<DL>

+<DT> <CODE>REQ_NEXT_CHAR</CODE>

+<DD> Move to next character.

+<DT> <CODE>REQ_PREV_CHAR</CODE>

+<DD> Move to previous character.

+<DT> <CODE>REQ_NEXT_LINE</CODE>

+<DD> Move to next line.

+<DT> <CODE>REQ_PREV_LINE</CODE>

+<DD> Move to previous line.

+<DT> <CODE>REQ_NEXT_WORD</CODE>

+<DD> Move to next word.

+<DT> <CODE>REQ_PREV_WORD</CODE>

+<DD> Move to previous word.

+<DT> <CODE>REQ_BEG_FIELD</CODE>

+<DD> Move to beginning of field.

+<DT> <CODE>REQ_END_FIELD</CODE>

+<DD> Move to end of field.

+<DT> <CODE>REQ_BEG_LINE</CODE>

+<DD> Move to beginning of line.

+<DT> <CODE>REQ_END_LINE</CODE>

+<DD> Move to end of line.

+<DT> <CODE>REQ_LEFT_CHAR</CODE>

+<DD> Move left in field.

+<DT> <CODE>REQ_RIGHT_CHAR</CODE>

+<DD> Move right in field.

+<DT> <CODE>REQ_UP_CHAR</CODE>

+<DD> Move up in field.

+<DT> <CODE>REQ_DOWN_CHAR</CODE>

+<DD> Move down in field.

+</DL>

+Each <EM>word</EM> is separated from the previous and next characters

+by whitespace. The commands to move to beginning and end of line or field

+look for the first or last non-pad character in their ranges.

+<H3><A NAME="fscroll">Scrolling Requests</A></H3>

+Fields that are dynamic and have grown and fields explicitly created

+with offscreen rows are scrollable. One-line fields scroll horizontally;

+multi-line fields scroll vertically. Most scrolling is triggered by

+editing and intra-field movement (the library scrolls the field to keep the

+cursor visible). It is possible to explicitly request scrolling with the

+following requests:

+<DL>

+<DT> <CODE>REQ_SCR_FLINE</CODE>

+<DD> Scroll vertically forward a line.

+<DT> <CODE>REQ_SCR_BLINE</CODE>

+<DD> Scroll vertically backward a line.

+<DT> <CODE>REQ_SCR_FPAGE</CODE>

+<DD> Scroll vertically forward a page.

+<DT> <CODE>REQ_SCR_BPAGE</CODE>

+<DD> Scroll vertically backward a page.

+<DT> <CODE>REQ_SCR_FHPAGE</CODE>

+<DD> Scroll vertically forward half a page.

+<DT> <CODE>REQ_SCR_BHPAGE</CODE>

+<DD> Scroll vertically backward half a page.

+<DT> <CODE>REQ_SCR_FCHAR</CODE>

+<DD> Scroll horizontally forward a character.

+<DT> <CODE>REQ_SCR_BCHAR</CODE>

+<DD> Scroll horizontally backward a character.

+<DT> <CODE>REQ_SCR_HFLINE</CODE>

+<DD> Scroll horizontally one field width forward.

+<DT> <CODE>REQ_SCR_HBLINE</CODE>

+<DD> Scroll horizontally one field width backward.

+<DT> <CODE>REQ_SCR_HFHALF</CODE>

+<DD> Scroll horizontally one half field width forward.

+<DT> <CODE>REQ_SCR_HBHALF</CODE>

+<DD> Scroll horizontally one half field width backward.

+</DL>

+For scrolling purposes, a <EM>page</EM> of a field is the height

+of its visible part.

+<H3><A NAME="fedit">Editing Requests</A></H3>

+When you pass the forms driver an ASCII character, it is treated as a

+request to add the character to the field's data buffer. Whether this

+is an insertion or a replacement depends on the field's edit mode

+(insertion is the default. <P>

+The following requests support editing the field and changing the edit

+mode:

+<DL>

+<DT> <CODE>REQ_INS_MODE</CODE>

+<DD> Set insertion mode.

+<DT> <CODE>REQ_OVL_MODE</CODE>

+<DD> Set overlay mode.

+<DT> <CODE>REQ_NEW_LINE</CODE>

+<DD> New line request (see below for explanation).

+<DT> <CODE>REQ_INS_CHAR</CODE>

+<DD> Insert space at character location.

+<DT> <CODE>REQ_INS_LINE</CODE>

+<DD> Insert blank line at character location.

+<DT> <CODE>REQ_DEL_CHAR</CODE>

+<DD> Delete character at cursor.

+<DT> <CODE>REQ_DEL_PREV</CODE>

+<DD> Delete previous word at cursor.

+<DT> <CODE>REQ_DEL_LINE</CODE>

+<DD> Delete line at cursor.

+<DT> <CODE>REQ_DEL_WORD</CODE>

+<DD> Delete word at cursor.

+<DT> <CODE>REQ_CLR_EOL</CODE>

+<DD> Clear to end of line.

+<DT> <CODE>REQ_CLR_EOF</CODE>

+<DD> Clear to end of field.

+<DT> <CODE>REQ_CLEAR_FIELD</CODE>

+<DD> Clear entire field.

+</DL>

+The behavior of the <CODE>REQ_NEW_LINE</CODE> and <CODE>REQ_DEL_PREV</CODE> requests

+is complicated and partly controlled by a pair of forms options.

+The special cases are triggered when the cursor is at the beginning of

+a field, or on the last line of the field. <P>

+First, we consider <CODE>REQ_NEW_LINE</CODE>: <P>

+The normal behavior of <CODE>REQ_NEW_LINE</CODE> in insert mode is to break the

+current line at the position of the edit cursor, inserting the portion of

+the current line after the cursor as a new line following the current

+and moving the cursor to the beginning of that new line (you may think

+of this as inserting a newline in the field buffer). <P>

+The normal behavior of <CODE>REQ_NEW_LINE</CODE> in overlay mode is to clear the

+current line from the position of the edit cursor to end of line.

+The cursor is then moved to the beginning of the next line. <P>

+However, <CODE>REQ_NEW_LINE</CODE> at the beginning of a field, or on the

+last line of a field, instead does a <CODE>REQ_NEXT_FIELD</CODE>.

+<CODE>O_NL_OVERLOAD</CODE> option is off, this special action is

+disabled. <P>

+Now, let us consider <CODE>REQ_DEL_PREV</CODE>: <P>

+The normal behavior of <CODE>REQ_DEL_PREV</CODE> is to delete the previous

+character. If insert mode is on, and the cursor is at the start of a

+line, and the text on that line will fit on the previous one, it

+instead appends the contents of the current line to the previous one

+and deletes the current line (you may think of this as deleting a

+newline from the field buffer). <P>

+However, <CODE>REQ_DEL_PREV</CODE> at the beginning of a field is instead

+treated as a <CODE>REQ_PREV_FIELD</CODE>. <P> If the

+<CODE>O_BS_OVERLOAD</CODE> option is off, this special action is

+disabled and the forms driver just returns <CODE>E_REQUEST_DENIED</CODE>. <P>

+See <A HREF="#frmoptions">Form Options</A> for discussion of how to set

+and clear the overload options.

+<H3><A NAME="forder">Order Requests</A></H3>

+If the type of your field is ordered, and has associated functions

+for getting the next and previous values of the type from a given value,

+there are requests that can fetch that value into the field buffer:

+<DL>

+<DT> <CODE>REQ_NEXT_CHOICE</CODE>

+<DD> Place the successor value of the current value in the buffer.

+<DT> <CODE>REQ_PREV_CHOICE</CODE>

+<DD> Place the predecessor value of the current value in the buffer.

+</DL>

+Of the built-in field types, only <CODE>TYPE_ENUM</CODE> has built-in successor

+and predecessor functions. When you define a field type of your own

+(see <A HREF="#fcustom">Custom Validation Types</A>), you can associate

+our own ordering functions.

+<H3><A NAME="fappcmds">Application Commands</A></H3>

+Form requests are represented as integers above the <CODE>curses</CODE> value

+greater than <CODE>KEY_MAX</CODE> and less than or equal to the constant

+<CODE>MAX_COMMAND</CODE>. If your input-virtualization routine returns a

+value above <CODE>MAX_COMMAND</CODE>, the forms driver will ignore it.

+<H2><A NAME="fhooks">Field Change Hooks</A></H2>

+It is possible to set function hooks to be executed whenever the

+current field or form changes. Here are the functions that support this:

+<PRE>

+typedef void (*HOOK)(); /* pointer to function returning void */

+int set_form_init(FORM *form, /* form to alter */

+ HOOK hook); /* initialization hook */

+HOOK form_init(FORM *form); /* form to query */

+int set_form_term(FORM *form, /* form to alter */

+ HOOK hook); /* termination hook */

+HOOK form_term(FORM *form); /* form to query */

+int set_field_init(FORM *form, /* form to alter */

+ HOOK hook); /* initialization hook */

+HOOK field_init(FORM *form); /* form to query */

+int set_field_term(FORM *form, /* form to alter */

+ HOOK hook); /* termination hook */

+HOOK field_term(FORM *form); /* form to query */

+</PRE>

+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 functions differ only in the timing

+of the hook call.

+<DL>

+<DT> form_init

+<DD> This hook is called when the form is posted; also, just after

+each page change operation.

+<DT> field_init

+<DD> This hook is called when the form is posted; also, just after

+each field change

+<DT> field_term

+<DD> This hook is called just after field validation; that is, just before

+the field is altered. It is also called when the form is unposted.

+<DT> form_term

+<DD> This hook is called when the form is unposted; also, just before

+each page change operation.

+</DL>

+Calls to these hooks may be triggered

+<OL>

+<LI>When user editing requests are processed by the forms driver

+<LI>When the current page is changed by <CODE>set_current_field()</CODE> call

+<LI>When the current field is changed by a <CODE>set_form_page()</CODE> call

+</OL>

+See <A NAME="ffocus">Field Change Commands</A> for discussion of the latter

+two cases. <P>

+You can set a default hook for all fields by passing one of the set functions

+a NULL first argument. <P>

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

+value.

+<H2><A HREF="#ffocus">Field Change Commands</A></H2>

+Normally, navigation through the form will be driven by the user's

+input requests. But sometimes it is useful to be able to move the

+focus for editing and viewing under control of your application, or

+ask which field it currently is in. The following functions help you

+accomplish this:

+<PRE>

+int set_current_field(FORM *form, /* form to alter */

+ FIELD *field); /* field to shift to */

+FIELD *current_field(FORM *form); /* form to query */

+int field_index(FORM *form, /* form to query */

+ FIELD *field); /* field to get index of */

+</PRE>

+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

+<CODE>set_form_fields()</CODE>). <P>

+The initial current field of a form is the first active field on the

+first page. The function <CODE>set_form_fields()</CODE> resets this.<P>

+It is also possible to move around by pages.

+<PRE>

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

+The initial page of a newly-created form is 0. The function

+<CODE>set_form_fields()</CODE> resets this.

+<H2><A NAME="frmoptions">Form Options</A></H2>

+Like fields, forms may have control option bits. They can be changed

+or queried with these functions:

+<PRE>

+int set_form_opts(FORM *form, /* form to alter */

+ int attr); /* attribute to set */

+int form_opts_on(FORM *form, /* form to alter */

+ int attr); /* attributes to turn on */

+int form_opts_off(FORM *form, /* form to alter */

+ int attr); /* attributes to turn off */

+int form_opts(FORM *form); /* form to query */

+</PRE>

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

+<DL>

+<DT> O_NL_OVERLOAD

+<DD> Enable overloading of <CODE>REQ_NEW_LINE</CODE> as described in <A

+href="#fedit">Editing Requests</A>. The value of this option is

+ignored on dynamic fields that have not reached their size limit;

+these have no last line, so the circumstances for triggering a

+<CODE>REQ_NEXT_FIELD</CODE> never arise.

+<DT> O_BS_OVERLOAD

+<DD> Enable overloading of <CODE>REQ_DEL_PREV</CODE> as described in

+<A href="#fedit">Editing Requests</A>.

+</DL>

+The option values are bit-masks and can be composed with logical-or in

+the obvious way.

+<H2><A NAME="fcustom">Custom Validation Types</A></H2>

+The <CODE>form</CODE> library gives you the capability to define custom

+validation types of your own. Further, the optional additional arguments

+of <CODE>set_field_type</CODE> effectively allow you to parameterize validation

+types. Most of the complications in the validation-type interface have to

+do with the handling of the additional arguments within custom validation

+functions.

+<H3><A NAME="flinktypes">Union Types</A></H3>

+The simplest way to create a custom data type is to compose it from two

+preexisting ones:

+<PRE>

+FIELD *link_fieldtype(FIELDTYPE *type1,

+ FIELDTYPE *type2);

+</PRE>

+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 <CODE>set_field_type()</CODE> call later requires arguments, the new

+composite type expects all arguments for the first type, than all arguments

+for the second. Order functions (see <A HREF="#forder">Order Requests</A>)

+associated with the component types will work on the composite; what it does

+is check the validation function for the first type, then for the second, to

+figure what type the buffer contents should be treated as.

+<H3><A NAME="fnewtypes">New Field Types</A></H3>

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

+following things:

+<UL>

+<LI>A character-validation function, to check each character as it is entered.

+<LI>A field-validation function to be applied on exit from the field.

+</UL>

+Here's how you do that:

+<PRE>

+typedef int (*HOOK)(); /* pointer to function returning int */

+FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */

+ HOOK c_validate) /* character validator */

+int free_fieldtype(FIELDTYPE *ftype); /* type to free */

+</PRE>

+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 processing a field of

+the new type. <P>

+The function <CODE>free_fieldtype()</CODE> deallocates the argument

+fieldtype, freeing all storage associated with it. <P>

+Normally, a field validator is called when the user attempts to

+leave the field. Its first argument is a field pointer, from which it

+can get to field buffer 0 and test it. If the function returns TRUE,

+the operation succeeds; if it returns FALSE, the edit cursor stays in

+the field. <P>

+A character validator gets the character passed in as a first argument.

+It too should return TRUE if the character is valid, FALSE otherwise.

+<H3><A NAME="fcheckargs">Validation Function Arguments</A></H3>

+Your field- and character- validation functions will be passed a

+second argument as well. This second argument is the address of a

+structure (which we'll call a <EM>pile</EM>) built from any of the

+field-type-specific arguments passed to <CODE>set_field_type()</CODE>. If

+no such arguments are defined for the field type, this pile pointer

+argument will be NULL. <P>

+In order to arrange for such arguments to be passed to your validation

+functions, you must associate a small set of storage-management functions

+with the type. The forms driver will use these to synthesize a pile

+from the trailing arguments of each <CODE>set_field_type()</CODE> argument, and

+a pointer to the pile will be passed to the validation functions. <P>

+Here is how you make the association:

+<PRE>

+typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */

+typedef void (*VOIDHOOK)(); /* pointer to function returning void */

+int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */

+ PTRHOOK make_str, /* make structure from args */

+ PTRHOOK copy_str, /* make copy of structure */

+ VOIDHOOK free_str); /* free structure storage */

+</PRE>

+Here is how the storage-management hooks are used:

+<DL>

+<DT> <CODE>make_str</CODE>

+<DD> This function is called by <CODE>set_field_type()</CODE>. It gets one

+argument, a <CODE>va_list</CODE> of the type-specific arguments passed to

+<CODE>set_field_type()</CODE>. It is expected to return a pile pointer to a data

+structure that encapsulates those arguments.

+<DT> <CODE>copy_str</CODE>

+<DD> This function is called by form library functions that allocate new

+field instances. It is expected to take a pile pointer, copy the pile

+to allocated storage, and return the address of the pile copy.

+<DT> <CODE>free_str</CODE>

+<DD> This function is called by field- and type-deallocation routines in the

+library. It takes a pile pointer argument, and is expected to free the

+storage of that pile.

+</DL>

+The <CODE>make_str</CODE> and <CODE>copy_str</CODE> functions may return NULL to

+signal allocation failure. The library routines will that call them will

+return error indication when this happens. Thus, your validation functions

+should never see a NULL file pointer and need not check specially for it.

+<H3><A NAME="fcustorder">Order Functions For Custom Types</A></H3>

+Some custom field types are simply ordered in the same well-defined way

+that <CODE>TYPE_ENUM</CODE> is. For such types, it is possible to define

+successor and predecessor functions to support the <CODE>REQ_NEXT_CHOICE</CODE>

+and <CODE>REQ_PREV_CHOICE</CODE> requests. Here's how:

+<PRE>

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

+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 <CODE>field_buffer()</CODE> to read the

+current value, and <CODE>set_field_buffer()</CODE> on buffer 0 to set the next

+or previous value. Either hook may return TRUE to indicate success (a

+legal next or previous value was set) or FALSE to indicate failure.

+<H3><A NAME="fcustprobs">Avoiding Problems</A></H3>

+The interface for defining custom types is complicated and tricky.

+Rather than attempting to create a custom type entirely from scratch,

+you should start by studying the library source code for whichever of

+the pre-defined types seems to be closest to what you want. <P>

+Use that code as a model, and evolve it towards what you really want.

+You will avoid many problems and annoyances that way. The code

+in the <CODE>ncurses</CODE> library has been specifically exempted from

+the package copyright to support this. <P>

+If your custom type defines order functions, have do something intuitive

+with a blank field. A useful convention is to make the successor of a

+blank field the types minimum value, and its predecessor the maximum.

+</BODY>

+</HTML>