aboutsummaryrefslogtreecommitdiff
path: root/doc/html/NCURSES-Programming-HOWTO.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/NCURSES-Programming-HOWTO.html')
-rw-r--r--doc/html/NCURSES-Programming-HOWTO.html6413
1 files changed, 6413 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">&lt;<a href=
+"mailto:ppadala@gmail.com">ppadala@gmail.com</a>&gt;</code></p>
+</div>
+</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>
+</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&lt;version&gt;.tar.gz # unzip and untar the archive
+ cd ncurses&lt;version&gt; # 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 &lt;downloaded rpm&gt;</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
+ |
+ |----&gt; JustForFun -- just for fun programs
+ |----&gt; basics -- basic programs
+ |----&gt; demo -- output files go into this directory after make
+ | |
+ | |----&gt; exe -- exe files of all example programs
+ |----&gt; forms -- programs related to form library
+ |----&gt; menus -- programs related to menus library
+ |----&gt; panels -- programs related to panels library
+ |----&gt; perl -- perl equivalents of the examples (contributed
+ | by Anuradha Ratnaweera)
+ |----&gt; Makefile -- the top level Makefile
+ |----&gt; README -- the top level README file. contains instructions
+ |----&gt; 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
+ |
+ |----&gt; hanoi.c -- The Towers of Hanoi Solver
+ |----&gt; life.c -- The Game of Life demo
+ |----&gt; magic.c -- An Odd Order Magic Square builder
+ |----&gt; queens.c -- The famous N-Queens Solver
+ |----&gt; shuffle.c -- A fun game, if you have time to kill
+ |----&gt; tt.c -- A very trivial typing tutor
+
+ basics
+ |
+ |----&gt; acs_vars.c -- ACS_ variables example
+ |----&gt; hello_world.c -- Simple "Hello World" Program
+ |----&gt; init_func_example.c -- Initialization functions example
+ |----&gt; key_code.c -- Shows the scan code of the key pressed
+ |----&gt; mouse_menu.c -- A menu accessible by mouse
+ |----&gt; other_border.c -- Shows usage of other border functions apa
+ | -- rt from box()
+ |----&gt; printw_example.c -- A very simple printw() example
+ |----&gt; scanw_example.c -- A very simple getstr() example
+ |----&gt; simple_attr.c -- A program that can print a c file with
+ | -- comments in attribute
+ |----&gt; simple_color.c -- A simple example demonstrating colors
+ |----&gt; simple_key.c -- A menu accessible with keyboard UP, DOWN
+ | -- arrows
+ |----&gt; temp_leave.c -- Demonstrates temporarily leaving curses mode
+ |----&gt; win_border.c -- Shows Creation of windows and borders
+ |----&gt; with_chgat.c -- chgat() usage example
+
+ forms
+ |
+ |----&gt; form_attrib.c -- Usage of field attributes
+ |----&gt; form_options.c -- Usage of field options
+ |----&gt; form_simple.c -- A simple form example
+ |----&gt; form_win.c -- Demo of windows associated with forms
+
+ menus
+ |
+ |----&gt; menu_attrib.c -- Usage of menu attributes
+ |----&gt; menu_item_data.c -- Usage of item_name() etc.. functions
+ |----&gt; menu_multi_column.c -- Creates multi columnar menus
+ |----&gt; menu_scroll.c -- Demonstrates scrolling capability of menus
+ |----&gt; menu_simple.c -- A simple menu accessed by arrow keys
+ |----&gt; menu_toggle.c -- Creates multi valued menus and explains
+ | -- REQ_TOGGLE_ITEM
+ |----&gt; menu_userptr.c -- Usage of user pointer
+ |----&gt; menu_win.c -- Demo of windows associated with menus
+
+ panels
+ |
+ |----&gt; panel_browse.c -- Panel browsing through tab. Usage of user
+ | -- pointer
+ |----&gt; panel_hide.c -- Hiding and Un hiding of panels
+ |----&gt; panel_resize.c -- Moving and resizing of panels
+ |----&gt; panel_simple.c -- A simple panel example
+
+ perl
+ |----&gt; 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">&#13; 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 &lt;path to docbook html stylesheet&gt;
+ NCURSES-Programming-HOWTO.sgml
+ to get pdf, first create a single html file of the HOWTO with
+ jade -t sgml -i html -d &lt;path to docbook html stylesheet&gt; -V nochunks
+ NCURSES-Programming-HOWTO.sgml &gt; NCURSES-ONE-BIG-FILE.html
+ then use htmldoc to get pdf file with
+ htmldoc --size universal -t pdf --firstpage p1 -f &lt;output file name.pdf&gt;
+ NCURSES-ONE-BIG-FILE.html
+ for ps, you would use
+ htmldoc --size universal -t ps --firstpage p1 -f &lt;output file name.ps&gt;
+ 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>
+<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>Copyright &copy; 2001 by Pradeep Padala.</p>
+<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>
+<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 &lt;ncurses.h&gt;
+ .
+ .
+ .
+
+ compile and link: gcc &lt;program file&gt; -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 &lt;ncurses.h&gt;
+
+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>
+<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>
+</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 &lt;ncurses.h&gt;
+
+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 &lt;enter&gt; 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>
+<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 &lt;ncurses.h&gt; /* ncurses.h includes stdio.h */
+#include &lt;string.h&gt;
+
+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>
+<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>
+<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>
+<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 &lt;ncurses.h&gt; /* ncurses.h includes stdio.h */
+#include &lt;string.h&gt;
+
+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>
+</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" &lt;spainhou@bellsouth.net&gt; */
+#include &lt;ncurses.h&gt;
+#include &lt;stdlib.h&gt;
+
+int main(int argc, char *argv[])
+{
+ int ch, prev, row, col;
+ prev = EOF;
+ FILE *fp;
+ int y, x;
+
+ if(argc != 2)
+ {
+ printf("Usage: %s &lt;a c file name&gt;\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("&lt;-Press Any Key-&gt;"); /* tell the user to press a key */
+ getch();
+ clear(); /* clear the screen */
+ move(0, 0); /* start at the beginning of the screen */
+ }
+ if(prev == '/' &amp;&amp; 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 == '*' &amp;&amp; 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 &lt;curses.h&gt; 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 &lt;ncurses.h&gt;
+
+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>
+<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 &lt;ncurses.h&gt;
+
+
+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>
+<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 &lt;ncurses.h&gt;
+
+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(&amp;win);
+ print_win_params(&amp;win);
+
+ attron(COLOR_PAIR(1));
+ printw("Press F1 to exit");
+ refresh();
+ attroff(COLOR_PAIR(1));
+
+ create_box(&amp;win, TRUE);
+ while((ch = getch()) != KEY_F(1))
+ { switch(ch)
+ { case KEY_LEFT:
+ create_box(&amp;win, FALSE);
+ --win.startx;
+ create_box(&amp;win, TRUE);
+ break;
+ case KEY_RIGHT:
+ create_box(&amp;win, FALSE);
+ ++win.startx;
+ create_box(&amp;win, TRUE);
+ break;
+ case KEY_UP:
+ create_box(&amp;win, FALSE);
+ --win.starty;
+ create_box(&amp;win, TRUE);
+ break;
+ case KEY_DOWN:
+ create_box(&amp;win, FALSE);
+ ++win.starty;
+ create_box(&amp;win, TRUE);
+ break;
+ }
+ }
+ endwin(); /* End curses mode */
+ return 0;
+}
+void init_win_params(WIN *p_win)
+{
+ p_win-&gt;height = 3;
+ p_win-&gt;width = 10;
+ p_win-&gt;starty = (LINES - p_win-&gt;height)/2;
+ p_win-&gt;startx = (COLS - p_win-&gt;width)/2;
+
+ p_win-&gt;border.ls = '|';
+ p_win-&gt;border.rs = '|';
+ p_win-&gt;border.ts = '-';
+ p_win-&gt;border.bs = '-';
+ p_win-&gt;border.tl = '+';
+ p_win-&gt;border.tr = '+';
+ p_win-&gt;border.bl = '+';
+ p_win-&gt;border.br = '+';
+
+}
+void print_win_params(WIN *p_win)
+{
+#ifdef _DEBUG
+ mvprintw(25, 0, "%d %d %d %d", p_win-&gt;startx, p_win-&gt;starty,
+ p_win-&gt;width, p_win-&gt;height);
+ refresh();
+#endif
+}
+void create_box(WIN *p_win, bool flag)
+{ int i, j;
+ int x, y, w, h;
+
+ x = p_win-&gt;startx;
+ y = p_win-&gt;starty;
+ w = p_win-&gt;width;
+ h = p_win-&gt;height;
+
+ if(flag == TRUE)
+ { mvaddch(y, x, p_win-&gt;border.tl);
+ mvaddch(y, x + w, p_win-&gt;border.tr);
+ mvaddch(y + h, x, p_win-&gt;border.bl);
+ mvaddch(y + h, x + w, p_win-&gt;border.br);
+ mvhline(y, x + 1, p_win-&gt;border.ts, w - 1);
+ mvhline(y + h, x + 1, p_win-&gt;border.bs, w - 1);
+ mvvline(y + 1, x, p_win-&gt;border.ls, h - 1);
+ mvvline(y + 1, x + w, p_win-&gt;border.rs, h - 1);
+
+ }
+ else
+ for(j = y; j &lt;= y + h; ++j)
+ for(i = x; i &lt;= x + w; ++i)
+ mvaddch(j, i, ' ');
+
+ refresh();
+
+}</span></font>
+</pre></td>
+</tr>
+</table>
+</div>
+</div>
+</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 &lt;ncurses.h&gt;
+
+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>
+<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 &lt;stdio.h&gt;
+#include &lt;ncurses.h&gt;
+
+#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 &lt; 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>
+</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(&amp;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 &amp; 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 &lt;ncurses.h&gt;
+
+#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(&amp;event) == OK)
+ { /* When the user clicks left mouse button */
+ if(event.bstate &amp; BUTTON1_PRESSED)
+ { report_choice(event.x + 1, event.y + 1, &amp;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 &lt; 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 &lt; n_choices; ++choice)
+ if(mouse_y == j + choice &amp;&amp; mouse_x &gt;= i &amp;&amp; mouse_x &lt;= 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>
+<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>
+<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>
+<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 &lt;ncurses.h&gt;
+
+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>
+<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 &lt;ncurses.h&gt;
+
+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>
+</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 &lt;panel.h&gt;
+ .
+ .
+ .
+
+ compile and link: gcc &lt;program file&gt; -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 &lt;panel.h&gt;
+
+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 &lt; 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 &lt;panel.h&gt;
+
+#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 &lt; 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>
+<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 &lt;TAB&gt; 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 &lt;panel.h&gt;
+
+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-&gt;x;
+ newy = top-&gt;y;
+ neww = top-&gt;w;
+ newh = top-&gt;h;
+ while((ch = getch()) != KEY_F(1))
+ { switch(ch)
+ { case 9: /* Tab */
+ top = (PANEL_DATA *)panel_userptr(stack_top);
+ top_panel(top-&gt;next);
+ stack_top = top-&gt;next;
+ top = (PANEL_DATA *)panel_userptr(stack_top);
+ newx = top-&gt;x;
+ newy = top-&gt;y;
+ neww = top-&gt;w;
+ newh = top-&gt;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 &lt;ENTER&gt; 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 &lt;ENTER&gt; 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-&gt;label, top-&gt;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 &lt; 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 &lt; 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], &amp;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
+&lt;ENTER&gt; 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 &lt;ENTER&gt; 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 &lt;panel.h&gt;
+
+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], &amp;panel_datas[0]);
+ set_panel_userptr(my_panels[1], &amp;panel_datas[1]);
+ set_panel_userptr(my_panels[2], &amp;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-&gt;hide == FALSE)
+ { hide_panel(my_panels[0]);
+ temp-&gt;hide = TRUE;
+ }
+ else
+ { show_panel(my_panels[0]);
+ temp-&gt;hide = FALSE;
+ }
+ break;
+ case 'b':
+ temp = (PANEL_DATA *)panel_userptr(my_panels[1]);
+ if(temp-&gt;hide == FALSE)
+ { hide_panel(my_panels[1]);
+ temp-&gt;hide = TRUE;
+ }
+ else
+ { show_panel(my_panels[1]);
+ temp-&gt;hide = FALSE;
+ }
+ break;
+ case 'c':
+ temp = (PANEL_DATA *)panel_userptr(my_panels[2]);
+ if(temp-&gt;hide == FALSE)
+ { hide_panel(my_panels[2]);
+ temp-&gt;hide = TRUE;
+ }
+ else
+ { show_panel(my_panels[2]);
+ temp-&gt;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 &lt; 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>
+<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>
+<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 &lt;menu.h&gt;
+ .
+ .
+ .
+
+ compile and link: gcc &lt;program file&gt; -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 &lt;curses.h&gt;
+#include &lt;menu.h&gt;
+
+#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 &lt; 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">&#13; 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.&#13;</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&shy;
+ 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 &lt;menu.h&gt;
+
+#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 &lt; 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 &lt; 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 &lt;curses.h&gt;
+#include &lt;menu.h&gt;
+
+#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 &lt; 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 &lt; 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 &lt;curses.h&gt;
+#include &lt;menu.h&gt;
+
+#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 &lt; 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 &lt; 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&shy;
+ 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 &lt;curses.h&gt;
+#include &lt;menu.h&gt;
+
+#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 &lt; 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 &lt;SPACE&gt; to select or unselect an item.");
+ mvprintw(LINES - 2, 0, "&lt;ENTER&gt; 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 &lt; 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 &lt;ENTER&gt; 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 &lt;menu.h&gt;
+
+#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 &lt; 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 &lt;ENTER&gt; 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 &lt; n_choices; ++i)
+ free_item(my_items[i]);
+ free_menu(my_menu);
+ endwin();
+}
+ </span></font>
+</pre></td>
+</tr>
+</table>
+</div>
+</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
+&lt;ENTER&gt;);</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 &lt;curses.h&gt;
+#include &lt;menu.h&gt;
+
+#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 &lt; 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 &lt;ENTER&gt; 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 &lt; 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>
+</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 &lt;form.h&gt;
+ .
+ .
+ .
+
+ compile and link: gcc &lt;program file&gt; -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 &lt;form.h&gt;
+
+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">&#13;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 */&#13;</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 &lt;form.h&gt;
+
+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 &lt;form.h&gt;
+
+#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 &lt; 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>
+<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 &lt;form.h&gt;
+
+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, &amp;rows, &amp;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>
+<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>
+</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">"&lt;/B/1&gt;This line should have a yellow foreground and a blue
+background.&lt;!1&gt;"</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>
+<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>
+<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>
+<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>
+</div>
+</body>
+</html>