-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
+"http://www.w3.org/TR/html4/strict.dtd">
+
<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">
+ <meta name="generator" content=
+ "HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
+
+ <title>NCURSES Programming HOWTO</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
</head>
+
<body class="ARTICLE" bgcolor="#FFFFFF" text="#000000" link=
"#0000FF" vlink="#840084" alink="#0000FF">
-<div class="ARTICLE">
-<div class="TITLEPAGE">
-<h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES Programming
-HOWTO</a></h1>
-<h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep Padala</a></h3>
-<div class="AFFILIATION">
-<div class="ADDRESS">
-<p class="ADDRESS"><code class="EMAIL"><<a href=
-"mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code></p>
-</div>
-</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<version>.tar.gz # unzip and untar the archive
+ <div class="ARTICLE">
+ <div class="TITLEPAGE">
+ <h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES
+ Programming HOWTO</a></h1>
+
+ <h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep
+ Padala</a></h3>
+
+ <div class="AFFILIATION">
+ <div class="ADDRESS">
+ <p class="ADDRESS"><code class="EMAIL"><<a href=
+ "mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code></p>
+ </div>
+ </div>
+
+ <p class="PUBDATE">v1.9, 2005-06-20<br></p>
+
+ <div class="REVHISTORY">
+ <table width="100%" border="0" summary="revisions">
+ <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><span class="emphasis"><i class="EMPHASIS">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></i></span></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>
+
+ <dd>
+ <dl>
+ <dt>1.6.1. <a href="#LISTFORMATS">Readily available
+ formats from tldp.org</a></dt>
+
+ <dt>1.6.2. <a href="#BUILDSOURCE">Building from
+ source</a></dt>
+ </dl>
+ </dd>
+
+ <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>
+
+ <dd>
+ <dl>
+ <dt>2.2.1. <a href="#ABOUT-INITSCR">About
+ initscr()</a></dt>
+
+ <dt>2.2.2. <a href="#MYST-REFRESH">The mysterious
+ refresh()</a></dt>
+
+ <dt>2.2.3. <a href="#ABOUT-ENDWIN">About
+ endwin()</a></dt>
+ </dl>
+ </dd>
+ </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>
+
+ <dd>
+ <dl>
+ <dt>6.3.1. <a href="#PRINTWMVPRINTW">printw() and
+ mvprintw</a></dt>
+
+ <dt>6.3.2. <a href="#WPRINTWMVWPRINTW">wprintw()
+ and mvwprintw</a></dt>
+
+ <dt>6.3.3. <a href="#VWPRINTW">vw_printw()</a></dt>
+
+ <dt>6.3.4. <a href="#SIMPLEPRINTWEX">A Simple
+ printw example</a></dt>
+ </dl>
+ </dd>
+
+ <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>
+
+ <dd>
+ <dl>
+ <dt>7.2.1. <a href="#SCANWMVSCANW">scanw() and
+ mvscanw</a></dt>
+
+ <dt>7.2.2. <a href="#WSCANWMVWSCANW">wscanw() and
+ mvwscanw()</a></dt>
+
+ <dt>7.2.3. <a href="#VWSCANW">vw_scanw()</a></dt>
+ </dl>
+ </dd>
+
+ <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="#ATTRGET">attr_get()</a></dt>
+
+ <dt>8.4. <a href="#ATTRFUNCS">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>
+
+ <dd>
+ <dl>
+ <dt>18.3.1. <a href="#FETCHINFO">Fetching Size and
+ Location of Field</a></dt>
+
+ <dt>18.3.2. <a href="#MOVEFIELD">Moving the
+ field</a></dt>
+
+ <dt>18.3.3. <a href="#JUSTIFYFIELD">Field
+ Justification</a></dt>
+
+ <dt>18.3.4. <a href="#FIELDDISPATTRIB">Field
+ Display Attributes</a></dt>
+
+ <dt>18.3.5. <a href="#FIELDOPTIONBITS">Field Option
+ Bits</a></dt>
+
+ <dt>18.3.6. <a href="#FIELDSTATUS">Field
+ Status</a></dt>
+
+ <dt>18.3.7. <a href="#FIELDUSERPTR">Field User
+ Pointer</a></dt>
+
+ <dt>18.3.8. <a href=
+ "#VARIABLESIZEFIELDS">Variable-Sized
+ Fields</a></dt>
+ </dl>
+ </dd>
+
+ <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>
+
+ <dd>
+ <dl>
+ <dt>18.6.1. <a href="#PAGENAVREQ">Page Navigation
+ Requests</a></dt>
+
+ <dt>18.6.2. <a href="#INTERFIELDNAVREQ">Inter-Field
+ Navigation Requests</a></dt>
+
+ <dt>18.6.3. <a href="#INTRAFIELDNAVREQ">Intra-Field
+ Navigation Requests</a></dt>
+
+ <dt>18.6.4. <a href="#SCROLLREQ">Scrolling
+ Requests</a></dt>
+
+ <dt>18.6.5. <a href="#EDITREQ">Editing
+ Requests</a></dt>
+
+ <dt>18.6.6. <a href="#ORDERREQ">Order
+ Requests</a></dt>
+
+ <dt>18.6.7. <a href="#APPLICCOMMANDS">Application
+ Commands</a></dt>
+ </dl>
+ </dd>
+ </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>
+
+ <dd>
+ <dl>
+ <dt>19.1.1. <a href="#WIDGETLIST">Widget
+ List</a></dt>
+
+ <dt>19.1.2. <a href="#CDKATTRACT">Some Attractive
+ Features</a></dt>
+
+ <dt>19.1.3. <a href=
+ "#CDKCONCLUSION">Conclusion</a></dt>
+ </dl>
+ </dd>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+echo "^[[0;31;40mIn Color"
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+echo "^[[0;37;40m"
+</pre>
+
+ <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 <tt class="LITERAL">termcap</tt>. 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 <tt class=
+ "LITERAL">terminfo</tt>. 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><span class="emphasis"><i class="EMPHASIS">Compiling the
+ package</i></span></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>
+ <pre class="PROGRAMLISTING">
+ tar zxvf ncurses<version>.tar.gz # unzip and untar the archive
cd ncurses<version> # cd to the directory
./configure # configure the build according to your
# environment
make # make it
su root # become root
- make install # install it</font>
-</pre></td>
-</tr>
-</table>
-<p><em>Using the RPM</em></p>
-<p>NCURSES RPM can be found and downloaded from <a href=
-"http://rpmfind.net" target="_top">http://rpmfind.net</a> . The RPM
-can be installed with the following command after becoming
-root.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> rpm -i <downloaded rpm></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PURPOSE" id="PURPOSE">1.4. Purpose/Scope
-of the document</a></h3>
-<p>This document is intended to be a "All in One" guide for
-programming with ncurses and its sister libraries. We graduate from
-a simple "Hello World" program to more complex form manipulation.
-No prior experience in ncurses is assumed. The writing is informal,
-but a lot of detail is provided for each of the examples.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ABOUTPROGRAMS" id="ABOUTPROGRAMS">1.5.
-About the Programs</a></h3>
-<p>All the programs in the document are available in zipped form
-<a href=
-"http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz"
-target="_top">here</a>. Unzip and untar it. The directory structure
-looks like this.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">ncurses
+ make install # install it
+</pre>
+
+ <p><span class="emphasis"><i class="EMPHASIS">Using the
+ RPM</i></span></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>
+ <pre class="PROGRAMLISTING">
+ rpm -i <downloaded rpm>
+</pre>
+ </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>
+
<pre class="PROGRAMLISTING">
+ncurses
|
|----> JustForFun -- just for fun programs
|----> basics -- basic programs
| by Anuradha Ratnaweera)
|----> Makefile -- the top level Makefile
|----> README -- the top level README file. contains instructions
- |----> COPYING -- copyright notice</font>
-</pre></td>
-</tr>
-</table>
-<p>The individual directories contain the following files.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">Description of files in each directory
+ |----> COPYING -- copyright notice
+</pre>
+
+ <p>The individual directories contain the following
+ files.</p>
+ <pre class="PROGRAMLISTING">
+Description of files in each directory
--------------------------------------
JustForFun
|
|----> panel_simple.c -- A simple panel example
perl
- |----> 01-10.pl -- Perl equivalents of first ten example programs</font>
-</pre></td>
-</tr>
-</table>
-<p>There is a top level Makefile included in the main directory. It
-builds all the files and puts the ready-to-use exes in demo/exe
-directory. You can also do selective make by going into the
-corresponding directory. Each directory contains a README file
-explaining the purpose of each c file in the directory.</p>
-<p>For every example, I have included path name for the file
-relative to the examples directory.</p>
-<p>If you prefer browsing individual programs, point your browser
-to <a href=
-"http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/"
-target=
-"_top">http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/</a></p>
-<p>All the programs are released under the same license that is
-used by ncurses (MIT-style). This gives you the ability to do
-pretty much anything other than claiming them as yours. Feel free
-to use them in your programs as appropriate.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="OTHERFORMATS" id="OTHERFORMATS">1.6.
-Other Formats of the document</a></h3>
-<p>This howto is also availabe in various other formats on the
-tldp.org site. Here are the links to other formats of this
-document.</p>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="LISTFORMATS" id="LISTFORMATS">1.6.1.
-Readily available formats from tldp.org</a></h4>
-<ul>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf"
-target="_top">Acrobat PDF Format</a></p>
-</li>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz"
-target="_top">PostScript Format</a></p>
-</li>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz"
-target="_top">In Multiple HTML pages</a></p>
-</li>
-<li>
-<p><a href=
-"http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html"
-target="_top">In One big HTML format</a></p>
-</li>
-</ul>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="BUILDSOURCE" id="BUILDSOURCE">1.6.2.
-Building from source</a></h4>
-<p>If above links are broken or if you want to experiment with sgml
-read on.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> Get both the source and the tar,gzipped programs, available at
+ |----> 01-10.pl -- Perl equivalents of first ten example programs
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ 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-ONE-BIG-FILE.html
for ps, you would use
htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps>
- NCURSES-ONE-BIG-FILE.html</font>
-</pre></td>
-</tr>
-</table>
-<p>See <a href="http://www.tldp.org/LDP/LDP-Author-Guide/" target=
-"_top">LDP Author guide</a> for more details. If all else failes,
-mail me at <a href="ppadala@gmail.com" target=
-"_top">ppadala@gmail.com</a></p>
-</div>
-</div>
-<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 © 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 <ncurses.h>
+ NCURSES-ONE-BIG-FILE.html
+</pre>
+
+ <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 © 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>
+ <pre class="PROGRAMLISTING">
+ #include <ncurses.h>
.
.
.
- compile and link: gcc <program file> -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="BHW" id="BHW"></a>
-<p><b>Example 1. The Hello World !!! Program</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <ncurses.h>
+ compile and link: gcc <program file> -lncurses
+</pre>
+
+ <div class="EXAMPLE">
+ <a name="BHW" id="BHW"></a>
+
+ <p><b>Example 1. The Hello World !!! Program</b></p>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
int main()
{
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 <ncurses.h>
+}</span>
+</pre>
+ </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
+ <tt class="LITERAL">stdscr</tt>) 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 <tt class=
+ "LITERAL">cbreak()</tt> 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. <tt class=
+ "LITERAL">noecho()</tt> 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 <tt class=
+ "LITERAL">noecho()</tt> 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 <tt class=
+ "LITERAL">keypad(stdscr, TRUE)</tt> 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
int main()
{ int ch;
endwin(); /* End curses mode */
return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This program is self-explanatory. But I used functions which
-aren't explained yet. The function <var class=
-"LITERAL">getch()</var> is used to get a character from user. It is
-equivalent to normal <var class="LITERAL">getchar()</var> except
-that we can disable the line buffering to avoid <enter> after
-input. Look for more about <var class="LITERAL">getch()</var>and
-reading keys in the <a href="#KEYS">key management section</a> .
-The functions attron and attroff are used to switch some attributes
-on and off respectively. In the example I used them to print the
-character in bold. These functions are explained in detail
-later.</p>
-</div>
-</div>
-<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 */
+}</span>
+</pre>
+ </div>
+
+ <p>This program is self-explanatory. But I used functions
+ which aren't explained yet. The function <tt class=
+ "LITERAL">getch()</tt> is used to get a character from
+ user. It is equivalent to normal <tt class=
+ "LITERAL">getchar()</tt> except that we can disable the
+ line buffering to avoid <enter> after input. Look for
+ more about <tt class="LITERAL">getch()</tt>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 <tt class=
+ "LITERAL">stdscr</tt> 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>
+ <pre class="PROGRAMLISTING">
+ printw("Hi There !!!");
+ refresh();
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ wprintw(win, "Hi There !!!");
+ wrefresh(win);
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ 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=
+ /* co-ordinates and then print */
+</pre>
+
+ <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 is 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 <tt class="LITERAL">ncurses.h</tt>.
+ For example, you want to print a character ch(of type
+ char) bold and underlined, you would call addch() as
+ below.</p>
+ <pre class="PROGRAMLISTING">
+ addch(ch | A_BOLD | A_UNDERLINE);
+</pre>
+ </li>
+
+ <li>
+ <p>By using functions like <tt class=
+ "LITERAL">attrset(),attron(),attroff()</tt>. 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, <tt class="LITERAL">curses</tt> 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 <tt class=
+ "LITERAL">ncurses.h</tt>. Try looking for macros beginning
+ with <tt class="LITERAL">ACS_</tt> 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><tt class="LITERAL">mvaddch()</tt> is used to move the
+ cursor to a given point, and then print. Thus, the
+ calls:</p>
+ <pre class="PROGRAMLISTING">
+ move(row,col); /* moves the cursor to row<span class=
+"emphasis"><i class=
+"EMPHASIS">th</i></span> row and col<span class="emphasis"><i class="EMPHASIS">th</i></span> column */
+ addch(ch);
+</pre>can be replaced by
+ <pre class="PROGRAMLISTING">
+ mvaddch(row,col,ch);
+</pre>
+
+ <p><tt class="LITERAL">waddch()</tt> is similar to
+ <tt class="LITERAL">addch()</tt>, except that it adds a
+ character into the given window. (Note that <tt class=
+ "LITERAL">addch()</tt> adds a character into the window
+ <tt class="LITERAL">stdscr</tt>.)</p>
+
+ <p>In a similar fashion <tt class="LITERAL">mvwaddch()</tt>
+ 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
+ <tt class="LITERAL">addch()</tt>. But, if we want to print
+ a string, it would be very annoying to print it character
+ by character. Fortunately, <tt class="LITERAL">ncurses</tt>
+ provides <tt class="LITERAL">printf</tt><span class=
+ "emphasis"><i class="EMPHASIS">-like</i></span> or
+ <tt class="LITERAL">puts</tt><span class=
+ "emphasis"><i class="EMPHASIS">-like</i></span>
+ 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 <tt class=
+ "LITERAL">printf()</tt> 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 <tt class=
+ "LITERAL">printf()</tt>. <tt class=
+ "LITERAL">mvprintw()</tt> 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 <tt class=
+ "LITERAL">printw()</tt> function, use <tt class=
+ "LITERAL">move()</tt> first and then use <tt class=
+ "LITERAL">printw()</tt> though I see no point why one
+ should avoid using <tt class="LITERAL">mvprintw()</tt>,
+ 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.
+ vw_printw()</a></h4>
+
+ <p>This function is similar to <tt class=
+ "LITERAL">vprintf()</tt>. 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>
+ <pre class="PROGRAMLISTING">
+<span class=
"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */
#include <string.h>
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=
+}</span>
+</pre>
+ </div>
+
+ <p>Above program demonstrates how easy it is to use
+ <tt class="LITERAL">printw</tt>. 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
+ <tt class="LITERAL">getmaxyx()</tt>, a macro defined in
+ <tt class="LITERAL">ncurses.h</tt>. It gives the number
+ of columns and the number of rows in a given window.
+ <tt class="LITERAL">getmaxyx()</tt> does this by updating
+ the variables given to it. Since <tt class=
+ "LITERAL">getmaxyx()</tt> 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><tt class="LITERAL">addstr()</tt> is used to put a
+ character string into a given window. This function is
+ similar to calling <tt class="LITERAL">addch()</tt> once
+ for each character in a given string. This is true for all
+ output functions. There are other functions from this
+ family such as <tt class=
+ "LITERAL">mvaddstr(),mvwaddstr()</tt> and <tt class=
+ "LITERAL">waddstr()</tt>, 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 <tt class=
+ "LITERAL">scanf()</tt> 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
+ <tt class="LITERAL">sscanf()</tt>, where the line to be
+ scanned is provided by <tt class="LITERAL">wgetstr()</tt>
+ function. That is, these functions call to <tt class=
+ "LITERAL">wgetstr()</tt> 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.
+ vw_scanw()</a></h4>
+
+ <p>This function is similar to <tt class=
+ "LITERAL">vscanf()</tt>. 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 <tt class=
+ "LITERAL">getch()</tt> until a newline, carriage return, or
+ end-of-file is received. The resulting string of characters
+ are pointed to by <tt class="LITERAL">str</tt>, 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>
+ <pre class="PROGRAMLISTING">
+<span class=
"INLINEMEDIAOBJECT">#include <ncurses.h> /* ncurses.h includes stdio.h */
#include <string.h>
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=
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class=
"INLINEMEDIAOBJECT">/* pager functionality by Joseph Spainhour" <spainhou@bellsouth.net> */
#include <ncurses.h>
#include <stdlib.h>
endwin(); /* End curses mode */
fclose(fp);
return 0;
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Don't worry about all those initialization and other crap.
-Concentrate on the while loop. It reads each character in the file
-and searches for the pattern /*. Once it spots the pattern, it
-switches the BOLD attribute on with <var class=
-"LITERAL">attron()</var> . When we get the pattern */ it is
-switched off by <var class="LITERAL">attroff()</var> .</p>
-<p>The above program also introduces us to two useful functions
-<var class="LITERAL">getyx()</var> and <var class=
-"LITERAL">move()</var>. The first function gets the co-ordinates of
-the present cursor into the variables y, x. Since getyx() is a
-macro we don't have to pass pointers to variables. The function
-<var class="LITERAL">move()</var> moves the cursor to the
-co-ordinates given to it.</p>
-<p>The above program is really a simple one which doesn't do much.
-On these lines one could write a more useful program which reads a
-C file, parses it and prints it in different colors. One could even
-extend it to other languages as well.</p>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTRIBDETAILS" id="ATTRIBDETAILS">8.1.
-The details</a></h3>
-<p>Let's get into more details of attributes. The functions
-<var class="LITERAL">attron(), attroff(), attrset()</var> , and
-their sister functions <var class="LITERAL">attr_get()</var> etc..
-can be used to switch attributes on/off , get attributes and
-produce a colorful display.</p>
-<p>The functions attron and attroff take a bit-mask of attributes
-and switch them on or off, respectively. The following video
-attributes, which are defined in <curses.h> can be passed to
-these functions.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000">
+}</span>
+</pre>
+ </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 <tt class=
+ "LITERAL">attron()</tt> . When we get the pattern */ it is
+ switched off by <tt class="LITERAL">attroff()</tt> .</p>
+
+ <p>The above program also introduces us to two useful
+ functions <tt class="LITERAL">getyx()</tt> and <tt class=
+ "LITERAL">move()</tt>. 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 <tt class="LITERAL">move()</tt> 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
+ <tt class="LITERAL">attron(), attroff(), attrset()</tt> ,
+ and their sister functions <tt class=
+ "LITERAL">attr_get()</tt> etc.. can be used to switch
+ attributes on/off , get attributes and produce a colorful
+ display.</p>
+
+ <p>The functions attron and attroff take a bit-mask of
+ attributes and switch them on or off, respectively. The
+ following video attributes, which are defined in
+ <curses.h> can be passed to these functions.</p>
+ <pre class="PROGRAMLISTING">
+
A_NORMAL Normal display (no highlight)
A_STANDOUT Best highlighting mode of the terminal.
A_UNDERLINE Underlining
A_ALTCHARSET Alternate character set
A_CHARTEXT Bit-mask to extract a character
COLOR_PAIR(n) Color-pair number n
- </font>
-</pre></td>
-</tr>
-</table>
-<p>The last one is the most colorful one :-) Colors are explained
-in the <a href="#color" target="_top">next sections</a>.</p>
-<p>We can OR(|) any number of above attributes to get a combined
-effect. If you wanted reverse video with blinking characters you
-can use</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> attron(A_REVERSE | A_BLINK);</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTRONVSATTRSET" id=
-"ATTRONVSATTRSET">8.2. attron() vs attrset()</a></h3>
-<p>Then what is the difference between attron() and attrset()?
-attrset sets the attributes of window whereas attron just switches
-on the attribute given to it. So attrset() fully overrides whatever
-attributes the window previously had and sets it to the new
-attribute(s). Similarly attroff() just switches off the
-attribute(s) given to it as an argument. This gives us the
-flexibility of managing attributes easily.But if you use them
-carelessly you may loose track of what attributes the window has
-and garble the display. This is especially true while managing
-menus with colors and highlighting. So decide on a consistent
-policy and stick to it. You can always use <var class=
-"LITERAL">standend()</var> which is equivalent to <var class=
-"LITERAL">attrset(A_NORMAL)</var> which turns off all attributes
-and brings you to normal mode.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTR_GET" id="ATTR_GET">8.3.
-attr_get()</a></h3>
-<p>The function attr_get() gets the current attributes and color
-pair of the window. Though we might not use this as often as the
-above functions, this is useful in scanning areas of screen. Say we
-wanted to do some complex update on screen and we are not sure what
-attribute each character is associated with. Then this function can
-be used with either attrset or attron to produce the desired
-effect.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="ATTR_FUNCS" id="ATTR_FUNCS">8.4. attr_
-functions</a></h3>
-<p>There are series of functions like attr_set(), attr_on etc..
-These are similar to above functions except that they take
-parameters of type <var class="LITERAL">attr_t</var>.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="WATTRFUNCS" id="WATTRFUNCS">8.5. wattr
-functions</a></h3>
-<p>For each of the above functions we have a corresponding function
-with 'w' which operates on a particular window. The above functions
-operate on stdscr.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="CHGAT" id="CHGAT">8.6. chgat()
-functions</a></h3>
-<p>The function chgat() is listed in the end of the man page
-curs_attr. It actually is a useful one. This function can be used
-to set attributes for a group of characters without moving. I mean
-it !!! without moving the cursor :-) It changes the attributes of a
-given number of characters starting at the current cursor
-location.</p>
-<p>We can give -1 as the character count to update till end of
-line. If you want to change attributes of characters from current
-position to end of line, just use this.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> chgat(-1, A_REVERSE, 0, NULL);</font>
-</pre></td>
-</tr>
-</table>
-<p>This function is useful when changing attributes for characters
-that are already on the screen. Move to the character from which
-you want to change and change the attribute.</p>
-<p>Other functions wchgat(), mvchgat(), wchgat() behave similarly
-except that the w functions operate on the particular window. The
-mv functions first move the cursor then perform the work given to
-them. Actually chgat is a macro which is replaced by a wchgat()
-with stdscr as the window. Most of the "w-less" functions are
-macros.</p>
-<div class="EXAMPLE"><a name="BWICH" id="BWICH"></a>
-<p><b>Example 6. Chgat() Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <ncurses.h>
+
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ attron(A_REVERSE | A_BLINK);
+</pre>
+ </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 <tt class="LITERAL">standend()</tt> which is
+ equivalent to <tt class="LITERAL">attrset(A_NORMAL)</tt>
+ which turns off all attributes and brings you to normal
+ mode.</p>
+ </div>
+
+ <div class="SECT2">
+ <hr>
+
+ <h3 class="SECT2"><a name="ATTRGET" id="ATTRGET">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="ATTRFUNCS" id="ATTRFUNCS">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 <tt class=
+ "LITERAL">attr_t</tt>.</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>
+ <pre class="PROGRAMLISTING">
+ chgat(-1, A_REVERSE, 0, NULL);
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
int main(int argc, char *argv[])
{ initscr(); /* Start curses mode */
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 <ncurses.h>
+}</span>
+</pre>
+ </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
+ <tt class="LITERAL">newwin()</tt>. 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 such as its 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 <tt class="LITERAL">box()</tt> 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
WINDOW *create_newwin(int height, int width, int starty, int startx);
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
+ * result of erasing the window. It will leave its four corners
* and so an ugly remnant of window.
*/
wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' ');
*/
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"> +------------+
+}</span>
+</pre>
+ </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 is 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 <tt class="LITERAL">create_newwin()</tt> function
+ creates a window with <tt class="LITERAL">newwin()</tt> and
+ displays a border around it with box. The function
+ <tt class="LITERAL">destroy_win()</tt> first erases the
+ window from screen by painting a border with ' ' character
+ and then calling <tt class="LITERAL">delwin()</tt> 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>
+ <pre class="PROGRAMLISTING">
+ wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');
+</pre>
+
+ <p>it produces some thing like</p>
+ <pre class="PROGRAMLISTING">
+ +------------+
| |
| |
| |
| |
| |
| |
- +------------+</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="OTHERSTUFF" id="OTHERSTUFF">9.4. The
-other stuff in the example</a></h3>
-<p>You can also see in the above examples, that I have used the
-variables COLS, LINES which are initialized to the screen sizes
-after initscr(). They can be useful in finding screen dimensions
-and finding the center co-ordinate of the screen as above. The
-function <var class="LITERAL">getch()</var> as usual gets the key
-from keyboard and according to the key it does the corresponding
-work. This type of switch- case is very common in any GUI based
-programs.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="OTHERBORDERFUNCS" id=
-"OTHERBORDERFUNCS">9.5. Other Border functions</a></h3>
-<p>Above program is grossly inefficient in that with each press of
-a key, a window is destroyed and another is created. So let's write
-a more efficient program which uses other border related
-functions.</p>
-<p>The following program uses <var class="LITERAL">mvhline()</var>
-and <var class="LITERAL">mvvline()</var> to achieve similar effect.
-These two functions are simple. They create a horizontal or
-vertical line of the specified length at the specified
-position.</p>
-<div class="EXAMPLE"><a name="BOTBO" id="BOTBO"></a>
-<p><b>Example 8. More border functions</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <ncurses.h>
+ +------------+
+</pre>
+ </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 <tt class=
+ "LITERAL">getch()</tt> 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 <tt class=
+ "LITERAL">mvhline()</tt> and <tt class=
+ "LITERAL">mvvline()</tt> 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
typedef struct _win_border_struct {
chtype ls, rs, ts, bs,
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 <ncurses.h>
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string);
int main(int argc, char *argv[])
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
+</span>
+</pre>
+ </div>
+
+ <p>As you can see, to start using color, you should first
+ call the function <tt class="LITERAL">start_color()</tt>.
+ 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
+ <tt class="LITERAL">has_colors()</tt> 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 <tt class="LITERAL">COLOR_BLACK</tt>
+ 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 <tt class="LITERAL">init_pair()</tt> 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 <tt class=
+ "LITERAL">COLOR_PAIR()</tt>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 <tt class=
+ "LITERAL">curses.h</tt>. You can use these as parameters
+ for various color functions.</p>
+ <pre class="PROGRAMLISTING">
+ 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);
+ COLOR_WHITE 7
+</pre>
+ </div>
+
+ <div class="SECT2">
+ <hr>
+
+ <h3 class="SECT2"><a name="CHANGECOLORDEFS" id=
+ "CHANGECOLORDEFS">10.2. Changing Color Definitions</a></h3>
+
+ <p>The function <tt class="LITERAL">init_color()</tt>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>
+ <pre class="PROGRAMLISTING">
+ 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 <stdio.h>
+ * param 2, 3, 4 : rgb content min = 0, max = 1000 */
+</pre>
+
+ <p>If your terminal cannot change the color definitions,
+ the function returns ERR. The function <tt class=
+ "LITERAL">can_change_color()</tt> 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 <tt class="LITERAL">color_content()</tt>
+ and <tt class="LITERAL">pair_content()</tt> 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 is very easy to get key input from the user. A simple way
+ of getting key presses is to use <tt class=
+ "LITERAL">getch()</tt> 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><tt class="LITERAL">getch()</tt> 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 <tt class=
+ "LITERAL">curses.h</tt>. 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>
+ <pre class="PROGRAMLISTING">
+ int ch;
+
+ ch = getch();
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ if(ch == KEY_LEFT)
+ printw("Left arrow is pressed\n");
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <stdio.h>
#include <ncurses.h>
#define WIDTH 30
}
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
+</span>
+</pre>
+ </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 <tt class=
+ "LITERAL">mousemask()</tt>.</p>
+ <pre class="PROGRAMLISTING">
+ mousemask( mmask_t newmask, /* The events you want to listen to */
+ mmask_t *oldmask) /* The old events mask */
+</pre>
+
+ <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 <tt class=
+ "LITERAL">ALL_MOUSE_EVENTS</tt> can be used to get all the
+ events.</p>
+
+ <p>The following are all the event masks:</p>
+ <pre class="PROGRAMLISTING">
+ Name Description
---------------------------------------------------------------------
BUTTON1_PRESSED mouse button 1 down
BUTTON1_RELEASED mouse button 1 up
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;
+ REPORT_MOUSE_POSITION report mouse movement
+</pre>
+ </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
+ <tt class="LITERAL">getmouse()</tt>.</p>
+
+ <p>The code approximately looks like this:</p>
+ <pre class="PROGRAMLISTING">
+ MEVENT event;
ch = getch();
if(ch == KEY_MOUSE)
if(getmouse(&event) == OK)
. /* Do some thing with the event */
.
- .</font>
-</pre></td>
-</tr>
-</table>
-<p>getmouse() returns the event into the pointer given to it. It's
-a structure which contains</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> typedef struct
+ .
+</pre>
+
+ <p>getmouse() returns the event into the pointer given to
+ it. It is a structure which contains</p>
+ <pre class="PROGRAMLISTING">
+ typedef struct
{
short id; /* ID to distinguish multiple devices */
int x, y, z; /* event coordinates */
mmask_t bstate; /* button state bits */
- } </font>
-</pre></td>
-</tr>
-</table>
-<p>The <var class="LITERAL">bstate</var> is the main variable we
-are interested in. It tells the button state of the mouse.</p>
-<p>Then with a code snippet like the following, we can find out
-what happened.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> if(event.bstate & BUTTON1_PRESSED)
- printw("Left Button Pressed");</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MOUSETOGETHER" id="MOUSETOGETHER">12.3.
-Putting it all Together</a></h3>
-<p>That's pretty much interfacing with mouse. Let's create the same
-menu and enable mouse interaction. To make things simpler, key
-handling is removed.</p>
-<div class="EXAMPLE"><a name="BMOME" id="BMOME"></a>
-<p><b>Example 11. Access the menu with mouse !!!</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <ncurses.h>
+ }
+</pre>
+
+ <p>The <tt class="LITERAL">bstate</tt> 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>
+ <pre class="PROGRAMLISTING">
+ if(event.bstate & BUTTON1_PRESSED)
+ printw("Left Button Pressed");
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
#define WIDTH 30
#define HEIGHT 10
*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);
+}</span>
+</pre>
+ </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 <tt class="LITERAL">getyx()</tt> 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>
+ <pre class="PROGRAMLISTING">
+ 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
+ */
+</pre>
+
+ <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 <tt class=
+ "LITERAL">putwin()</tt> and <tt class=
+ "LITERAL">getwin()</tt> can be used. <tt class=
+ "LITERAL">putwin()</tt> puts the present window state into
+ a file, which can be later restored by <tt class=
+ "LITERAL">getwin()</tt>.</p>
+
+ <p>The function <tt class="LITERAL">copywin()</tt> 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. Its
+ 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>
+ <pre class="PROGRAMLISTING">
+ 0 : invisible or
1 : normal or
- 2 : very visible.</font>
-</pre></td>
-</tr>
-</table>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="TEMPLEAVE" id="TEMPLEAVE">14.2.
-Temporarily Leaving Curses mode</a></h3>
-<p>Some times you may want to get back to cooked mode (normal line
-buffering mode) temporarily. In such a case you will first need to
-save the tty modes with a call to <var class=
-"LITERAL">def_prog_mode()</var> and then call <var class=
-"LITERAL">endwin()</var> to end the curses mode. This will leave
-you in the original tty mode. To get back to curses once you are
-done, call <var class="LITERAL">reset_prog_mode()</var> . This
-function returns the tty to the state stored by <var class=
-"LITERAL">def_prog_mode()</var>. Then do refresh(), and you are
-back to the curses mode. Here is an example showing the sequence of
-things to be done.</p>
-<div class="EXAMPLE"><a name="BTELE" id="BTELE"></a>
-<p><b>Example 12. Temporarily Leaving Curses Mode</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <ncurses.h>
+ 2 : very visible.
+</pre>
+ </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
+ <tt class="LITERAL">def_prog_mode()</tt> and then call
+ <tt class="LITERAL">endwin()</tt> to end the curses mode.
+ This will leave you in the original tty mode. To get back
+ to curses once you are done, call <tt class=
+ "LITERAL">reset_prog_mode()</tt> . This function returns
+ the tty to the state stored by <tt class=
+ "LITERAL">def_prog_mode()</tt>. 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
int main()
{
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 <ncurses.h>
+}</span>
+</pre>
+ </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
+ <tt class="LITERAL">box()</tt> 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <ncurses.h>
int main()
{
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 <panel.h>
+}</span>
+</pre>
+ </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><span class="emphasis"><i class="EMPHASIS">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.</i></span></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>
+ <pre class="PROGRAMLISTING">
+ #include <panel.h>
.
.
.
- compile and link: gcc <program file> -lpanel -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="PPASI" id="PPASI"></a>
-<p><b>Example 14. Panel basics</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <panel.h>
+ compile and link: gcc <program file> -lpanel -lncurses
+</pre>
+
+ <div class="EXAMPLE">
+ <a name="PPASI" id="PPASI"></a>
+
+ <p><b>Example 14. Panel basics</b></p>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <panel.h>
int main()
{ WINDOW *my_wins[3];
getch();
endwin();
}
-</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>As you can see, above program follows a simple flow as
-explained. The windows are created with newwin() and then they are
-attached to panels with new_panel(). As we attach one panel after
-another, the stack of panels gets updated. To put them on screen
-update_panels() and doupdate() are called.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELBROWSING" id="PANELBROWSING">16.3.
-Panel Window Browsing</a></h3>
-<p>A slightly complicated example is given below. This program
-creates 3 windows which can be cycled through using tab. Have a
-look at the code.</p>
-<div class="EXAMPLE"><a name="PPABR" id="PPABR"></a>
-<p><b>Example 15. Panel Window Browsing Example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <panel.h>
+</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <panel.h>
#define NLINES 10
#define NCOLS 40
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 <TAB> as
-usual. To resize or move the active panel press 'r' for resize 'm'
-for moving. Then use arrow keys to resize or move it to the desired
-way and press enter to end your resizing or moving. This example
-makes use of user data to get the required data to do the
-operations.</p>
-<div class="EXAMPLE"><a name="PPARE" id="PPARE"></a>
-<p><b>Example 16. Panel Moving and Resizing example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <panel.h>
+}</span>
+</pre>
+ </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 <tt class="LITERAL">set_panel_userptr()</tt>. It
+ can be accessed using the function <tt class=
+ "LITERAL">panel_userptr()</tt> which will return the user
+ pointer for the panel given as argument. After finding the
+ next panel in the cycle It is 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 <tt class="LITERAL">move_panel()</tt> can
+ be used to move a panel to the desired location. It does
+ not change the position of the panel in the stack. Make
+ sure that you use move_panel() instead mvwin() on the
+ window associated with the panel.</p>
+
+ <p>Resizing a panel is slightly complex. There is no
+ straight forward function just to resize the window
+ associated with a panel. A solution to resize a panel is to
+ create a new window with the desired sizes, change the
+ window associated with the panel using replace_panel().
+ Don't forget to delete the old window. The window
+ associated with a panel can be found by using the function
+ panel_window().</p>
+
+ <p>The following program shows these concepts, in
+ supposedly simple program. You can cycle through the window
+ with <TAB> as usual. To resize or move the active
+ panel press 'r' for resize 'm' for moving. Then use arrow
+ keys to resize or move it to the desired way and press
+ enter to end your resizing or moving. This example makes
+ use of user data to get the required data to do the
+ operations.</p>
+
+ <div class="EXAMPLE">
+ <a name="PPARE" id="PPARE"></a>
+
+ <p><b>Example 16. Panel Moving and Resizing
+ example</b></p>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <panel.h>
typedef struct _PANEL_DATA {
int x, y, w, h;
mvwprintw(win, y, x, "%s", string);
wattroff(win, color);
refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Concentrate on the main while loop. Once it finds out the type
-of key pressed, it takes appropriate action. If 'r' is pressed
-resizing mode is started. After this the new sizes are updated as
-the user presses the arrow keys. When the user presses
-<ENTER> present selection ends and panel is resized by using
-the concept explained. While in resizing mode the program doesn't
-show how the window is getting resized. It's left as an exercise to
-the reader to print a dotted border while it gets resized to a new
-position.</p>
-<p>When the user presses 'm' the move mode starts. This is a bit
-simpler than resizing. As the arrow keys are pressed the new
-position is updated and pressing of <ENTER> causes the panel
-to be moved by calling the function move_panel().</p>
-<p>In this program the user data which is represented as
-PANEL_DATA, plays very important role in finding the associated
-information with a panel. As written in the comments, the
-PANEL_DATA stores the panel sizes, label, label color and a pointer
-to the next panel in the cycle.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="PANELSHOWHIDE" id="PANELSHOWHIDE">16.6.
-Hiding and Showing Panels</a></h3>
-<p>A Panel can be hidden by using the function hide_panel(). This
-function merely removes it form the stack of panels, thus hiding it
-on the screen once you do update_panels() and doupdate(). It
-doesn't destroy the PANEL structure associated with the hidden
-panel. It can be shown again by using the show_panel()
-function.</p>
-<p>The following program shows the hiding of panels. Press 'a' or
-'b' or 'c' to show or hide first, second and third windows
-respectively. It uses a user data with a small variable hide, which
-keeps track of whether the window is hidden or not. For some reason
-the function <var class="LITERAL">panel_hidden()</var> which tells
-whether a panel is hidden or not is not working. A bug report was
-also presented by Michael Andres <a href=
-"http://www.geocrawler.com/archives/3/344/1999/9/0/2643549/"
-target="_top">here</a></p>
-<div class="EXAMPLE"><a name="PPAHI" id="PPAHI"></a>
-<p><b>Example 17. Panel Hiding and Showing example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <panel.h>
+}</span>
+</pre>
+ </div>
+
+ <p>Concentrate on the main while loop. Once it finds out
+ the type of key pressed, it takes appropriate action. If
+ 'r' is pressed resizing mode is started. After this the new
+ sizes are updated as the user presses the arrow keys. When
+ the user presses <ENTER> present selection ends and
+ panel is resized by using the concept explained. While in
+ resizing mode the program doesn't show how the window is
+ getting resized. It is left as an exercise to the reader to
+ print a dotted border while it gets resized to a new
+ position.</p>
+
+ <p>When the user presses 'm' the move mode starts. This is
+ a bit simpler than resizing. As the arrow keys are pressed
+ the new position is updated and pressing of <ENTER>
+ causes the panel to be moved by calling the function
+ move_panel().</p>
+
+ <p>In this program the user data which is represented as
+ PANEL_DATA, plays very important role in finding the
+ associated information with a panel. As written in the
+ comments, the PANEL_DATA stores the panel sizes, label,
+ label color and a pointer to the next panel in the
+ cycle.</p>
+ </div>
+
+ <div class="SECT2">
+ <hr>
+
+ <h3 class="SECT2"><a name="PANELSHOWHIDE" id=
+ "PANELSHOWHIDE">16.6. Hiding and Showing Panels</a></h3>
+
+ <p>A Panel can be hidden by using the function
+ hide_panel(). This function merely removes it form the
+ stack of panels, thus hiding it on the screen once you do
+ update_panels() and doupdate(). It doesn't destroy the
+ PANEL structure associated with the hidden panel. It can be
+ shown again by using the show_panel() function.</p>
+
+ <p>The following program shows the hiding of panels. Press
+ 'a' or 'b' or 'c' to show or hide first, second and third
+ windows respectively. It uses a user data with a small
+ variable hide, which keeps track of whether the window is
+ hidden or not. For some reason the function <tt class=
+ "LITERAL">panel_hidden()</tt> 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <panel.h>
typedef struct _PANEL_DATA {
int hide; /* TRUE if panel is hidden */
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 <menu.h>
+}</span>
+</pre>
+ </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 <tt class="LITERAL">panel_above()</tt> and
+ <tt class="LITERAL">panel_below()</tt> 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>
+ <pre class="PROGRAMLISTING">
+ #include <menu.h>
.
.
.
- compile and link: gcc <program file> -lmenu -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="MMESI" id="MMESI"></a>
-<p><b>Example 18. Menu Basics</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <curses.h>
+ compile and link: gcc <program file> -lmenu -lncurses
+</pre>
+
+ <div class="EXAMPLE">
+ <a name="MMESI" id="MMESI"></a>
+
+ <p><b>Example 18. Menu Basics</b></p>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
free_menu(my_menu);
endwin();
}
- </span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This program demonstrates the basic concepts involved in
-creating a menu using menus library. First we create the items
-using new_item() and then attach them to the menu with new_menu()
-function. After posting the menu and refreshing the screen, the
-main processing loop starts. It reads user input and takes
-corresponding action. The function menu_driver() is the main work
-horse of the menu system. The second parameter to this function
-tells what's to be done with the menu. According to the parameter,
-menu_driver() does the corresponding task. The value can be either
-a menu navigational request, an ascii character, or a KEY_MOUSE
-special key associated with a mouse event.</p>
-<p>The menu_driver accepts following navigational requests.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> REQ_LEFT_ITEM Move left to an item.
+ </span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+ 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_CLEAR_PATTERN Clear the menu pattern buffer.
REQ_BACK_PATTERN Delete the previous character from the pattern buffer.
REQ_NEXT_MATCH Move to the next item matching the pattern match.
- REQ_PREV_MATCH Move to the previous item matching the pattern match. </font>
-</pre></td>
-</tr>
-</table>
-<p>Don't get overwhelmed by the number of options. We will see them
-slowly one after another. The options of interest in this example
-are REQ_UP_ITEM and REQ_DOWN_ITEM. These two options when passed to
-menu_driver, menu driver updates the current item to one item up or
-down respectively.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUDRIVER" id="MENUDRIVER">17.3. Menu
-Driver: The work horse of the menu system</a></h3>
-<p>As you have seen in the above example, menu_driver plays an
-important role in updating the menu. It is very important to
-understand various options it takes and what they do. As explained
-above, the second parameter to menu_driver() can be either a
-navigational request, a printable character or a KEY_MOUSE key.
-Let's dissect the different navigational requests.</p>
-<ul>
-<li>
-<p><em>REQ_LEFT_ITEM and REQ_RIGHT_ITEM</em></p>
-<p>A Menu can be displayed with multiple columns for more than one
-item. This can be done by using the <var class=
-"LITERAL">menu_format()</var>function. When a multi columnar menu
-is displayed these requests cause the menu driver to move the
-current selection to left or right.</p>
-</li>
-<li>
-<p><em>REQ_UP_ITEM and REQ_DOWN_ITEM</em></p>
-<p>These two options you have seen in the above example. These
-options when given, makes the menu_driver to move the current
-selection to an item up or down.</p>
-</li>
-<li>
-<p><em>REQ_SCR_* options</em></p>
-<p>The four options REQ_SCR_ULINE, REQ_SCR_DLINE, REQ_SCR_DPAGE,
-REQ_SCR_UPAGE are related to scrolling. If all the items in the
-menu cannot be displayed in the menu sub window, then the menu is
-scrollable. These requests can be given to the menu_driver to do
-the scrolling either one line up, down or one page down or up
-respectively.</p>
-</li>
-<li>
-<p><em>REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM and
-REQ_PREV_ITEM</em></p>
-<p>These requests are self explanatory.</p>
-</li>
-<li>
-<p><em>REQ_TOGGLE_ITEM</em></p>
-<p>This request when given, toggles the present selection. This
-option is to be used only in a multi valued menu. So to use this
-request the option O_ONEVALUE must be off. This option can be made
-off or on with set_menu_opts().</p>
-</li>
-<li>
-<p><em>Pattern Requests</em></p>
-<p>Every menu has an associated pattern buffer, which is used to
-find the nearest match to the ascii characters entered by the user.
-Whenever ascii characters are given to menu_driver, it puts in to
-the pattern buffer. It also tries to find the nearest match to the
-pattern in the items list and moves current selection to that item.
-The request REQ_CLEAR_PATTERN clears the pattern buffer. The
-request REQ_BACK_PATTERN deletes the previous character in the
-pattern buffer. In case the pattern matches more than one item then
-the matched items can be cycled through REQ_NEXT_MATCH and
-REQ_PREV_MATCH which move the current selection to the next and
-previous matches respectively.</p>
-</li>
-<li>
-<p><em>Mouse Requests</em></p>
-<p>In case of KEY_MOUSE requests, according to the mouse position
-an action is taken accordingly. The action to be taken is explained
-in the man page as,</p>
-<table border="0" bgcolor="#E0E0E0" width="90%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"><em> If the second argument is the KEY_MOUSE special key, the
+ REQ_PREV_MATCH Move to the previous item matching the pattern match.
+</pre>
+
+ <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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_LEFT_ITEM and
+ REQ_RIGHT_ITEM</i></span></p>
+
+ <p>A Menu can be displayed with multiple columns for
+ more than one item. This can be done by using the
+ <tt class="LITERAL">menu_format()</tt>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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_UP_ITEM and REQ_DOWN_ITEM</i></span></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><span class="emphasis"><i class="EMPHASIS">REQ_SCR_*
+ options</i></span></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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM
+ and REQ_PREV_ITEM</i></span></p>
+
+ <p>These requests are self explanatory.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_TOGGLE_ITEM</i></span></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><span class="emphasis"><i class="EMPHASIS">Pattern
+ Requests</i></span></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><span class="emphasis"><i class="EMPHASIS">Mouse
+ Requests</i></span></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>
+ <pre class="PROGRAMLISTING">
+<span class="emphasis"><i class=
+"EMPHASIS"> 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­
generated, if you doubleclick a REQ_SCR_DPAGE is generated
and if you tripleclick a REQ_LAST_ITEM is generated. If
you click at an item inside the display area of the menu,
- the menu cursor is positioned to that item.</em></font>
-</pre></td>
-</tr>
-</table>
-</li>
-</ul>
-<p>Each of the above requests will be explained in the following
-lines with several examples whenever appropriate.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUWINDOWS" id="MENUWINDOWS">17.4. Menu
-Windows</a></h3>
-<p>Every menu created is associated with a window and a sub window.
-The menu window displays any title or border associated with the
-menu. The menu sub window displays the menu items currently
-available for selection. But we didn't specify any window or sub
-window in the simple example. When a window is not specified,
-stdscr is taken as the main window, and then menu system calculates
-the sub window size required for the display of items. Then items
-are displayed in the calculated sub window. So let's play with
-these windows and display a menu with a border and a title.</p>
-<div class="EXAMPLE"><a name="MMEWI" id="MMEWI"></a>
-<p><b>Example 19. Menu Windows Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <menu.h>
+ the menu cursor is positioned to that item.</i></span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
#define CTRLD 4
mvwprintw(win, y, x, "%s", string);
wattroff(win, color);
refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This example creates a menu with a title, border, a fancy line
-separating title and the items. As you can see, in order to attach
-a window to a menu the function set_menu_win() has to be used. Then
-we attach the sub window also. This displays the items in the sub
-window. You can also set the mark string which gets displayed to
-the left of the selected item with set_menu_mark().</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="SCROLLMENUS" id="SCROLLMENUS">17.5.
-Scrolling Menus</a></h3>
-<p>If the sub window given for a window is not big enough to show
-all the items, then the menu will be scrollable. When you are on
-the last item in the present list, if you send REQ_DOWN_ITEM, it
-gets translated into REQ_SCR_DLINE and the menu scrolls by one
-item. You can manually give REQ_SCR_ operations to do scrolling.
-Let's see how it can be done.</p>
-<div class="EXAMPLE"><a name="MMESC" id="MMESC"></a>
-<p><b>Example 20. Scrolling Menus example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <curses.h>
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
mvwprintw(win, y, x, "%s", string);
wattroff(win, color);
refresh();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>This program is self-explanatory. In this example the number of
-choices has been increased to ten, which is larger than our sub
-window size which can hold 6 items. This message has to be
-explicitly conveyed to the menu system with the function
-set_menu_format(). In here we specify the number of rows and
-columns we want to be displayed for a single page. We can specify
-any number of items to be shown, in the rows variables, if it is
-less than the height of the sub window. If the key pressed by the
-user is a PAGE UP or PAGE DOWN, the menu is scrolled a page due to
-the requests (REQ_SCR_DPAGE and REQ_SCR_UPAGE) given to
-menu_driver().</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MULTICOLUMN" id="MULTICOLUMN">17.6.
-Multi Columnar Menus</a></h3>
-<p>In the above example you have seen how to use the function
-set_menu_format(). I didn't mention what the cols variable (third
-parameter) does. Well, If your sub window is wide enough, you can
-opt to display more than one item per row. This can be specified in
-the cols variable. To make things simpler, the following example
-doesn't show descriptions for the items.</p>
-<div class="EXAMPLE"><a name="MMEMUCO" id="MMEMUCO"></a>
-<p><b>Example 21. Milt Columnar Menus Example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <curses.h>
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
for(i = 0; i < n_choices; ++i)
free_item(my_items[i]);
endwin();
-}</span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Watch the function call to set_menu_format(). It specifies the
-number of columns to be 3, thus displaying 3 items per row. We have
-also switched off the showing descriptions with the function
-menu_opts_off(). There are couple of functions set_menu_opts(),
-menu_opts_on() and menu_opts() which can be used to manipulate menu
-options. The following menu options can be specified.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"> O_ONEVALUE
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+ O_ONEVALUE
Only one item can be selected for this menu.
O_SHOWDESC
O_NONCYCLIC
Don't wrap around next-item and previous-item,
- requests to the other end of the menu.</font>
-</pre></td>
-</tr>
-</table>
-<p>All options are on by default. You can switch specific
-attributes on or off with menu_opts_on() and menu_opts_off()
-functions. You can also use set_menu_opts() to directly specify the
-options. The argument to this function should be a OR ed value of
-some of those above constants. The function menu_opts() can be used
-to find out a menu's present options.</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MULTIVALUEMENUS" id=
-"MULTIVALUEMENUS">17.7. Multi Valued Menus</a></h3>
-<p>You might be wondering what if you switch off the option
-O_ONEVALUE. Then the menu becomes multi-valued. That means you can
-select more than one item. This brings us to the request
-REQ_TOGGLE_ITEM. Let's see it in action.</p>
-<div class="EXAMPLE"><a name="MMETO" id="MMETO"></a>
-<p><b>Example 22. Multi Valued Menus example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <curses.h>
+ requests to the other end of the menu.
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
free_menu(my_menu);
endwin();
}
- </span></font>
-</pre></td>
-</tr>
-</table>
-</div>
-<p>Whew, A lot of new functions. Let's take them one after another.
-Firstly, the REQ_TOGGLE_ITEM. In a multi-valued menu, the user
-should be allowed to select or un select more than one item. The
-request REQ_TOGGLE_ITEM toggles the present selection. In this case
-when space is pressed REQ_TOGGLE_ITEM request is sent to
-menu_driver to achieve the result.</p>
-<p>Now when the user presses <ENTER> we show the items he
-presently selected. First we find out the items associated with the
-menu using the function menu_items(). Then we loop through the
-items to find out if the item is selected or not. The function
-item_value() returns TRUE if an item is selected. The function
-item_count() returns the number of items in the menu. The item name
-can be found with item_name(). You can also find the description
-associated with an item using item_description().</p>
-</div>
-<div class="SECT2">
-<hr>
-<h3 class="SECT2"><a name="MENUOPT" id="MENUOPT">17.8. Menu
-Options</a></h3>
-<p>Well, by this time you must be itching for some difference in
-your menu, with lots of functionality. I know. You want Colors !!!.
-You want to create nice menus similar to those text mode <a href=
-"http://www.jersey.net/~debinjoe/games/" target="_top">dos
-games</a>. The functions set_menu_fore() and set_menu_back() can be
-used to change the attribute of the selected item and unselected
-item. The names are misleading. They don't change menu's foreground
-or background which would have been useless.</p>
-<p>The function set_menu_grey() can be used to set the display
-attribute for the non-selectable items in the menu. This brings us
-to the interesting option for an item the one and only
-O_SELECTABLE. We can turn it off by the function item_opts_off()
-and after that that item is not selectable. It's like a grayed item
-in those fancy windows menus. Let's put these concepts in practice
-with this example</p>
-<div class="EXAMPLE"><a name="MMEAT" id="MMEAT"></a>
-<p><b>Example 23. Menu Options example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <menu.h>
+ </span>
+</pre>
+ </div>
+
+ <p>Whew, A lot of new functions. Let's take them one after
+ another. Firstly, the REQ_TOGGLE_ITEM. In a multi-valued
+ menu, the user should be allowed to select or un select
+ more than one item. The request REQ_TOGGLE_ITEM toggles the
+ present selection. In this case when space is pressed
+ REQ_TOGGLE_ITEM request is sent to menu_driver to achieve
+ the result.</p>
+
+ <p>Now when the user presses <ENTER> we show the
+ items he presently selected. First we find out the items
+ associated with the menu using the function menu_items().
+ Then we loop through the items to find out if the item is
+ selected or not. The function item_value() returns TRUE if
+ an item is selected. The function item_count() returns the
+ number of items in the menu. The item name can be found
+ with item_name(). You can also find the description
+ associated with an item using item_description().</p>
+ </div>
+
+ <div class="SECT2">
+ <hr>
+
+ <h3 class="SECT2"><a name="MENUOPT" id="MENUOPT">17.8. Menu
+ Options</a></h3>
+
+ <p>Well, by this time you must be itching for some
+ difference in your menu, with lots of functionality. I
+ know. You want Colors !!!. You want to create nice menus
+ similar to those text mode <a href=
+ "http://www.jersey.net/~debinjoe/games/" target="_top">dos
+ games</a>. The functions set_menu_fore() and
+ set_menu_back() can be used to change the attribute of the
+ selected item and unselected item. The names are
+ misleading. They don't change menu's foreground or
+ background which would have been useless.</p>
+
+ <p>The function set_menu_grey() can be used to set the
+ display attribute for the non-selectable items in the menu.
+ This brings us to the interesting option for an item the
+ one and only O_SELECTABLE. We can turn it off by the
+ function item_opts_off() and after that that item is not
+ selectable. It is 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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
#define CTRLD 4
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
-<ENTER>);</p>
-<div class="EXAMPLE"><a name="MMEUS" id="MMEUS"></a>
-<p><b>Example 24. Menu User Pointer Usage</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <curses.h>
+ </span>
+</pre>
+ </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 is
+ 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 is selected and
+ may be the user pressed <ENTER>);</p>
+
+ <div class="EXAMPLE">
+ <a name="MMEUS" id="MMEUS"></a>
+
+ <p><b>Example 24. Menu User Pointer Usage</b></p>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <curses.h>
#include <menu.h>
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
{ 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 <form.h>
+} </span>
+</pre>
+ </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 is 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>
+ <pre class="PROGRAMLISTING">
+ #include <form.h>
.
.
.
- compile and link: gcc <program file> -lform -lncurses</font>
-</pre></td>
-</tr>
-</table>
-<div class="EXAMPLE"><a name="FFOSI" id="FFOSI"></a>
-<p><b>Example 25. Forms Basics</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <form.h>
+ compile and link: gcc <program file> -lform -lncurses
+</pre>
+
+ <div class="EXAMPLE">
+ <a name="FFOSI" id="FFOSI"></a>
+
+ <p><b>Example 25. Forms Basics</b></p>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <form.h>
int main()
{ FIELD *field[3];
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 */
+}</span>
+</pre>
+ </div>
+
+ <p>Above example is pretty straight forward. It creates two
+ fields with <tt class="LITERAL">new_field()</tt>.
+ 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>
+ <pre class="PROGRAMLISTING">
+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 *nbuf); /* number of working buffers */
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+int move_field( FIELD *field, /* field to alter */
+ int top, int left); /* new upper-left corner */
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ int set_field_just(FIELD *field, /* field to alter */
int justmode); /* mode to set */
- int field_just(FIELD *field); /* fetch justify mode of field */</font>
-</pre></td>
-</tr>
-</table>
-<p>The justification mode valued accepted and returned by these
-functions are NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or
-JUSTIFY_CENTER.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="FIELDDISPATTRIB" id=
-"FIELDDISPATTRIB">18.3.4. Field Display Attributes</a></h4>
-<p>As you have seen, in the above example, display attribute for
-the fields can be set with set_field_fore() and setfield_back().
-These functions set foreground and background attribute of the
-fields. You can also specify a pad character which will be filled
-in the unfilled portion of the field. The pad character is set with
-a call to set_field_pad(). Default pad value is a space. The
-functions field_fore(), field_back, field_pad() can be used to
-query the present foreground, background attributes and pad
-character for the field. The following list gives the usage of
-functions.</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000"> int set_field_fore(FIELD *field, /* field to alter */
+ int field_just(FIELD *field); /* fetch justify mode of field */
+</pre>
+
+ <p>The justification mode valued accepted and returned by
+ these functions are NO_JUSTIFICATION, JUSTIFY_RIGHT,
+ JUSTIFY_LEFT, or JUSTIFY_CENTER.</p>
+ </div>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+ int set_field_fore(FIELD *field, /* field to alter */
chtype attr); /* attribute to set */
chtype field_fore(FIELD *field); /* field to query */
int pad); /* pad character to set */
chtype field_pad(FIELD *field); /* field to query */
- /* returns present pad character */ </font>
-</pre></td>
-</tr>
-</table>
-<p>Though above functions seem quite simple, using colors with
-set_field_fore() may be frustrating in the beginning. Let me first
-explain about foreground and background attributes of a field. The
-foreground attribute is associated with the character. That means a
-character in the field is printed with the attribute you have set
-with set_field_fore(). Background attribute is the attribute used
-to fill background of field, whether any character is there or not.
-So what about colors? Since colors are always defined in pairs,
-what is the right way to display colored fields? Here's an example
-clarifying color attributes.</p>
-<div class="EXAMPLE"><a name="FFOAT" id="FFOAT"></a>
-<p><b>Example 26. Form Attributes example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <form.h>
+ /* returns present pad character */
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <form.h>
int main()
{ FIELD *field[3];
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 */
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+int set_field_opts(FIELD *field, /* field to alter */
int attr); /* attribute to set */
int field_opts_on(FIELD *field, /* field to alter */
int field_opts_off(FIELD *field, /* field to alter */
int attr); /* attributes to turn off */
-int field_opts(FIELD *field); /* field to query */ </font>
-</pre></td>
-</tr>
-</table>
-<p>The function set_field_opts() can be used to directly set
-attributes of a field or you can choose to switch a few attributes
-on and off with field_opts_on() and field_opts_off() selectively.
-Anytime you can query the attributes of a field with field_opts().
-The following is the list of available options. By default, all
-options are on.</p>
-<div class="VARIABLELIST">
-<dl>
-<dt>O_VISIBLE</dt>
-<dd>
-<p>Controls whether the field is visible on the screen. Can be used
-during form processing to hide or pop up fields depending on the
-value of parent fields.</p>
-</dd>
-<dt>O_ACTIVE</dt>
-<dd>
-<p>Controls whether the field is active during forms processing
-(i.e. visited by form navigation keys). Can be used to make labels
-or derived fields with buffer values alterable by the forms
-application, not the user.</p>
-</dd>
-<dt>O_PUBLIC</dt>
-<dd>
-<p>Controls whether data is displayed during field entry. If this
-option is turned off on a field, the library will accept and edit
-data in that field, but it will not be displayed and the visible
-field cursor will not move. You can turn off the O_PUBLIC bit to
-define password fields.</p>
-</dd>
-<dt>O_EDIT</dt>
-<dd>
-<p>Controls whether the field's data can be modified. When this
-option is off, all editing requests except <var class=
-"LITERAL">REQ_PREV_CHOICE</var> and <var class=
-"LITERAL">REQ_NEXT_CHOICE</var>will fail. Such read-only fields may
-be useful for help messages.</p>
-</dd>
-<dt>O_WRAP</dt>
-<dd>
-<p>Controls word-wrapping in multi-line fields. Normally, when any
-character of a (blank-separated) word reaches the end of the
-current line, the entire word is wrapped to the next line (assuming
-there is one). When this option is off, the word will be split
-across the line break.</p>
-</dd>
-<dt>O_BLANK</dt>
-<dd>
-<p>Controls field blanking. When this option is on, entering a
-character at the first field position erases the entire field
-(except for the just-entered character).</p>
-</dd>
-<dt>O_AUTOSKIP</dt>
-<dd>
-<p>Controls automatic skip to next field when this one fills.
-Normally, when the forms user tries to type more data into a field
-than will fit, the editing location jumps to next field. When this
-option is off, the user's cursor will hang at the end of the field.
-This option is ignored in dynamic fields that have not reached
-their size limit.</p>
-</dd>
-<dt>O_NULLOK</dt>
-<dd>
-<p>Controls whether validation is applied to blank fields.
-Normally, it is not; the user can leave a field blank without
-invoking the usual validation check on exit. If this option is off
-on a field, exit from it will invoke a validation check.</p>
-</dd>
-<dt>O_PASSOK</dt>
-<dd>
-<p>Controls whether validation occurs on every exit, or only after
-the field is modified. Normally the latter is true. Setting
-O_PASSOK may be useful if your field's validation function may
-change during forms processing.</p>
-</dd>
-<dt>O_STATIC</dt>
-<dd>
-<p>Controls whether the field is fixed to its initial dimensions.
-If you turn this off, the field becomes dynamic and will stretch to
-fit entered data.</p>
-</dd>
-</dl>
-</div>
-<p>A field's options cannot be changed while the field is currently
-selected. However, options may be changed on posted fields that are
-not current.</p>
-<p>The option values are bit-masks and can be composed with
-logical-or in the obvious way. You have seen the usage of switching
-off O_AUTOSKIP option. The following example clarifies usage of
-some more options. Other options are explained where
-appropriate.</p>
-<div class="EXAMPLE"><a name="FFOOP" id="FFOOP"></a>
-<p><b>Example 27. Field Options Usage example</b></p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color="#000000"><span class=
-"INLINEMEDIAOBJECT">#include <form.h>
+int field_opts(FIELD *field); /* field to query */
+</pre>
+
+ <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 <tt class=
+ "LITERAL">REQ_PREV_CHOICE</tt> and <tt class=
+ "LITERAL">REQ_NEXT_CHOICE</tt>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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <form.h>
#define STARTX 15
#define STARTY 4
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 */
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+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,
+int field_status(FIELD *field); /* fetch status of field */
+</pre>
+
+ <p>It is 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>
+ <pre class="PROGRAMLISTING">
+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 */
+char *field_userptr(FIELD *field); /* fetch user pointer of the field */
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+ field_opts_off(field_pointer, O_STATIC);
+</pre>
+
+ <p>But it is usually not advisable to allow a field to
+ grow infinitely. You can set a maximum limit to the
+ growth of the field with</p>
+ <pre class="PROGRAMLISTING">
+int set_max_field(FIELD *field, /* Field on which to operate */
+ int max_growth); /* maximum growth allowed for the field */
+</pre>
+
+ <p>The field info for a dynamically growable field can be
+ retrieved by</p>
+ <pre class="PROGRAMLISTING">
+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
+ /* in this */
+</pre>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 <form.h>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+<span class="INLINEMEDIAOBJECT">#include <form.h>
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype 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 */
+}</span>
+</pre>
+ </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>
+ <pre class="PROGRAMLISTING">
+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 */
+ ...); /* additional arguments*/
+</pre>Once set, the validation type for a field can be queried with
+ <pre class="PROGRAMLISTING">
+FIELDTYPE *field_type(FIELD *field); /* field to query */
+</pre>
+
+ <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 is 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>
+ <pre class="PROGRAMLISTING">
+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 */
+ int width); /* minimum width of field */
+</pre>
+
+ <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 is 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>
+ <pre class="PROGRAMLISTING">
+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 */
+ int width); /* minimum width of field */
+</pre>
+
+ <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 is 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>
+ <pre class="PROGRAMLISTING">
+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 */
+ int checkunique); /* must specify uniquely? */
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+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 */
+ int vmin, int vmax); /* valid range */
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+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 */
+ int vmin, int vmax); /* valid range */
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+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
+ char *regexp); /* expression to match */
+</pre>
+
+ <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>
+ <pre class="PROGRAMLISTING">
+int form_driver(FORM *form, /* form on which to operate */
+ int request) /* form request code */
+</pre>
+
+ <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 is 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>
+ <pre class="PROGRAMLISTING">
+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 */
+</pre>
+
+ <p>The following requests allow you to move to different
+ pages</p>
+
+ <ul>
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEXT_PAGE</i></span> Move to the next
+ form page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_PREV_PAGE</i></span> Move to the
+ previous form page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_FIRST_PAGE</i></span> Move to the
+ first form page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_LAST_PAGE</i></span> 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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEXT_FIELD</i></span> Move to next
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_PREV_FIELD</i></span> Move to previous
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_FIRST_FIELD</i></span> Move to the
+ first field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_LAST_FIELD</i></span> Move to the last
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SNEXT_FIELD</i></span> Move to sorted
+ next field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SPREV_FIELD</i></span> Move to sorted
+ previous field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SFIRST_FIELD</i></span> Move to the
+ sorted first field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SLAST_FIELD</i></span> Move to the
+ sorted last field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_LEFT_FIELD</i></span> Move left to
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_RIGHT_FIELD</i></span> Move right to
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_UP_FIELD</i></span> Move up to
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_DOWN_FIELD</i></span> 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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEXT_CHAR</i></span> Move to next
+ character.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_PREV_CHAR</i></span> Move to previous
+ character.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEXT_LINE</i></span> Move to next
+ line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_PREV_LINE</i></span> Move to previous
+ line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEXT_WORD</i></span> Move to next
+ word.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_PREV_WORD</i></span> Move to previous
+ word.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_BEG_FIELD</i></span> Move to beginning
+ of field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_END_FIELD</i></span> Move to end of
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_BEG_LINE</i></span> Move to beginning
+ of line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_END_LINE</i></span> Move to end of
+ line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_LEFT_CHAR</i></span> Move left in
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_RIGHT_CHAR</i></span> Move right in
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_UP_CHAR</i></span> Move up in
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_DOWN_CHAR</i></span> 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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_FLINE</i></span> Scroll vertically
+ forward a line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_BLINE</i></span> Scroll vertically
+ backward a line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_FPAGE</i></span> Scroll vertically
+ forward a page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_BPAGE</i></span> Scroll vertically
+ backward a page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_FHPAGE</i></span> Scroll
+ vertically forward half a page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_BHPAGE</i></span> Scroll
+ vertically backward half a page.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_FCHAR</i></span> Scroll
+ horizontally forward a character.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_BCHAR</i></span> Scroll
+ horizontally backward a character.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_HFLINE</i></span> Scroll
+ horizontally one field width forward.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_HBLINE</i></span> Scroll
+ horizontally one field width backward.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_HFHALF</i></span> Scroll
+ horizontally one half field width forward.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_SCR_HBHALF</i></span> 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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_INS_MODE</i></span> Set insertion
+ mode.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_OVL_MODE</i></span> Set overlay
+ mode.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEW_LINE</i></span> New line request
+ (see below for explanation).</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_INS_CHAR</i></span> Insert space at
+ character location.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_INS_LINE</i></span> Insert blank line
+ at character location.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_DEL_CHAR</i></span> Delete character
+ at cursor.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_DEL_PREV</i></span> Delete previous
+ word at cursor.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_DEL_LINE</i></span> Delete line at
+ cursor.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_DEL_WORD</i></span> Delete word at
+ cursor.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_CLR_EOL</i></span> Clear to end of
+ line.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_CLR_EOF</i></span> Clear to end of
+ field.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_CLR_FIELD</i></span> 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><span class="emphasis"><i class=
+ "EMPHASIS">REQ_NEXT_CHOICE</i></span> Place the
+ successor value of the current value in the
+ buffer.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis"><i class=
+ "EMPHASIS">REQ_PREV_CHOICE</i></span> 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><span class="emphasis"><i class="EMPHASIS">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.</i></span></p>
+
+ <p>The kit provides some useful widgets, which can be used
+ in your programs directly. It is 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=
+ "https://invisible-island.net/cdk/" target=
+ "_top">https://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>
+ <pre class="PROGRAMLISTING">
+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
dates and phone numbers.
Viewer This is a file/information viewer. Very useful
when you need to display loads of information.
-===========================================================================</font>
-</pre></td>
-</tr>
-</table>
-<p>A few of the widgets are modified by Thomas Dickey in recent
-versions.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="CDKATTRACT" id="CDKATTRACT">19.1.2. Some
-Attractive Features</a></h4>
-<p>Apart from making our life easier with readily usable widgets,
-cdk solves one frustrating problem with printing multi colored
-strings, justified strings elegantly. Special formatting tags can
-be embedded in the strings which are passed to CDK functions. For
-Example</p>
-<p>If the string</p>
-<table border="0" bgcolor="#E0E0E0" width="100%">
-<tr>
-<td>
-<pre class="PROGRAMLISTING">
-<font color=
-"#000000">"</B/1>This line should have a yellow foreground and a blue
-background.<!1>"</font>
-</pre></td>
-</tr>
-</table>
-<p>given as a parameter to newCDKLabel(), it prints the line with
-yellow foreground and blue background. There are other tags
-available for justifying string, embedding special drawing
-characters etc.. Please refer to the man page cdk_display(3X) for
-details. The man page explains the usage with nice examples.</p>
-</div>
-<div class="SECT3">
-<hr>
-<h4 class="SECT3"><a name="CDKCONCLUSION" id=
-"CDKCONCLUSION">19.1.3. Conclusion</a></h4>
-<p>All in all, CDK is a well-written package of widgets, which if
-used properly can form a strong frame work for developing complex
-GUI.</p>
-</div>
-</div>
-<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>
projects / ncurses.git / blobdiff