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