mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-11-15 06:42:51 +01:00
aae38d10b4
Among the changes from before: - Add support for extended colors on widechar version - Enable ncurses extended functions - Enable version 2 of the extended mouse support - Enable SCREEN extensions Modification that differs from upstream: - _nc_delink_entries used to be exposed and was turn static, turn it back as dynamic to not break abi - Adapt our old termcap.c to modern ncurses MFC after: 3 weeks
7416 lines
268 KiB
HTML
7416 lines
268 KiB
HTML
<!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 (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" 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
|
|
</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
|
|
|----> demo -- output files go into this directory after make
|
|
| |
|
|
| |----> exe -- exe files of all example programs
|
|
|----> forms -- programs related to form library
|
|
|----> menus -- programs related to menus library
|
|
|----> panels -- programs related to panels library
|
|
|----> perl -- perl equivalents of the examples (contributed
|
|
| by Anuradha Ratnaweera)
|
|
|----> Makefile -- the top level Makefile
|
|
|----> README -- the top level README file. contains instructions
|
|
|----> COPYING -- copyright notice
|
|
</pre>
|
|
|
|
<p>The individual directories contain the following
|
|
files.</p>
|
|
<pre class="PROGRAMLISTING">
|
|
Description of files in each directory
|
|
--------------------------------------
|
|
JustForFun
|
|
|
|
|
|----> hanoi.c -- The Towers of Hanoi Solver
|
|
|----> life.c -- The Game of Life demo
|
|
|----> magic.c -- An Odd Order Magic Square builder
|
|
|----> queens.c -- The famous N-Queens Solver
|
|
|----> shuffle.c -- A fun game, if you have time to kill
|
|
|----> tt.c -- A very trivial typing tutor
|
|
|
|
basics
|
|
|
|
|
|----> acs_vars.c -- ACS_ variables example
|
|
|----> hello_world.c -- Simple "Hello World" Program
|
|
|----> init_func_example.c -- Initialization functions example
|
|
|----> key_code.c -- Shows the scan code of the key pressed
|
|
|----> mouse_menu.c -- A menu accessible by mouse
|
|
|----> other_border.c -- Shows usage of other border functions apa
|
|
| -- rt from box()
|
|
|----> printw_example.c -- A very simple printw() example
|
|
|----> scanw_example.c -- A very simple getstr() example
|
|
|----> simple_attr.c -- A program that can print a c file with
|
|
| -- comments in attribute
|
|
|----> simple_color.c -- A simple example demonstrating colors
|
|
|----> simple_key.c -- A menu accessible with keyboard UP, DOWN
|
|
| -- arrows
|
|
|----> temp_leave.c -- Demonstrates temporarily leaving curses mode
|
|
|----> win_border.c -- Shows Creation of windows and borders
|
|
|----> with_chgat.c -- chgat() usage example
|
|
|
|
forms
|
|
|
|
|
|----> form_attrib.c -- Usage of field attributes
|
|
|----> form_options.c -- Usage of field options
|
|
|----> form_simple.c -- A simple form example
|
|
|----> form_win.c -- Demo of windows associated with forms
|
|
|
|
menus
|
|
|
|
|
|----> menu_attrib.c -- Usage of menu attributes
|
|
|----> menu_item_data.c -- Usage of item_name() etc.. functions
|
|
|----> menu_multi_column.c -- Creates multi columnar menus
|
|
|----> menu_scroll.c -- Demonstrates scrolling capability of menus
|
|
|----> menu_simple.c -- A simple menu accessed by arrow keys
|
|
|----> menu_toggle.c -- Creates multi valued menus and explains
|
|
| -- REQ_TOGGLE_ITEM
|
|
|----> menu_userptr.c -- Usage of user pointer
|
|
|----> menu_win.c -- Demo of windows associated with menus
|
|
|
|
panels
|
|
|
|
|
|----> panel_browse.c -- Panel browsing through tab. Usage of user
|
|
| -- pointer
|
|
|----> panel_hide.c -- Hiding and Un hiding of panels
|
|
|----> panel_resize.c -- Moving and resizing of panels
|
|
|----> panel_simple.c -- A simple panel example
|
|
|
|
perl
|
|
|----> 01-10.pl -- Perl equivalents of first ten example programs
|
|
</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-HOWTO/ncurses_programs.tar.gz
|
|
|
|
Unzip ncurses_programs.tar.gz with
|
|
tar zxvf ncurses_programs.tar.gz
|
|
|
|
Use jade to create various formats. For example if you just want to create
|
|
the multiple html files, you would use
|
|
jade -t sgml -i html -d <path to docbook html stylesheet>
|
|
NCURSES-Programming-HOWTO.sgml
|
|
to get pdf, first create a single html file of the HOWTO with
|
|
jade -t sgml -i html -d <path to docbook html stylesheet> -V nochunks
|
|
NCURSES-Programming-HOWTO.sgml > NCURSES-ONE-BIG-FILE.html
|
|
then use htmldoc to get pdf file with
|
|
htmldoc --size universal -t pdf --firstpage p1 -f <output file name.pdf>
|
|
NCURSES-ONE-BIG-FILE.html
|
|
for ps, you would use
|
|
htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps>
|
|
NCURSES-ONE-BIG-FILE.html
|
|
</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
|
|
</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()
|
|
{
|
|
initscr(); /* Start curses mode */
|
|
printw("Hello World !!!"); /* Print Hello World */
|
|
refresh(); /* Print it on to the real screen */
|
|
getch(); /* Wait for user input */
|
|
endwin(); /* End curses mode */
|
|
|
|
return 0;
|
|
}</span>
|
|
</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;
|
|
|
|
initscr(); /* Start curses mode */
|
|
raw(); /* Line buffering disabled */
|
|
keypad(stdscr, TRUE); /* We get F1, F2 etc.. */
|
|
noecho(); /* Don't echo() while we do getch */
|
|
|
|
printw("Type any character to see it in bold\n");
|
|
ch = getch(); /* If raw() hadn't been called
|
|
* we have to press enter before it
|
|
* gets to the program */
|
|
if(ch == KEY_F(1)) /* Without keypad enabled this will */
|
|
printw("F1 Key pressed");/* not get to us either */
|
|
/* Without noecho() some ugly escape
|
|
* charachters might have been printed
|
|
* on screen */
|
|
else
|
|
{ printw("The pressed key is ");
|
|
attron(A_BOLD);
|
|
printw("%c", ch);
|
|
attroff(A_BOLD);
|
|
}
|
|
refresh(); /* Print it on to the real screen */
|
|
getch(); /* Wait for user input */
|
|
endwin(); /* End curses mode */
|
|
|
|
return 0;
|
|
}</span>
|
|
</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 */
|
|
</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'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 <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>
|
|
|
|
int main()
|
|
{
|
|
char mesg[]="Just a string"; /* message to be appeared on the screen */
|
|
int row,col; /* to store the number of rows and *
|
|
* the number of colums of the screen */
|
|
initscr(); /* start the curses mode */
|
|
getmaxyx(stdscr,row,col); /* get the number of rows and columns */
|
|
mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);
|
|
/* print the message at the center of the screen */
|
|
mvprintw(row-2,0,"This screen has %d rows and %d columns\n",row,col);
|
|
printw("Try resizing your window(if possible) and then run this program again");
|
|
refresh();
|
|
getch();
|
|
endwin();
|
|
|
|
return 0;
|
|
}</span>
|
|
</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>
|
|
|
|
int main()
|
|
{
|
|
char mesg[]="Enter a string: "; /* message to be appeared on the screen */
|
|
char str[80];
|
|
int row,col; /* to store the number of rows and *
|
|
* the number of colums of the screen */
|
|
initscr(); /* start the curses mode */
|
|
getmaxyx(stdscr,row,col); /* get the number of rows and columns */
|
|
mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);
|
|
/* print the message at the center of the screen */
|
|
getstr(str);
|
|
mvprintw(LINES - 2, 0, "You Entered: %s", str);
|
|
getch();
|
|
endwin();
|
|
|
|
return 0;
|
|
}</span>
|
|
</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>
|
|
|
|
int main(int argc, char *argv[])
|
|
{
|
|
int ch, prev, row, col;
|
|
prev = EOF;
|
|
FILE *fp;
|
|
int y, x;
|
|
|
|
if(argc != 2)
|
|
{
|
|
printf("Usage: %s <a c file name>\n", argv[0]);
|
|
exit(1);
|
|
}
|
|
fp = fopen(argv[1], "r");
|
|
if(fp == NULL)
|
|
{
|
|
perror("Cannot open input file");
|
|
exit(1);
|
|
}
|
|
initscr(); /* Start curses mode */
|
|
getmaxyx(stdscr, row, col); /* find the boundaries of the screeen */
|
|
while((ch = fgetc(fp)) != EOF) /* read the file till we reach the end */
|
|
{
|
|
getyx(stdscr, y, x); /* get the current curser position */
|
|
if(y == (row - 1)) /* are we are at the end of the screen */
|
|
{
|
|
printw("<-Press Any Key->"); /* tell the user to press a key */
|
|
getch();
|
|
clear(); /* clear the screen */
|
|
move(0, 0); /* start at the beginning of the screen */
|
|
}
|
|
if(prev == '/' && ch == '*') /* If it is / and * then only
|
|
* switch bold on */
|
|
{
|
|
attron(A_BOLD); /* cut bold on */
|
|
getyx(stdscr, y, x); /* get the current curser position */
|
|
move(y, x - 1); /* back up one space */
|
|
printw("%c%c", '/', ch); /* The actual printing is done here */
|
|
}
|
|
else
|
|
printw("%c", ch);
|
|
refresh();
|
|
if(prev == '*' && ch == '/')
|
|
attroff(A_BOLD); /* Switch it off once we got *
|
|
* and then / */
|
|
prev = ch;
|
|
}
|
|
endwin(); /* End curses mode */
|
|
fclose(fp);
|
|
return 0;
|
|
}</span>
|
|
</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_REVERSE Reverse video
|
|
A_BLINK Blinking
|
|
A_DIM Half bright
|
|
A_BOLD Extra bright or bold
|
|
A_PROTECT Protected mode
|
|
A_INVIS Invisible or blank mode
|
|
A_ALTCHARSET Alternate character set
|
|
A_CHARTEXT Bit-mask to extract a character
|
|
COLOR_PAIR(n) Color-pair number n
|
|
|
|
</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 */
|
|
start_color(); /* Start color functionality */
|
|
|
|
init_pair(1, COLOR_CYAN, COLOR_BLACK);
|
|
printw("A Big string which i didn't care to type fully ");
|
|
mvchgat(0, 0, -1, A_BLINK, 1, NULL);
|
|
/*
|
|
* First two parameters specify the position at which to start
|
|
* Third parameter number of characters to update. -1 means till
|
|
* end of line
|
|
* Forth parameter is the normal attribute you wanted to give
|
|
* to the charcter
|
|
* Fifth is the color index. It is the index given during init_pair()
|
|
* use 0 if you didn't want color
|
|
* Sixth one is always NULL
|
|
*/
|
|
refresh();
|
|
getch();
|
|
endwin(); /* End curses mode */
|
|
return 0;
|
|
}</span>
|
|
</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 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 <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);
|
|
|
|
int main(int argc, char *argv[])
|
|
{ WINDOW *my_win;
|
|
int startx, starty, width, height;
|
|
int ch;
|
|
|
|
initscr(); /* Start curses mode */
|
|
cbreak(); /* Line buffering disabled, Pass on
|
|
* everty thing to me */
|
|
keypad(stdscr, TRUE); /* I need that nifty F1 */
|
|
|
|
height = 3;
|
|
width = 10;
|
|
starty = (LINES - height) / 2; /* Calculating for a center placement */
|
|
startx = (COLS - width) / 2; /* of the window */
|
|
printw("Press F1 to exit");
|
|
refresh();
|
|
my_win = create_newwin(height, width, starty, startx);
|
|
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case KEY_LEFT:
|
|
destroy_win(my_win);
|
|
my_win = create_newwin(height, width, starty,--startx);
|
|
break;
|
|
case KEY_RIGHT:
|
|
destroy_win(my_win);
|
|
my_win = create_newwin(height, width, starty,++startx);
|
|
break;
|
|
case KEY_UP:
|
|
destroy_win(my_win);
|
|
my_win = create_newwin(height, width, --starty,startx);
|
|
break;
|
|
case KEY_DOWN:
|
|
destroy_win(my_win);
|
|
my_win = create_newwin(height, width, ++starty,startx);
|
|
break;
|
|
}
|
|
}
|
|
|
|
endwin(); /* End curses mode */
|
|
return 0;
|
|
}
|
|
|
|
WINDOW *create_newwin(int height, int width, int starty, int startx)
|
|
{ WINDOW *local_win;
|
|
|
|
local_win = newwin(height, width, starty, startx);
|
|
box(local_win, 0 , 0); /* 0, 0 gives default characters
|
|
* for the vertical and horizontal
|
|
* lines */
|
|
wrefresh(local_win); /* Show that box */
|
|
|
|
return local_win;
|
|
}
|
|
|
|
void destroy_win(WINDOW *local_win)
|
|
{
|
|
/* box(local_win, ' ', ' '); : This won't produce the desired
|
|
* result of erasing the window. It will leave it's four corners
|
|
* and so an ugly remnant of window.
|
|
*/
|
|
wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' ');
|
|
/* The parameters taken are
|
|
* 1. win: the window on which to operate
|
|
* 2. ls: character to be used for the left side of the window
|
|
* 3. rs: character to be used for the right side of the window
|
|
* 4. ts: character to be used for the top side of the window
|
|
* 5. bs: character to be used for the bottom side of the window
|
|
* 6. tl: character to be used for the top left corner of the window
|
|
* 7. tr: character to be used for the top right corner of the window
|
|
* 8. bl: character to be used for the bottom left corner of the window
|
|
* 9. br: character to be used for the bottom right corner of the window
|
|
*/
|
|
wrefresh(local_win);
|
|
delwin(local_win);
|
|
}</span>
|
|
</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'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 <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">
|
|
+------------+
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
+------------+
|
|
</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,
|
|
tl, tr, bl, br;
|
|
}WIN_BORDER;
|
|
|
|
typedef struct _WIN_struct {
|
|
|
|
int startx, starty;
|
|
int height, width;
|
|
WIN_BORDER border;
|
|
}WIN;
|
|
|
|
void init_win_params(WIN *p_win);
|
|
void print_win_params(WIN *p_win);
|
|
void create_box(WIN *win, bool flag);
|
|
|
|
int main(int argc, char *argv[])
|
|
{ WIN win;
|
|
int ch;
|
|
|
|
initscr(); /* Start curses mode */
|
|
start_color(); /* Start the color functionality */
|
|
cbreak(); /* Line buffering disabled, Pass on
|
|
* everty thing to me */
|
|
keypad(stdscr, TRUE); /* I need that nifty F1 */
|
|
noecho();
|
|
init_pair(1, COLOR_CYAN, COLOR_BLACK);
|
|
|
|
/* Initialize the window parameters */
|
|
init_win_params(&win);
|
|
print_win_params(&win);
|
|
|
|
attron(COLOR_PAIR(1));
|
|
printw("Press F1 to exit");
|
|
refresh();
|
|
attroff(COLOR_PAIR(1));
|
|
|
|
create_box(&win, TRUE);
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case KEY_LEFT:
|
|
create_box(&win, FALSE);
|
|
--win.startx;
|
|
create_box(&win, TRUE);
|
|
break;
|
|
case KEY_RIGHT:
|
|
create_box(&win, FALSE);
|
|
++win.startx;
|
|
create_box(&win, TRUE);
|
|
break;
|
|
case KEY_UP:
|
|
create_box(&win, FALSE);
|
|
--win.starty;
|
|
create_box(&win, TRUE);
|
|
break;
|
|
case KEY_DOWN:
|
|
create_box(&win, FALSE);
|
|
++win.starty;
|
|
create_box(&win, TRUE);
|
|
break;
|
|
}
|
|
}
|
|
endwin(); /* End curses mode */
|
|
return 0;
|
|
}
|
|
void init_win_params(WIN *p_win)
|
|
{
|
|
p_win->height = 3;
|
|
p_win->width = 10;
|
|
p_win->starty = (LINES - p_win->height)/2;
|
|
p_win->startx = (COLS - p_win->width)/2;
|
|
|
|
p_win->border.ls = '|';
|
|
p_win->border.rs = '|';
|
|
p_win->border.ts = '-';
|
|
p_win->border.bs = '-';
|
|
p_win->border.tl = '+';
|
|
p_win->border.tr = '+';
|
|
p_win->border.bl = '+';
|
|
p_win->border.br = '+';
|
|
|
|
}
|
|
void print_win_params(WIN *p_win)
|
|
{
|
|
#ifdef _DEBUG
|
|
mvprintw(25, 0, "%d %d %d %d", p_win->startx, p_win->starty,
|
|
p_win->width, p_win->height);
|
|
refresh();
|
|
#endif
|
|
}
|
|
void create_box(WIN *p_win, bool flag)
|
|
{ int i, j;
|
|
int x, y, w, h;
|
|
|
|
x = p_win->startx;
|
|
y = p_win->starty;
|
|
w = p_win->width;
|
|
h = p_win->height;
|
|
|
|
if(flag == TRUE)
|
|
{ mvaddch(y, x, p_win->border.tl);
|
|
mvaddch(y, x + w, p_win->border.tr);
|
|
mvaddch(y + h, x, p_win->border.bl);
|
|
mvaddch(y + h, x + w, p_win->border.br);
|
|
mvhline(y, x + 1, p_win->border.ts, w - 1);
|
|
mvhline(y + h, x + 1, p_win->border.bs, w - 1);
|
|
mvvline(y + 1, x, p_win->border.ls, h - 1);
|
|
mvvline(y + 1, x + w, p_win->border.rs, h - 1);
|
|
|
|
}
|
|
else
|
|
for(j = y; j <= y + h; ++j)
|
|
for(i = x; i <= x + w; ++i)
|
|
mvaddch(j, i, ' ');
|
|
|
|
refresh();
|
|
|
|
}</span>
|
|
</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[])
|
|
{ initscr(); /* Start curses mode */
|
|
if(has_colors() == FALSE)
|
|
{ endwin();
|
|
printf("Your terminal does not support color\n");
|
|
exit(1);
|
|
}
|
|
start_color(); /* Start color */
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
|
|
attron(COLOR_PAIR(1));
|
|
print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ...");
|
|
attroff(COLOR_PAIR(1));
|
|
getch();
|
|
endwin();
|
|
}
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
mvwprintw(win, y, x, "%s", string);
|
|
refresh();
|
|
}
|
|
</span>
|
|
</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
|
|
</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 */
|
|
</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's 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
|
|
#define HEIGHT 10
|
|
|
|
int startx = 0;
|
|
int starty = 0;
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Exit",
|
|
};
|
|
int n_choices = sizeof(choices) / sizeof(char *);
|
|
void print_menu(WINDOW *menu_win, int highlight);
|
|
|
|
int main()
|
|
{ WINDOW *menu_win;
|
|
int highlight = 1;
|
|
int choice = 0;
|
|
int c;
|
|
|
|
initscr();
|
|
clear();
|
|
noecho();
|
|
cbreak(); /* Line buffering disabled. pass on everything */
|
|
startx = (80 - WIDTH) / 2;
|
|
starty = (24 - HEIGHT) / 2;
|
|
|
|
menu_win = newwin(HEIGHT, WIDTH, starty, startx);
|
|
keypad(menu_win, TRUE);
|
|
mvprintw(0, 0, "Use arrow keys to go up and down, Press enter to select a choice");
|
|
refresh();
|
|
print_menu(menu_win, highlight);
|
|
while(1)
|
|
{ c = wgetch(menu_win);
|
|
switch(c)
|
|
{ case KEY_UP:
|
|
if(highlight == 1)
|
|
highlight = n_choices;
|
|
else
|
|
--highlight;
|
|
break;
|
|
case KEY_DOWN:
|
|
if(highlight == n_choices)
|
|
highlight = 1;
|
|
else
|
|
++highlight;
|
|
break;
|
|
case 10:
|
|
choice = highlight;
|
|
break;
|
|
default:
|
|
mvprintw(24, 0, "Charcter pressed is = %3d Hopefully it can be printed as '%c'", c, c);
|
|
refresh();
|
|
break;
|
|
}
|
|
print_menu(menu_win, highlight);
|
|
if(choice != 0) /* User did a choice come out of the infinite loop */
|
|
break;
|
|
}
|
|
mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, choices[choice - 1]);
|
|
clrtoeol();
|
|
refresh();
|
|
endwin();
|
|
return 0;
|
|
}
|
|
|
|
|
|
void print_menu(WINDOW *menu_win, int highlight)
|
|
{
|
|
int x, y, i;
|
|
|
|
x = 2;
|
|
y = 2;
|
|
box(menu_win, 0, 0);
|
|
for(i = 0; i < n_choices; ++i)
|
|
{ if(highlight == i + 1) /* High light the present choice */
|
|
{ wattron(menu_win, A_REVERSE);
|
|
mvwprintw(menu_win, y, x, "%s", choices[i]);
|
|
wattroff(menu_win, A_REVERSE);
|
|
}
|
|
else
|
|
mvwprintw(menu_win, y, x, "%s", choices[i]);
|
|
++y;
|
|
}
|
|
wrefresh(menu_win);
|
|
}
|
|
</span>
|
|
</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
|
|
BUTTON1_CLICKED mouse button 1 clicked
|
|
BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
|
|
BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
|
|
BUTTON2_PRESSED mouse button 2 down
|
|
BUTTON2_RELEASED mouse button 2 up
|
|
BUTTON2_CLICKED mouse button 2 clicked
|
|
BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
|
|
BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
|
|
BUTTON3_PRESSED mouse button 3 down
|
|
BUTTON3_RELEASED mouse button 3 up
|
|
BUTTON3_CLICKED mouse button 3 clicked
|
|
BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
|
|
BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
|
|
BUTTON4_PRESSED mouse button 4 down
|
|
BUTTON4_RELEASED mouse button 4 up
|
|
BUTTON4_CLICKED mouse button 4 clicked
|
|
BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
|
|
BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
|
|
BUTTON_SHIFT shift was down during button state change
|
|
BUTTON_CTRL control was down during button state change
|
|
BUTTON_ALT alt was down during button state change
|
|
ALL_MOUSE_EVENTS report all button state changes
|
|
REPORT_MOUSE_POSITION report mouse movement
|
|
</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 */
|
|
.
|
|
.
|
|
</pre>
|
|
|
|
<p>getmouse() returns the event into the pointer given to
|
|
it. It's 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 */
|
|
}
|
|
</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
|
|
|
|
int startx = 0;
|
|
int starty = 0;
|
|
|
|
char *choices[] = { "Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Exit",
|
|
};
|
|
|
|
int n_choices = sizeof(choices) / sizeof(char *);
|
|
|
|
void print_menu(WINDOW *menu_win, int highlight);
|
|
void report_choice(int mouse_x, int mouse_y, int *p_choice);
|
|
|
|
int main()
|
|
{ int c, choice = 0;
|
|
WINDOW *menu_win;
|
|
MEVENT event;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
clear();
|
|
noecho();
|
|
cbreak(); //Line buffering disabled. pass on everything
|
|
|
|
/* Try to put the window in the middle of screen */
|
|
startx = (80 - WIDTH) / 2;
|
|
starty = (24 - HEIGHT) / 2;
|
|
|
|
attron(A_REVERSE);
|
|
mvprintw(23, 1, "Click on Exit to quit (Works best in a virtual console)");
|
|
refresh();
|
|
attroff(A_REVERSE);
|
|
|
|
/* Print the menu for the first time */
|
|
menu_win = newwin(HEIGHT, WIDTH, starty, startx);
|
|
print_menu(menu_win, 1);
|
|
/* Get all the mouse events */
|
|
mousemask(ALL_MOUSE_EVENTS, NULL);
|
|
|
|
while(1)
|
|
{ c = wgetch(menu_win);
|
|
switch(c)
|
|
{ case KEY_MOUSE:
|
|
if(getmouse(&event) == OK)
|
|
{ /* When the user clicks left mouse button */
|
|
if(event.bstate & BUTTON1_PRESSED)
|
|
{ report_choice(event.x + 1, event.y + 1, &choice);
|
|
if(choice == -1) //Exit chosen
|
|
goto end;
|
|
mvprintw(22, 1, "Choice made is : %d String Chosen is \"%10s\"", choice, choices[choice - 1]);
|
|
refresh();
|
|
}
|
|
}
|
|
print_menu(menu_win, choice);
|
|
break;
|
|
}
|
|
}
|
|
end:
|
|
endwin();
|
|
return 0;
|
|
}
|
|
|
|
|
|
void print_menu(WINDOW *menu_win, int highlight)
|
|
{
|
|
int x, y, i;
|
|
|
|
x = 2;
|
|
y = 2;
|
|
box(menu_win, 0, 0);
|
|
for(i = 0; i < n_choices; ++i)
|
|
{ if(highlight == i + 1)
|
|
{ wattron(menu_win, A_REVERSE);
|
|
mvwprintw(menu_win, y, x, "%s", choices[i]);
|
|
wattroff(menu_win, A_REVERSE);
|
|
}
|
|
else
|
|
mvwprintw(menu_win, y, x, "%s", choices[i]);
|
|
++y;
|
|
}
|
|
wrefresh(menu_win);
|
|
}
|
|
|
|
/* Report the choice according to mouse position */
|
|
void report_choice(int mouse_x, int mouse_y, int *p_choice)
|
|
{ int i,j, choice;
|
|
|
|
i = startx + 2;
|
|
j = starty + 3;
|
|
|
|
for(choice = 0; choice < n_choices; ++choice)
|
|
if(mouse_y == j + choice && mouse_x >= i && mouse_x <= i + strlen(choices[choice]))
|
|
{ if(choice == n_choices - 1)
|
|
*p_choice = -1;
|
|
else
|
|
*p_choice = choice + 1;
|
|
break;
|
|
}
|
|
}</span>
|
|
</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
|
|
*/
|
|
</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. 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>
|
|
<pre class="PROGRAMLISTING">
|
|
0 : invisible or
|
|
1 : normal or
|
|
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()
|
|
{
|
|
initscr(); /* Start curses mode */
|
|
printw("Hello World !!!\n"); /* Print Hello World */
|
|
refresh(); /* Print it on to the real screen */
|
|
def_prog_mode(); /* Save the tty modes */
|
|
endwin(); /* End curses mode temporarily */
|
|
system("/bin/sh"); /* Do whatever you like in cooked mode */
|
|
reset_prog_mode(); /* Return to the previous tty mode*/
|
|
/* stored by def_prog_mode() */
|
|
refresh(); /* Do refresh() to restore the */
|
|
/* Screen contents */
|
|
printw("Another String\n"); /* Back to curses use the full */
|
|
refresh(); /* capabilities of curses */
|
|
endwin(); /* End curses mode */
|
|
|
|
return 0;
|
|
}</span>
|
|
</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()
|
|
{
|
|
initscr();
|
|
|
|
printw("Upper left corner "); addch(ACS_ULCORNER); printw("\n");
|
|
printw("Lower left corner "); addch(ACS_LLCORNER); printw("\n");
|
|
printw("Lower right corner "); addch(ACS_LRCORNER); printw("\n");
|
|
printw("Tee pointing right "); addch(ACS_LTEE); printw("\n");
|
|
printw("Tee pointing left "); addch(ACS_RTEE); printw("\n");
|
|
printw("Tee pointing up "); addch(ACS_BTEE); printw("\n");
|
|
printw("Tee pointing down "); addch(ACS_TTEE); printw("\n");
|
|
printw("Horizontal line "); addch(ACS_HLINE); printw("\n");
|
|
printw("Vertical line "); addch(ACS_VLINE); printw("\n");
|
|
printw("Large Plus or cross over "); addch(ACS_PLUS); printw("\n");
|
|
printw("Scan Line 1 "); addch(ACS_S1); printw("\n");
|
|
printw("Scan Line 3 "); addch(ACS_S3); printw("\n");
|
|
printw("Scan Line 7 "); addch(ACS_S7); printw("\n");
|
|
printw("Scan Line 9 "); addch(ACS_S9); printw("\n");
|
|
printw("Diamond "); addch(ACS_DIAMOND); printw("\n");
|
|
printw("Checker board (stipple) "); addch(ACS_CKBOARD); printw("\n");
|
|
printw("Degree Symbol "); addch(ACS_DEGREE); printw("\n");
|
|
printw("Plus/Minus Symbol "); addch(ACS_PLMINUS); printw("\n");
|
|
printw("Bullet "); addch(ACS_BULLET); printw("\n");
|
|
printw("Arrow Pointing Left "); addch(ACS_LARROW); printw("\n");
|
|
printw("Arrow Pointing Right "); addch(ACS_RARROW); printw("\n");
|
|
printw("Arrow Pointing Down "); addch(ACS_DARROW); printw("\n");
|
|
printw("Arrow Pointing Up "); addch(ACS_UARROW); printw("\n");
|
|
printw("Board of squares "); addch(ACS_BOARD); printw("\n");
|
|
printw("Lantern Symbol "); addch(ACS_LANTERN); printw("\n");
|
|
printw("Solid Square Block "); addch(ACS_BLOCK); printw("\n");
|
|
printw("Less/Equal sign "); addch(ACS_LEQUAL); printw("\n");
|
|
printw("Greater/Equal sign "); addch(ACS_GEQUAL); printw("\n");
|
|
printw("Pi "); addch(ACS_PI); printw("\n");
|
|
printw("Not equal "); addch(ACS_NEQUAL); printw("\n");
|
|
printw("UK pound sign "); addch(ACS_STERLING); printw("\n");
|
|
|
|
refresh();
|
|
getch();
|
|
endwin();
|
|
|
|
return 0;
|
|
}</span>
|
|
</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
|
|
</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];
|
|
PANEL *my_panels[3];
|
|
int lines = 10, cols = 40, y = 2, x = 4, i;
|
|
|
|
initscr();
|
|
cbreak();
|
|
noecho();
|
|
|
|
/* Create windows for the panels */
|
|
my_wins[0] = newwin(lines, cols, y, x);
|
|
my_wins[1] = newwin(lines, cols, y + 1, x + 5);
|
|
my_wins[2] = newwin(lines, cols, y + 2, x + 10);
|
|
|
|
/*
|
|
* Create borders around the windows so that you can see the effect
|
|
* of panels
|
|
*/
|
|
for(i = 0; i < 3; ++i)
|
|
box(my_wins[i], 0, 0);
|
|
|
|
/* Attach a panel to each window */ /* Order is bottom up */
|
|
my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
|
|
my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
|
|
my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
|
|
|
|
/* Update the stacking order. 2nd panel will be on top */
|
|
update_panels();
|
|
|
|
/* Show it on the screen */
|
|
doupdate();
|
|
|
|
getch();
|
|
endwin();
|
|
}
|
|
</span>
|
|
</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
|
|
|
|
void init_wins(WINDOW **wins, int n);
|
|
void win_show(WINDOW *win, char *label, int label_color);
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
|
|
|
|
int main()
|
|
{ WINDOW *my_wins[3];
|
|
PANEL *my_panels[3];
|
|
PANEL *top;
|
|
int ch;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize all the colors */
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_GREEN, COLOR_BLACK);
|
|
init_pair(3, COLOR_BLUE, COLOR_BLACK);
|
|
init_pair(4, COLOR_CYAN, COLOR_BLACK);
|
|
|
|
init_wins(my_wins, 3);
|
|
|
|
/* Attach a panel to each window */ /* Order is bottom up */
|
|
my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
|
|
my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
|
|
my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
|
|
|
|
/* Set up the user pointers to the next panel */
|
|
set_panel_userptr(my_panels[0], my_panels[1]);
|
|
set_panel_userptr(my_panels[1], my_panels[2]);
|
|
set_panel_userptr(my_panels[2], my_panels[0]);
|
|
|
|
/* Update the stacking order. 2nd panel will be on top */
|
|
update_panels();
|
|
|
|
/* Show it on the screen */
|
|
attron(COLOR_PAIR(4));
|
|
mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");
|
|
attroff(COLOR_PAIR(4));
|
|
doupdate();
|
|
|
|
top = my_panels[2];
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case 9:
|
|
top = (PANEL *)panel_userptr(top);
|
|
top_panel(top);
|
|
break;
|
|
}
|
|
update_panels();
|
|
doupdate();
|
|
}
|
|
endwin();
|
|
return 0;
|
|
}
|
|
|
|
/* Put all the windows */
|
|
void init_wins(WINDOW **wins, int n)
|
|
{ int x, y, i;
|
|
char label[80];
|
|
|
|
y = 2;
|
|
x = 10;
|
|
for(i = 0; i < n; ++i)
|
|
{ wins[i] = newwin(NLINES, NCOLS, y, x);
|
|
sprintf(label, "Window Number %d", i + 1);
|
|
win_show(wins[i], label, i + 1);
|
|
y += 3;
|
|
x += 7;
|
|
}
|
|
}
|
|
|
|
/* Show the window with a border and a label */
|
|
void win_show(WINDOW *win, char *label, int label_color)
|
|
{ int startx, starty, height, width;
|
|
|
|
getbegyx(win, starty, startx);
|
|
getmaxyx(win, height, width);
|
|
|
|
box(win, 0, 0);
|
|
mvwaddch(win, 2, 0, ACS_LTEE);
|
|
mvwhline(win, 2, 1, ACS_HLINE, width - 2);
|
|
mvwaddch(win, 2, width - 1, ACS_RTEE);
|
|
|
|
print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));
|
|
}
|
|
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
wattron(win, color);
|
|
mvwprintw(win, y, x, "%s", string);
|
|
wattroff(win, color);
|
|
refresh();
|
|
}</span>
|
|
</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'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 <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;
|
|
char label[80];
|
|
int label_color;
|
|
PANEL *next;
|
|
}PANEL_DATA;
|
|
|
|
#define NLINES 10
|
|
#define NCOLS 40
|
|
|
|
void init_wins(WINDOW **wins, int n);
|
|
void win_show(WINDOW *win, char *label, int label_color);
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
|
|
void set_user_ptrs(PANEL **panels, int n);
|
|
|
|
int main()
|
|
{ WINDOW *my_wins[3];
|
|
PANEL *my_panels[3];
|
|
PANEL_DATA *top;
|
|
PANEL *stack_top;
|
|
WINDOW *temp_win, *old_win;
|
|
int ch;
|
|
int newx, newy, neww, newh;
|
|
int size = FALSE, move = FALSE;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize all the colors */
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_GREEN, COLOR_BLACK);
|
|
init_pair(3, COLOR_BLUE, COLOR_BLACK);
|
|
init_pair(4, COLOR_CYAN, COLOR_BLACK);
|
|
|
|
init_wins(my_wins, 3);
|
|
|
|
/* Attach a panel to each window */ /* Order is bottom up */
|
|
my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
|
|
my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
|
|
my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
|
|
|
|
set_user_ptrs(my_panels, 3);
|
|
/* Update the stacking order. 2nd panel will be on top */
|
|
update_panels();
|
|
|
|
/* Show it on the screen */
|
|
attron(COLOR_PAIR(4));
|
|
mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing");
|
|
mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");
|
|
attroff(COLOR_PAIR(4));
|
|
doupdate();
|
|
|
|
stack_top = my_panels[2];
|
|
top = (PANEL_DATA *)panel_userptr(stack_top);
|
|
newx = top->x;
|
|
newy = top->y;
|
|
neww = top->w;
|
|
newh = top->h;
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case 9: /* Tab */
|
|
top = (PANEL_DATA *)panel_userptr(stack_top);
|
|
top_panel(top->next);
|
|
stack_top = top->next;
|
|
top = (PANEL_DATA *)panel_userptr(stack_top);
|
|
newx = top->x;
|
|
newy = top->y;
|
|
neww = top->w;
|
|
newh = top->h;
|
|
break;
|
|
case 'r': /* Re-Size*/
|
|
size = TRUE;
|
|
attron(COLOR_PAIR(4));
|
|
mvprintw(LINES - 4, 0, "Entered Resizing :Use Arrow Keys to resize and press <ENTER> to end resizing");
|
|
refresh();
|
|
attroff(COLOR_PAIR(4));
|
|
break;
|
|
case 'm': /* Move */
|
|
attron(COLOR_PAIR(4));
|
|
mvprintw(LINES - 4, 0, "Entered Moving: Use Arrow Keys to Move and press <ENTER> to end moving");
|
|
refresh();
|
|
attroff(COLOR_PAIR(4));
|
|
move = TRUE;
|
|
break;
|
|
case KEY_LEFT:
|
|
if(size == TRUE)
|
|
{ --newx;
|
|
++neww;
|
|
}
|
|
if(move == TRUE)
|
|
--newx;
|
|
break;
|
|
case KEY_RIGHT:
|
|
if(size == TRUE)
|
|
{ ++newx;
|
|
--neww;
|
|
}
|
|
if(move == TRUE)
|
|
++newx;
|
|
break;
|
|
case KEY_UP:
|
|
if(size == TRUE)
|
|
{ --newy;
|
|
++newh;
|
|
}
|
|
if(move == TRUE)
|
|
--newy;
|
|
break;
|
|
case KEY_DOWN:
|
|
if(size == TRUE)
|
|
{ ++newy;
|
|
--newh;
|
|
}
|
|
if(move == TRUE)
|
|
++newy;
|
|
break;
|
|
case 10: /* Enter */
|
|
move(LINES - 4, 0);
|
|
clrtoeol();
|
|
refresh();
|
|
if(size == TRUE)
|
|
{ old_win = panel_window(stack_top);
|
|
temp_win = newwin(newh, neww, newy, newx);
|
|
replace_panel(stack_top, temp_win);
|
|
win_show(temp_win, top->label, top->label_color);
|
|
delwin(old_win);
|
|
size = FALSE;
|
|
}
|
|
if(move == TRUE)
|
|
{ move_panel(stack_top, newy, newx);
|
|
move = FALSE;
|
|
}
|
|
break;
|
|
|
|
}
|
|
attron(COLOR_PAIR(4));
|
|
mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing");
|
|
mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)");
|
|
attroff(COLOR_PAIR(4));
|
|
refresh();
|
|
update_panels();
|
|
doupdate();
|
|
}
|
|
endwin();
|
|
return 0;
|
|
}
|
|
|
|
/* Put all the windows */
|
|
void init_wins(WINDOW **wins, int n)
|
|
{ int x, y, i;
|
|
char label[80];
|
|
|
|
y = 2;
|
|
x = 10;
|
|
for(i = 0; i < n; ++i)
|
|
{ wins[i] = newwin(NLINES, NCOLS, y, x);
|
|
sprintf(label, "Window Number %d", i + 1);
|
|
win_show(wins[i], label, i + 1);
|
|
y += 3;
|
|
x += 7;
|
|
}
|
|
}
|
|
|
|
/* Set the PANEL_DATA structures for individual panels */
|
|
void set_user_ptrs(PANEL **panels, int n)
|
|
{ PANEL_DATA *ptrs;
|
|
WINDOW *win;
|
|
int x, y, w, h, i;
|
|
char temp[80];
|
|
|
|
ptrs = (PANEL_DATA *)calloc(n, sizeof(PANEL_DATA));
|
|
|
|
for(i = 0;i < n; ++i)
|
|
{ win = panel_window(panels[i]);
|
|
getbegyx(win, y, x);
|
|
getmaxyx(win, h, w);
|
|
ptrs[i].x = x;
|
|
ptrs[i].y = y;
|
|
ptrs[i].w = w;
|
|
ptrs[i].h = h;
|
|
sprintf(temp, "Window Number %d", i + 1);
|
|
strcpy(ptrs[i].label, temp);
|
|
ptrs[i].label_color = i + 1;
|
|
if(i + 1 == n)
|
|
ptrs[i].next = panels[0];
|
|
else
|
|
ptrs[i].next = panels[i + 1];
|
|
set_panel_userptr(panels[i], &ptrs[i]);
|
|
}
|
|
}
|
|
|
|
/* Show the window with a border and a label */
|
|
void win_show(WINDOW *win, char *label, int label_color)
|
|
{ int startx, starty, height, width;
|
|
|
|
getbegyx(win, starty, startx);
|
|
getmaxyx(win, height, width);
|
|
|
|
box(win, 0, 0);
|
|
mvwaddch(win, 2, 0, ACS_LTEE);
|
|
mvwhline(win, 2, 1, ACS_HLINE, width - 2);
|
|
mvwaddch(win, 2, width - 1, ACS_RTEE);
|
|
|
|
print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));
|
|
}
|
|
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
wattron(win, color);
|
|
mvwprintw(win, y, x, "%s", string);
|
|
wattroff(win, color);
|
|
refresh();
|
|
}</span>
|
|
</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'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 <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 */
|
|
}PANEL_DATA;
|
|
|
|
#define NLINES 10
|
|
#define NCOLS 40
|
|
|
|
void init_wins(WINDOW **wins, int n);
|
|
void win_show(WINDOW *win, char *label, int label_color);
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
|
|
|
|
int main()
|
|
{ WINDOW *my_wins[3];
|
|
PANEL *my_panels[3];
|
|
PANEL_DATA panel_datas[3];
|
|
PANEL_DATA *temp;
|
|
int ch;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize all the colors */
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_GREEN, COLOR_BLACK);
|
|
init_pair(3, COLOR_BLUE, COLOR_BLACK);
|
|
init_pair(4, COLOR_CYAN, COLOR_BLACK);
|
|
|
|
init_wins(my_wins, 3);
|
|
|
|
/* Attach a panel to each window */ /* Order is bottom up */
|
|
my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */
|
|
my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */
|
|
my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */
|
|
|
|
/* Initialize panel datas saying that nothing is hidden */
|
|
panel_datas[0].hide = FALSE;
|
|
panel_datas[1].hide = FALSE;
|
|
panel_datas[2].hide = FALSE;
|
|
|
|
set_panel_userptr(my_panels[0], &panel_datas[0]);
|
|
set_panel_userptr(my_panels[1], &panel_datas[1]);
|
|
set_panel_userptr(my_panels[2], &panel_datas[2]);
|
|
|
|
/* Update the stacking order. 2nd panel will be on top */
|
|
update_panels();
|
|
|
|
/* Show it on the screen */
|
|
attron(COLOR_PAIR(4));
|
|
mvprintw(LINES - 3, 0, "Show or Hide a window with 'a'(first window) 'b'(Second Window) 'c'(Third Window)");
|
|
mvprintw(LINES - 2, 0, "F1 to Exit");
|
|
|
|
attroff(COLOR_PAIR(4));
|
|
doupdate();
|
|
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case 'a':
|
|
temp = (PANEL_DATA *)panel_userptr(my_panels[0]);
|
|
if(temp->hide == FALSE)
|
|
{ hide_panel(my_panels[0]);
|
|
temp->hide = TRUE;
|
|
}
|
|
else
|
|
{ show_panel(my_panels[0]);
|
|
temp->hide = FALSE;
|
|
}
|
|
break;
|
|
case 'b':
|
|
temp = (PANEL_DATA *)panel_userptr(my_panels[1]);
|
|
if(temp->hide == FALSE)
|
|
{ hide_panel(my_panels[1]);
|
|
temp->hide = TRUE;
|
|
}
|
|
else
|
|
{ show_panel(my_panels[1]);
|
|
temp->hide = FALSE;
|
|
}
|
|
break;
|
|
case 'c':
|
|
temp = (PANEL_DATA *)panel_userptr(my_panels[2]);
|
|
if(temp->hide == FALSE)
|
|
{ hide_panel(my_panels[2]);
|
|
temp->hide = TRUE;
|
|
}
|
|
else
|
|
{ show_panel(my_panels[2]);
|
|
temp->hide = FALSE;
|
|
}
|
|
break;
|
|
}
|
|
update_panels();
|
|
doupdate();
|
|
}
|
|
endwin();
|
|
return 0;
|
|
}
|
|
|
|
/* Put all the windows */
|
|
void init_wins(WINDOW **wins, int n)
|
|
{ int x, y, i;
|
|
char label[80];
|
|
|
|
y = 2;
|
|
x = 10;
|
|
for(i = 0; i < n; ++i)
|
|
{ wins[i] = newwin(NLINES, NCOLS, y, x);
|
|
sprintf(label, "Window Number %d", i + 1);
|
|
win_show(wins[i], label, i + 1);
|
|
y += 3;
|
|
x += 7;
|
|
}
|
|
}
|
|
|
|
/* Show the window with a border and a label */
|
|
void win_show(WINDOW *win, char *label, int label_color)
|
|
{ int startx, starty, height, width;
|
|
|
|
getbegyx(win, starty, startx);
|
|
getmaxyx(win, height, width);
|
|
|
|
box(win, 0, 0);
|
|
mvwaddch(win, 2, 0, ACS_LTEE);
|
|
mvwhline(win, 2, 1, ACS_HLINE, width - 2);
|
|
mvwaddch(win, 2, width - 1, ACS_RTEE);
|
|
|
|
print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color));
|
|
}
|
|
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
wattron(win, color);
|
|
mvwprintw(win, y, x, "%s", string);
|
|
wattroff(win, color);
|
|
refresh();
|
|
}</span>
|
|
</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
|
|
</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]))
|
|
#define CTRLD 4
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Exit",
|
|
};
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
int n_choices, i;
|
|
ITEM *cur_item;
|
|
|
|
|
|
initscr();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
|
|
|
|
for(i = 0; i < n_choices; ++i)
|
|
my_items[i] = new_item(choices[i], choices[i]);
|
|
my_items[n_choices] = (ITEM *)NULL;
|
|
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
mvprintw(LINES - 2, 0, "F1 to Exit");
|
|
post_menu(my_menu);
|
|
refresh();
|
|
|
|
while((c = getch()) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
}
|
|
}
|
|
|
|
free_item(my_items[0]);
|
|
free_item(my_items[1]);
|
|
free_menu(my_menu);
|
|
endwin();
|
|
}
|
|
</span>
|
|
</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_SCR_ULINE Scroll up a line.
|
|
REQ_SCR_DLINE Scroll down a line.
|
|
REQ_SCR_DPAGE Scroll down a page.
|
|
REQ_SCR_UPAGE Scroll up a page.
|
|
REQ_FIRST_ITEM Move to the first item.
|
|
REQ_LAST_ITEM Move to the last item.
|
|
REQ_NEXT_ITEM Move to the next item.
|
|
REQ_PREV_ITEM Move to the previous item.
|
|
REQ_TOGGLE_ITEM Select/deselect an item.
|
|
REQ_CLEAR_PATTERN Clear the menu pattern buffer.
|
|
REQ_BACK_PATTERN Delete the previous character from the pattern buffer.
|
|
REQ_NEXT_MATCH Move to the next item matching the pattern match.
|
|
REQ_PREV_MATCH Move to the previous item matching the pattern match.
|
|
</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­
|
|
tion window) are handled. If you click above the display
|
|
region of the menu, a REQ_SCR_ULINE is generated, if you
|
|
doubleclick a REQ_SCR_UPAGE is generated and if you
|
|
tripleclick a REQ_FIRST_ITEM is generated. If you click
|
|
below the display region of the menu, a REQ_SCR_DLINE is
|
|
generated, if you doubleclick a REQ_SCR_DPAGE is generated
|
|
and if you tripleclick a REQ_LAST_ITEM is generated. If
|
|
you click at an item inside the display area of the menu,
|
|
the menu cursor is positioned to that item.</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
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Exit",
|
|
(char *)NULL,
|
|
};
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
WINDOW *my_menu_win;
|
|
int n_choices, i;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
|
|
/* Create items */
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));
|
|
for(i = 0; i < n_choices; ++i)
|
|
my_items[i] = new_item(choices[i], choices[i]);
|
|
|
|
/* Crate menu */
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
|
|
/* Create the window to be associated with the menu */
|
|
my_menu_win = newwin(10, 40, 4, 4);
|
|
keypad(my_menu_win, TRUE);
|
|
|
|
/* Set main window and sub window */
|
|
set_menu_win(my_menu, my_menu_win);
|
|
set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1));
|
|
|
|
/* Set menu mark to the string " * " */
|
|
set_menu_mark(my_menu, " * ");
|
|
|
|
/* Print a border around the main window and print a title */
|
|
box(my_menu_win, 0, 0);
|
|
print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1));
|
|
mvwaddch(my_menu_win, 2, 0, ACS_LTEE);
|
|
mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38);
|
|
mvwaddch(my_menu_win, 2, 39, ACS_RTEE);
|
|
mvprintw(LINES - 2, 0, "F1 to exit");
|
|
refresh();
|
|
|
|
/* Post the menu */
|
|
post_menu(my_menu);
|
|
wrefresh(my_menu_win);
|
|
|
|
while((c = wgetch(my_menu_win)) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
}
|
|
wrefresh(my_menu_win);
|
|
}
|
|
|
|
/* Unpost and free all the memory taken up */
|
|
unpost_menu(my_menu);
|
|
free_menu(my_menu);
|
|
for(i = 0; i < n_choices; ++i)
|
|
free_item(my_items[i]);
|
|
endwin();
|
|
}
|
|
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
wattron(win, color);
|
|
mvwprintw(win, y, x, "%s", string);
|
|
wattroff(win, color);
|
|
refresh();
|
|
}</span>
|
|
</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]))
|
|
#define CTRLD 4
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Choice 5",
|
|
"Choice 6",
|
|
"Choice 7",
|
|
"Choice 8",
|
|
"Choice 9",
|
|
"Choice 10",
|
|
"Exit",
|
|
(char *)NULL,
|
|
};
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color);
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
WINDOW *my_menu_win;
|
|
int n_choices, i;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_CYAN, COLOR_BLACK);
|
|
|
|
/* Create items */
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));
|
|
for(i = 0; i < n_choices; ++i)
|
|
my_items[i] = new_item(choices[i], choices[i]);
|
|
|
|
/* Crate menu */
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
|
|
/* Create the window to be associated with the menu */
|
|
my_menu_win = newwin(10, 40, 4, 4);
|
|
keypad(my_menu_win, TRUE);
|
|
|
|
/* Set main window and sub window */
|
|
set_menu_win(my_menu, my_menu_win);
|
|
set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1));
|
|
set_menu_format(my_menu, 5, 1);
|
|
|
|
/* Set menu mark to the string " * " */
|
|
set_menu_mark(my_menu, " * ");
|
|
|
|
/* Print a border around the main window and print a title */
|
|
box(my_menu_win, 0, 0);
|
|
print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1));
|
|
mvwaddch(my_menu_win, 2, 0, ACS_LTEE);
|
|
mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38);
|
|
mvwaddch(my_menu_win, 2, 39, ACS_RTEE);
|
|
|
|
/* Post the menu */
|
|
post_menu(my_menu);
|
|
wrefresh(my_menu_win);
|
|
|
|
attron(COLOR_PAIR(2));
|
|
mvprintw(LINES - 2, 0, "Use PageUp and PageDown to scoll down or up a page of items");
|
|
mvprintw(LINES - 1, 0, "Arrow Keys to navigate (F1 to Exit)");
|
|
attroff(COLOR_PAIR(2));
|
|
refresh();
|
|
|
|
while((c = wgetch(my_menu_win)) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
case KEY_NPAGE:
|
|
menu_driver(my_menu, REQ_SCR_DPAGE);
|
|
break;
|
|
case KEY_PPAGE:
|
|
menu_driver(my_menu, REQ_SCR_UPAGE);
|
|
break;
|
|
}
|
|
wrefresh(my_menu_win);
|
|
}
|
|
|
|
/* Unpost and free all the memory taken up */
|
|
unpost_menu(my_menu);
|
|
free_menu(my_menu);
|
|
for(i = 0; i < n_choices; ++i)
|
|
free_item(my_items[i]);
|
|
endwin();
|
|
}
|
|
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
wattron(win, color);
|
|
mvwprintw(win, y, x, "%s", string);
|
|
wattroff(win, color);
|
|
refresh();
|
|
}</span>
|
|
</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]))
|
|
#define CTRLD 4
|
|
|
|
char *choices[] = {
|
|
"Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5",
|
|
"Choice 6", "Choice 7", "Choice 8", "Choice 9", "Choice 10",
|
|
"Choice 11", "Choice 12", "Choice 13", "Choice 14", "Choice 15",
|
|
"Choice 16", "Choice 17", "Choice 18", "Choice 19", "Choice 20",
|
|
"Exit",
|
|
(char *)NULL,
|
|
};
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
WINDOW *my_menu_win;
|
|
int n_choices, i;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_CYAN, COLOR_BLACK);
|
|
|
|
/* Create items */
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *));
|
|
for(i = 0; i < n_choices; ++i)
|
|
my_items[i] = new_item(choices[i], choices[i]);
|
|
|
|
/* Crate menu */
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
|
|
/* Set menu option not to show the description */
|
|
menu_opts_off(my_menu, O_SHOWDESC);
|
|
|
|
/* Create the window to be associated with the menu */
|
|
my_menu_win = newwin(10, 70, 4, 4);
|
|
keypad(my_menu_win, TRUE);
|
|
|
|
/* Set main window and sub window */
|
|
set_menu_win(my_menu, my_menu_win);
|
|
set_menu_sub(my_menu, derwin(my_menu_win, 6, 68, 3, 1));
|
|
set_menu_format(my_menu, 5, 3);
|
|
set_menu_mark(my_menu, " * ");
|
|
|
|
/* Print a border around the main window and print a title */
|
|
box(my_menu_win, 0, 0);
|
|
|
|
attron(COLOR_PAIR(2));
|
|
mvprintw(LINES - 3, 0, "Use PageUp and PageDown to scroll");
|
|
mvprintw(LINES - 2, 0, "Use Arrow Keys to navigate (F1 to Exit)");
|
|
attroff(COLOR_PAIR(2));
|
|
refresh();
|
|
|
|
/* Post the menu */
|
|
post_menu(my_menu);
|
|
wrefresh(my_menu_win);
|
|
|
|
while((c = wgetch(my_menu_win)) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
case KEY_LEFT:
|
|
menu_driver(my_menu, REQ_LEFT_ITEM);
|
|
break;
|
|
case KEY_RIGHT:
|
|
menu_driver(my_menu, REQ_RIGHT_ITEM);
|
|
break;
|
|
case KEY_NPAGE:
|
|
menu_driver(my_menu, REQ_SCR_DPAGE);
|
|
break;
|
|
case KEY_PPAGE:
|
|
menu_driver(my_menu, REQ_SCR_UPAGE);
|
|
break;
|
|
}
|
|
wrefresh(my_menu_win);
|
|
}
|
|
|
|
/* Unpost and free all the memory taken up */
|
|
unpost_menu(my_menu);
|
|
free_menu(my_menu);
|
|
for(i = 0; i < n_choices; ++i)
|
|
free_item(my_items[i]);
|
|
endwin();
|
|
}</span>
|
|
</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
|
|
Display the item descriptions when the menu is
|
|
posted.
|
|
|
|
O_ROWMAJOR
|
|
Display the menu in row-major order.
|
|
|
|
O_IGNORECASE
|
|
Ignore the case when pattern-matching.
|
|
|
|
O_SHOWMATCH
|
|
Move the cursor to within the item name while pat­
|
|
tern-matching.
|
|
|
|
O_NONCYCLIC
|
|
Don't wrap around next-item and previous-item,
|
|
requests to the other end of the menu.
|
|
</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]))
|
|
#define CTRLD 4
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Choice 5",
|
|
"Choice 6",
|
|
"Choice 7",
|
|
"Exit",
|
|
};
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
int n_choices, i;
|
|
ITEM *cur_item;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize items */
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
|
|
for(i = 0; i < n_choices; ++i)
|
|
my_items[i] = new_item(choices[i], choices[i]);
|
|
my_items[n_choices] = (ITEM *)NULL;
|
|
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
|
|
/* Make the menu multi valued */
|
|
menu_opts_off(my_menu, O_ONEVALUE);
|
|
|
|
mvprintw(LINES - 3, 0, "Use <SPACE> to select or unselect an item.");
|
|
mvprintw(LINES - 2, 0, "<ENTER> to see presently selected items(F1 to Exit)");
|
|
post_menu(my_menu);
|
|
refresh();
|
|
|
|
while((c = getch()) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
case ' ':
|
|
menu_driver(my_menu, REQ_TOGGLE_ITEM);
|
|
break;
|
|
case 10: /* Enter */
|
|
{ char temp[200];
|
|
ITEM **items;
|
|
|
|
items = menu_items(my_menu);
|
|
temp[0] = '\0';
|
|
for(i = 0; i < item_count(my_menu); ++i)
|
|
if(item_value(items[i]) == TRUE)
|
|
{ strcat(temp, item_name(items[i]));
|
|
strcat(temp, " ");
|
|
}
|
|
move(20, 0);
|
|
clrtoeol();
|
|
mvprintw(20, 0, temp);
|
|
refresh();
|
|
}
|
|
break;
|
|
}
|
|
}
|
|
|
|
free_item(my_items[0]);
|
|
free_item(my_items[1]);
|
|
free_menu(my_menu);
|
|
endwin();
|
|
}
|
|
</span>
|
|
</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'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>
|
|
<pre class="PROGRAMLISTING">
|
|
<span class="INLINEMEDIAOBJECT">#include <menu.h>
|
|
|
|
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
|
|
#define CTRLD 4
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Choice 5",
|
|
"Choice 6",
|
|
"Choice 7",
|
|
"Exit",
|
|
};
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
int n_choices, i;
|
|
ITEM *cur_item;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_GREEN, COLOR_BLACK);
|
|
init_pair(3, COLOR_MAGENTA, COLOR_BLACK);
|
|
|
|
/* Initialize items */
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
|
|
for(i = 0; i < n_choices; ++i)
|
|
my_items[i] = new_item(choices[i], choices[i]);
|
|
my_items[n_choices] = (ITEM *)NULL;
|
|
item_opts_off(my_items[3], O_SELECTABLE);
|
|
item_opts_off(my_items[6], O_SELECTABLE);
|
|
|
|
/* Create menu */
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
|
|
/* Set fore ground and back ground of the menu */
|
|
set_menu_fore(my_menu, COLOR_PAIR(1) | A_REVERSE);
|
|
set_menu_back(my_menu, COLOR_PAIR(2));
|
|
set_menu_grey(my_menu, COLOR_PAIR(3));
|
|
|
|
/* Post the menu */
|
|
mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected");
|
|
mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)");
|
|
post_menu(my_menu);
|
|
refresh();
|
|
|
|
while((c = getch()) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
case 10: /* Enter */
|
|
move(20, 0);
|
|
clrtoeol();
|
|
mvprintw(20, 0, "Item selected is : %s",
|
|
item_name(current_item(my_menu)));
|
|
pos_menu_cursor(my_menu);
|
|
break;
|
|
}
|
|
}
|
|
unpost_menu(my_menu);
|
|
for(i = 0; i < n_choices; ++i)
|
|
free_item(my_items[i]);
|
|
free_menu(my_menu);
|
|
endwin();
|
|
}
|
|
</span>
|
|
</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'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>
|
|
<pre class="PROGRAMLISTING">
|
|
<span class="INLINEMEDIAOBJECT">#include <curses.h>
|
|
#include <menu.h>
|
|
|
|
#define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0]))
|
|
#define CTRLD 4
|
|
|
|
char *choices[] = {
|
|
"Choice 1",
|
|
"Choice 2",
|
|
"Choice 3",
|
|
"Choice 4",
|
|
"Choice 5",
|
|
"Choice 6",
|
|
"Choice 7",
|
|
"Exit",
|
|
};
|
|
void func(char *name);
|
|
|
|
int main()
|
|
{ ITEM **my_items;
|
|
int c;
|
|
MENU *my_menu;
|
|
int n_choices, i;
|
|
ITEM *cur_item;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
init_pair(2, COLOR_GREEN, COLOR_BLACK);
|
|
init_pair(3, COLOR_MAGENTA, COLOR_BLACK);
|
|
|
|
/* Initialize items */
|
|
n_choices = ARRAY_SIZE(choices);
|
|
my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *));
|
|
for(i = 0; i < n_choices; ++i)
|
|
{ my_items[i] = new_item(choices[i], choices[i]);
|
|
/* Set the user pointer */
|
|
set_item_userptr(my_items[i], func);
|
|
}
|
|
my_items[n_choices] = (ITEM *)NULL;
|
|
|
|
/* Create menu */
|
|
my_menu = new_menu((ITEM **)my_items);
|
|
|
|
/* Post the menu */
|
|
mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected");
|
|
mvprintw(LINES - 2, 0, "Up and Down arrow keys to naviage (F1 to Exit)");
|
|
post_menu(my_menu);
|
|
refresh();
|
|
|
|
while((c = getch()) != KEY_F(1))
|
|
{ switch(c)
|
|
{ case KEY_DOWN:
|
|
menu_driver(my_menu, REQ_DOWN_ITEM);
|
|
break;
|
|
case KEY_UP:
|
|
menu_driver(my_menu, REQ_UP_ITEM);
|
|
break;
|
|
case 10: /* Enter */
|
|
{ ITEM *cur;
|
|
void (*p)(char *);
|
|
|
|
cur = current_item(my_menu);
|
|
p = item_userptr(cur);
|
|
p((char *)item_name(cur));
|
|
pos_menu_cursor(my_menu);
|
|
break;
|
|
}
|
|
break;
|
|
}
|
|
}
|
|
unpost_menu(my_menu);
|
|
for(i = 0; i < n_choices; ++i)
|
|
free_item(my_items[i]);
|
|
free_menu(my_menu);
|
|
endwin();
|
|
}
|
|
|
|
void func(char *name)
|
|
{ move(20, 0);
|
|
clrtoeol();
|
|
mvprintw(20, 0, "Item selected is : %s", name);
|
|
} </span>
|
|
</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'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>
|
|
<pre class="PROGRAMLISTING">
|
|
#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];
|
|
FORM *my_form;
|
|
int ch;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize the fields */
|
|
field[0] = new_field(1, 10, 4, 18, 0, 0);
|
|
field[1] = new_field(1, 10, 6, 18, 0, 0);
|
|
field[2] = NULL;
|
|
|
|
/* Set field options */
|
|
set_field_back(field[0], A_UNDERLINE); /* Print a line for the option */
|
|
field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */
|
|
/* Field is filled up */
|
|
set_field_back(field[1], A_UNDERLINE);
|
|
field_opts_off(field[1], O_AUTOSKIP);
|
|
|
|
/* Create the form and post it */
|
|
my_form = new_form(field);
|
|
post_form(my_form);
|
|
refresh();
|
|
|
|
mvprintw(4, 10, "Value 1:");
|
|
mvprintw(6, 10, "Value 2:");
|
|
refresh();
|
|
|
|
/* Loop through to get user requests */
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case KEY_DOWN:
|
|
/* Go to next field */
|
|
form_driver(my_form, REQ_NEXT_FIELD);
|
|
/* Go to the end of the present buffer */
|
|
/* Leaves nicely at the last character */
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
case KEY_UP:
|
|
/* Go to previous field */
|
|
form_driver(my_form, REQ_PREV_FIELD);
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
default:
|
|
/* If this is a normal character, it gets */
|
|
/* Printed */
|
|
form_driver(my_form, ch);
|
|
break;
|
|
}
|
|
}
|
|
|
|
/* Un post form and free the memory */
|
|
unpost_form(my_form);
|
|
free_form(my_form);
|
|
free_field(field[0]);
|
|
free_field(field[1]);
|
|
|
|
endwin();
|
|
return 0;
|
|
}</span>
|
|
</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 */
|
|
</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 */
|
|
</pre>
|
|
|
|
<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>
|
|
<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 */
|
|
/* returns foreground attribute */
|
|
|
|
int set_field_back(FIELD *field, /* field to alter */
|
|
chtype attr); /* attribute to set */
|
|
|
|
chtype field_back(FIELD *field); /* field to query */
|
|
/* returns background attribute */
|
|
|
|
int set_field_pad(FIELD *field, /* field to alter */
|
|
int pad); /* pad character to set */
|
|
|
|
chtype field_pad(FIELD *field); /* field to query */
|
|
/* returns present pad character */
|
|
</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];
|
|
FORM *my_form;
|
|
int ch;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize few color pairs */
|
|
init_pair(1, COLOR_WHITE, COLOR_BLUE);
|
|
init_pair(2, COLOR_WHITE, COLOR_BLUE);
|
|
|
|
/* Initialize the fields */
|
|
field[0] = new_field(1, 10, 4, 18, 0, 0);
|
|
field[1] = new_field(1, 10, 6, 18, 0, 0);
|
|
field[2] = NULL;
|
|
|
|
/* Set field options */
|
|
set_field_fore(field[0], COLOR_PAIR(1));/* Put the field with blue background */
|
|
set_field_back(field[0], COLOR_PAIR(2));/* and white foreground (characters */
|
|
/* are printed in white */
|
|
field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */
|
|
/* Field is filled up */
|
|
set_field_back(field[1], A_UNDERLINE);
|
|
field_opts_off(field[1], O_AUTOSKIP);
|
|
|
|
/* Create the form and post it */
|
|
my_form = new_form(field);
|
|
post_form(my_form);
|
|
refresh();
|
|
|
|
set_current_field(my_form, field[0]); /* Set focus to the colored field */
|
|
mvprintw(4, 10, "Value 1:");
|
|
mvprintw(6, 10, "Value 2:");
|
|
mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields");
|
|
refresh();
|
|
|
|
/* Loop through to get user requests */
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case KEY_DOWN:
|
|
/* Go to next field */
|
|
form_driver(my_form, REQ_NEXT_FIELD);
|
|
/* Go to the end of the present buffer */
|
|
/* Leaves nicely at the last character */
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
case KEY_UP:
|
|
/* Go to previous field */
|
|
form_driver(my_form, REQ_PREV_FIELD);
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
default:
|
|
/* If this is a normal character, it gets */
|
|
/* Printed */
|
|
form_driver(my_form, ch);
|
|
break;
|
|
}
|
|
}
|
|
|
|
/* Un post form and free the memory */
|
|
unpost_form(my_form);
|
|
free_form(my_form);
|
|
free_field(field[0]);
|
|
free_field(field[1]);
|
|
|
|
endwin();
|
|
return 0;
|
|
}</span>
|
|
</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 attr); /* attributes to turn on */
|
|
|
|
int field_opts_off(FIELD *field, /* field to alter */
|
|
int attr); /* attributes to turn off */
|
|
|
|
int field_opts(FIELD *field); /* field to query */
|
|
</pre>
|
|
|
|
<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
|
|
#define WIDTH 25
|
|
|
|
#define N_FIELDS 3
|
|
|
|
int main()
|
|
{ FIELD *field[N_FIELDS];
|
|
FORM *my_form;
|
|
int ch, i;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize the fields */
|
|
for(i = 0; i < N_FIELDS - 1; ++i)
|
|
field[i] = new_field(1, WIDTH, STARTY + i * 2, STARTX, 0, 0);
|
|
field[N_FIELDS - 1] = NULL;
|
|
|
|
/* Set field options */
|
|
set_field_back(field[1], A_UNDERLINE); /* Print a line for the option */
|
|
|
|
field_opts_off(field[0], O_ACTIVE); /* This field is a static label */
|
|
field_opts_off(field[1], O_PUBLIC); /* This filed is like a password field*/
|
|
field_opts_off(field[1], O_AUTOSKIP); /* To avoid entering the same field */
|
|
/* after last character is entered */
|
|
|
|
/* Create the form and post it */
|
|
my_form = new_form(field);
|
|
post_form(my_form);
|
|
refresh();
|
|
|
|
set_field_just(field[0], JUSTIFY_CENTER); /* Center Justification */
|
|
set_field_buffer(field[0], 0, "This is a static Field");
|
|
/* Initialize the field */
|
|
mvprintw(STARTY, STARTX - 10, "Field 1:");
|
|
mvprintw(STARTY + 2, STARTX - 10, "Field 2:");
|
|
refresh();
|
|
|
|
/* Loop through to get user requests */
|
|
while((ch = getch()) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case KEY_DOWN:
|
|
/* Go to next field */
|
|
form_driver(my_form, REQ_NEXT_FIELD);
|
|
/* Go to the end of the present buffer */
|
|
/* Leaves nicely at the last character */
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
case KEY_UP:
|
|
/* Go to previous field */
|
|
form_driver(my_form, REQ_PREV_FIELD);
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
default:
|
|
/* If this is a normal character, it gets */
|
|
/* Printed */
|
|
form_driver(my_form, ch);
|
|
break;
|
|
}
|
|
}
|
|
|
|
/* Un post form and free the memory */
|
|
unpost_form(my_form);
|
|
free_form(my_form);
|
|
free_field(field[0]);
|
|
free_field(field[1]);
|
|
|
|
endwin();
|
|
return 0;
|
|
}</span>
|
|
</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 */
|
|
</pre>
|
|
|
|
<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>
|
|
<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 */
|
|
</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'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>
|
|
<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 */
|
|
</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>
|
|
<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);
|
|
|
|
int main()
|
|
{
|
|
FIELD *field[3];
|
|
FORM *my_form;
|
|
WINDOW *my_form_win;
|
|
int ch, rows, cols;
|
|
|
|
/* Initialize curses */
|
|
initscr();
|
|
start_color();
|
|
cbreak();
|
|
noecho();
|
|
keypad(stdscr, TRUE);
|
|
|
|
/* Initialize few color pairs */
|
|
init_pair(1, COLOR_RED, COLOR_BLACK);
|
|
|
|
/* Initialize the fields */
|
|
field[0] = new_field(1, 10, 6, 1, 0, 0);
|
|
field[1] = new_field(1, 10, 8, 1, 0, 0);
|
|
field[2] = NULL;
|
|
|
|
/* Set field options */
|
|
set_field_back(field[0], A_UNDERLINE);
|
|
field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */
|
|
/* Field is filled up */
|
|
set_field_back(field[1], A_UNDERLINE);
|
|
field_opts_off(field[1], O_AUTOSKIP);
|
|
|
|
/* Create the form and post it */
|
|
my_form = new_form(field);
|
|
|
|
/* Calculate the area required for the form */
|
|
scale_form(my_form, &rows, &cols);
|
|
|
|
/* Create the window to be associated with the form */
|
|
my_form_win = newwin(rows + 4, cols + 4, 4, 4);
|
|
keypad(my_form_win, TRUE);
|
|
|
|
/* Set main window and sub window */
|
|
set_form_win(my_form, my_form_win);
|
|
set_form_sub(my_form, derwin(my_form_win, rows, cols, 2, 2));
|
|
|
|
/* Print a border around the main window and print a title */
|
|
box(my_form_win, 0, 0);
|
|
print_in_middle(my_form_win, 1, 0, cols + 4, "My Form", COLOR_PAIR(1));
|
|
|
|
post_form(my_form);
|
|
wrefresh(my_form_win);
|
|
|
|
mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields");
|
|
refresh();
|
|
|
|
/* Loop through to get user requests */
|
|
while((ch = wgetch(my_form_win)) != KEY_F(1))
|
|
{ switch(ch)
|
|
{ case KEY_DOWN:
|
|
/* Go to next field */
|
|
form_driver(my_form, REQ_NEXT_FIELD);
|
|
/* Go to the end of the present buffer */
|
|
/* Leaves nicely at the last character */
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
case KEY_UP:
|
|
/* Go to previous field */
|
|
form_driver(my_form, REQ_PREV_FIELD);
|
|
form_driver(my_form, REQ_END_LINE);
|
|
break;
|
|
default:
|
|
/* If this is a normal character, it gets */
|
|
/* Printed */
|
|
form_driver(my_form, ch);
|
|
break;
|
|
}
|
|
}
|
|
|
|
/* Un post form and free the memory */
|
|
unpost_form(my_form);
|
|
free_form(my_form);
|
|
free_field(field[0]);
|
|
free_field(field[1]);
|
|
|
|
endwin();
|
|
return 0;
|
|
}
|
|
|
|
void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color)
|
|
{ int length, x, y;
|
|
float temp;
|
|
|
|
if(win == NULL)
|
|
win = stdscr;
|
|
getyx(win, y, x);
|
|
if(startx != 0)
|
|
x = startx;
|
|
if(starty != 0)
|
|
y = starty;
|
|
if(width == 0)
|
|
width = 80;
|
|
|
|
length = strlen(string);
|
|
temp = (width - length)/ 2;
|
|
x = startx + (int)temp;
|
|
wattron(win, color);
|
|
mvwprintw(win, y, x, "%s", string);
|
|
wattroff(win, color);
|
|
refresh();
|
|
}</span>
|
|
</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*/
|
|
</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'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>
|
|
<pre class="PROGRAMLISTING">
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ALPHA, /* type to associate */
|
|
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'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>
|
|
<pre class="PROGRAMLISTING">
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ALNUM, /* type to associate */
|
|
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'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>
|
|
<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? */
|
|
</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 */
|
|
</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 */
|
|
</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 */
|
|
</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'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>
|
|
<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'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=
|
|
"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
|
|
few characters of the desired word.
|
|
Buttonbox This creates a multiple button widget.
|
|
Calendar Creates a little simple calendar widget.
|
|
Dialog Prompts the user with a message, and the user
|
|
can pick an answer from the buttons provided.
|
|
Entry Allows the user to enter various types of information.
|
|
File Selector A file selector built from Cdk base widgets. This
|
|
example shows how to create more complicated widgets
|
|
using the Cdk widget library.
|
|
Graph Draws a graph.
|
|
Histogram Draws a histogram.
|
|
Item List Creates a pop up field which allows the user to select
|
|
one of several choices in a small field. Very useful
|
|
for things like days of the week or month names.
|
|
Label Displays messages in a pop up box, or the label can be
|
|
considered part of the screen.
|
|
Marquee Displays a message in a scrolling marquee.
|
|
Matrix Creates a complex matrix with lots of options.
|
|
Menu Creates a pull-down menu interface.
|
|
Multiple Line Entry A multiple line entry field. Very useful
|
|
for long fields. (like a description
|
|
field)
|
|
Radio List Creates a radio button list.
|
|
Scale Creates a numeric scale. Used for allowing a user to
|
|
pick a numeric value and restrict them to a range of
|
|
values.
|
|
Scrolling List Creates a scrolling list/menu list.
|
|
Scrolling Window Creates a scrolling log file viewer. Can add
|
|
information into the window while its running.
|
|
A good widget for displaying the progress of
|
|
something. (akin to a console window)
|
|
Selection List Creates a multiple option selection list.
|
|
Slider Akin to the scale widget, this widget provides a
|
|
visual slide bar to represent the numeric value.
|
|
Template Creates a entry field with character sensitive
|
|
positions. Used for pre-formatted fields like
|
|
dates and phone numbers.
|
|
Viewer This is a file/information viewer. Very useful
|
|
when you need to display loads of information.
|
|
===========================================================================
|
|
</pre>
|
|
|
|
<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>
|
|
<pre class="PROGRAMLISTING">
|
|
"</B/1>This line should have a yellow foreground and a blue
|
|
background.<!1>"
|
|
</pre>
|
|
|
|
<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><span class="emphasis"><i class="EMPHASIS">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</i></span></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="https://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
|
|
<tt class="LITERAL">perl</tt> directory.</p>
|
|
|
|
<p>For more information see man pages Curses(3) ,
|
|
Curses::Form(3) and Curses::Widgets(3). These pages are
|
|
installed only when the above modules are acquired and
|
|
installed.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT1">
|
|
<hr>
|
|
|
|
<h2 class="SECT1"><a name="JUSTFORFUN" id="JUSTFORFUN">20.
|
|
Just For Fun !!!</a></h2>
|
|
|
|
<p>This section contains few programs written by me just for
|
|
fun. They don't signify a better programming practice or the
|
|
best way of using ncurses. They are provided here so as to
|
|
allow beginners to get ideas and add more programs to this
|
|
section. If you have written a couple of nice, simple
|
|
programs in curses and want them to included here, contact
|
|
<a href="mailto:ppadala@gmail.com" target="_top">me</a>.</p>
|
|
|
|
<div class="SECT2">
|
|
<hr>
|
|
|
|
<h3 class="SECT2"><a name="GAMEOFLIFE" id=
|
|
"GAMEOFLIFE">20.1. The Game of Life</a></h3>
|
|
|
|
<p>Game of life is a wonder of math. In <a href=
|
|
"http://www.math.com/students/wonders/life/life.html"
|
|
target="_top">Paul Callahan</a>'s words</p>
|
|
<pre class="PROGRAMLISTING">
|
|
<span class="emphasis"><i class=
|
|
"EMPHASIS">The Game of Life (or simply Life) is not a game in the conventional sense. There
|
|
are no players, and no winning or losing. Once the "pieces" are placed in the
|
|
starting position, the rules determine everything that happens later.
|
|
Nevertheless, Life is full of surprises! In most cases, it is impossible to look
|
|
at a starting position (or pattern) and see what will happen in the future. The
|
|
only way to find out is to follow the rules of the game.</i></span>
|
|
</pre>
|
|
|
|
<p>This program starts with a simple inverted U pattern and
|
|
shows how wonderful life works. There is a lot of room for
|
|
improvement in the program. You can let the user enter
|
|
pattern of his choice or even take input from a file. You
|
|
can also change rules and play with a lot of variations.
|
|
Search on <a href="http://www.google.com" target=
|
|
"_top">google</a> for interesting information on game of
|
|
life.</p>
|
|
|
|
<p><span class="emphasis"><i class="EMPHASIS">File Path:
|
|
JustForFun/life.c</i></span></p>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<hr>
|
|
|
|
<h3 class="SECT2"><a name="MAGIC" id="MAGIC">20.2. Magic
|
|
Square</a></h3>
|
|
|
|
<p>Magic Square, another wonder of math, is very simple to
|
|
understand but very difficult to make. In a magic square
|
|
sum of the numbers in each row, each column is equal. Even
|
|
diagnol sum can be equal. There are many variations which
|
|
have special properties.</p>
|
|
|
|
<p>This program creates a simple magic square of odd
|
|
order.</p>
|
|
|
|
<p><span class="emphasis"><i class="EMPHASIS">File Path:
|
|
JustForFun/magic.c</i></span></p>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<hr>
|
|
|
|
<h3 class="SECT2"><a name="HANOI" id="HANOI">20.3. Towers
|
|
of Hanoi</a></h3>
|
|
|
|
<p>The famous towers of hanoi solver. The aim of the game
|
|
is to move the disks on the first peg to last peg, using
|
|
middle peg as a temporary stay. The catch is not to place a
|
|
larger disk over a small disk at any time.</p>
|
|
|
|
<p><span class="emphasis"><i class="EMPHASIS">File Path:
|
|
JustForFun/hanoi.c</i></span></p>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<hr>
|
|
|
|
<h3 class="SECT2"><a name="QUEENS" id="QUEENS">20.4. Queens
|
|
Puzzle</a></h3>
|
|
|
|
<p>The objective of the famous N-Queen puzzle is to put N
|
|
queens on a N X N chess board without attacking each
|
|
other.</p>
|
|
|
|
<p>This program solves it with a simple backtracking
|
|
technique.</p>
|
|
|
|
<p><span class="emphasis"><i class="EMPHASIS">File Path:
|
|
JustForFun/queens.c</i></span></p>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<hr>
|
|
|
|
<h3 class="SECT2"><a name="SHUFFLE" id="SHUFFLE">20.5.
|
|
Shuffle</a></h3>
|
|
|
|
<p>A fun game, if you have time to kill.</p>
|
|
|
|
<p><span class="emphasis"><i class="EMPHASIS">File Path:
|
|
JustForFun/shuffle.c</i></span></p>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<hr>
|
|
|
|
<h3 class="SECT2"><a name="TT" id="TT">20.6. Typing
|
|
Tutor</a></h3>
|
|
|
|
<p>A simple typing tutor, I created more out of need than
|
|
for ease of use. If you know how to put your fingers
|
|
correctly on the keyboard, but lack practice, this can be
|
|
helpful.</p>
|
|
|
|
<p><span class="emphasis"><i class="EMPHASIS">File Path:
|
|
JustForFun/tt.c</i></span></p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT1">
|
|
<hr>
|
|
|
|
<h2 class="SECT1"><a name="REF" id="REF">21.
|
|
References</a></h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>NCURSES man pages</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>NCURSES FAQ at <a href=
|
|
"https://invisible-island.net/ncurses/ncurses.faq.html"
|
|
target=
|
|
"_top">https://invisible-island.net/ncurses/ncurses.faq.html</a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Writing programs with NCURSES by Eric Raymond and Zeyd
|
|
M. Ben-Halim at <a href=
|
|
"https://invisible-island.net/ncurses/ncurses-intro.html"
|
|
target=
|
|
"_top">https://invisible-island.net/ncurses/ncurses-intro.html</a>
|
|
- somewhat obsolete. I was inspired by this document and
|
|
the structure of this HOWTO follows from the original
|
|
document</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|