ncurses 6.1 - patch 20180519
[ncurses.git] / doc / html / NCURSES-Programming-HOWTO.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3
4 <html>
5 <head>
6   <meta name="generator" content=
7   "HTML Tidy for Linux (vers 25 March 2009), see www.w3.org">
8
9   <title>NCURSES Programming HOWTO</title>
10   <meta name="GENERATOR" content=
11   "Modular DocBook HTML Stylesheet Version 1.79">
12 </head>
13
14 <body class="ARTICLE" bgcolor="#FFFFFF" text="#000000" link=
15 "#0000FF" vlink="#840084" alink="#0000FF">
16   <div class="ARTICLE">
17     <div class="TITLEPAGE">
18       <h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES
19       Programming HOWTO</a></h1>
20
21       <h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep
22       Padala</a></h3>
23
24       <div class="AFFILIATION">
25         <div class="ADDRESS">
26           <p class="ADDRESS"><code class="EMAIL">&lt;<a href=
27           "mailto:ppadala@gmail.com">ppadala@gmail.com</a>&gt;</code></p>
28         </div>
29       </div>
30
31       <p class="PUBDATE">v1.9, 2005-06-20<br></p>
32
33       <div class="REVHISTORY">
34         <table width="100%" border="0">
35           <tr>
36             <th align="left" valign="top" colspan="3"><b>Revision
37             History</b></th>
38           </tr>
39
40           <tr>
41             <td align="left">Revision 1.9</td>
42
43             <td align="left">2005-06-20</td>
44
45             <td align="left">Revised by: ppadala</td>
46           </tr>
47
48           <tr>
49             <td align="left" colspan="3">The license has been
50             changed to the MIT-style license used by NCURSES. Note
51             that the programs are also re-licensed under this.</td>
52           </tr>
53
54           <tr>
55             <td align="left">Revision 1.8</td>
56
57             <td align="left">2005-06-17</td>
58
59             <td align="left">Revised by: ppadala</td>
60           </tr>
61
62           <tr>
63             <td align="left" colspan="3">Lots of updates. Added
64             references and perl examples. Changes to examples. Many
65             grammatical and stylistic changes to the content.
66             Changes to NCURSES history.</td>
67           </tr>
68
69           <tr>
70             <td align="left">Revision 1.7.1</td>
71
72             <td align="left">2002-06-25</td>
73
74             <td align="left">Revised by: ppadala</td>
75           </tr>
76
77           <tr>
78             <td align="left" colspan="3">Added a README file for
79             building and instructions for building from
80             source.</td>
81           </tr>
82
83           <tr>
84             <td align="left">Revision 1.7</td>
85
86             <td align="left">2002-06-25</td>
87
88             <td align="left">Revised by: ppadala</td>
89           </tr>
90
91           <tr>
92             <td align="left" colspan="3">Added "Other formats"
93             section and made a lot of fancy changes to the
94             programs. Inlining of programs is gone.</td>
95           </tr>
96
97           <tr>
98             <td align="left">Revision 1.6.1</td>
99
100             <td align="left">2002-02-24</td>
101
102             <td align="left">Revised by: ppadala</td>
103           </tr>
104
105           <tr>
106             <td align="left" colspan="3">Removed the old Changelog
107             section, cleaned the makefiles</td>
108           </tr>
109
110           <tr>
111             <td align="left">Revision 1.6</td>
112
113             <td align="left">2002-02-16</td>
114
115             <td align="left">Revised by: ppadala</td>
116           </tr>
117
118           <tr>
119             <td align="left" colspan="3">Corrected a lot of
120             spelling mistakes, added ACS variables section</td>
121           </tr>
122
123           <tr>
124             <td align="left">Revision 1.5</td>
125
126             <td align="left">2002-01-05</td>
127
128             <td align="left">Revised by: ppadala</td>
129           </tr>
130
131           <tr>
132             <td align="left" colspan="3">Changed structure to
133             present proper TOC</td>
134           </tr>
135
136           <tr>
137             <td align="left">Revision 1.3.1</td>
138
139             <td align="left">2001-07-26</td>
140
141             <td align="left">Revised by: ppadala</td>
142           </tr>
143
144           <tr>
145             <td align="left" colspan="3">Corrected maintainers
146             paragraph, Corrected stable release number</td>
147           </tr>
148
149           <tr>
150             <td align="left">Revision 1.3</td>
151
152             <td align="left">2001-07-24</td>
153
154             <td align="left">Revised by: ppadala</td>
155           </tr>
156
157           <tr>
158             <td align="left" colspan="3">Added copyright notices to
159             main document (LDP license) and programs (GPL),
160             Corrected printw_example.</td>
161           </tr>
162
163           <tr>
164             <td align="left">Revision 1.2</td>
165
166             <td align="left">2001-06-05</td>
167
168             <td align="left">Revised by: ppadala</td>
169           </tr>
170
171           <tr>
172             <td align="left" colspan="3">Incorporated ravi's
173             changes. Mainly to introduction, menu, form, justforfun
174             sections</td>
175           </tr>
176
177           <tr>
178             <td align="left">Revision 1.1</td>
179
180             <td align="left">2001-05-22</td>
181
182             <td align="left">Revised by: ppadala</td>
183           </tr>
184
185           <tr>
186             <td align="left" colspan="3">Added "a word about
187             window" section, Added scanw_example.</td>
188           </tr>
189         </table>
190       </div>
191
192       <div>
193         <div class="ABSTRACT">
194           <a name="AEN67" id="AEN67"></a>
195
196           <p><span class="emphasis"><i class="EMPHASIS">This
197           document is intended to be an "All in One" guide for
198           programming with ncurses and its sister libraries. We
199           graduate from a simple "Hello World" program to more
200           complex form manipulation. No prior experience in ncurses
201           is assumed. Send comments to <a href=
202           "mailto:ppadala@gmail.com" target="_top">this
203           address</a></i></span></p>
204         </div>
205       </div>
206       <hr>
207     </div>
208
209     <div class="TOC">
210       <dl>
211         <dt><b>Table of Contents</b></dt>
212
213         <dt>1. <a href="#INTRO">Introduction</a></dt>
214
215         <dd>
216           <dl>
217             <dt>1.1. <a href="#WHATIS">What is NCURSES?</a></dt>
218
219             <dt>1.2. <a href="#WHATCANWEDO">What we can do with
220             NCURSES</a></dt>
221
222             <dt>1.3. <a href="#WHERETOGETIT">Where to get
223             it</a></dt>
224
225             <dt>1.4. <a href="#PURPOSE">Purpose/Scope of the
226             document</a></dt>
227
228             <dt>1.5. <a href="#ABOUTPROGRAMS">About the
229             Programs</a></dt>
230
231             <dt>1.6. <a href="#OTHERFORMATS">Other Formats of the
232             document</a></dt>
233
234             <dd>
235               <dl>
236                 <dt>1.6.1. <a href="#LISTFORMATS">Readily available
237                 formats from tldp.org</a></dt>
238
239                 <dt>1.6.2. <a href="#BUILDSOURCE">Building from
240                 source</a></dt>
241               </dl>
242             </dd>
243
244             <dt>1.7. <a href="#CREDITS">Credits</a></dt>
245
246             <dt>1.8. <a href="#WISHLIST">Wish List</a></dt>
247
248             <dt>1.9. <a href="#COPYRIGHT">Copyright</a></dt>
249           </dl>
250         </dd>
251
252         <dt>2. <a href="#HELLOWORLD">Hello World !!!</a></dt>
253
254         <dd>
255           <dl>
256             <dt>2.1. <a href="#COMPILECURSES">Compiling With the
257             NCURSES Library</a></dt>
258
259             <dt>2.2. <a href="#DISSECTION">Dissection</a></dt>
260
261             <dd>
262               <dl>
263                 <dt>2.2.1. <a href="#ABOUT-INITSCR">About
264                 initscr()</a></dt>
265
266                 <dt>2.2.2. <a href="#MYST-REFRESH">The mysterious
267                 refresh()</a></dt>
268
269                 <dt>2.2.3. <a href="#ABOUT-ENDWIN">About
270                 endwin()</a></dt>
271               </dl>
272             </dd>
273           </dl>
274         </dd>
275
276         <dt>3. <a href="#GORY">The Gory Details</a></dt>
277
278         <dt>4. <a href="#INIT">Initialization</a></dt>
279
280         <dd>
281           <dl>
282             <dt>4.1. <a href="#ABOUTINIT">Initialization
283             functions</a></dt>
284
285             <dt>4.2. <a href="#RAWCBREAK">raw() and
286             cbreak()</a></dt>
287
288             <dt>4.3. <a href="#ECHONOECHO">echo() and
289             noecho()</a></dt>
290
291             <dt>4.4. <a href="#KEYPAD">keypad()</a></dt>
292
293             <dt>4.5. <a href="#HALFDELAY">halfdelay()</a></dt>
294
295             <dt>4.6. <a href="#MISCINIT">Miscellaneous
296             Initialization functions</a></dt>
297
298             <dt>4.7. <a href="#INITEX">An Example</a></dt>
299           </dl>
300         </dd>
301
302         <dt>5. <a href="#AWORDWINDOWS">A Word about
303         Windows</a></dt>
304
305         <dt>6. <a href="#PRINTW">Output functions</a></dt>
306
307         <dd>
308           <dl>
309             <dt>6.1. <a href="#ADDCHCLASS">addch() class of
310             functions</a></dt>
311
312             <dt>6.2. <a href="#AEN298">mvaddch(), waddch() and
313             mvwaddch()</a></dt>
314
315             <dt>6.3. <a href="#PRINTWCLASS">printw() class of
316             functions</a></dt>
317
318             <dd>
319               <dl>
320                 <dt>6.3.1. <a href="#PRINTWMVPRINTW">printw() and
321                 mvprintw</a></dt>
322
323                 <dt>6.3.2. <a href="#WPRINTWMVWPRINTW">wprintw()
324                 and mvwprintw</a></dt>
325
326                 <dt>6.3.3. <a href="#VWPRINTW">vwprintw()</a></dt>
327
328                 <dt>6.3.4. <a href="#SIMPLEPRINTWEX">A Simple
329                 printw example</a></dt>
330               </dl>
331             </dd>
332
333             <dt>6.4. <a href="#ADDSTRCLASS">addstr() class of
334             functions</a></dt>
335
336             <dt>6.5. <a href="#ACAUTION">A word of caution</a></dt>
337           </dl>
338         </dd>
339
340         <dt>7. <a href="#SCANW">Input functions</a></dt>
341
342         <dd>
343           <dl>
344             <dt>7.1. <a href="#GETCHCLASS">getch() class of
345             functions</a></dt>
346
347             <dt>7.2. <a href="#SCANWCLASS">scanw() class of
348             functions</a></dt>
349
350             <dd>
351               <dl>
352                 <dt>7.2.1. <a href="#SCANWMVSCANW">scanw() and
353                 mvscanw</a></dt>
354
355                 <dt>7.2.2. <a href="#WSCANWMVWSCANW">wscanw() and
356                 mvwscanw()</a></dt>
357
358                 <dt>7.2.3. <a href="#VWSCANW">vwscanw()</a></dt>
359               </dl>
360             </dd>
361
362             <dt>7.3. <a href="#GETSTRCLASS">getstr() class of
363             functions</a></dt>
364
365             <dt>7.4. <a href="#GETSTREX">Some examples</a></dt>
366           </dl>
367         </dd>
368
369         <dt>8. <a href="#ATTRIB">Attributes</a></dt>
370
371         <dd>
372           <dl>
373             <dt>8.1. <a href="#ATTRIBDETAILS">The details</a></dt>
374
375             <dt>8.2. <a href="#ATTRONVSATTRSET">attron() vs
376             attrset()</a></dt>
377
378             <dt>8.3. <a href="#ATTRGET">attr_get()</a></dt>
379
380             <dt>8.4. <a href="#ATTRFUNCS">attr_ functions</a></dt>
381
382             <dt>8.5. <a href="#WATTRFUNCS">wattr functions</a></dt>
383
384             <dt>8.6. <a href="#CHGAT">chgat() functions</a></dt>
385           </dl>
386         </dd>
387
388         <dt>9. <a href="#WINDOWS">Windows</a></dt>
389
390         <dd>
391           <dl>
392             <dt>9.1. <a href="#WINDOWBASICS">The basics</a></dt>
393
394             <dt>9.2. <a href="#LETBEWINDOW">Let there be a Window
395             !!!</a></dt>
396
397             <dt>9.3. <a href="#BORDEREXEXPL">Explanation</a></dt>
398
399             <dt>9.4. <a href="#OTHERSTUFF">The other stuff in the
400             example</a></dt>
401
402             <dt>9.5. <a href="#OTHERBORDERFUNCS">Other Border
403             functions</a></dt>
404           </dl>
405         </dd>
406
407         <dt>10. <a href="#COLOR">Colors</a></dt>
408
409         <dd>
410           <dl>
411             <dt>10.1. <a href="#COLORBASICS">The basics</a></dt>
412
413             <dt>10.2. <a href="#CHANGECOLORDEFS">Changing Color
414             Definitions</a></dt>
415
416             <dt>10.3. <a href="#COLORCONTENT">Color
417             Content</a></dt>
418           </dl>
419         </dd>
420
421         <dt>11. <a href="#KEYS">Interfacing with the key
422         board</a></dt>
423
424         <dd>
425           <dl>
426             <dt>11.1. <a href="#KEYSBASICS">The Basics</a></dt>
427
428             <dt>11.2. <a href="#SIMPLEKEYEX">A Simple Key Usage
429             example</a></dt>
430           </dl>
431         </dd>
432
433         <dt>12. <a href="#MOUSE">Interfacing with the
434         mouse</a></dt>
435
436         <dd>
437           <dl>
438             <dt>12.1. <a href="#MOUSEBASICS">The Basics</a></dt>
439
440             <dt>12.2. <a href="#GETTINGEVENTS">Getting the
441             events</a></dt>
442
443             <dt>12.3. <a href="#MOUSETOGETHER">Putting it all
444             Together</a></dt>
445
446             <dt>12.4. <a href="#MISCMOUSEFUNCS">Miscellaneous
447             Functions</a></dt>
448           </dl>
449         </dd>
450
451         <dt>13. <a href="#SCREEN">Screen Manipulation</a></dt>
452
453         <dd>
454           <dl>
455             <dt>13.1. <a href="#GETYX">getyx() functions</a></dt>
456
457             <dt>13.2. <a href="#SCREENDUMP">Screen Dumping</a></dt>
458
459             <dt>13.3. <a href="#WINDOWDUMP">Window Dumping</a></dt>
460           </dl>
461         </dd>
462
463         <dt>14. <a href="#MISC">Miscellaneous features</a></dt>
464
465         <dd>
466           <dl>
467             <dt>14.1. <a href="#CURSSET">curs_set()</a></dt>
468
469             <dt>14.2. <a href="#TEMPLEAVE">Temporarily Leaving
470             Curses mode</a></dt>
471
472             <dt>14.3. <a href="#ACSVARS">ACS_ variables</a></dt>
473           </dl>
474         </dd>
475
476         <dt>15. <a href="#OTHERLIB">Other libraries</a></dt>
477
478         <dt>16. <a href="#PANELS">Panel Library</a></dt>
479
480         <dd>
481           <dl>
482             <dt>16.1. <a href="#PANELBASICS">The Basics</a></dt>
483
484             <dt>16.2. <a href="#COMPILEPANELS">Compiling With the
485             Panels Library</a></dt>
486
487             <dt>16.3. <a href="#PANELBROWSING">Panel Window
488             Browsing</a></dt>
489
490             <dt>16.4. <a href="#USERPTRUSING">Using User
491             Pointers</a></dt>
492
493             <dt>16.5. <a href="#PANELMOVERESIZE">Moving and
494             Resizing Panels</a></dt>
495
496             <dt>16.6. <a href="#PANELSHOWHIDE">Hiding and Showing
497             Panels</a></dt>
498
499             <dt>16.7. <a href="#PANELABOVE">panel_above() and
500             panel_below() Functions</a></dt>
501           </dl>
502         </dd>
503
504         <dt>17. <a href="#MENUS">Menus Library</a></dt>
505
506         <dd>
507           <dl>
508             <dt>17.1. <a href="#MENUBASICS">The Basics</a></dt>
509
510             <dt>17.2. <a href="#COMPILEMENUS">Compiling With the
511             Menu Library</a></dt>
512
513             <dt>17.3. <a href="#MENUDRIVER">Menu Driver: The work
514             horse of the menu system</a></dt>
515
516             <dt>17.4. <a href="#MENUWINDOWS">Menu Windows</a></dt>
517
518             <dt>17.5. <a href="#SCROLLMENUS">Scrolling
519             Menus</a></dt>
520
521             <dt>17.6. <a href="#MULTICOLUMN">Multi Columnar
522             Menus</a></dt>
523
524             <dt>17.7. <a href="#MULTIVALUEMENUS">Multi Valued
525             Menus</a></dt>
526
527             <dt>17.8. <a href="#MENUOPT">Menu Options</a></dt>
528
529             <dt>17.9. <a href="#MENUUSERPTR">The useful User
530             Pointer</a></dt>
531           </dl>
532         </dd>
533
534         <dt>18. <a href="#FORMS">Forms Library</a></dt>
535
536         <dd>
537           <dl>
538             <dt>18.1. <a href="#FORMBASICS">The Basics</a></dt>
539
540             <dt>18.2. <a href="#COMPILEFORMS">Compiling With the
541             Forms Library</a></dt>
542
543             <dt>18.3. <a href="#PLAYFIELDS">Playing with
544             Fields</a></dt>
545
546             <dd>
547               <dl>
548                 <dt>18.3.1. <a href="#FETCHINFO">Fetching Size and
549                 Location of Field</a></dt>
550
551                 <dt>18.3.2. <a href="#MOVEFIELD">Moving the
552                 field</a></dt>
553
554                 <dt>18.3.3. <a href="#JUSTIFYFIELD">Field
555                 Justification</a></dt>
556
557                 <dt>18.3.4. <a href="#FIELDDISPATTRIB">Field
558                 Display Attributes</a></dt>
559
560                 <dt>18.3.5. <a href="#FIELDOPTIONBITS">Field Option
561                 Bits</a></dt>
562
563                 <dt>18.3.6. <a href="#FIELDSTATUS">Field
564                 Status</a></dt>
565
566                 <dt>18.3.7. <a href="#FIELDUSERPTR">Field User
567                 Pointer</a></dt>
568
569                 <dt>18.3.8. <a href=
570                 "#VARIABLESIZEFIELDS">Variable-Sized
571                 Fields</a></dt>
572               </dl>
573             </dd>
574
575             <dt>18.4. <a href="#FORMWINDOWS">Form Windows</a></dt>
576
577             <dt>18.5. <a href="#FILEDVALIDATE">Field
578             Validation</a></dt>
579
580             <dt>18.6. <a href="#FORMDRIVER">Form Driver: The work
581             horse of the forms system</a></dt>
582
583             <dd>
584               <dl>
585                 <dt>18.6.1. <a href="#PAGENAVREQ">Page Navigation
586                 Requests</a></dt>
587
588                 <dt>18.6.2. <a href="#INTERFIELDNAVREQ">Inter-Field
589                 Navigation Requests</a></dt>
590
591                 <dt>18.6.3. <a href="#INTRAFIELDNAVREQ">Intra-Field
592                 Navigation Requests</a></dt>
593
594                 <dt>18.6.4. <a href="#SCROLLREQ">Scrolling
595                 Requests</a></dt>
596
597                 <dt>18.6.5. <a href="#EDITREQ">Editing
598                 Requests</a></dt>
599
600                 <dt>18.6.6. <a href="#ORDERREQ">Order
601                 Requests</a></dt>
602
603                 <dt>18.6.7. <a href="#APPLICCOMMANDS">Application
604                 Commands</a></dt>
605               </dl>
606             </dd>
607           </dl>
608         </dd>
609
610         <dt>19. <a href="#TOOLS">Tools and Widget
611         Libraries</a></dt>
612
613         <dd>
614           <dl>
615             <dt>19.1. <a href="#CDK">CDK (Curses Development
616             Kit)</a></dt>
617
618             <dd>
619               <dl>
620                 <dt>19.1.1. <a href="#WIDGETLIST">Widget
621                 List</a></dt>
622
623                 <dt>19.1.2. <a href="#CDKATTRACT">Some Attractive
624                 Features</a></dt>
625
626                 <dt>19.1.3. <a href=
627                 "#CDKCONCLUSION">Conclusion</a></dt>
628               </dl>
629             </dd>
630
631             <dt>19.2. <a href="#DIALOG">The dialog</a></dt>
632
633             <dt>19.3. <a href="#PERLCURSES">Perl Curses Modules
634             CURSES::FORM and CURSES::WIDGETS</a></dt>
635           </dl>
636         </dd>
637
638         <dt>20. <a href="#JUSTFORFUN">Just For Fun !!!</a></dt>
639
640         <dd>
641           <dl>
642             <dt>20.1. <a href="#GAMEOFLIFE">The Game of
643             Life</a></dt>
644
645             <dt>20.2. <a href="#MAGIC">Magic Square</a></dt>
646
647             <dt>20.3. <a href="#HANOI">Towers of Hanoi</a></dt>
648
649             <dt>20.4. <a href="#QUEENS">Queens Puzzle</a></dt>
650
651             <dt>20.5. <a href="#SHUFFLE">Shuffle</a></dt>
652
653             <dt>20.6. <a href="#TT">Typing Tutor</a></dt>
654           </dl>
655         </dd>
656
657         <dt>21. <a href="#REF">References</a></dt>
658       </dl>
659     </div>
660
661     <div class="SECT1">
662       <h2 class="SECT1"><a name="INTRO" id="INTRO">1.
663       Introduction</a></h2>
664
665       <p>In the olden days of teletype terminals, terminals were
666       away from computers and were connected to them through serial
667       cables. The terminals could be configured by sending a series
668       of bytes. All the capabilities (such as moving the cursor to
669       a new location, erasing part of the screen, scrolling the
670       screen, changing modes etc.) of terminals could be accessed
671       through these series of bytes. These control seeuqnces are
672       usually called escape sequences, because they start with an
673       escape(0x1B) character. Even today, with proper emulation, we
674       can send escape sequences to the emulator and achieve the
675       same effect on a terminal window.</p>
676
677       <p>Suppose you wanted to print a line in color. Try typing
678       this on your console.</p>
679       <pre class="PROGRAMLISTING">
680 echo "^[[0;31;40mIn Color"
681 </pre>
682
683       <p>The first character is an escape character, which looks
684       like two characters ^ and [. To be able to print it, you have
685       to press CTRL+V and then the ESC key. All the others are
686       normal printable characters. You should be able to see the
687       string "In Color" in red. It stays that way and to revert
688       back to the original mode type this.</p>
689       <pre class="PROGRAMLISTING">
690 echo "^[[0;37;40m"
691 </pre>
692
693       <p>Now, what do these magic characters mean? Difficult to
694       comprehend? They might even be different for different
695       terminals. So the designers of UNIX invented a mechanism
696       named <tt class="LITERAL">termcap</tt>. It is a file that
697       lists all the capabilities of a particular terminal, along
698       with the escape sequences needed to achieve a particular
699       effect. In the later years, this was replaced by <tt class=
700       "LITERAL">terminfo</tt>. Without delving too much into
701       details, this mechanism allows application programs to query
702       the terminfo database and obtain the control characters to be
703       sent to a terminal or terminal emulator.</p>
704
705       <div class="SECT2">
706         <hr>
707
708         <h3 class="SECT2"><a name="WHATIS" id="WHATIS">1.1. What is
709         NCURSES?</a></h3>
710
711         <p>You might be wondering, what the import of all this
712         technical gibberish is. In the above scenario, every
713         application program is supposed to query the terminfo and
714         perform the necessary stuff (sending control characters
715         etc.). It soon became difficult to manage this complexity
716         and this gave birth to 'CURSES'. Curses is a pun on the
717         name "cursor optimization". The Curses library forms a
718         wrapper over working with raw terminal codes, and provides
719         highly flexible and efficient API (Application Programming
720         Interface). It provides functions to move the cursor,
721         create windows, produce colors, play with mouse etc. The
722         application programs need not worry about the underlying
723         terminal capabilities.</p>
724
725         <p>So what is NCURSES? NCURSES is a clone of the original
726         System V Release 4.0 (SVr4) curses. It is a freely
727         distributable library, fully compatible with older version
728         of curses. In short, it is a library of functions that
729         manages an application's display on character-cell
730         terminals. In the remainder of the document, the terms
731         curses and ncurses are used interchangeably.</p>
732
733         <p>A detailed history of NCURSES can be found in the NEWS
734         file from the source distribution. The current package is
735         maintained by <a href="mailto:dickey@his.com" target=
736         "_top">Thomas Dickey</a>. You can contact the maintainers
737         at <a href="mailto:bug-ncurses@gnu.org" target=
738         "_top">bug-ncurses@gnu.org</a>.</p>
739       </div>
740
741       <div class="SECT2">
742         <hr>
743
744         <h3 class="SECT2"><a name="WHATCANWEDO" id=
745         "WHATCANWEDO">1.2. What we can do with NCURSES</a></h3>
746
747         <p>NCURSES not only creates a wrapper over terminal
748         capabilities, but also gives a robust framework to create
749         nice looking UI (User Interface)s in text mode. It provides
750         functions to create windows etc. Its sister libraries
751         panel, menu and form provide an extension to the basic
752         curses library. These libraries usually come along with
753         curses. One can create applications that contain multiple
754         windows, menus, panels and forms. Windows can be managed
755         independently, can provide 'scrollability' and even can be
756         hidden.</p>
757
758         <p>Menus provide the user with an easy command selection
759         option. Forms allow the creation of easy-to-use data entry
760         and display windows. Panels extend the capabilities of
761         ncurses to deal with overlapping and stacked windows.</p>
762
763         <p>These are just some of the basic things we can do with
764         ncurses. As we move along, We will see all the capabilities
765         of these libraries.</p>
766       </div>
767
768       <div class="SECT2">
769         <hr>
770
771         <h3 class="SECT2"><a name="WHERETOGETIT" id=
772         "WHERETOGETIT">1.3. Where to get it</a></h3>
773
774         <p>All right, now that you know what you can do with
775         ncurses, you must be rearing to get started. NCURSES is
776         usually shipped with your installation. In case you don't
777         have the library or want to compile it on your own, read
778         on.</p>
779
780         <p><span class="emphasis"><i class="EMPHASIS">Compiling the
781         package</i></span></p>
782
783         <p>NCURSES can be obtained from <a href=
784         "ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz" target=
785         "_top">ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz</a>
786         or any of the ftp sites mentioned in <a href=
787         "http://www.gnu.org/order/ftp.html" target=
788         "_top">http://www.gnu.org/order/ftp.html</a>.</p>
789
790         <p>Read the README and INSTALL files for details on to how
791         to install it. It usually involves the following
792         operations.</p>
793         <pre class="PROGRAMLISTING">
794     tar zxvf ncurses&lt;version&gt;.tar.gz  # unzip and untar the archive
795     cd ncurses&lt;version&gt;               # cd to the directory
796     ./configure                             # configure the build according to your 
797                                             # environment
798     make                                    # make it
799     su root                                 # become root
800     make install                            # install it
801 </pre>
802
803         <p><span class="emphasis"><i class="EMPHASIS">Using the
804         RPM</i></span></p>
805
806         <p>NCURSES RPM can be found and downloaded from <a href=
807         "http://rpmfind.net" target="_top">http://rpmfind.net</a> .
808         The RPM can be installed with the following command after
809         becoming root.</p>
810         <pre class="PROGRAMLISTING">
811     rpm -i &lt;downloaded rpm&gt;
812 </pre>
813       </div>
814
815       <div class="SECT2">
816         <hr>
817
818         <h3 class="SECT2"><a name="PURPOSE" id="PURPOSE">1.4.
819         Purpose/Scope of the document</a></h3>
820
821         <p>This document is intended to be a "All in One" guide for
822         programming with ncurses and its sister libraries. We
823         graduate from a simple "Hello World" program to more
824         complex form manipulation. No prior experience in ncurses
825         is assumed. The writing is informal, but a lot of detail is
826         provided for each of the examples.</p>
827       </div>
828
829       <div class="SECT2">
830         <hr>
831
832         <h3 class="SECT2"><a name="ABOUTPROGRAMS" id=
833         "ABOUTPROGRAMS">1.5. About the Programs</a></h3>
834
835         <p>All the programs in the document are available in zipped
836         form <a href=
837         "http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz"
838         target="_top">here</a>. Unzip and untar it. The directory
839         structure looks like this.</p>
840         <pre class="PROGRAMLISTING">
841 ncurses
842    |
843    |----&gt; JustForFun     -- just for fun programs
844    |----&gt; basics         -- basic programs
845    |----&gt; demo           -- output files go into this directory after make
846    |          |
847    |          |----&gt; exe -- exe files of all example programs
848    |----&gt; forms          -- programs related to form library
849    |----&gt; menus          -- programs related to menus library
850    |----&gt; panels         -- programs related to panels library
851    |----&gt; perl           -- perl equivalents of the examples (contributed
852    |                            by Anuradha Ratnaweera)
853    |----&gt; Makefile       -- the top level Makefile
854    |----&gt; README         -- the top level README file. contains instructions
855    |----&gt; COPYING        -- copyright notice
856 </pre>
857
858         <p>The individual directories contain the following
859         files.</p>
860         <pre class="PROGRAMLISTING">
861 Description of files in each directory
862 --------------------------------------
863 JustForFun
864     |
865     |----&gt; hanoi.c   -- The Towers of Hanoi Solver
866     |----&gt; life.c    -- The Game of Life demo
867     |----&gt; magic.c   -- An Odd Order Magic Square builder 
868     |----&gt; queens.c  -- The famous N-Queens Solver
869     |----&gt; shuffle.c -- A fun game, if you have time to kill
870     |----&gt; tt.c      -- A very trivial typing tutor
871
872   basics
873     |
874     |----&gt; acs_vars.c            -- ACS_ variables example
875     |----&gt; hello_world.c         -- Simple "Hello World" Program
876     |----&gt; init_func_example.c   -- Initialization functions example
877     |----&gt; key_code.c            -- Shows the scan code of the key pressed
878     |----&gt; mouse_menu.c          -- A menu accessible by mouse
879     |----&gt; other_border.c        -- Shows usage of other border functions apa
880     |                               -- rt from box()
881     |----&gt; printw_example.c      -- A very simple printw() example
882     |----&gt; scanw_example.c       -- A very simple getstr() example
883     |----&gt; simple_attr.c         -- A program that can print a c file with 
884     |                               -- comments in attribute
885     |----&gt; simple_color.c        -- A simple example demonstrating colors
886     |----&gt; simple_key.c          -- A menu accessible with keyboard UP, DOWN 
887     |                               -- arrows
888     |----&gt; temp_leave.c          -- Demonstrates temporarily leaving curses mode
889     |----&gt; win_border.c          -- Shows Creation of windows and borders
890     |----&gt; with_chgat.c          -- chgat() usage example
891
892   forms 
893     |
894     |----&gt; form_attrib.c     -- Usage of field attributes
895     |----&gt; form_options.c    -- Usage of field options
896     |----&gt; form_simple.c     -- A simple form example
897     |----&gt; form_win.c        -- Demo of windows associated with forms
898
899   menus 
900     |
901     |----&gt; menu_attrib.c     -- Usage of menu attributes
902     |----&gt; menu_item_data.c  -- Usage of item_name() etc.. functions
903     |----&gt; menu_multi_column.c    -- Creates multi columnar menus
904     |----&gt; menu_scroll.c     -- Demonstrates scrolling capability of menus
905     |----&gt; menu_simple.c     -- A simple menu accessed by arrow keys
906     |----&gt; menu_toggle.c     -- Creates multi valued menus and explains
907     |                           -- REQ_TOGGLE_ITEM
908     |----&gt; menu_userptr.c    -- Usage of user pointer
909     |----&gt; menu_win.c        -- Demo of windows associated with menus
910
911   panels 
912     |
913     |----&gt; panel_browse.c    -- Panel browsing through tab. Usage of user 
914     |                           -- pointer
915     |----&gt; panel_hide.c      -- Hiding and Un hiding of panels
916     |----&gt; panel_resize.c    -- Moving and resizing of panels
917     |----&gt; panel_simple.c    -- A simple panel example
918
919   perl
920     |----&gt; 01-10.pl          -- Perl equivalents of first ten example programs
921 </pre>
922
923         <p>There is a top level Makefile included in the main
924         directory. It builds all the files and puts the
925         ready-to-use exes in demo/exe directory. You can also do
926         selective make by going into the corresponding directory.
927         Each directory contains a README file explaining the
928         purpose of each c file in the directory.</p>
929
930         <p>For every example, I have included path name for the
931         file relative to the examples directory.</p>
932
933         <p>If you prefer browsing individual programs, point your
934         browser to <a href=
935         "http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/"
936         target=
937         "_top">http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/</a></p>
938
939         <p>All the programs are released under the same license
940         that is used by ncurses (MIT-style). This gives you the
941         ability to do pretty much anything other than claiming them
942         as yours. Feel free to use them in your programs as
943         appropriate.</p>
944       </div>
945
946       <div class="SECT2">
947         <hr>
948
949         <h3 class="SECT2"><a name="OTHERFORMATS" id=
950         "OTHERFORMATS">1.6. Other Formats of the document</a></h3>
951
952         <p>This howto is also availabe in various other formats on
953         the tldp.org site. Here are the links to other formats of
954         this document.</p>
955
956         <div class="SECT3">
957           <hr>
958
959           <h4 class="SECT3"><a name="LISTFORMATS" id=
960           "LISTFORMATS">1.6.1. Readily available formats from
961           tldp.org</a></h4>
962
963           <ul>
964             <li>
965               <p><a href=
966               "http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf"
967               target="_top">Acrobat PDF Format</a></p>
968             </li>
969
970             <li>
971               <p><a href=
972               "http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz"
973               target="_top">PostScript Format</a></p>
974             </li>
975
976             <li>
977               <p><a href=
978               "http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz"
979               target="_top">In Multiple HTML pages</a></p>
980             </li>
981
982             <li>
983               <p><a href=
984               "http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html"
985               target="_top">In One big HTML format</a></p>
986             </li>
987           </ul>
988         </div>
989
990         <div class="SECT3">
991           <hr>
992
993           <h4 class="SECT3"><a name="BUILDSOURCE" id=
994           "BUILDSOURCE">1.6.2. Building from source</a></h4>
995
996           <p>If above links are broken or if you want to experiment
997           with sgml read on.</p>
998           <pre class="PROGRAMLISTING">
999 &#13;    Get both the source and the tar,gzipped programs, available at
1000         http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
1001         NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml
1002         http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
1003         NCURSES-HOWTO/ncurses_programs.tar.gz
1004
1005     Unzip ncurses_programs.tar.gz with
1006     tar zxvf ncurses_programs.tar.gz
1007
1008     Use jade to create various formats. For example if you just want to create
1009     the multiple html files, you would use
1010         jade -t sgml -i html -d &lt;path to docbook html stylesheet&gt;
1011         NCURSES-Programming-HOWTO.sgml
1012     to get pdf, first create a single html file of the HOWTO with 
1013         jade -t sgml -i html -d &lt;path to docbook html stylesheet&gt; -V nochunks
1014         NCURSES-Programming-HOWTO.sgml &gt; NCURSES-ONE-BIG-FILE.html
1015     then use htmldoc to get pdf file with
1016         htmldoc --size universal -t pdf --firstpage p1 -f &lt;output file name.pdf&gt;
1017         NCURSES-ONE-BIG-FILE.html
1018     for ps, you would use
1019         htmldoc --size universal -t ps --firstpage p1 -f &lt;output file name.ps&gt;
1020         NCURSES-ONE-BIG-FILE.html
1021 </pre>
1022
1023           <p>See <a href=
1024           "http://www.tldp.org/LDP/LDP-Author-Guide/" target=
1025           "_top">LDP Author guide</a> for more details. If all else
1026           failes, mail me at <a href="ppadala@gmail.com" target=
1027           "_top">ppadala@gmail.com</a></p>
1028         </div>
1029       </div>
1030
1031       <div class="SECT2">
1032         <hr>
1033
1034         <h3 class="SECT2"><a name="CREDITS" id="CREDITS">1.7.
1035         Credits</a></h3>
1036
1037         <p>I thank <a href="mailto:sharath_1@usa.net" target=
1038         "_top">Sharath</a> and Emre Akbas for helping me with few
1039         sections. The introduction was initially written by
1040         sharath. I rewrote it with few excerpts taken from his
1041         initial work. Emre helped in writing printw and scanw
1042         sections.</p>
1043
1044         <p>Perl equivalents of the example programs are contributed
1045         by <a href="mailto:Aratnaweera@virtusa.com" target=
1046         "_top">Anuradha Ratnaweera</a>.</p>
1047
1048         <p>Then comes <a href="mailto:parimi@ece.arizona.edu"
1049         target="_top">Ravi Parimi</a>, my dearest friend, who has
1050         been on this project before even one line was written. He
1051         constantly bombarded me with suggestions and patiently
1052         reviewed the whole text. He also checked each program on
1053         Linux and Solaris.</p>
1054       </div>
1055
1056       <div class="SECT2">
1057         <hr>
1058
1059         <h3 class="SECT2"><a name="WISHLIST" id="WISHLIST">1.8.
1060         Wish List</a></h3>
1061
1062         <p>This is the wish list, in the order of priority. If you
1063         have a wish or you want to work on completing the wish,
1064         mail <a href="mailto:ppadala@gmail.com" target=
1065         "_top">me</a>.</p>
1066
1067         <ul>
1068           <li>
1069             <p>Add examples to last parts of forms section.</p>
1070           </li>
1071
1072           <li>
1073             <p>Prepare a Demo showing all the programs and allow
1074             the user to browse through description of each program.
1075             Let the user compile and see the program in action. A
1076             dialog based interface is preferred.</p>
1077           </li>
1078
1079           <li>
1080             <p>Add debug info. _tracef, _tracemouse stuff.</p>
1081           </li>
1082
1083           <li>
1084             <p>Accessing termcap, terminfo using functions provided
1085             by ncurses package.</p>
1086           </li>
1087
1088           <li>
1089             <p>Working on two terminals simultaneously.</p>
1090           </li>
1091
1092           <li>
1093             <p>Add more stuff to miscellaneous section.</p>
1094           </li>
1095         </ul>
1096       </div>
1097
1098       <div class="SECT2">
1099         <hr>
1100
1101         <h3 class="SECT2"><a name="COPYRIGHT" id="COPYRIGHT">1.9.
1102         Copyright</a></h3>
1103
1104         <p>Copyright &copy; 2001 by Pradeep Padala.</p>
1105
1106         <p>Permission is hereby granted, free of charge, to any
1107         person obtaining a copy of this software and associated
1108         documentation files (the "Software"), to deal in the
1109         Software without restriction, including without limitation
1110         the rights to use, copy, modify, merge, publish,
1111         distribute, distribute with modifications, sublicense,
1112         and/or sell copies of the Software, and to permit persons
1113         to whom the Software is furnished to do so, subject to the
1114         following conditions:</p>
1115
1116         <p>The above copyright notice and this permission notice
1117         shall be included in all copies or substantial portions of
1118         the Software.</p>
1119
1120         <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
1121         ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
1122         THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
1123         PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE ABOVE
1124         COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1125         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
1126         OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
1127         SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
1128
1129         <p>Except as contained in this notice, the name(s) of the
1130         above copyright holders shall not be used in advertising or
1131         otherwise to promote the sale, use or other dealings in
1132         this Software without prior written authorization.</p>
1133       </div>
1134     </div>
1135
1136     <div class="SECT1">
1137       <hr>
1138
1139       <h2 class="SECT1"><a name="HELLOWORLD" id="HELLOWORLD">2.
1140       Hello World !!!</a></h2>
1141
1142       <p>Welcome to the world of curses. Before we plunge into the
1143       library and look into its various features, let's write a
1144       simple program and say hello to the world.</p>
1145
1146       <div class="SECT2">
1147         <hr>
1148
1149         <h3 class="SECT2"><a name="COMPILECURSES" id=
1150         "COMPILECURSES">2.1. Compiling With the NCURSES
1151         Library</a></h3>
1152
1153         <p>To use ncurses library functions, you have to include
1154         ncurses.h in your programs. To link the program with
1155         ncurses the flag -lncurses should be added.</p>
1156         <pre class="PROGRAMLISTING">
1157     #include &lt;ncurses.h&gt;
1158     .
1159     .
1160     .
1161
1162     compile and link: gcc &lt;program file&gt; -lncurses
1163 </pre>
1164
1165         <div class="EXAMPLE">
1166           <a name="BHW" id="BHW"></a>
1167
1168           <p><b>Example 1. The Hello World !!! Program</b></p>
1169           <pre class="PROGRAMLISTING">
1170 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
1171
1172 int main()
1173 {       
1174         initscr();                      /* Start curses mode              */
1175         printw("Hello World !!!");      /* Print Hello World              */
1176         refresh();                      /* Print it on to the real screen */
1177         getch();                        /* Wait for user input */
1178         endwin();                       /* End curses mode                */
1179
1180         return 0;
1181 }</span>
1182 </pre>
1183         </div>
1184       </div>
1185
1186       <div class="SECT2">
1187         <hr>
1188
1189         <h3 class="SECT2"><a name="DISSECTION" id="DISSECTION">2.2.
1190         Dissection</a></h3>
1191
1192         <p>The above program prints "Hello World !!!" to the screen
1193         and exits. This program shows how to initialize curses and
1194         do screen manipulation and end curses mode. Let's dissect
1195         it line by line.</p>
1196
1197         <div class="SECT3">
1198           <hr>
1199
1200           <h4 class="SECT3"><a name="ABOUT-INITSCR" id=
1201           "ABOUT-INITSCR">2.2.1. About initscr()</a></h4>
1202
1203           <p>The function initscr() initializes the terminal in
1204           curses mode. In some implementations, it clears the
1205           screen and presents a blank screen. To do any screen
1206           manipulation using curses package this has to be called
1207           first. This function initializes the curses system and
1208           allocates memory for our present window (called
1209           <tt class="LITERAL">stdscr</tt>) and some other
1210           data-structures. Under extreme cases this function might
1211           fail due to insufficient memory to allocate memory for
1212           curses library's data structures.</p>
1213
1214           <p>After this is done, we can do a variety of
1215           initializations to customize our curses settings. These
1216           details will be explained <a href="#INIT">later</a> .</p>
1217         </div>
1218
1219         <div class="SECT3">
1220           <hr>
1221
1222           <h4 class="SECT3"><a name="MYST-REFRESH" id=
1223           "MYST-REFRESH">2.2.2. The mysterious refresh()</a></h4>
1224
1225           <p>The next line printw prints the string "Hello World
1226           !!!" on to the screen. This function is analogous to
1227           normal printf in all respects except that it prints the
1228           data on a window called stdscr at the current (y,x)
1229           co-ordinates. Since our present co-ordinates are at 0,0
1230           the string is printed at the left hand corner of the
1231           window.</p>
1232
1233           <p>This brings us to that mysterious refresh(). Well,
1234           when we called printw the data is actually written to an
1235           imaginary window, which is not updated on the screen yet.
1236           The job of printw is to update a few flags and data
1237           structures and write the data to a buffer corresponding
1238           to stdscr. In order to show it on the screen, we need to
1239           call refresh() and tell the curses system to dump the
1240           contents on the screen.</p>
1241
1242           <p>The philosophy behind all this is to allow the
1243           programmer to do multiple updates on the imaginary screen
1244           or windows and do a refresh once all his screen update is
1245           done. refresh() checks the window and updates only the
1246           portion which has been changed. This improves performance
1247           and offers greater flexibility too. But, it is sometimes
1248           frustrating to beginners. A common mistake committed by
1249           beginners is to forget to call refresh() after they did
1250           some update through printw() class of functions. I still
1251           forget to add it sometimes :-)</p>
1252         </div>
1253
1254         <div class="SECT3">
1255           <hr>
1256
1257           <h4 class="SECT3"><a name="ABOUT-ENDWIN" id=
1258           "ABOUT-ENDWIN">2.2.3. About endwin()</a></h4>
1259
1260           <p>And finally don't forget to end the curses mode.
1261           Otherwise your terminal might behave strangely after the
1262           program quits. endwin() frees the memory taken by curses
1263           sub-system and its data structures and puts the terminal
1264           in normal mode. This function must be called after you
1265           are done with the curses mode.</p>
1266         </div>
1267       </div>
1268     </div>
1269
1270     <div class="SECT1">
1271       <hr>
1272
1273       <h2 class="SECT1"><a name="GORY" id="GORY">3. The Gory
1274       Details</a></h2>
1275
1276       <p>Now that we have seen how to write a simple curses program
1277       let's get into the details. There are many functions that
1278       help customize what you see on screen and many features which
1279       can be put to full use.</p>
1280
1281       <p>Here we go...</p>
1282     </div>
1283
1284     <div class="SECT1">
1285       <hr>
1286
1287       <h2 class="SECT1"><a name="INIT" id="INIT">4.
1288       Initialization</a></h2>
1289
1290       <p>We now know that to initialize curses system the function
1291       initscr() has to be called. There are functions which can be
1292       called after this initialization to customize our curses
1293       session. We may ask the curses system to set the terminal in
1294       raw mode or initialize color or initialize the mouse etc..
1295       Let's discuss some of the functions that are normally called
1296       immediately after initscr();</p>
1297
1298       <div class="SECT2">
1299         <hr>
1300
1301         <h3 class="SECT2"><a name="ABOUTINIT" id="ABOUTINIT">4.1.
1302         Initialization functions</a></h3>
1303       </div>
1304
1305       <div class="SECT2">
1306         <hr>
1307
1308         <h3 class="SECT2"><a name="RAWCBREAK" id="RAWCBREAK">4.2.
1309         raw() and cbreak()</a></h3>
1310
1311         <p>Normally the terminal driver buffers the characters a
1312         user types until a new line or carriage return is
1313         encountered. But most programs require that the characters
1314         be available as soon as the user types them. The above two
1315         functions are used to disable line buffering. The
1316         difference between these two functions is in the way
1317         control characters like suspend (CTRL-Z), interrupt and
1318         quit (CTRL-C) are passed to the program. In the raw() mode
1319         these characters are directly passed to the program without
1320         generating a signal. In the <tt class=
1321         "LITERAL">cbreak()</tt> mode these control characters are
1322         interpreted as any other character by the terminal driver.
1323         I personally prefer to use raw() as I can exercise greater
1324         control over what the user does.</p>
1325       </div>
1326
1327       <div class="SECT2">
1328         <hr>
1329
1330         <h3 class="SECT2"><a name="ECHONOECHO" id="ECHONOECHO">4.3.
1331         echo() and noecho()</a></h3>
1332
1333         <p>These functions control the echoing of characters typed
1334         by the user to the terminal. <tt class=
1335         "LITERAL">noecho()</tt> switches off echoing. The reason
1336         you might want to do this is to gain more control over
1337         echoing or to suppress unnecessary echoing while taking
1338         input from the user through the getch() etc. functions.
1339         Most of the interactive programs call <tt class=
1340         "LITERAL">noecho()</tt> at initialization and do the
1341         echoing of characters in a controlled manner. It gives the
1342         programmer the flexibility of echoing characters at any
1343         place in the window without updating current (y,x)
1344         co-ordinates.</p>
1345       </div>
1346
1347       <div class="SECT2">
1348         <hr>
1349
1350         <h3 class="SECT2"><a name="KEYPAD" id="KEYPAD">4.4.
1351         keypad()</a></h3>
1352
1353         <p>This is my favorite initialization function. It enables
1354         the reading of function keys like F1, F2, arrow keys etc.
1355         Almost every interactive program enables this, as arrow
1356         keys are a major part of any User Interface. Do <tt class=
1357         "LITERAL">keypad(stdscr, TRUE)</tt> to enable this feature
1358         for the regular screen (stdscr). You will learn more about
1359         key management in later sections of this document.</p>
1360       </div>
1361
1362       <div class="SECT2">
1363         <hr>
1364
1365         <h3 class="SECT2"><a name="HALFDELAY" id="HALFDELAY">4.5.
1366         halfdelay()</a></h3>
1367
1368         <p>This function, though not used very often, is a useful
1369         one at times. halfdelay()is called to enable the half-delay
1370         mode, which is similar to the cbreak() mode in that
1371         characters typed are immediately available to program.
1372         However, it waits for 'X' tenths of a second for input and
1373         then returns ERR, if no input is available. 'X' is the
1374         timeout value passed to the function halfdelay(). This
1375         function is useful when you want to ask the user for input,
1376         and if he doesn't respond with in certain time, we can do
1377         some thing else. One possible example is a timeout at the
1378         password prompt.</p>
1379       </div>
1380
1381       <div class="SECT2">
1382         <hr>
1383
1384         <h3 class="SECT2"><a name="MISCINIT" id="MISCINIT">4.6.
1385         Miscellaneous Initialization functions</a></h3>
1386
1387         <p>There are few more functions which are called at
1388         initialization to customize curses behavior. They are not
1389         used as extensively as those mentioned above. Some of them
1390         are explained where appropriate.</p>
1391       </div>
1392
1393       <div class="SECT2">
1394         <hr>
1395
1396         <h3 class="SECT2"><a name="INITEX" id="INITEX">4.7. An
1397         Example</a></h3>
1398
1399         <p>Let's write a program which will clarify the usage of
1400         these functions.</p>
1401
1402         <div class="EXAMPLE">
1403           <a name="BINFU" id="BINFU"></a>
1404
1405           <p><b>Example 2. Initialization Function Usage
1406           example</b></p>
1407           <pre class="PROGRAMLISTING">
1408 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
1409
1410 int main()
1411 {       int ch;
1412
1413         initscr();                      /* Start curses mode            */
1414         raw();                          /* Line buffering disabled      */
1415         keypad(stdscr, TRUE);           /* We get F1, F2 etc..          */
1416         noecho();                       /* Don't echo() while we do getch */
1417
1418         printw("Type any character to see it in bold\n");
1419         ch = getch();                   /* If raw() hadn't been called
1420                                          * we have to press enter before it
1421                                          * gets to the program          */
1422         if(ch == KEY_F(1))              /* Without keypad enabled this will */
1423                 printw("F1 Key pressed");/*  not get to us either       */
1424                                         /* Without noecho() some ugly escape
1425                                          * charachters might have been printed
1426                                          * on screen                    */
1427         else
1428         {       printw("The pressed key is ");
1429                 attron(A_BOLD);
1430                 printw("%c", ch);
1431                 attroff(A_BOLD);
1432         }
1433         refresh();                      /* Print it on to the real screen */
1434         getch();                        /* Wait for user input */
1435         endwin();                       /* End curses mode                */
1436
1437         return 0;
1438 }</span>
1439 </pre>
1440         </div>
1441
1442         <p>This program is self-explanatory. But I used functions
1443         which aren't explained yet. The function <tt class=
1444         "LITERAL">getch()</tt> is used to get a character from
1445         user. It is equivalent to normal <tt class=
1446         "LITERAL">getchar()</tt> except that we can disable the
1447         line buffering to avoid &lt;enter&gt; after input. Look for
1448         more about <tt class="LITERAL">getch()</tt>and reading keys
1449         in the <a href="#KEYS">key management section</a> . The
1450         functions attron and attroff are used to switch some
1451         attributes on and off respectively. In the example I used
1452         them to print the character in bold. These functions are
1453         explained in detail later.</p>
1454       </div>
1455     </div>
1456
1457     <div class="SECT1">
1458       <hr>
1459
1460       <h2 class="SECT1"><a name="AWORDWINDOWS" id="AWORDWINDOWS">5.
1461       A Word about Windows</a></h2>
1462
1463       <p>Before we plunge into the myriad ncurses functions, let me
1464       clear few things about windows. Windows are explained in
1465       detail in following <a href="#WINDOWS">sections</a></p>
1466
1467       <p>A Window is an imaginary screen defined by curses system.
1468       A window does not mean a bordered window which you usually
1469       see on Win9X platforms. When curses is initialized, it
1470       creates a default window named <tt class=
1471       "LITERAL">stdscr</tt> which represents your 80x25 (or the
1472       size of window in which you are running) screen. If you are
1473       doing simple tasks like printing few strings, reading input
1474       etc., you can safely use this single window for all of your
1475       purposes. You can also create windows and call functions
1476       which explicitly work on the specified window.</p>
1477
1478       <p>For example, if you call</p>
1479       <pre class="PROGRAMLISTING">
1480     printw("Hi There !!!");
1481     refresh();
1482 </pre>
1483
1484       <p>It prints the string on stdscr at the present cursor
1485       position. Similarly the call to refresh(), works on stdscr
1486       only.</p>
1487
1488       <p>Say you have created <a href="#WINDOWS">windows</a> then
1489       you have to call a function with a 'w' added to the usual
1490       function.</p>
1491       <pre class="PROGRAMLISTING">
1492     wprintw(win, "Hi There !!!");
1493     wrefresh(win);
1494 </pre>
1495
1496       <p>As you will see in the rest of the document, naming of
1497       functions follow the same convention. For each function there
1498       usually are three more functions.</p>
1499       <pre class="PROGRAMLISTING">
1500     printw(string);        /* Print on stdscr at present cursor position */
1501     mvprintw(y, x, string);/* Move to (y, x) then print string     */
1502     wprintw(win, string);  /* Print on window win at present cursor position */
1503                            /* in the window */
1504     mvwprintw(win, y, x, string);   /* Move to (y, x) relative to window */
1505                                     /* co-ordinates and then print         */
1506 </pre>
1507
1508       <p>Usually the w-less functions are macros which expand to
1509       corresponding w-function with stdscr as the window
1510       parameter.</p>
1511     </div>
1512
1513     <div class="SECT1">
1514       <hr>
1515
1516       <h2 class="SECT1"><a name="PRINTW" id="PRINTW">6. Output
1517       functions</a></h2>
1518
1519       <p>I guess you can't wait any more to see some action. Back
1520       to our odyssey of curses functions. Now that curses is
1521       initialized, let's interact with world.</p>
1522
1523       <p>There are three classes of functions which you can use to
1524       do output on screen.</p>
1525
1526       <ol type="1">
1527         <li>
1528           <p>addch() class: Print single character with
1529           attributes</p>
1530         </li>
1531
1532         <li>
1533           <p>printw() class: Print formatted output similar to
1534           printf()</p>
1535         </li>
1536
1537         <li>
1538           <p>addstr() class: Print strings</p>
1539         </li>
1540       </ol>
1541
1542       <p>These functions can be used interchangeably and it's a
1543       matter of style as to which class is used. Let's see each one
1544       in detail.</p>
1545
1546       <div class="SECT2">
1547         <hr>
1548
1549         <h3 class="SECT2"><a name="ADDCHCLASS" id="ADDCHCLASS">6.1.
1550         addch() class of functions</a></h3>
1551
1552         <p>These functions put a single character into the current
1553         cursor location and advance the position of the cursor. You
1554         can give the character to be printed but they usually are
1555         used to print a character with some attributes. Attributes
1556         are explained in detail in later <a href=
1557         "#ATTRIB">sections</a> of the document. If a character is
1558         associated with an attribute(bold, reverse video etc.),
1559         when curses prints the character, it is printed in that
1560         attribute.</p>
1561
1562         <p>In order to combine a character with some attributes,
1563         you have two options:</p>
1564
1565         <ul>
1566           <li>
1567             <p>By OR'ing a single character with the desired
1568             attribute macros. These attribute macros could be found
1569             in the header file <tt class="LITERAL">ncurses.h</tt>.
1570             For example, you want to print a character ch(of type
1571             char) bold and underlined, you would call addch() as
1572             below.</p>
1573             <pre class="PROGRAMLISTING">
1574     addch(ch | A_BOLD | A_UNDERLINE);
1575 </pre>
1576           </li>
1577
1578           <li>
1579             <p>By using functions like <tt class=
1580             "LITERAL">attrset(),attron(),attroff()</tt>. These
1581             functions are explained in the <a href=
1582             "#ATTRIB">Attributes</a> section. Briefly, they
1583             manipulate the current attributes of the given window.
1584             Once set, the character printed in the window are
1585             associated with the attributes until it is turned
1586             off.</p>
1587           </li>
1588         </ul>
1589
1590         <p>Additionally, <tt class="LITERAL">curses</tt> provides
1591         some special characters for character-based graphics. You
1592         can draw tables, horizontal or vertical lines, etc. You can
1593         find all avaliable characters in the header file <tt class=
1594         "LITERAL">ncurses.h</tt>. Try looking for macros beginning
1595         with <tt class="LITERAL">ACS_</tt> in this file.</p>
1596       </div>
1597
1598       <div class="SECT2">
1599         <hr>
1600
1601         <h3 class="SECT2"><a name="AEN298" id="AEN298">6.2.
1602         mvaddch(), waddch() and mvwaddch()</a></h3>
1603
1604         <p><tt class="LITERAL">mvaddch()</tt> is used to move the
1605         cursor to a given point, and then print. Thus, the
1606         calls:</p>
1607         <pre class="PROGRAMLISTING">
1608     move(row,col);    /* moves the cursor to row<span class=
1609 "emphasis"><i class=
1610 "EMPHASIS">th</i></span> row and col<span class="emphasis"><i class="EMPHASIS">th</i></span> column */
1611     addch(ch);
1612 </pre>can be replaced by
1613         <pre class="PROGRAMLISTING">
1614     mvaddch(row,col,ch);
1615 </pre>
1616
1617         <p><tt class="LITERAL">waddch()</tt> is similar to
1618         <tt class="LITERAL">addch()</tt>, except that it adds a
1619         character into the given window. (Note that <tt class=
1620         "LITERAL">addch()</tt> adds a character into the window
1621         <tt class="LITERAL">stdscr</tt>.)</p>
1622
1623         <p>In a similar fashion <tt class="LITERAL">mvwaddch()</tt>
1624         function is used to add a character into the given window
1625         at the given coordinates.</p>
1626
1627         <p>Now, we are familiar with the basic output function
1628         <tt class="LITERAL">addch()</tt>. But, if we want to print
1629         a string, it would be very annoying to print it character
1630         by character. Fortunately, <tt class="LITERAL">ncurses</tt>
1631         provides <tt class="LITERAL">printf</tt><span class=
1632         "emphasis"><i class="EMPHASIS">-like</i></span> or
1633         <tt class="LITERAL">puts</tt><span class=
1634         "emphasis"><i class="EMPHASIS">-like</i></span>
1635         functions.</p>
1636       </div>
1637
1638       <div class="SECT2">
1639         <hr>
1640
1641         <h3 class="SECT2"><a name="PRINTWCLASS" id=
1642         "PRINTWCLASS">6.3. printw() class of functions</a></h3>
1643
1644         <p>These functions are similar to <tt class=
1645         "LITERAL">printf()</tt> with the added capability of
1646         printing at any position on the screen.</p>
1647
1648         <div class="SECT3">
1649           <hr>
1650
1651           <h4 class="SECT3"><a name="PRINTWMVPRINTW" id=
1652           "PRINTWMVPRINTW">6.3.1. printw() and mvprintw</a></h4>
1653
1654           <p>These two functions work much like <tt class=
1655           "LITERAL">printf()</tt>. <tt class=
1656           "LITERAL">mvprintw()</tt> can be used to move the cursor
1657           to a position and then print. If you want to move the
1658           cursor first and then print using <tt class=
1659           "LITERAL">printw()</tt> function, use <tt class=
1660           "LITERAL">move()</tt> first and then use <tt class=
1661           "LITERAL">printw()</tt> though I see no point why one
1662           should avoid using <tt class="LITERAL">mvprintw()</tt>,
1663           you have the flexibility to manipulate.</p>
1664         </div>
1665
1666         <div class="SECT3">
1667           <hr>
1668
1669           <h4 class="SECT3"><a name="WPRINTWMVWPRINTW" id=
1670           "WPRINTWMVWPRINTW">6.3.2. wprintw() and
1671           mvwprintw</a></h4>
1672
1673           <p>These two functions are similar to above two except
1674           that they print in the corresponding window given as
1675           argument.</p>
1676         </div>
1677
1678         <div class="SECT3">
1679           <hr>
1680
1681           <h4 class="SECT3"><a name="VWPRINTW" id="VWPRINTW">6.3.3.
1682           vwprintw()</a></h4>
1683
1684           <p>This function is similar to <tt class=
1685           "LITERAL">vprintf()</tt>. This can be used when variable
1686           number of arguments are to be printed.</p>
1687         </div>
1688
1689         <div class="SECT3">
1690           <hr>
1691
1692           <h4 class="SECT3"><a name="SIMPLEPRINTWEX" id=
1693           "SIMPLEPRINTWEX">6.3.4. A Simple printw example</a></h4>
1694
1695           <div class="EXAMPLE">
1696             <a name="BPREX" id="BPREX"></a>
1697
1698             <p><b>Example 3. A Simple printw example</b></p>
1699             <pre class="PROGRAMLISTING">
1700 <span class=
1701 "INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;                   /* ncurses.h includes stdio.h */  
1702 #include &lt;string.h&gt; 
1703  
1704 int main()
1705 {
1706  char mesg[]="Just a string";           /* message to be appeared on the screen */
1707  int row,col;                           /* to store the number of rows and *
1708                                          * the number of colums of the screen */
1709  initscr();                             /* start the curses mode */
1710  getmaxyx(stdscr,row,col);              /* get the number of rows and columns */
1711  mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);
1712                                         /* print the message at the center of the screen */
1713  mvprintw(row-2,0,"This screen has %d rows and %d columns\n",row,col);
1714  printw("Try resizing your window(if possible) and then run this program again");
1715  refresh();
1716  getch();
1717  endwin();
1718
1719  return 0;
1720 }</span>
1721 </pre>
1722           </div>
1723
1724           <p>Above program demonstrates how easy it is to use
1725           <tt class="LITERAL">printw</tt>. You just feed the
1726           coordinates and the message to be appeared on the screen,
1727           then it does what you want.</p>
1728
1729           <p>The above program introduces us to a new function
1730           <tt class="LITERAL">getmaxyx()</tt>, a macro defined in
1731           <tt class="LITERAL">ncurses.h</tt>. It gives the number
1732           of columns and the number of rows in a given window.
1733           <tt class="LITERAL">getmaxyx()</tt> does this by updating
1734           the variables given to it. Since <tt class=
1735           "LITERAL">getmaxyx()</tt> is not a function we don't pass
1736           pointers to it, we just give two integer variables.</p>
1737         </div>
1738       </div>
1739
1740       <div class="SECT2">
1741         <hr>
1742
1743         <h3 class="SECT2"><a name="ADDSTRCLASS" id=
1744         "ADDSTRCLASS">6.4. addstr() class of functions</a></h3>
1745
1746         <p><tt class="LITERAL">addstr()</tt> is used to put a
1747         character string into a given window. This function is
1748         similar to calling <tt class="LITERAL">addch()</tt> once
1749         for each character in a given string. This is true for all
1750         output functions. There are other functions from this
1751         family such as <tt class=
1752         "LITERAL">mvaddstr(),mvwaddstr()</tt> and <tt class=
1753         "LITERAL">waddstr()</tt>, which obey the naming convention
1754         of curses.(e.g. mvaddstr() is similar to the respective
1755         calls move() and then addstr().) Another function of this
1756         family is addnstr(), which takes an integer parameter(say
1757         n) additionally. This function puts at most n characters
1758         into the screen. If n is negative, then the entire string
1759         will be added.</p>
1760       </div>
1761
1762       <div class="SECT2">
1763         <hr>
1764
1765         <h3 class="SECT2"><a name="ACAUTION" id="ACAUTION">6.5. A
1766         word of caution</a></h3>
1767
1768         <p>All these functions take y co-ordinate first and then x
1769         in their arguments. A common mistake by beginners is to
1770         pass x,y in that order. If you are doing too many
1771         manipulations of (y,x) co-ordinates, think of dividing the
1772         screen into windows and manipulate each one separately.
1773         Windows are explained in the <a href="#WINDOWS">windows</a>
1774         section.</p>
1775       </div>
1776     </div>
1777
1778     <div class="SECT1">
1779       <hr>
1780
1781       <h2 class="SECT1"><a name="SCANW" id="SCANW">7. Input
1782       functions</a></h2>
1783
1784       <p>Well, printing without taking input, is boring. Let's see
1785       functions which allow us to get input from user. These
1786       functions also can be divided into three categories.</p>
1787
1788       <ol type="1">
1789         <li>
1790           <p>getch() class: Get a character</p>
1791         </li>
1792
1793         <li>
1794           <p>scanw() class: Get formatted input</p>
1795         </li>
1796
1797         <li>
1798           <p>getstr() class: Get strings</p>
1799         </li>
1800       </ol>
1801
1802       <div class="SECT2">
1803         <hr>
1804
1805         <h3 class="SECT2"><a name="GETCHCLASS" id="GETCHCLASS">7.1.
1806         getch() class of functions</a></h3>
1807
1808         <p>These functions read a single character from the
1809         terminal. But there are several subtle facts to consider.
1810         For example if you don't use the function cbreak(), curses
1811         will not read your input characters contiguously but will
1812         begin read them only after a new line or an EOF is
1813         encountered. In order to avoid this, the cbreak() function
1814         must used so that characters are immediately available to
1815         your program. Another widely used function is noecho(). As
1816         the name suggests, when this function is set (used), the
1817         characters that are keyed in by the user will not show up
1818         on the screen. The two functions cbreak() and noecho() are
1819         typical examples of key management. Functions of this genre
1820         are explained in the <a href="#KEYS">key management
1821         section</a> .</p>
1822       </div>
1823
1824       <div class="SECT2">
1825         <hr>
1826
1827         <h3 class="SECT2"><a name="SCANWCLASS" id="SCANWCLASS">7.2.
1828         scanw() class of functions</a></h3>
1829
1830         <p>These functions are similar to <tt class=
1831         "LITERAL">scanf()</tt> with the added capability of getting
1832         the input from any location on the screen.</p>
1833
1834         <div class="SECT3">
1835           <hr>
1836
1837           <h4 class="SECT3"><a name="SCANWMVSCANW" id=
1838           "SCANWMVSCANW">7.2.1. scanw() and mvscanw</a></h4>
1839
1840           <p>The usage of these functions is similar to that of
1841           <tt class="LITERAL">sscanf()</tt>, where the line to be
1842           scanned is provided by <tt class="LITERAL">wgetstr()</tt>
1843           function. That is, these functions call to <tt class=
1844           "LITERAL">wgetstr()</tt> function(explained below) and
1845           uses the resulting line for a scan.</p>
1846         </div>
1847
1848         <div class="SECT3">
1849           <hr>
1850
1851           <h4 class="SECT3"><a name="WSCANWMVWSCANW" id=
1852           "WSCANWMVWSCANW">7.2.2. wscanw() and mvwscanw()</a></h4>
1853
1854           <p>These are similar to above two functions except that
1855           they read from a window, which is supplied as one of the
1856           arguments to these functions.</p>
1857         </div>
1858
1859         <div class="SECT3">
1860           <hr>
1861
1862           <h4 class="SECT3"><a name="VWSCANW" id="VWSCANW">7.2.3.
1863           vwscanw()</a></h4>
1864
1865           <p>This function is similar to <tt class=
1866           "LITERAL">vscanf()</tt>. This can be used when a variable
1867           number of arguments are to be scanned.</p>
1868         </div>
1869       </div>
1870
1871       <div class="SECT2">
1872         <hr>
1873
1874         <h3 class="SECT2"><a name="GETSTRCLASS" id=
1875         "GETSTRCLASS">7.3. getstr() class of functions</a></h3>
1876
1877         <p>These functions are used to get strings from the
1878         terminal. In essence, this function performs the same task
1879         as would be achieved by a series of calls to <tt class=
1880         "LITERAL">getch()</tt> until a newline, carriage return, or
1881         end-of-file is received. The resulting string of characters
1882         are pointed to by <tt class="LITERAL">str</tt>, which is a
1883         character pointer provided by the user.</p>
1884       </div>
1885
1886       <div class="SECT2">
1887         <hr>
1888
1889         <h3 class="SECT2"><a name="GETSTREX" id="GETSTREX">7.4.
1890         Some examples</a></h3>
1891
1892         <div class="EXAMPLE">
1893           <a name="BSCEX" id="BSCEX"></a>
1894
1895           <p><b>Example 4. A Simple scanw example</b></p>
1896           <pre class="PROGRAMLISTING">
1897 <span class=
1898 "INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;                   /* ncurses.h includes stdio.h */  
1899 #include &lt;string.h&gt; 
1900  
1901 int main()
1902 {
1903  char mesg[]="Enter a string: ";                /* message to be appeared on the screen */
1904  char str[80];
1905  int row,col;                           /* to store the number of rows and *
1906                                          * the number of colums of the screen */
1907  initscr();                             /* start the curses mode */
1908  getmaxyx(stdscr,row,col);              /* get the number of rows and columns */
1909  mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg);
1910                                 /* print the message at the center of the screen */
1911  getstr(str);
1912  mvprintw(LINES - 2, 0, "You Entered: %s", str);
1913  getch();
1914  endwin();
1915
1916  return 0;
1917 }</span>
1918 </pre>
1919         </div>
1920       </div>
1921     </div>
1922
1923     <div class="SECT1">
1924       <hr>
1925
1926       <h2 class="SECT1"><a name="ATTRIB" id="ATTRIB">8.
1927       Attributes</a></h2>
1928
1929       <p>We have seen an example of how attributes can be used to
1930       print characters with some special effects. Attributes, when
1931       set prudently, can present information in an easy,
1932       understandable manner. The following program takes a C file
1933       as input and prints the file with comments in bold. Scan
1934       through the code.</p>
1935
1936       <div class="EXAMPLE">
1937         <a name="BSIAT" id="BSIAT"></a>
1938
1939         <p><b>Example 5. A Simple Attributes example</b></p>
1940         <pre class="PROGRAMLISTING">
1941 <span class=
1942 "INLINEMEDIAOBJECT">/* pager functionality by Joseph Spainhour" &lt;spainhou@bellsouth.net&gt; */
1943 #include &lt;ncurses.h&gt;
1944 #include &lt;stdlib.h&gt;
1945
1946 int main(int argc, char *argv[])
1947
1948   int ch, prev, row, col;
1949   prev = EOF;
1950   FILE *fp;
1951   int y, x;
1952
1953   if(argc != 2)
1954   {
1955     printf("Usage: %s &lt;a c file name&gt;\n", argv[0]);
1956     exit(1);
1957   }
1958   fp = fopen(argv[1], "r");
1959   if(fp == NULL)
1960   {
1961     perror("Cannot open input file");
1962     exit(1);
1963   }
1964   initscr();                            /* Start curses mode */
1965   getmaxyx(stdscr, row, col);           /* find the boundaries of the screeen */
1966   while((ch = fgetc(fp)) != EOF)        /* read the file till we reach the end */
1967   {
1968     getyx(stdscr, y, x);                /* get the current curser position */
1969     if(y == (row - 1))                  /* are we are at the end of the screen */
1970     {
1971       printw("&lt;-Press Any Key-&gt;");      /* tell the user to press a key */
1972       getch();
1973       clear();                          /* clear the screen */
1974       move(0, 0);                       /* start at the beginning of the screen */
1975     }
1976     if(prev == '/' &amp;&amp; ch == '*')        /* If it is / and * then only
1977                                          * switch bold on */    
1978     {
1979       attron(A_BOLD);                   /* cut bold on */
1980       getyx(stdscr, y, x);              /* get the current curser position */
1981       move(y, x - 1);                   /* back up one space */
1982       printw("%c%c", '/', ch);          /* The actual printing is done here */
1983     }
1984     else
1985       printw("%c", ch);
1986     refresh();
1987     if(prev == '*' &amp;&amp; ch == '/')
1988       attroff(A_BOLD);                  /* Switch it off once we got *
1989                                          * and then / */
1990     prev = ch;
1991   }
1992   endwin();                             /* End curses mode */
1993   fclose(fp);
1994   return 0;
1995 }</span>
1996 </pre>
1997       </div>
1998
1999       <p>Don't worry about all those initialization and other crap.
2000       Concentrate on the while loop. It reads each character in the
2001       file and searches for the pattern /*. Once it spots the
2002       pattern, it switches the BOLD attribute on with <tt class=
2003       "LITERAL">attron()</tt> . When we get the pattern */ it is
2004       switched off by <tt class="LITERAL">attroff()</tt> .</p>
2005
2006       <p>The above program also introduces us to two useful
2007       functions <tt class="LITERAL">getyx()</tt> and <tt class=
2008       "LITERAL">move()</tt>. The first function gets the
2009       co-ordinates of the present cursor into the variables y, x.
2010       Since getyx() is a macro we don't have to pass pointers to
2011       variables. The function <tt class="LITERAL">move()</tt> moves
2012       the cursor to the co-ordinates given to it.</p>
2013
2014       <p>The above program is really a simple one which doesn't do
2015       much. On these lines one could write a more useful program
2016       which reads a C file, parses it and prints it in different
2017       colors. One could even extend it to other languages as
2018       well.</p>
2019
2020       <div class="SECT2">
2021         <hr>
2022
2023         <h3 class="SECT2"><a name="ATTRIBDETAILS" id=
2024         "ATTRIBDETAILS">8.1. The details</a></h3>
2025
2026         <p>Let's get into more details of attributes. The functions
2027         <tt class="LITERAL">attron(), attroff(), attrset()</tt> ,
2028         and their sister functions <tt class=
2029         "LITERAL">attr_get()</tt> etc.. can be used to switch
2030         attributes on/off , get attributes and produce a colorful
2031         display.</p>
2032
2033         <p>The functions attron and attroff take a bit-mask of
2034         attributes and switch them on or off, respectively. The
2035         following video attributes, which are defined in
2036         &lt;curses.h&gt; can be passed to these functions.</p>
2037         <pre class="PROGRAMLISTING">
2038     
2039     A_NORMAL        Normal display (no highlight)
2040     A_STANDOUT      Best highlighting mode of the terminal.
2041     A_UNDERLINE     Underlining
2042     A_REVERSE       Reverse video
2043     A_BLINK         Blinking
2044     A_DIM           Half bright
2045     A_BOLD          Extra bright or bold
2046     A_PROTECT       Protected mode
2047     A_INVIS         Invisible or blank mode
2048     A_ALTCHARSET    Alternate character set
2049     A_CHARTEXT      Bit-mask to extract a character
2050     COLOR_PAIR(n)   Color-pair number n 
2051     
2052 </pre>
2053
2054         <p>The last one is the most colorful one :-) Colors are
2055         explained in the <a href="#color" target="_top">next
2056         sections</a>.</p>
2057
2058         <p>We can OR(|) any number of above attributes to get a
2059         combined effect. If you wanted reverse video with blinking
2060         characters you can use</p>
2061         <pre class="PROGRAMLISTING">
2062     attron(A_REVERSE | A_BLINK);
2063 </pre>
2064       </div>
2065
2066       <div class="SECT2">
2067         <hr>
2068
2069         <h3 class="SECT2"><a name="ATTRONVSATTRSET" id=
2070         "ATTRONVSATTRSET">8.2. attron() vs attrset()</a></h3>
2071
2072         <p>Then what is the difference between attron() and
2073         attrset()? attrset sets the attributes of window whereas
2074         attron just switches on the attribute given to it. So
2075         attrset() fully overrides whatever attributes the window
2076         previously had and sets it to the new attribute(s).
2077         Similarly attroff() just switches off the attribute(s)
2078         given to it as an argument. This gives us the flexibility
2079         of managing attributes easily.But if you use them
2080         carelessly you may loose track of what attributes the
2081         window has and garble the display. This is especially true
2082         while managing menus with colors and highlighting. So
2083         decide on a consistent policy and stick to it. You can
2084         always use <tt class="LITERAL">standend()</tt> which is
2085         equivalent to <tt class="LITERAL">attrset(A_NORMAL)</tt>
2086         which turns off all attributes and brings you to normal
2087         mode.</p>
2088       </div>
2089
2090       <div class="SECT2">
2091         <hr>
2092
2093         <h3 class="SECT2"><a name="ATTRGET" id="ATTRGET">8.3.
2094         attr_get()</a></h3>
2095
2096         <p>The function attr_get() gets the current attributes and
2097         color pair of the window. Though we might not use this as
2098         often as the above functions, this is useful in scanning
2099         areas of screen. Say we wanted to do some complex update on
2100         screen and we are not sure what attribute each character is
2101         associated with. Then this function can be used with either
2102         attrset or attron to produce the desired effect.</p>
2103       </div>
2104
2105       <div class="SECT2">
2106         <hr>
2107
2108         <h3 class="SECT2"><a name="ATTRFUNCS" id="ATTRFUNCS">8.4.
2109         attr_ functions</a></h3>
2110
2111         <p>There are series of functions like attr_set(), attr_on
2112         etc.. These are similar to above functions except that they
2113         take parameters of type <tt class=
2114         "LITERAL">attr_t</tt>.</p>
2115       </div>
2116
2117       <div class="SECT2">
2118         <hr>
2119
2120         <h3 class="SECT2"><a name="WATTRFUNCS" id="WATTRFUNCS">8.5.
2121         wattr functions</a></h3>
2122
2123         <p>For each of the above functions we have a corresponding
2124         function with 'w' which operates on a particular window.
2125         The above functions operate on stdscr.</p>
2126       </div>
2127
2128       <div class="SECT2">
2129         <hr>
2130
2131         <h3 class="SECT2"><a name="CHGAT" id="CHGAT">8.6. chgat()
2132         functions</a></h3>
2133
2134         <p>The function chgat() is listed in the end of the man
2135         page curs_attr. It actually is a useful one. This function
2136         can be used to set attributes for a group of characters
2137         without moving. I mean it !!! without moving the cursor :-)
2138         It changes the attributes of a given number of characters
2139         starting at the current cursor location.</p>
2140
2141         <p>We can give -1 as the character count to update till end
2142         of line. If you want to change attributes of characters
2143         from current position to end of line, just use this.</p>
2144         <pre class="PROGRAMLISTING">
2145     chgat(-1, A_REVERSE, 0, NULL);
2146 </pre>
2147
2148         <p>This function is useful when changing attributes for
2149         characters that are already on the screen. Move to the
2150         character from which you want to change and change the
2151         attribute.</p>
2152
2153         <p>Other functions wchgat(), mvchgat(), wchgat() behave
2154         similarly except that the w functions operate on the
2155         particular window. The mv functions first move the cursor
2156         then perform the work given to them. Actually chgat is a
2157         macro which is replaced by a wchgat() with stdscr as the
2158         window. Most of the "w-less" functions are macros.</p>
2159
2160         <div class="EXAMPLE">
2161           <a name="BWICH" id="BWICH"></a>
2162
2163           <p><b>Example 6. Chgat() Usage example</b></p>
2164           <pre class="PROGRAMLISTING">
2165 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
2166
2167 int main(int argc, char *argv[])
2168 {       initscr();                      /* Start curses mode            */
2169         start_color();                  /* Start color functionality    */
2170         
2171         init_pair(1, COLOR_CYAN, COLOR_BLACK);
2172         printw("A Big string which i didn't care to type fully ");
2173         mvchgat(0, 0, -1, A_BLINK, 1, NULL);    
2174         /* 
2175          * First two parameters specify the position at which to start 
2176          * Third parameter number of characters to update. -1 means till 
2177          * end of line
2178          * Forth parameter is the normal attribute you wanted to give 
2179          * to the charcter
2180          * Fifth is the color index. It is the index given during init_pair()
2181          * use 0 if you didn't want color
2182          * Sixth one is always NULL 
2183          */
2184         refresh();
2185         getch();
2186         endwin();                       /* End curses mode                */
2187         return 0;
2188 }</span>
2189 </pre>
2190         </div>
2191
2192         <p>This example also introduces us to the color world of
2193         curses. Colors will be explained in detail later. Use 0 for
2194         no color.</p>
2195       </div>
2196     </div>
2197
2198     <div class="SECT1">
2199       <hr>
2200
2201       <h2 class="SECT1"><a name="WINDOWS" id="WINDOWS">9.
2202       Windows</a></h2>
2203
2204       <p>Windows form the most important concept in curses. You
2205       have seen the standard window stdscr above where all the
2206       functions implicitly operated on this window. Now to make
2207       design even a simplest GUI, you need to resort to windows.
2208       The main reason you may want to use windows is to manipulate
2209       parts of the screen separately, for better efficiency, by
2210       updating only the windows that need to be changed and for a
2211       better design. I would say the last reason is the most
2212       important in going for windows. You should always strive for
2213       a better and easy-to-manage design in your programs. If you
2214       are writing big, complex GUIs this is of pivotal importance
2215       before you start doing anything.</p>
2216
2217       <div class="SECT2">
2218         <hr>
2219
2220         <h3 class="SECT2"><a name="WINDOWBASICS" id=
2221         "WINDOWBASICS">9.1. The basics</a></h3>
2222
2223         <p>A Window can be created by calling the function
2224         <tt class="LITERAL">newwin()</tt>. It doesn't create any
2225         thing on the screen actually. It allocates memory for a
2226         structure to manipulate the window and updates the
2227         structure with data regarding the window like it's size,
2228         beginy, beginx etc.. Hence in curses, a window is just an
2229         abstraction of an imaginary window, which can be
2230         manipulated independent of other parts of screen. The
2231         function newwin() returns a pointer to structure WINDOW,
2232         which can be passed to window related functions like
2233         wprintw() etc.. Finally the window can be destroyed with
2234         delwin(). It will deallocate the memory associated with the
2235         window structure.</p>
2236       </div>
2237
2238       <div class="SECT2">
2239         <hr>
2240
2241         <h3 class="SECT2"><a name="LETBEWINDOW" id=
2242         "LETBEWINDOW">9.2. Let there be a Window !!!</a></h3>
2243
2244         <p>What fun is it, if a window is created and we can't see
2245         it. So the fun part begins by displaying the window. The
2246         function <tt class="LITERAL">box()</tt> can be used to draw
2247         a border around the window. Let's explore these functions
2248         in more detail in this example.</p>
2249
2250         <div class="EXAMPLE">
2251           <a name="BWIBO" id="BWIBO"></a>
2252
2253           <p><b>Example 7. Window Border example</b></p>
2254           <pre class="PROGRAMLISTING">
2255 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
2256
2257
2258 WINDOW *create_newwin(int height, int width, int starty, int startx);
2259 void destroy_win(WINDOW *local_win);
2260
2261 int main(int argc, char *argv[])
2262 {       WINDOW *my_win;
2263         int startx, starty, width, height;
2264         int ch;
2265
2266         initscr();                      /* Start curses mode            */
2267         cbreak();                       /* Line buffering disabled, Pass on
2268                                          * everty thing to me           */
2269         keypad(stdscr, TRUE);           /* I need that nifty F1         */
2270
2271         height = 3;
2272         width = 10;
2273         starty = (LINES - height) / 2;  /* Calculating for a center placement */
2274         startx = (COLS - width) / 2;    /* of the window                */
2275         printw("Press F1 to exit");
2276         refresh();
2277         my_win = create_newwin(height, width, starty, startx);
2278
2279         while((ch = getch()) != KEY_F(1))
2280         {       switch(ch)
2281                 {       case KEY_LEFT:
2282                                 destroy_win(my_win);
2283                                 my_win = create_newwin(height, width, starty,--startx);
2284                                 break;
2285                         case KEY_RIGHT:
2286                                 destroy_win(my_win);
2287                                 my_win = create_newwin(height, width, starty,++startx);
2288                                 break;
2289                         case KEY_UP:
2290                                 destroy_win(my_win);
2291                                 my_win = create_newwin(height, width, --starty,startx);
2292                                 break;
2293                         case KEY_DOWN:
2294                                 destroy_win(my_win);
2295                                 my_win = create_newwin(height, width, ++starty,startx);
2296                                 break;  
2297                 }
2298         }
2299                 
2300         endwin();                       /* End curses mode                */
2301         return 0;
2302 }
2303
2304 WINDOW *create_newwin(int height, int width, int starty, int startx)
2305 {       WINDOW *local_win;
2306
2307         local_win = newwin(height, width, starty, startx);
2308         box(local_win, 0 , 0);          /* 0, 0 gives default characters 
2309                                          * for the vertical and horizontal
2310                                          * lines                        */
2311         wrefresh(local_win);            /* Show that box                */
2312
2313         return local_win;
2314 }
2315
2316 void destroy_win(WINDOW *local_win)
2317 {       
2318         /* box(local_win, ' ', ' '); : This won't produce the desired
2319          * result of erasing the window. It will leave it's four corners 
2320          * and so an ugly remnant of window. 
2321          */
2322         wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' ');
2323         /* The parameters taken are 
2324          * 1. win: the window on which to operate
2325          * 2. ls: character to be used for the left side of the window 
2326          * 3. rs: character to be used for the right side of the window 
2327          * 4. ts: character to be used for the top side of the window 
2328          * 5. bs: character to be used for the bottom side of the window 
2329          * 6. tl: character to be used for the top left corner of the window 
2330          * 7. tr: character to be used for the top right corner of the window 
2331          * 8. bl: character to be used for the bottom left corner of the window 
2332          * 9. br: character to be used for the bottom right corner of the window
2333          */
2334         wrefresh(local_win);
2335         delwin(local_win);
2336 }</span>
2337 </pre>
2338         </div>
2339       </div>
2340
2341       <div class="SECT2">
2342         <hr>
2343
2344         <h3 class="SECT2"><a name="BORDEREXEXPL" id=
2345         "BORDEREXEXPL">9.3. Explanation</a></h3>
2346
2347         <p>Don't scream. I know it's a big example. But I have to
2348         explain some important things here :-). This program
2349         creates a rectangular window that can be moved with left,
2350         right, up, down arrow keys. It repeatedly creates and
2351         destroys windows as user press a key. Don't go beyond the
2352         screen limits. Checking for those limits is left as an
2353         exercise for the reader. Let's dissect it by line by
2354         line.</p>
2355
2356         <p>The <tt class="LITERAL">create_newwin()</tt> function
2357         creates a window with <tt class="LITERAL">newwin()</tt> and
2358         displays a border around it with box. The function
2359         <tt class="LITERAL">destroy_win()</tt> first erases the
2360         window from screen by painting a border with ' ' character
2361         and then calling <tt class="LITERAL">delwin()</tt> to
2362         deallocate memory related to it. Depending on the key the
2363         user presses, starty or startx is changed and a new window
2364         is created.</p>
2365
2366         <p>In the destroy_win, as you can see, I used wborder
2367         instead of box. The reason is written in the comments (You
2368         missed it. I know. Read the code :-)). wborder draws a
2369         border around the window with the characters given to it as
2370         the 4 corner points and the 4 lines. To put it clearly, if
2371         you have called wborder as below:</p>
2372         <pre class="PROGRAMLISTING">
2373     wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');
2374 </pre>
2375
2376         <p>it produces some thing like</p>
2377         <pre class="PROGRAMLISTING">
2378     +------------+
2379     |            |
2380     |            |
2381     |            |
2382     |            |
2383     |            |
2384     |            |
2385     +------------+
2386 </pre>
2387       </div>
2388
2389       <div class="SECT2">
2390         <hr>
2391
2392         <h3 class="SECT2"><a name="OTHERSTUFF" id="OTHERSTUFF">9.4.
2393         The other stuff in the example</a></h3>
2394
2395         <p>You can also see in the above examples, that I have used
2396         the variables COLS, LINES which are initialized to the
2397         screen sizes after initscr(). They can be useful in finding
2398         screen dimensions and finding the center co-ordinate of the
2399         screen as above. The function <tt class=
2400         "LITERAL">getch()</tt> as usual gets the key from keyboard
2401         and according to the key it does the corresponding work.
2402         This type of switch- case is very common in any GUI based
2403         programs.</p>
2404       </div>
2405
2406       <div class="SECT2">
2407         <hr>
2408
2409         <h3 class="SECT2"><a name="OTHERBORDERFUNCS" id=
2410         "OTHERBORDERFUNCS">9.5. Other Border functions</a></h3>
2411
2412         <p>Above program is grossly inefficient in that with each
2413         press of a key, a window is destroyed and another is
2414         created. So let's write a more efficient program which uses
2415         other border related functions.</p>
2416
2417         <p>The following program uses <tt class=
2418         "LITERAL">mvhline()</tt> and <tt class=
2419         "LITERAL">mvvline()</tt> to achieve similar effect. These
2420         two functions are simple. They create a horizontal or
2421         vertical line of the specified length at the specified
2422         position.</p>
2423
2424         <div class="EXAMPLE">
2425           <a name="BOTBO" id="BOTBO"></a>
2426
2427           <p><b>Example 8. More border functions</b></p>
2428           <pre class="PROGRAMLISTING">
2429 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
2430
2431 typedef struct _win_border_struct {
2432         chtype  ls, rs, ts, bs, 
2433                 tl, tr, bl, br;
2434 }WIN_BORDER;
2435
2436 typedef struct _WIN_struct {
2437
2438         int startx, starty;
2439         int height, width;
2440         WIN_BORDER border;
2441 }WIN;
2442
2443 void init_win_params(WIN *p_win);
2444 void print_win_params(WIN *p_win);
2445 void create_box(WIN *win, bool flag);
2446
2447 int main(int argc, char *argv[])
2448 {       WIN win;
2449         int ch;
2450
2451         initscr();                      /* Start curses mode            */
2452         start_color();                  /* Start the color functionality */
2453         cbreak();                       /* Line buffering disabled, Pass on
2454                                          * everty thing to me           */
2455         keypad(stdscr, TRUE);           /* I need that nifty F1         */
2456         noecho();
2457         init_pair(1, COLOR_CYAN, COLOR_BLACK);
2458
2459         /* Initialize the window parameters */
2460         init_win_params(&amp;win);
2461         print_win_params(&amp;win);
2462
2463         attron(COLOR_PAIR(1));
2464         printw("Press F1 to exit");
2465         refresh();
2466         attroff(COLOR_PAIR(1));
2467         
2468         create_box(&amp;win, TRUE);
2469         while((ch = getch()) != KEY_F(1))
2470         {       switch(ch)
2471                 {       case KEY_LEFT:
2472                                 create_box(&amp;win, FALSE);
2473                                 --win.startx;
2474                                 create_box(&amp;win, TRUE);
2475                                 break;
2476                         case KEY_RIGHT:
2477                                 create_box(&amp;win, FALSE);
2478                                 ++win.startx;
2479                                 create_box(&amp;win, TRUE);
2480                                 break;
2481                         case KEY_UP:
2482                                 create_box(&amp;win, FALSE);
2483                                 --win.starty;
2484                                 create_box(&amp;win, TRUE);
2485                                 break;
2486                         case KEY_DOWN:
2487                                 create_box(&amp;win, FALSE);
2488                                 ++win.starty;
2489                                 create_box(&amp;win, TRUE);
2490                                 break;  
2491                 }
2492         }
2493         endwin();                       /* End curses mode                */
2494         return 0;
2495 }
2496 void init_win_params(WIN *p_win)
2497 {
2498         p_win-&gt;height = 3;
2499         p_win-&gt;width = 10;
2500         p_win-&gt;starty = (LINES - p_win-&gt;height)/2;      
2501         p_win-&gt;startx = (COLS - p_win-&gt;width)/2;
2502
2503         p_win-&gt;border.ls = '|';
2504         p_win-&gt;border.rs = '|';
2505         p_win-&gt;border.ts = '-';
2506         p_win-&gt;border.bs = '-';
2507         p_win-&gt;border.tl = '+';
2508         p_win-&gt;border.tr = '+';
2509         p_win-&gt;border.bl = '+';
2510         p_win-&gt;border.br = '+';
2511
2512 }
2513 void print_win_params(WIN *p_win)
2514 {
2515 #ifdef _DEBUG
2516         mvprintw(25, 0, "%d %d %d %d", p_win-&gt;startx, p_win-&gt;starty, 
2517                                 p_win-&gt;width, p_win-&gt;height);
2518         refresh();
2519 #endif
2520 }
2521 void create_box(WIN *p_win, bool flag)
2522 {       int i, j;
2523         int x, y, w, h;
2524
2525         x = p_win-&gt;startx;
2526         y = p_win-&gt;starty;
2527         w = p_win-&gt;width;
2528         h = p_win-&gt;height;
2529
2530         if(flag == TRUE)
2531         {       mvaddch(y, x, p_win-&gt;border.tl);
2532                 mvaddch(y, x + w, p_win-&gt;border.tr);
2533                 mvaddch(y + h, x, p_win-&gt;border.bl);
2534                 mvaddch(y + h, x + w, p_win-&gt;border.br);
2535                 mvhline(y, x + 1, p_win-&gt;border.ts, w - 1);
2536                 mvhline(y + h, x + 1, p_win-&gt;border.bs, w - 1);
2537                 mvvline(y + 1, x, p_win-&gt;border.ls, h - 1);
2538                 mvvline(y + 1, x + w, p_win-&gt;border.rs, h - 1);
2539
2540         }
2541         else
2542                 for(j = y; j &lt;= y + h; ++j)
2543                         for(i = x; i &lt;= x + w; ++i)
2544                                 mvaddch(j, i, ' ');
2545                                 
2546         refresh();
2547
2548 }</span>
2549 </pre>
2550         </div>
2551       </div>
2552     </div>
2553
2554     <div class="SECT1">
2555       <hr>
2556
2557       <h2 class="SECT1"><a name="COLOR" id="COLOR">10.
2558       Colors</a></h2>
2559
2560       <div class="SECT2">
2561         <h3 class="SECT2"><a name="COLORBASICS" id=
2562         "COLORBASICS">10.1. The basics</a></h3>
2563
2564         <p>Life seems dull with no colors. Curses has a nice
2565         mechanism to handle colors. Let's get into the thick of the
2566         things with a small program.</p>
2567
2568         <div class="EXAMPLE">
2569           <a name="BSICO" id="BSICO"></a>
2570
2571           <p><b>Example 9. A Simple Color example</b></p>
2572           <pre class="PROGRAMLISTING">
2573 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
2574
2575 void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string);
2576 int main(int argc, char *argv[])
2577 {       initscr();                      /* Start curses mode            */
2578         if(has_colors() == FALSE)
2579         {       endwin();
2580                 printf("Your terminal does not support color\n");
2581                 exit(1);
2582         }
2583         start_color();                  /* Start color                  */
2584         init_pair(1, COLOR_RED, COLOR_BLACK);
2585
2586         attron(COLOR_PAIR(1));
2587         print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ...");
2588         attroff(COLOR_PAIR(1));
2589         getch();
2590         endwin();
2591 }
2592 void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string)
2593 {       int length, x, y;
2594         float temp;
2595
2596         if(win == NULL)
2597                 win = stdscr;
2598         getyx(win, y, x);
2599         if(startx != 0)
2600                 x = startx;
2601         if(starty != 0)
2602                 y = starty;
2603         if(width == 0)
2604                 width = 80;
2605
2606         length = strlen(string);
2607         temp = (width - length)/ 2;
2608         x = startx + (int)temp;
2609         mvwprintw(win, y, x, "%s", string);
2610         refresh();
2611 }
2612 </span>
2613 </pre>
2614         </div>
2615
2616         <p>As you can see, to start using color, you should first
2617         call the function <tt class="LITERAL">start_color()</tt>.
2618         After that, you can use color capabilities of your
2619         terminals using various functions. To find out whether a
2620         terminal has color capabilities or not, you can use
2621         <tt class="LITERAL">has_colors()</tt> function, which
2622         returns FALSE if the terminal does not support color.</p>
2623
2624         <p>Curses initializes all the colors supported by terminal
2625         when start_color() is called. These can be accessed by the
2626         define constants like <tt class="LITERAL">COLOR_BLACK</tt>
2627         etc. Now to actually start using colors, you have to define
2628         pairs. Colors are always used in pairs. That means you have
2629         to use the function <tt class="LITERAL">init_pair()</tt> to
2630         define the foreground and background for the pair number
2631         you give. After that that pair number can be used as a
2632         normal attribute with <tt class=
2633         "LITERAL">COLOR_PAIR()</tt>function. This may seem to be
2634         cumbersome at first. But this elegant solution allows us to
2635         manage color pairs very easily. To appreciate it, you have
2636         to look into the the source code of "dialog", a utility for
2637         displaying dialog boxes from shell scripts. The developers
2638         have defined foreground and background combinations for all
2639         the colors they might need and initialized at the
2640         beginning. This makes it very easy to set attributes just
2641         by accessing a pair which we already have defined as a
2642         constant.</p>
2643
2644         <p>The following colors are defined in <tt class=
2645         "LITERAL">curses.h</tt>. You can use these as parameters
2646         for various color functions.</p>
2647         <pre class="PROGRAMLISTING">
2648         COLOR_BLACK   0
2649         COLOR_RED     1
2650         COLOR_GREEN   2
2651         COLOR_YELLOW  3
2652         COLOR_BLUE    4
2653         COLOR_MAGENTA 5
2654         COLOR_CYAN    6
2655         COLOR_WHITE   7
2656 </pre>
2657       </div>
2658
2659       <div class="SECT2">
2660         <hr>
2661
2662         <h3 class="SECT2"><a name="CHANGECOLORDEFS" id=
2663         "CHANGECOLORDEFS">10.2. Changing Color Definitions</a></h3>
2664
2665         <p>The function <tt class="LITERAL">init_color()</tt>can be
2666         used to change the rgb values for the colors defined by
2667         curses initially. Say you wanted to lighten the intensity
2668         of red color by a minuscule. Then you can use this function
2669         as</p>
2670         <pre class="PROGRAMLISTING">
2671     init_color(COLOR_RED, 700, 0, 0);
2672     /* param 1     : color name
2673      * param 2, 3, 4 : rgb content min = 0, max = 1000 */
2674 </pre>
2675
2676         <p>If your terminal cannot change the color definitions,
2677         the function returns ERR. The function <tt class=
2678         "LITERAL">can_change_color()</tt> can be used to find out
2679         whether the terminal has the capability of changing color
2680         content or not. The rgb content is scaled from 0 to 1000.
2681         Initially RED color is defined with content 1000(r), 0(g),
2682         0(b).</p>
2683       </div>
2684
2685       <div class="SECT2">
2686         <hr>
2687
2688         <h3 class="SECT2"><a name="COLORCONTENT" id=
2689         "COLORCONTENT">10.3. Color Content</a></h3>
2690
2691         <p>The functions <tt class="LITERAL">color_content()</tt>
2692         and <tt class="LITERAL">pair_content()</tt> can be used to
2693         find the color content and foreground, background
2694         combination for the pair.</p>
2695       </div>
2696     </div>
2697
2698     <div class="SECT1">
2699       <hr>
2700
2701       <h2 class="SECT1"><a name="KEYS" id="KEYS">11. Interfacing
2702       with the key board</a></h2>
2703
2704       <div class="SECT2">
2705         <h3 class="SECT2"><a name="KEYSBASICS" id=
2706         "KEYSBASICS">11.1. The Basics</a></h3>
2707
2708         <p>No GUI is complete without a strong user interface and
2709         to interact with the user, a curses program should be
2710         sensitive to key presses or the mouse actions done by the
2711         user. Let's deal with the keys first.</p>
2712
2713         <p>As you have seen in almost all of the above examples,
2714         it's very easy to get key input from the user. A simple way
2715         of getting key presses is to use <tt class=
2716         "LITERAL">getch()</tt> function. The cbreak mode should be
2717         enabled to read keys when you are interested in reading
2718         individual key hits rather than complete lines of text
2719         (which usually end with a carriage return). keypad should
2720         be enabled to get the Functions keys, arrow keys etc. See
2721         the initialization section for details.</p>
2722
2723         <p><tt class="LITERAL">getch()</tt> returns an integer
2724         corresponding to the key pressed. If it is a normal
2725         character, the integer value will be equivalent to the
2726         character. Otherwise it returns a number which can be
2727         matched with the constants defined in <tt class=
2728         "LITERAL">curses.h</tt>. For example if the user presses
2729         F1, the integer returned is 265. This can be checked using
2730         the macro KEY_F() defined in curses.h. This makes reading
2731         keys portable and easy to manage.</p>
2732
2733         <p>For example, if you call getch() like this</p>
2734         <pre class="PROGRAMLISTING">
2735     int ch;
2736
2737     ch = getch();
2738 </pre>
2739
2740         <p>getch() will wait for the user to press a key, (unless
2741         you specified a timeout) and when user presses a key, the
2742         corresponding integer is returned. Then you can check the
2743         value returned with the constants defined in curses.h to
2744         match against the keys you want.</p>
2745
2746         <p>The following code piece will do that job.</p>
2747         <pre class="PROGRAMLISTING">
2748     if(ch == KEY_LEFT)
2749         printw("Left arrow is pressed\n");
2750 </pre>
2751
2752         <p>Let's write a small program which creates a menu which
2753         can be navigated by up and down arrows.</p>
2754       </div>
2755
2756       <div class="SECT2">
2757         <hr>
2758
2759         <h3 class="SECT2"><a name="SIMPLEKEYEX" id=
2760         "SIMPLEKEYEX">11.2. A Simple Key Usage example</a></h3>
2761
2762         <div class="EXAMPLE">
2763           <a name="BSIKE" id="BSIKE"></a>
2764
2765           <p><b>Example 10. A Simple Key Usage example</b></p>
2766           <pre class="PROGRAMLISTING">
2767 <span class="INLINEMEDIAOBJECT">#include &lt;stdio.h&gt;
2768 #include &lt;ncurses.h&gt;
2769
2770 #define WIDTH 30
2771 #define HEIGHT 10 
2772
2773 int startx = 0;
2774 int starty = 0;
2775
2776 char *choices[] = { 
2777                         "Choice 1",
2778                         "Choice 2",
2779                         "Choice 3",
2780                         "Choice 4",
2781                         "Exit",
2782                   };
2783 int n_choices = sizeof(choices) / sizeof(char *);
2784 void print_menu(WINDOW *menu_win, int highlight);
2785
2786 int main()
2787 {       WINDOW *menu_win;
2788         int highlight = 1;
2789         int choice = 0;
2790         int c;
2791
2792         initscr();
2793         clear();
2794         noecho();
2795         cbreak();       /* Line buffering disabled. pass on everything */
2796         startx = (80 - WIDTH) / 2;
2797         starty = (24 - HEIGHT) / 2;
2798                 
2799         menu_win = newwin(HEIGHT, WIDTH, starty, startx);
2800         keypad(menu_win, TRUE);
2801         mvprintw(0, 0, "Use arrow keys to go up and down, Press enter to select a choice");
2802         refresh();
2803         print_menu(menu_win, highlight);
2804         while(1)
2805         {       c = wgetch(menu_win);
2806                 switch(c)
2807                 {       case KEY_UP:
2808                                 if(highlight == 1)
2809                                         highlight = n_choices;
2810                                 else
2811                                         --highlight;
2812                                 break;
2813                         case KEY_DOWN:
2814                                 if(highlight == n_choices)
2815                                         highlight = 1;
2816                                 else 
2817                                         ++highlight;
2818                                 break;
2819                         case 10:
2820                                 choice = highlight;
2821                                 break;
2822                         default:
2823                                 mvprintw(24, 0, "Charcter pressed is = %3d Hopefully it can be printed as '%c'", c, c);
2824                                 refresh();
2825                                 break;
2826                 }
2827                 print_menu(menu_win, highlight);
2828                 if(choice != 0) /* User did a choice come out of the infinite loop */
2829                         break;
2830         }       
2831         mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, choices[choice - 1]);
2832         clrtoeol();
2833         refresh();
2834         endwin();
2835         return 0;
2836 }
2837
2838
2839 void print_menu(WINDOW *menu_win, int highlight)
2840 {
2841         int x, y, i;    
2842
2843         x = 2;
2844         y = 2;
2845         box(menu_win, 0, 0);
2846         for(i = 0; i &lt; n_choices; ++i)
2847         {       if(highlight == i + 1) /* High light the present choice */
2848                 {       wattron(menu_win, A_REVERSE); 
2849                         mvwprintw(menu_win, y, x, "%s", choices[i]);
2850                         wattroff(menu_win, A_REVERSE);
2851                 }
2852                 else
2853                         mvwprintw(menu_win, y, x, "%s", choices[i]);
2854                 ++y;
2855         }
2856         wrefresh(menu_win);
2857 }
2858 </span>
2859 </pre>
2860         </div>
2861       </div>
2862     </div>
2863
2864     <div class="SECT1">
2865       <hr>
2866
2867       <h2 class="SECT1"><a name="MOUSE" id="MOUSE">12. Interfacing
2868       with the mouse</a></h2>
2869
2870       <p>Now that you have seen how to get keys, lets do the same
2871       thing from mouse. Usually each UI allows the user to interact
2872       with both keyboard and mouse.</p>
2873
2874       <div class="SECT2">
2875         <hr>
2876
2877         <h3 class="SECT2"><a name="MOUSEBASICS" id=
2878         "MOUSEBASICS">12.1. The Basics</a></h3>
2879
2880         <p>Before you do any thing else, the events you want to
2881         receive have to be enabled with <tt class=
2882         "LITERAL">mousemask()</tt>.</p>
2883         <pre class="PROGRAMLISTING">
2884     mousemask(  mmask_t newmask,    /* The events you want to listen to */
2885                 mmask_t *oldmask)    /* The old events mask                */
2886 </pre>
2887
2888         <p>The first parameter to above function is a bit mask of
2889         events you would like to listen. By default, all the events
2890         are turned off. The bit mask <tt class=
2891         "LITERAL">ALL_MOUSE_EVENTS</tt> can be used to get all the
2892         events.</p>
2893
2894         <p>The following are all the event masks:</p>
2895         <pre class="PROGRAMLISTING">
2896     Name            Description
2897        ---------------------------------------------------------------------
2898        BUTTON1_PRESSED          mouse button 1 down
2899        BUTTON1_RELEASED         mouse button 1 up
2900        BUTTON1_CLICKED          mouse button 1 clicked
2901        BUTTON1_DOUBLE_CLICKED   mouse button 1 double clicked
2902        BUTTON1_TRIPLE_CLICKED   mouse button 1 triple clicked
2903        BUTTON2_PRESSED          mouse button 2 down
2904        BUTTON2_RELEASED         mouse button 2 up
2905        BUTTON2_CLICKED          mouse button 2 clicked
2906        BUTTON2_DOUBLE_CLICKED   mouse button 2 double clicked
2907        BUTTON2_TRIPLE_CLICKED   mouse button 2 triple clicked
2908        BUTTON3_PRESSED          mouse button 3 down
2909        BUTTON3_RELEASED         mouse button 3 up
2910        BUTTON3_CLICKED          mouse button 3 clicked
2911        BUTTON3_DOUBLE_CLICKED   mouse button 3 double clicked
2912        BUTTON3_TRIPLE_CLICKED   mouse button 3 triple clicked
2913        BUTTON4_PRESSED          mouse button 4 down
2914        BUTTON4_RELEASED         mouse button 4 up
2915        BUTTON4_CLICKED          mouse button 4 clicked
2916        BUTTON4_DOUBLE_CLICKED   mouse button 4 double clicked
2917        BUTTON4_TRIPLE_CLICKED   mouse button 4 triple clicked
2918        BUTTON_SHIFT             shift was down during button state change
2919        BUTTON_CTRL              control was down during button state change
2920        BUTTON_ALT               alt was down during button state change
2921        ALL_MOUSE_EVENTS         report all button state changes
2922        REPORT_MOUSE_POSITION    report mouse movement
2923 </pre>
2924       </div>
2925
2926       <div class="SECT2">
2927         <hr>
2928
2929         <h3 class="SECT2"><a name="GETTINGEVENTS" id=
2930         "GETTINGEVENTS">12.2. Getting the events</a></h3>
2931
2932         <p>Once a class of mouse events have been enabled, getch()
2933         class of functions return KEY_MOUSE every time some mouse
2934         event happens. Then the mouse event can be retrieved with
2935         <tt class="LITERAL">getmouse()</tt>.</p>
2936
2937         <p>The code approximately looks like this:</p>
2938         <pre class="PROGRAMLISTING">
2939     MEVENT event;
2940
2941     ch = getch();
2942     if(ch == KEY_MOUSE)
2943         if(getmouse(&amp;event) == OK)
2944             .    /* Do some thing with the event */
2945             .
2946             .
2947 </pre>
2948
2949         <p>getmouse() returns the event into the pointer given to
2950         it. It's a structure which contains</p>
2951         <pre class="PROGRAMLISTING">
2952     typedef struct
2953     {
2954         short id;         /* ID to distinguish multiple devices */
2955         int x, y, z;      /* event coordinates */
2956         mmask_t bstate;   /* button state bits */
2957     }    
2958 </pre>
2959
2960         <p>The <tt class="LITERAL">bstate</tt> is the main variable
2961         we are interested in. It tells the button state of the
2962         mouse.</p>
2963
2964         <p>Then with a code snippet like the following, we can find
2965         out what happened.</p>
2966         <pre class="PROGRAMLISTING">
2967     if(event.bstate &amp; BUTTON1_PRESSED)
2968         printw("Left Button Pressed");
2969 </pre>
2970       </div>
2971
2972       <div class="SECT2">
2973         <hr>
2974
2975         <h3 class="SECT2"><a name="MOUSETOGETHER" id=
2976         "MOUSETOGETHER">12.3. Putting it all Together</a></h3>
2977
2978         <p>That's pretty much interfacing with mouse. Let's create
2979         the same menu and enable mouse interaction. To make things
2980         simpler, key handling is removed.</p>
2981
2982         <div class="EXAMPLE">
2983           <a name="BMOME" id="BMOME"></a>
2984
2985           <p><b>Example 11. Access the menu with mouse !!!</b></p>
2986           <pre class="PROGRAMLISTING">
2987 <span class="INLINEMEDIAOBJECT">#include &lt;ncurses.h&gt;
2988
2989 #define WIDTH 30
2990 #define HEIGHT 10 
2991
2992 int startx = 0;
2993 int starty = 0;
2994
2995 char *choices[] = {     "Choice 1",
2996                         "Choice 2",
2997                         "Choice 3",
2998                         "Choice 4",
2999                         "Exit",
3000                   };
3001
3002 int n_choices = sizeof(choices) / sizeof(char *);
3003
3004 void print_menu(WINDOW *menu_win, int highlight);
3005 void report_choice(int mouse_x, int mouse_y, int *p_choice);
3006
3007 int main()
3008 {       int c, choice = 0;
3009         WINDOW *menu_win;
3010         MEVENT event;
3011
3012         /* Initialize curses */
3013         initscr();
3014         clear();
3015         noecho();
3016         cbreak();       //Line buffering disabled. pass on everything
3017
3018         /* Try to put the window in the middle of screen */
3019         startx = (80 - WIDTH) / 2;
3020         starty = (24 - HEIGHT) / 2;
3021         
3022         attron(A_REVERSE);
3023         mvprintw(23, 1, "Click on Exit to quit (Works best in a virtual console)");
3024         refresh();
3025         attroff(A_REVERSE);
3026
3027         /* Print the menu for the first time */
3028         menu_win = newwin(HEIGHT, WIDTH, starty, startx);
3029         print_menu(menu_win, 1);
3030         /* Get all the mouse events */
3031         mousemask(ALL_MOUSE_EVENTS, NULL);
3032         
3033         while(1)
3034         {       c = wgetch(menu_win);
3035                 switch(c)
3036                 {       case KEY_MOUSE:
3037                         if(getmouse(&amp;event) == OK)
3038                         {       /* When the user clicks left mouse button */
3039                                 if(event.bstate &amp; BUTTON1_PRESSED)
3040                                 {       report_choice(event.x + 1, event.y + 1, &amp;choice);
3041                                         if(choice == -1) //Exit chosen
3042                                                 goto end;
3043                                         mvprintw(22, 1, "Choice made is : %d String Chosen is \"%10s\"", choice, choices[choice - 1]);
3044                                         refresh(); 
3045                                 }
3046                         }
3047                         print_menu(menu_win, choice);
3048                         break;
3049                 }
3050         }               
3051 end:
3052         endwin();
3053         return 0;
3054 }
3055
3056
3057 void print_menu(WINDOW *menu_win, int highlight)
3058 {
3059         int x, y, i;    
3060
3061         x = 2;
3062         y = 2;
3063         box(menu_win, 0, 0);
3064         for(i = 0; i &lt; n_choices; ++i)
3065         {       if(highlight == i + 1)
3066                 {       wattron(menu_win, A_REVERSE); 
3067                         mvwprintw(menu_win, y, x, "%s", choices[i]);
3068                         wattroff(menu_win, A_REVERSE);
3069                 }
3070                 else
3071                         mvwprintw(menu_win, y, x, "%s", choices[i]);
3072                 ++y;
3073         }
3074         wrefresh(menu_win);
3075 }
3076
3077 /* Report the choice according to mouse position */
3078 void report_choice(int mouse_x, int mouse_y, int *p_choice)
3079 {       int i,j, choice;
3080
3081         i = startx + 2;
3082         j = starty + 3;
3083         
3084         for(choice = 0; choice &lt; n_choices; ++choice)
3085                 if(mouse_y == j + choice &amp;&amp; mouse_x &gt;= i &amp;&amp; mouse_x &lt;= i + strlen(choices[choice]))
3086                 {       if(choice == n_choices - 1)
3087                                 *p_choice = -1;         
3088                         else
3089                                 *p_choice = choice + 1; 
3090                         break;
3091                 }
3092 }</span>
3093 </pre>
3094         </div>
3095       </div>
3096
3097       <div class="SECT2">
3098         <hr>
3099
3100         <h3 class="SECT2"><a name="MISCMOUSEFUNCS" id=
3101         "MISCMOUSEFUNCS">12.4. Miscellaneous Functions</a></h3>
3102
3103         <p>The functions mouse_trafo() and wmouse_trafo() can be
3104         used to convert to mouse co-ordinates to screen relative
3105         co-ordinates. See curs_mouse(3X) man page for details.</p>
3106
3107         <p>The mouseinterval function sets the maximum time (in
3108         thousands of a second) that can elapse between press and
3109         release events in order for them to be recognized as a
3110         click. This function returns the previous interval value.
3111         The default is one fifth of a second.</p>
3112       </div>
3113     </div>
3114
3115     <div class="SECT1">
3116       <hr>
3117
3118       <h2 class="SECT1"><a name="SCREEN" id="SCREEN">13. Screen
3119       Manipulation</a></h2>
3120
3121       <p>In this section, we will look into some functions, which
3122       allow us to manage the screen efficiently and to write some
3123       fancy programs. This is especially important in writing
3124       games.</p>
3125
3126       <div class="SECT2">
3127         <hr>
3128
3129         <h3 class="SECT2"><a name="GETYX" id="GETYX">13.1. getyx()
3130         functions</a></h3>
3131
3132         <p>The function <tt class="LITERAL">getyx()</tt> can be
3133         used to find out the present cursor co-ordinates. It will
3134         fill the values of x and y co-ordinates in the arguments
3135         given to it. Since getyx() is a macro you don't have to
3136         pass the address of the variables. It can be called as</p>
3137         <pre class="PROGRAMLISTING">
3138     getyx(win, y, x);
3139     /* win: window pointer
3140      *   y, x: y, x co-ordinates will be put into this variables 
3141      */
3142 </pre>
3143
3144         <p>The function getparyx() gets the beginning co-ordinates
3145         of the sub window relative to the main window. This is some
3146         times useful to update a sub window. When designing fancy
3147         stuff like writing multiple menus, it becomes difficult to
3148         store the menu positions, their first option co-ordinates
3149         etc. A simple solution to this problem, is to create menus
3150         in sub windows and later find the starting co-ordinates of
3151         the menus by using getparyx().</p>
3152
3153         <p>The functions getbegyx() and getmaxyx() store current
3154         window's beginning and maximum co-ordinates. These
3155         functions are useful in the same way as above in managing
3156         the windows and sub windows effectively.</p>
3157       </div>
3158
3159       <div class="SECT2">
3160         <hr>
3161
3162         <h3 class="SECT2"><a name="SCREENDUMP" id=
3163         "SCREENDUMP">13.2. Screen Dumping</a></h3>
3164
3165         <p>While writing games, some times it becomes necessary to
3166         store the state of the screen and restore it back to the
3167         same state. The function scr_dump() can be used to dump the
3168         screen contents to a file given as an argument. Later it
3169         can be restored by scr_restore function. These two simple
3170         functions can be used effectively to maintain a fast moving
3171         game with changing scenarios.</p>
3172       </div>
3173
3174       <div class="SECT2">
3175         <hr>
3176
3177         <h3 class="SECT2"><a name="WINDOWDUMP" id=
3178         "WINDOWDUMP">13.3. Window Dumping</a></h3>
3179
3180         <p>To store and restore windows, the functions <tt class=
3181         "LITERAL">putwin()</tt> and <tt class=
3182         "LITERAL">getwin()</tt> can be used. <tt class=
3183         "LITERAL">putwin()</tt> puts the present window state into
3184         a file, which can be later restored by <tt class=
3185         "LITERAL">getwin()</tt>.</p>
3186
3187         <p>The function <tt class="LITERAL">copywin()</tt> can be
3188         used to copy a window completely onto another window. It
3189         takes the source and destination windows as parameters and
3190         according to the rectangle specified, it copies the
3191         rectangular region from source to destination window. It's
3192         last parameter specifies whether to overwrite or just
3193         overlay the contents on to the destination window. If this
3194         argument is true, then the copying is non-destructive.</p>
3195       </div>
3196     </div>
3197
3198     <div class="SECT1">
3199       <hr>
3200
3201       <h2 class="SECT1"><a name="MISC" id="MISC">14. Miscellaneous
3202       features</a></h2>
3203
3204       <p>Now you know enough features to write a good curses
3205       program, with all bells and whistles. There are some
3206       miscellaneous functions which are useful in various cases.
3207       Let's go headlong into some of those.</p>
3208
3209       <div class="SECT2">
3210         <hr>
3211
3212         <h3 class="SECT2"><a name="CURSSET" id="CURSSET">14.1.
3213         curs_set()</a></h3>
3214
3215         <p>This function can be used to make the cursor invisible.
3216         The parameter to this function should be</p>
3217         <pre class="PROGRAMLISTING">
3218     0 : invisible      or
3219     1 : normal    or
3220     2 : very visible.
3221 </pre>
3222       </div>
3223
3224       <div class="SECT2">
3225         <hr>
3226
3227         <h3 class="SECT2"><a name="TEMPLEAVE" id="TEMPLEAVE">14.2.
3228         Temporarily Leaving Curses mode</a></h3>
3229
3230         <p>Some times you may want to get back to cooked mode
3231         (normal line buffering mode) temporarily. In such a case