mirror of https://github.com/tLDP/LDP
4027 lines
150 KiB
Plaintext
4027 lines
150 KiB
Plaintext
<!--Title : NCURSES Programming Howto"
|
|
Author : Pradeep Padala
|
|
E-Mail : ppadala@gmail.com
|
|
Web-Page : http://www.eecs.umich.edu/~ppadala
|
|
-->
|
|
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
|
|
|
<article id="index">
|
|
<articleinfo>
|
|
<title> NCURSES Programming HOWTO </title>
|
|
<author>
|
|
<firstname> Pradeep </firstname>
|
|
<surname> Padala </surname>
|
|
<affiliation>
|
|
<address><email>ppadala@gmail.com</email></address>
|
|
</affiliation>
|
|
</author>
|
|
<revhistory>
|
|
|
|
<revision>
|
|
<revnumber>1.9</revnumber>
|
|
<date>2005-06-20</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>The license has been changed to the MIT-style license used
|
|
by NCURSES. Note that the programs are also re-licensed under this.
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.8</revnumber>
|
|
<date>2005-06-17</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Lots of updates. Added references and perl examples.
|
|
Changes to examples. Many grammatical and stylistic changes to the
|
|
content. Changes to NCURSES history.
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.7.1</revnumber>
|
|
<date>2002-06-25</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Added a README file for building and instructions
|
|
for building from source.
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.7</revnumber>
|
|
<date>2002-06-25</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Added "Other formats" section and made a lot of fancy
|
|
changes to the programs. Inlining of programs is gone.
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.6.1</revnumber>
|
|
<date>2002-02-24</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Removed the old Changelog section, cleaned the makefiles
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.6</revnumber>
|
|
<date>2002-02-16</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Corrected a lot of spelling mistakes, added ACS variables
|
|
section </revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.5</revnumber>
|
|
<date>2002-01-05</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Changed structure to present proper TOC</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.3.1</revnumber>
|
|
<date>2001-07-26</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Corrected maintainers paragraph, Corrected stable release number
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.3</revnumber>
|
|
<date>2001-07-24</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Added copyright notices to main document (LDP license)
|
|
and programs (GPL), Corrected
|
|
printw_example.
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.2</revnumber>
|
|
<date>2001-06-05</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Incorporated ravi's changes. Mainly to introduction, menu,
|
|
form, justforfun sections
|
|
</revremark>
|
|
</revision>
|
|
|
|
<revision>
|
|
<revnumber>1.1</revnumber>
|
|
<date>2001-05-22</date>
|
|
<authorinitials>ppadala</authorinitials>
|
|
<revremark>Added "a word about window" section, Added scanw_example.
|
|
</revremark>
|
|
</revision>
|
|
|
|
</revhistory>
|
|
<pubdate>v1.9, 2005-06-20</pubdate>
|
|
<abstract>
|
|
<para>
|
|
<emphasis>
|
|
This document is intended to be an "All in One" guide for programming with
|
|
ncurses and its sister libraries. We graduate from a simple "Hello World"
|
|
program to more complex form manipulation. No prior experience in ncurses is
|
|
assumed. Send comments to <ulink url="mailto:ppadala@gmail.com">this address
|
|
</ulink>
|
|
</emphasis>
|
|
</para>
|
|
</abstract>
|
|
|
|
</articleinfo>
|
|
|
|
<sect1 id="intro"> <title>Introduction</title>
|
|
<para>
|
|
In the olden days of teletype terminals, terminals were away from computers and
|
|
were connected to them through serial cables. The terminals could be configured
|
|
by sending a series of bytes. All the capabilities (such as
|
|
moving the cursor to a new location, erasing part of the screen, scrolling the
|
|
screen, changing modes etc.) of terminals could be accessed through these
|
|
series of bytes. These control sequences are usually called escape sequences,
|
|
because they start
|
|
with an escape(0x1B) character. Even today, with proper emulation, we can send
|
|
escape sequences to the emulator and achieve the same effect on a terminal
|
|
window.
|
|
</para>
|
|
|
|
<para>
|
|
Suppose you wanted to print a line in color. Try typing this on your console.
|
|
</para>
|
|
|
|
<programlisting>
|
|
echo "^[[0;31;40mIn Color"
|
|
</programlisting>
|
|
|
|
<para>
|
|
The first character is an escape character, which looks like two characters ^
|
|
and [. To be able to print it, you have to press CTRL+V and then the ESC key.
|
|
All the others are normal printable characters. You should be able to see the
|
|
string "In Color" in red. It stays that way and to revert back to the original
|
|
mode type this.
|
|
</para>
|
|
|
|
<programlisting>
|
|
echo "^[[0;37;40m"
|
|
</programlisting>
|
|
|
|
<para>
|
|
Now, what do these magic characters mean? Difficult to comprehend? They might
|
|
even be different for different terminals. So the designers of UNIX invented a
|
|
mechanism named <literal remap="tt">termcap</literal>. It is a file that
|
|
lists all the capabilities of a particular terminal, along with the escape
|
|
sequences needed to achieve a particular effect. In the later years, this was
|
|
replaced by <literal remap="tt">terminfo</literal>. Without delving too
|
|
much into details, this mechanism allows application
|
|
programs to query the terminfo database and obtain the control characters to be
|
|
sent to a terminal or terminal emulator.
|
|
</para>
|
|
|
|
<sect2 id="whatis"> <title> What is NCURSES? </title>
|
|
<para>
|
|
You might be wondering, what the import of all this technical gibberish is. In
|
|
the above scenario, every application program is supposed to query the terminfo
|
|
and perform the necessary stuff (sending control characters etc.). It soon became
|
|
difficult to manage this complexity and this gave birth to 'CURSES'. Curses is
|
|
a pun on the name "cursor optimization". The Curses library forms a wrapper
|
|
over working with raw terminal codes, and provides highly flexible and
|
|
efficient API (Application Programming Interface). It provides functions to
|
|
move the cursor, create windows, produce colors, play with mouse etc. The
|
|
application programs need not worry about the underlying terminal capabilities.
|
|
</para>
|
|
|
|
<para>
|
|
So what is NCURSES? NCURSES is a clone of the original System V Release 4.0
|
|
(SVr4) curses. It is a freely distributable library, fully compatible with
|
|
older version of curses. In short, it is a library of functions that manages
|
|
an application's display on character-cell terminals. In the remainder of the
|
|
document, the terms curses and ncurses are used interchangeably.
|
|
</para>
|
|
|
|
<para>
|
|
A detailed history of NCURSES can be found in the NEWS file from the source
|
|
distribution. The current package is maintained by
|
|
<ulink url="mailto:dickey@his.com">Thomas Dickey</ulink>.
|
|
You can contact the maintainers at <ulink url="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</ulink>.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="whatcanwedo"> <title>What we can do with NCURSES</title>
|
|
|
|
<para>
|
|
NCURSES not only creates a wrapper over terminal capabilities, but also gives a
|
|
robust framework to create nice looking UI (User Interface)s in text mode. It
|
|
provides functions to create windows etc. Its sister libraries panel, menu and
|
|
form provide an extension to the basic curses library. These libraries usually
|
|
come along with curses. One can create applications that contain multiple
|
|
windows, menus, panels and forms. Windows can be managed independently, can
|
|
provide 'scrollability' and even can be hidden.
|
|
</para>
|
|
|
|
<para>
|
|
Menus provide the user with an easy command selection option. Forms allow the
|
|
creation of easy-to-use data entry and display windows. Panels extend the
|
|
capabilities of ncurses to deal with overlapping and stacked windows.
|
|
</para>
|
|
|
|
<para>
|
|
These are just some of the basic things we can do with ncurses. As we move
|
|
along, We will see all the capabilities of these libraries.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="wheretogetit"><title>Where to get it</title>
|
|
|
|
<para>
|
|
All right, now that you know what you can do with ncurses, you must be rearing
|
|
to get started. NCURSES is usually shipped with your installation. In case
|
|
you don't have the library or want to compile it on your own, read on.
|
|
</para>
|
|
|
|
<para><emphasis>Compiling the package</emphasis> </para>
|
|
|
|
<para>
|
|
NCURSES can be obtained from <ulink url=
|
|
"ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz">
|
|
ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz</ulink> or any of the ftp
|
|
sites mentioned in <ulink url="http://www.gnu.org/order/ftp.html">
|
|
http://www.gnu.org/order/ftp.html</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
Read the README and INSTALL files for details on to how to install it. It
|
|
usually involves the following operations.
|
|
</para>
|
|
|
|
<programlisting>
|
|
tar zxvf ncurses<version>.tar.gz # unzip and untar the archive
|
|
cd ncurses<version> # cd to the directory
|
|
./configure # configure the build according to your
|
|
# environment
|
|
make # make it
|
|
su root # become root
|
|
make install # install it
|
|
</programlisting>
|
|
|
|
<para><emphasis>Using the RPM </emphasis></para>
|
|
|
|
<para>
|
|
NCURSES RPM can be found and downloaded from <ulink url="http://rpmfind.net">
|
|
http://rpmfind.net </ulink>. The RPM can be installed with the following
|
|
command after becoming root.
|
|
</para>
|
|
|
|
<programlisting>
|
|
rpm -i <downloaded rpm>
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="purpose"><title>Purpose/Scope of the document</title>
|
|
<para>
|
|
This document is intended to be a "All in One" guide for programming with
|
|
ncurses and its sister libraries. We graduate from a simple "Hello World"
|
|
program to more complex form manipulation. No prior experience in ncurses is
|
|
assumed. The writing is informal, but a lot of detail is provided for
|
|
each of the examples.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="aboutprograms"><title>About the Programs</title>
|
|
<para>
|
|
All the programs in the document are available in zipped form
|
|
<ulink url="http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/resources/ncurses_programs.tar.gz">
|
|
here</ulink>. Unzip and untar it. The directory structure looks like this.
|
|
</para>
|
|
|
|
<programlisting>
|
|
ncurses
|
|
|
|
|
|----> JustForFun -- just for fun programs
|
|
|----> basics -- basic programs
|
|
|----> demo -- output files go into this directory after make
|
|
| |
|
|
| |----> exe -- exe files of all example programs
|
|
|----> forms -- programs related to form library
|
|
|----> menus -- programs related to menus library
|
|
|----> panels -- programs related to panels library
|
|
|----> perl -- perl equivalents of the examples (contributed
|
|
| by Anuradha Ratnaweera)
|
|
|----> Makefile -- the top level Makefile
|
|
|----> README -- the top level README file. contains instructions
|
|
|----> COPYING -- copyright notice
|
|
</programlisting>
|
|
|
|
<para>
|
|
The individual directories contain the following files.
|
|
</para>
|
|
|
|
<programlisting>
|
|
Description of files in each directory
|
|
--------------------------------------
|
|
JustForFun
|
|
|
|
|
|----> hanoi.c -- The Towers of Hanoi Solver
|
|
|----> life.c -- The Game of Life demo
|
|
|----> magic.c -- An Odd Order Magic Square builder
|
|
|----> queens.c -- The famous N-Queens Solver
|
|
|----> shuffle.c -- A fun game, if you have time to kill
|
|
|----> tt.c -- A very trivial typing tutor
|
|
|
|
basics
|
|
|
|
|
|----> acs_vars.c -- ACS_ variables example
|
|
|----> hello_world.c -- Simple "Hello World" Program
|
|
|----> init_func_example.c -- Initialization functions example
|
|
|----> key_code.c -- Shows the scan code of the key pressed
|
|
|----> mouse_menu.c -- A menu accessible by mouse
|
|
|----> other_border.c -- Shows usage of other border functions apa
|
|
| -- rt from box()
|
|
|----> printw_example.c -- A very simple printw() example
|
|
|----> scanw_example.c -- A very simple getstr() example
|
|
|----> simple_attr.c -- A program that can print a c file with
|
|
| -- comments in attribute
|
|
|----> simple_color.c -- A simple example demonstrating colors
|
|
|----> simple_key.c -- A menu accessible with keyboard UP, DOWN
|
|
| -- arrows
|
|
|----> temp_leave.c -- Demonstrates temporarily leaving curses mode
|
|
|----> win_border.c -- Shows Creation of windows and borders
|
|
|----> with_chgat.c -- chgat() usage example
|
|
|
|
forms
|
|
|
|
|
|----> form_attrib.c -- Usage of field attributes
|
|
|----> form_options.c -- Usage of field options
|
|
|----> form_simple.c -- A simple form example
|
|
|----> form_win.c -- Demo of windows associated with forms
|
|
|
|
menus
|
|
|
|
|
|----> menu_attrib.c -- Usage of menu attributes
|
|
|----> menu_item_data.c -- Usage of item_name() etc.. functions
|
|
|----> menu_multi_column.c -- Creates multi columnar menus
|
|
|----> menu_scroll.c -- Demonstrates scrolling capability of menus
|
|
|----> menu_simple.c -- A simple menu accessed by arrow keys
|
|
|----> menu_toggle.c -- Creates multi valued menus and explains
|
|
| -- REQ_TOGGLE_ITEM
|
|
|----> menu_userptr.c -- Usage of user pointer
|
|
|----> menu_win.c -- Demo of windows associated with menus
|
|
|
|
panels
|
|
|
|
|
|----> panel_browse.c -- Panel browsing through tab. Usage of user
|
|
| -- pointer
|
|
|----> panel_hide.c -- Hiding and Un hiding of panels
|
|
|----> panel_resize.c -- Moving and resizing of panels
|
|
|----> panel_simple.c -- A simple panel example
|
|
|
|
perl
|
|
|----> 01-10.pl -- Perl equivalents of first ten example programs
|
|
</programlisting>
|
|
|
|
<para>
|
|
There is a top level Makefile included in the main directory. It builds all the
|
|
files and puts the ready-to-use exes in demo/exe directory. You can also
|
|
do selective make by going into the corresponding directory. Each directory
|
|
contains a README file explaining the purpose of each c file in the directory.
|
|
</para>
|
|
|
|
<para>
|
|
For every example, I have included path name for the file relative to the
|
|
examples directory.
|
|
</para>
|
|
|
|
<simpara> If you prefer browsing individual programs, point your browser to
|
|
<ulink
|
|
url="http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/resources/ncurses_programs/">
|
|
http://tldp.org/HOWTO/NCURSES-Programming-HOWTO/resources/ncurses_programs/
|
|
</ulink></simpara>
|
|
|
|
<para>
|
|
All the programs are released under the same license that is used by ncurses
|
|
(MIT-style). This gives you the ability to do pretty much anything other than
|
|
claiming them as yours. Feel free to use them in your programs as appropriate.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="otherformats"><title>Other Formats of the document </title>
|
|
|
|
<para>
|
|
This howto is also availabe in various other formats on the tldp.org site.
|
|
Here are the links to other formats of this document.
|
|
</para>
|
|
|
|
<sect3 id="listformats"><title>Readily available formats from tldp.org</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf">Acrobat PDF Format</ulink>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz">PostScript Format</ulink>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz">In Multiple HTML pages</ulink>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html">In One big HTML format</ulink>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="buildsource"><title> Building from source </title>
|
|
<para>
|
|
If above links are broken or if you want to experiment with sgml read on.
|
|
<programlisting>
|
|
|
|
Get both the source and the tar,gzipped programs, available at
|
|
http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
|
|
NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml
|
|
http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/
|
|
NCURSES-HOWTO/resources/ncurses_programs.tar.gz
|
|
|
|
Unzip ncurses_programs.tar.gz with
|
|
tar zxvf ncurses_programs.tar.gz
|
|
|
|
Use jade to create various formats. For example if you just want to create
|
|
the multiple html files, you would use
|
|
jade -t sgml -i html -d <path to docbook html stylesheet>
|
|
NCURSES-Programming-HOWTO.sgml
|
|
to get pdf, first create a single html file of the HOWTO with
|
|
jade -t sgml -i html -d <path to docbook html stylesheet> -V nochunks
|
|
NCURSES-Programming-HOWTO.sgml > NCURSES-ONE-BIG-FILE.html
|
|
then use htmldoc to get pdf file with
|
|
htmldoc --size universal -t pdf --firstpage p1 -f <output file name.pdf>
|
|
NCURSES-ONE-BIG-FILE.html
|
|
for ps, you would use
|
|
htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps>
|
|
NCURSES-ONE-BIG-FILE.html
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
See <ulink url="http://www.tldp.org/LDP/LDP-Author-Guide/">
|
|
LDP Author guide</ulink> for more details. If all else failes, mail me at
|
|
<ulink url= "ppadala@gmail.com">ppadala@gmail.com</ulink>
|
|
</para>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="credits"><title>Credits </title>
|
|
|
|
<para>
|
|
I thank <ulink url="mailto:sharath_1@usa.net">Sharath</ulink> and Emre Akbas for
|
|
helping me with few sections. The introduction was initially written by sharath.
|
|
I rewrote it with few excerpts taken from his initial work. Emre helped in
|
|
writing printw and scanw sections.
|
|
</para>
|
|
|
|
<para>
|
|
Perl equivalents of the example programs are contributed by <ulink
|
|
url="mailto:Aratnaweera@virtusa.com">Anuradha Ratnaweera</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
Then comes <ulink url="mailto:parimi@ece.arizona.edu">Ravi Parimi</ulink>, my
|
|
dearest friend, who has been on this project before even one line was written.
|
|
He constantly bombarded me with suggestions and patiently reviewed the whole
|
|
text. He also checked each program on Linux and Solaris.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="wishlist"><title>Wish List</title>
|
|
|
|
<para>
|
|
This is the wish list, in the order of priority. If you have a wish or you want
|
|
to work on completing the wish, mail <ulink url="mailto:ppadala@gmail.com">me
|
|
</ulink>.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
<para>Add examples to last parts of forms section.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Prepare a Demo showing all the programs and allow the user to browse through
|
|
description of each program. Let the user compile and see the program in action.
|
|
A dialog based interface is preferred.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Add debug info. _tracef, _tracemouse stuff.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Accessing termcap, terminfo using functions provided by ncurses
|
|
package.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Working on two terminals simultaneously.</para></listitem>
|
|
<listitem><para>Add more stuff to miscellaneous section.</para></listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="copyright"><title>Copyright</title>
|
|
<para>
|
|
Copyright © 2001 by Pradeep Padala. </para>
|
|
|
|
<para>
|
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
of this software and associated documentation files (the "Software"), to deal
|
|
in the Software without restriction, including without limitation the rights
|
|
to use, copy, modify, merge, publish, distribute, distribute with
|
|
modifications, sublicense, and/or sell copies of the Software, and to permit
|
|
persons to whom the Software is furnished to do so, subject to the following
|
|
conditions:
|
|
</para>
|
|
|
|
<para>
|
|
The above copyright notice and this permission notice shall be included in all
|
|
copies or substantial portions of the Software.
|
|
</para>
|
|
|
|
<para>
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
|
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
|
|
IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
</para>
|
|
|
|
<para>
|
|
Except as contained in this notice, the name(s) of the above copyright holders
|
|
shall not be used in advertising or otherwise to promote the sale, use or
|
|
other dealings in this Software without prior written authorization.
|
|
</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="helloworld"><title>Hello World !!!</title>
|
|
|
|
<para>
|
|
Welcome to the world of curses. Before we plunge into the library and look into
|
|
its various features, let's write a simple program and say
|
|
hello to the world.
|
|
</para>
|
|
|
|
<sect2 id="compilecurses"><title> Compiling With the NCURSES Library </title>
|
|
|
|
<para>
|
|
To use ncurses library functions, you have to include ncurses.h in your
|
|
programs. To link the
|
|
program with ncurses the flag -lncurses should be added.
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <ncurses.h>
|
|
.
|
|
.
|
|
.
|
|
|
|
compile and link: gcc <program file> -lncurses
|
|
</programlisting>
|
|
|
|
<example id="bhw"> <title> The Hello World !!! Program </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/hello_world.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="dissection"><title>Dissection</title>
|
|
<para>
|
|
The above program prints "Hello World !!!" to the screen and exits. This
|
|
program shows how to initialize curses and do screen manipulation and
|
|
end curses mode. Let's dissect it line by line.
|
|
</para>
|
|
|
|
<sect3 id="about-initscr"><title>About initscr()</title>
|
|
<para>
|
|
The function initscr() initializes the terminal in curses mode. In some
|
|
implementations, it clears the screen and presents a blank screen. To do any
|
|
screen manipulation using curses package this has to be called first. This
|
|
function initializes the curses system and allocates memory for our present
|
|
window (called <literal remap="tt">stdscr</literal>) and some other data-structures. Under extreme
|
|
cases this function might fail due to insufficient memory to allocate memory
|
|
for curses library's data structures.
|
|
</para>
|
|
|
|
<para>
|
|
After this is done, we can do a variety of initializations to customize
|
|
our curses settings. These details will be explained <link linkend="init">
|
|
later </link>.
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="myst-refresh"><title>The mysterious refresh()</title>
|
|
|
|
<para>
|
|
The next line printw prints the string "Hello World !!!" on to the screen. This
|
|
function is analogous to normal printf in all respects except that it prints
|
|
the data on a window called stdscr at the current (y,x) co-ordinates. Since our
|
|
present co-ordinates are at 0,0 the string is printed at the left hand corner
|
|
of the window.
|
|
</para>
|
|
|
|
<para>
|
|
This brings us to that mysterious refresh(). Well, when we called printw
|
|
the data is actually written to an imaginary window, which is not updated
|
|
on the screen yet. The job of printw is to update a few flags
|
|
and data structures and write the data to a buffer corresponding to stdscr.
|
|
In order to show it on the screen, we need to call refresh() and tell the
|
|
curses system to dump the contents on the screen.
|
|
</para>
|
|
|
|
<para>
|
|
The philosophy behind all this is to allow the programmer to do multiple updates
|
|
on the imaginary screen or windows and do a refresh once all his screen update
|
|
is done. refresh() checks the window and updates only the portion which has been
|
|
changed. This improves performance and offers greater flexibility too. But, it is
|
|
sometimes frustrating to beginners. A common mistake committed by beginners is
|
|
to forget to call refresh() after they did some update through printw() class of
|
|
functions. I still forget to add it sometimes :-)
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="about-endwin"><title>About endwin()</title>
|
|
<para>
|
|
And finally don't forget to end the curses mode. Otherwise your terminal might
|
|
behave strangely after the program quits. endwin() frees the memory taken by
|
|
curses sub-system and its data structures and puts the terminal in normal
|
|
mode. This function must be called after you are done with the curses mode.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="gory"><title>The Gory Details </title>
|
|
|
|
<para>
|
|
Now that we have seen how to write a simple curses program let's get into the
|
|
details. There are many functions that help customize what you see on screen and
|
|
many features which can be put to full use.
|
|
</para>
|
|
|
|
<simpara>Here we go...</simpara>
|
|
</sect1>
|
|
|
|
<sect1 id="init"> <title>Initialization </title>
|
|
<para>
|
|
We now know that to initialize curses system the function initscr() has to be
|
|
called. There are functions which can be called after this initialization to
|
|
customize our curses session. We may ask the curses system to set the terminal
|
|
in raw mode or initialize color or initialize the mouse etc.. Let's discuss some
|
|
of the functions that are normally called immediately after initscr();
|
|
</para>
|
|
|
|
<sect2 id="aboutinit"><title>Initialization functions</title>
|
|
<para> </para>
|
|
</sect2>
|
|
|
|
<sect2 id="rawcbreak"><title>raw() and cbreak()</title>
|
|
<para>
|
|
Normally the terminal driver buffers the characters a user types until a new
|
|
line or carriage return is encountered. But most programs require that the
|
|
characters be available as soon as the user types them. The above two functions
|
|
are used to disable line buffering. The difference between these two functions
|
|
is in the way control characters like suspend (CTRL-Z), interrupt and quit
|
|
(CTRL-C) are passed to the program. In the raw() mode these characters are
|
|
directly passed to the program without generating a signal. In the
|
|
<literal remap="tt">cbreak()</literal> mode these control characters are
|
|
interpreted as any other character by the terminal driver. I personally prefer
|
|
to use raw() as I can exercise greater control over what the user does.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="echonoecho"><title>echo() and noecho() </title>
|
|
<para>
|
|
These functions control the echoing of characters typed by the user to the
|
|
terminal. <literal remap="tt">noecho()</literal> switches off echoing. The
|
|
reason you might want to do this is to gain more control over echoing or to
|
|
suppress unnecessary echoing while taking input from the user through the
|
|
getch() etc. functions. Most of the interactive programs call
|
|
<literal remap="tt">noecho()</literal> at initialization and do the echoing
|
|
of characters in a controlled manner. It gives the programmer the flexibility
|
|
of echoing characters at any place in the window without updating current (y,x)
|
|
co-ordinates.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="keypad"><title>keypad()</title>
|
|
<para>
|
|
This is my favorite initialization function. It enables the reading of function
|
|
keys like F1, F2, arrow keys etc. Almost every interactive program enables this,
|
|
as arrow keys are a major part of any User Interface. Do
|
|
<literal remap="tt">keypad(stdscr, TRUE) </literal> to enable this feature
|
|
for the regular screen (stdscr). You will learn more about key management in
|
|
later sections of this document.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="halfdelay"><title>halfdelay()</title>
|
|
<para>
|
|
This function, though not used very often, is a useful one at times.
|
|
halfdelay()is called to enable the half-delay mode, which is similar to the
|
|
cbreak() mode in that characters typed are immediately available to program.
|
|
However, it waits for 'X' tenths of a second for input and then returns ERR, if
|
|
no input is available. 'X' is the timeout value passed to the function
|
|
halfdelay(). This function is useful when you want to ask the user for input,
|
|
and if he doesn't respond with in certain time, we can do some thing else. One
|
|
possible example is a timeout at the password prompt.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="miscinit"><title>Miscellaneous Initialization functions</title>
|
|
<para>
|
|
There are few more functions which are called at initialization to
|
|
customize curses behavior. They are not used as extensively as those mentioned
|
|
above. Some of them are explained where appropriate.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="initex"><title>An Example</title>
|
|
|
|
<simpara>
|
|
Let's write a program which will clarify the usage of these functions.
|
|
</simpara>
|
|
|
|
<example id="binfu"> <title> Initialization Function Usage example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/init_func_example.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
<para>
|
|
This program is self-explanatory. But I used functions which aren't explained
|
|
yet. The function <literal remap="tt">getch()</literal> is used to get a
|
|
character from user. It is equivalent to normal
|
|
<literal remap="tt">getchar()</literal> except that we can disable the line
|
|
buffering to avoid <enter> after input. Look for more about
|
|
<literal remap ="tt">getch()</literal>and reading keys in the <link
|
|
linkend="keys"> key management section </link>. The functions attron and attroff
|
|
are used to switch some attributes on and off respectively. In the example I
|
|
used them to print the character in bold. These functions are explained in detail
|
|
later.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="awordwindows"><title>A Word about Windows</title>
|
|
|
|
<para>
|
|
Before we plunge into the myriad ncurses functions, let me clear few things
|
|
about windows. Windows are explained in detail in following <link
|
|
linkend="windows"> sections </link>
|
|
</para>
|
|
|
|
<para>
|
|
A Window is an imaginary screen defined by curses system. A window does not mean
|
|
a bordered window which you usually see on Win9X platforms. When curses is
|
|
initialized, it creates a default window named
|
|
<literal remap="tt">stdscr</literal> which represents your 80x25 (or the size
|
|
of window in which you are running) screen. If you are doing simple tasks like
|
|
printing few strings, reading input etc., you can safely use this single window
|
|
for all of your purposes. You can also create windows and call functions which
|
|
explicitly work on the specified window.
|
|
</para>
|
|
|
|
<para>
|
|
For example, if you call
|
|
</para>
|
|
|
|
<programlisting>
|
|
printw("Hi There !!!");
|
|
refresh();
|
|
</programlisting>
|
|
|
|
<para>
|
|
It prints the string on stdscr at the present cursor position. Similarly the
|
|
call to refresh(), works on stdscr only.
|
|
</para>
|
|
|
|
<para>
|
|
Say you have created <link linkend="windows">windows</link> then you have to
|
|
call a function with a 'w' added to the usual function.
|
|
</para>
|
|
|
|
<programlisting>
|
|
wprintw(win, "Hi There !!!");
|
|
wrefresh(win);
|
|
</programlisting>
|
|
|
|
<para>
|
|
As you will see in the rest of the document, naming of functions follow the
|
|
same convention. For each function there usually are three more functions.
|
|
</para>
|
|
|
|
<programlisting>
|
|
printw(string); /* Print on stdscr at present cursor position */
|
|
mvprintw(y, x, string);/* Move to (y, x) then print string */
|
|
wprintw(win, string); /* Print on window win at present cursor position */
|
|
/* in the window */
|
|
mvwprintw(win, y, x, string); /* Move to (y, x) relative to window */
|
|
/* co-ordinates and then print */
|
|
</programlisting>
|
|
|
|
<para>
|
|
Usually the w-less functions are macros which expand to corresponding w-function
|
|
with stdscr as the window parameter.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="printw"><title>Output functions</title>
|
|
|
|
<para>
|
|
I guess you can't wait any more to see some action. Back to our odyssey of
|
|
curses functions. Now that curses is initialized, let's interact with
|
|
world.
|
|
</para>
|
|
|
|
<para>
|
|
There are three classes of functions which you can use to do output on screen.
|
|
<orderedlist>
|
|
<listitem><para>addch() class: Print single character with attributes </para>
|
|
</listitem>
|
|
<listitem><para>printw() class: Print formatted output similar to printf()
|
|
</para> </listitem>
|
|
<listitem><para>addstr() class: Print strings</para></listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
These functions can be used interchangeably and it's a matter of style as to
|
|
which class is used. Let's see each one in detail.
|
|
</para>
|
|
|
|
<sect2 id="addchclass"> <title> addch() class of functions </title>
|
|
|
|
<para>
|
|
These functions put a single character into the current cursor location and
|
|
advance the position of the cursor. You can give the character to be printed but
|
|
they usually are used to print a character with some attributes. Attributes are
|
|
explained in detail in later <link linkend="attrib"> sections </link> of the
|
|
document. If a character is associated with an attribute(bold, reverse video
|
|
etc.), when curses prints the character, it is printed in that attribute.
|
|
</para>
|
|
|
|
<para>
|
|
In order to combine a character with some attributes, you have two options:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
By OR'ing a single character with the desired attribute macros. These attribute
|
|
macros could be found in the header file
|
|
<literal remap="tt">ncurses.h</literal>. For example, you want to print a
|
|
character ch(of type char) bold and underlined, you would call addch() as below.
|
|
<programlisting>
|
|
addch(ch | A_BOLD | A_UNDERLINE);
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
By using functions like <literal remap="tt">attrset(),attron(),attroff()
|
|
</literal>. These functions are explained in the <link linkend="attrib">
|
|
Attributes</link> section. Briefly, they manipulate the current attributes of
|
|
the given window. Once set, the character printed in the window are associated
|
|
with the attributes until it is turned off.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Additionally, <literal remap="tt">curses</literal> provides some special
|
|
characters for character-based graphics. You can draw tables, horizontal or
|
|
vertical lines, etc. You can find all avaliable characters in the header file
|
|
<literal remap="tt">ncurses.h</literal>. Try looking for macros beginning
|
|
with <literal remap="tt">ACS_</literal> in this file.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2><title>mvaddch(), waddch() and mvwaddch() </title>
|
|
|
|
<para>
|
|
<literal remap="tt">mvaddch()</literal> is used to move the cursor to a
|
|
given point, and then print. Thus, the calls:
|
|
<programlisting>
|
|
move(row,col); /* moves the cursor to row<emphasis>th</emphasis> row and col<emphasis>th</emphasis> column */
|
|
addch(ch);
|
|
</programlisting>
|
|
can be replaced by
|
|
<programlisting>
|
|
mvaddch(row,col,ch);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
<literal remap="tt">waddch()</literal> is similar to
|
|
<literal remap="tt">addch()</literal>, except that it adds a character into
|
|
the given window. (Note that <literal remap="tt">addch()</literal> adds a
|
|
character into the window <literal remap="tt">stdscr</literal>.)
|
|
</para>
|
|
|
|
<para>
|
|
In a similar fashion <literal remap="tt">mvwaddch()</literal> function is
|
|
used to add a character into the given window at the given coordinates.
|
|
</para>
|
|
|
|
<para>
|
|
Now, we are familiar with the basic output function
|
|
<literal remap="tt">addch()</literal>. But, if we want to print a string, it
|
|
would be very annoying to print it character by character. Fortunately,
|
|
<literal remap="tt">ncurses</literal> provides <literal remap="tt">
|
|
printf</literal><emphasis>-like</emphasis> or
|
|
<literal remap="tt">puts</literal><emphasis>-like</emphasis> functions.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="printwclass"><title>printw() class of functions </title>
|
|
|
|
<para>
|
|
These functions are similar to <literal remap="tt">printf()</literal> with
|
|
the added capability of printing at any position on the screen.
|
|
</para>
|
|
|
|
<sect3 id="printwmvprintw"> <title>printw() and mvprintw </title>
|
|
<para>
|
|
These two functions work much like <literal remap="tt">printf()</literal>.
|
|
<literal remap="tt">mvprintw()</literal> can be used to move the cursor to a
|
|
position and then print. If you want to move the cursor first and then print
|
|
using <literal remap="tt">printw()</literal> function, use
|
|
<literal remap="tt">move() </literal> first and then use
|
|
<literal remap="tt">printw()</literal> though I see no point why one should
|
|
avoid using <literal remap="tt">mvprintw()</literal>, you have the
|
|
flexibility to manipulate.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="wprintwmvwprintw"><title>wprintw() and mvwprintw </title>
|
|
<para>
|
|
These two functions are similar to above two except that they print in the
|
|
corresponding window given as argument.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="vwprintw"><title>vwprintw()</title>
|
|
<para>
|
|
This function is similar to <literal remap="tt">vprintf()</literal>. This can
|
|
be used when variable number of arguments are to be printed.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="simpleprintwex"> <title> A Simple printw example </title>
|
|
<example id="bprex"> <title> A Simple printw example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/printw_example.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Above program demonstrates how easy it is to use <literal remap="tt">printw
|
|
</literal>. You just feed the coordinates and the message to be appeared
|
|
on the screen, then it does what you want.
|
|
</para>
|
|
|
|
<para>
|
|
The above program introduces us to a new function
|
|
<literal remap="tt">getmaxyx()</literal>, a macro defined in
|
|
<literal remap="tt">ncurses.h</literal>. It gives the number of columns and
|
|
the number of rows in a given window.
|
|
<literal remap="tt">getmaxyx()</literal> does this by updating the variables
|
|
given to it. Since <literal remap="tt">getmaxyx()</literal> is not a function
|
|
we don't pass pointers to it, we just give two integer variables.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="addstrclass"><title>addstr() class of functions </title>
|
|
|
|
<para>
|
|
<literal remap="tt">addstr()</literal> is used to put a character string into
|
|
a given window. This function is similar to calling
|
|
<literal remap="tt">addch()</literal> once for each character in a given
|
|
string. This is true for all output functions. There are other functions from
|
|
this family such as <literal remap="tt">mvaddstr(),mvwaddstr()</literal> and
|
|
<literal remap="tt">waddstr()</literal>, which obey the naming convention of
|
|
curses.(e.g. mvaddstr() is similar to the respective calls move() and then
|
|
addstr().) Another function of this family is addnstr(), which takes an integer
|
|
parameter(say n) additionally. This function puts at most n characters into the
|
|
screen. If n is negative, then the entire string will be added.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="acaution"><title>A word of caution</title>
|
|
<para>
|
|
All these functions take y co-ordinate first and then x in their arguments.
|
|
A common mistake by beginners is to pass x,y in that order. If you are
|
|
doing too many manipulations of (y,x) co-ordinates, think of dividing the
|
|
screen into windows and manipulate each one separately. Windows are explained
|
|
in the <link linkend="windows"> windows </link> section.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="scanw"><title>Input functions</title>
|
|
|
|
<para>
|
|
Well, printing without taking input, is boring. Let's see functions which
|
|
allow us to get input from user. These functions also can be divided into
|
|
three categories.
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem><para>getch() class: Get a character</para></listitem>
|
|
<listitem><para>scanw() class: Get formatted input</para></listitem>
|
|
<listitem><para>getstr() class: Get strings</para></listitem>
|
|
</orderedlist>
|
|
|
|
<sect2 id="getchclass"><title>getch() class of functions</title>
|
|
<para>
|
|
These functions read a single character from the terminal. But there are several
|
|
subtle facts to consider. For example if you don't use the function cbreak(),
|
|
curses will not read your input characters contiguously but will begin read them
|
|
only after a new line or an EOF is encountered. In order to avoid this, the
|
|
cbreak() function must used so that characters are immediately available to your
|
|
program. Another widely used function is noecho(). As the name suggests, when
|
|
this function is set (used), the characters that are keyed in by the user will
|
|
not show up on the screen. The two functions cbreak() and noecho() are typical
|
|
examples of key management. Functions of this genre are explained in the
|
|
<link linkend="keys">key management section </link>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="scanwclass"><title>scanw() class of functions</title>
|
|
<para>
|
|
These functions are similar to <literal remap="tt">scanf()</literal> with the
|
|
added capability of getting the input from any location on the screen.
|
|
</para>
|
|
|
|
<sect3 id="scanwmvscanw"><title>scanw() and mvscanw </title>
|
|
<para>
|
|
The usage of these functions is similar to that of
|
|
<literal remap="tt">sscanf()</literal>, where the line to be scanned is
|
|
provided by <literal remap="tt">wgetstr()</literal> function. That is, these
|
|
functions call to <literal remap="tt">wgetstr()</literal> function(explained
|
|
below) and uses the resulting line for a scan.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="wscanwmvwscanw"><title>wscanw() and mvwscanw()</title>
|
|
<para>
|
|
These are similar to above two functions except that they read from a window,
|
|
which is supplied as one of the arguments to these functions.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="vwscanw"><title>vwscanw()</title>
|
|
<para>
|
|
This function is similar to <literal remap="tt">vscanf()</literal>. This can
|
|
be used when a variable number of arguments are to be scanned.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="getstrclass"><title>getstr() class of functions </title>
|
|
<para>
|
|
These functions are used to get strings from the terminal. In essence, this
|
|
function performs the same task as would be achieved by a series of calls to
|
|
<literal remap="tt">getch()</literal> until a newline, carriage return, or
|
|
end-of-file is received. The resulting string of characters are pointed to by
|
|
<literal remap="tt">str</literal>, which is a character pointer provided by
|
|
the user.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="getstrex"><title>Some examples</title>
|
|
<example id="bscex"> <title> A Simple scanw example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/scanw_example.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="attrib"><title>Attributes</title>
|
|
<para>
|
|
We have seen an example of how attributes can be used to print characters with
|
|
some special effects. Attributes, when set prudently, can present information in
|
|
an easy, understandable manner. The following program takes a C file as input
|
|
and prints the file with comments in bold. Scan through the code.
|
|
</para>
|
|
|
|
<example id="bsiat"> <title> A Simple Attributes example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/simple_attr.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Don't worry about all those initialization and other crap. Concentrate on
|
|
the while loop. It reads each character in the file and searches for the
|
|
pattern /*. Once it spots the pattern, it switches the BOLD attribute on with
|
|
<literal remap="tt"> attron()</literal> . When we get the pattern */ it is
|
|
switched off by <literal remap="tt"> attroff()</literal> .
|
|
</para>
|
|
|
|
<para>
|
|
The above program also introduces us to two useful functions
|
|
<literal remap="tt">getyx() </literal> and
|
|
<literal remap="tt">move()</literal>. The first function gets the
|
|
co-ordinates of the present cursor into the variables y, x. Since getyx() is a
|
|
macro we don't have to pass pointers to variables. The function
|
|
<literal remap="tt">move()</literal> moves the cursor to the co-ordinates
|
|
given to it.
|
|
</para>
|
|
|
|
<para>
|
|
The above program is really a simple one which doesn't do much. On these lines
|
|
one could write a more useful program which reads a C file, parses it and prints
|
|
it in different colors. One could even extend it to other languages as well.
|
|
</para>
|
|
|
|
<sect2 id="attribdetails"><title>The details</title>
|
|
|
|
<para>
|
|
Let's get into more details of attributes. The functions <literal remap="tt">
|
|
attron(), attroff(), attrset() </literal>, and their sister functions
|
|
<literal remap="tt"> attr_get()</literal> etc.. can be used to switch
|
|
attributes on/off , get attributes and produce a colorful display.
|
|
</para>
|
|
|
|
<para>
|
|
The functions attron and attroff take a bit-mask of attributes and switch them
|
|
on or off, respectively. The following video attributes, which are defined in
|
|
<curses.h> can be passed to these functions.
|
|
</para>
|
|
|
|
<programlisting>
|
|
|
|
A_NORMAL Normal display (no highlight)
|
|
A_STANDOUT Best highlighting mode of the terminal.
|
|
A_UNDERLINE Underlining
|
|
A_REVERSE Reverse video
|
|
A_BLINK Blinking
|
|
A_DIM Half bright
|
|
A_BOLD Extra bright or bold
|
|
A_PROTECT Protected mode
|
|
A_INVIS Invisible or blank mode
|
|
A_ALTCHARSET Alternate character set
|
|
A_CHARTEXT Bit-mask to extract a character
|
|
COLOR_PAIR(n) Color-pair number n
|
|
|
|
</programlisting>
|
|
|
|
<para>
|
|
The last one is the most colorful one :-) Colors are explained in the
|
|
<ulink url="#color">next sections</ulink>.
|
|
</para>
|
|
|
|
<para>
|
|
We can OR(|) any number of above attributes to get a combined effect. If you
|
|
wanted reverse video with blinking characters you can use
|
|
</para>
|
|
|
|
<programlisting>
|
|
attron(A_REVERSE | A_BLINK);
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="attronvsattrset"><title>attron() vs attrset() </title>
|
|
|
|
<para>
|
|
Then what is the difference between attron() and attrset()? attrset sets the
|
|
attributes of window whereas attron just switches on the attribute given to it.
|
|
So attrset() fully overrides whatever attributes the window previously had and
|
|
sets it to the new attribute(s). Similarly attroff() just switches off the
|
|
attribute(s) given to it as an argument. This gives us the flexibility of
|
|
managing attributes easily.But if you use them carelessly you may loose track of
|
|
what attributes the window has and garble the display. This is especially true
|
|
while managing menus with colors and highlighting. So decide on a consistent
|
|
policy and stick to it. You can always use <literal remap="tt"> standend()
|
|
</literal> which is equivalent to <literal remap="tt"> attrset(A_NORMAL)
|
|
</literal> which turns off all attributes and brings you to normal mode.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- jade forbids underscore in id="" attribute; thus attr-get -->
|
|
<sect2 id="attr-get"><title>attr_get()</title>
|
|
|
|
<para>
|
|
|
|
The function attr_get() gets the current attributes and color pair of the
|
|
window. Though we might not use this as often as the above functions, this is
|
|
useful in scanning areas of screen. Say we wanted to do some complex update on
|
|
screen and we are not sure what attribute each character is associated with.
|
|
Then this function can be used with either attrset or attron to produce the
|
|
desired effect.
|
|
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- jade forbids underscore in id="" attribute; thus attr-funcs -->
|
|
<sect2 id="attr-funcs"><title>attr_ functions</title>
|
|
<para>
|
|
There are series of functions like attr_set(), attr_on etc.. These are similar
|
|
to above functions except that they take parameters of type
|
|
<literal remap="tt">attr_t</literal>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="wattrfuncs"><title>wattr functions</title>
|
|
<para>
|
|
For each of the above functions we have a corresponding function with 'w' which
|
|
operates on a particular window. The above functions operate on stdscr.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="chgat"><title>chgat() functions</title>
|
|
<para>
|
|
The function chgat() is listed in the end of the man page curs_attr. It actually
|
|
is a useful one. This function can be used to set attributes for a group of
|
|
characters without moving. I mean it !!! without moving the cursor :-) It
|
|
changes the attributes of a given number of characters starting at the current
|
|
cursor location.
|
|
</para>
|
|
|
|
<para>
|
|
We can give -1 as the character count to update till end of line. If you want to
|
|
change attributes of characters from current position to end of line, just use
|
|
this.
|
|
</para>
|
|
|
|
<programlisting>
|
|
chgat(-1, A_REVERSE, 0, NULL);
|
|
</programlisting>
|
|
|
|
<para>
|
|
This function is useful when changing attributes for characters that are
|
|
already on the screen. Move to the character from which you want to change and
|
|
change the attribute.
|
|
</para>
|
|
|
|
<para>
|
|
Other functions wchgat(), mvchgat(), wchgat() behave similarly except that the w
|
|
functions operate on the particular window. The mv functions first move the
|
|
cursor then perform the work given to them. Actually chgat is a macro which is
|
|
replaced by a wchgat() with stdscr as the window. Most of the "w-less" functions
|
|
are macros.
|
|
</para>
|
|
|
|
<example id="bwich"> <title> Chgat() Usage example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/with_chgat.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
This example also introduces us to the color world of curses. Colors will be
|
|
explained in detail later. Use 0 for no color.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="windows"><title>Windows</title>
|
|
<para>
|
|
Windows form the most important concept in curses. You have seen the standard
|
|
window stdscr above where all the functions implicitly operated on this window.
|
|
Now to make design even a simplest GUI, you need to resort to windows. The main
|
|
reason you may want to use windows is to manipulate parts of the screen
|
|
separately, for better efficiency, by updating only the windows that need to be
|
|
changed and for a better design. I would say the last reason is the most
|
|
important in going for windows. You should always strive for a better and
|
|
easy-to-manage design in your programs. If you are writing big, complex GUIs
|
|
this is of pivotal importance before you start doing anything.
|
|
</para>
|
|
|
|
<sect2 id="windowbasics"><title>The basics</title>
|
|
|
|
<para>
|
|
A Window can be created by calling the function
|
|
<literal remap="tt">newwin()</literal>. It doesn't create any thing on the
|
|
screen actually. It allocates memory for a structure to manipulate the window
|
|
and updates the structure with data regarding the window like it's size, beginy,
|
|
beginx etc.. Hence in curses, a window is just an abstraction of an imaginary
|
|
window, which can be manipulated independent of other parts of screen. The
|
|
function newwin() returns a pointer to structure WINDOW, which can be passed to
|
|
window related functions like wprintw() etc.. Finally the window can be
|
|
destroyed with delwin(). It will deallocate the memory associated with the
|
|
window structure.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="letbewindow"><title>Let there be a Window !!!</title>
|
|
<para>
|
|
What fun is it, if a window is created and we can't see it. So the fun part
|
|
begins by displaying the window. The function
|
|
<literal remap="tt">box()</literal> can be used to draw a border around the
|
|
window. Let's explore these functions in more detail in this example.
|
|
</para>
|
|
|
|
<example id="bwibo"> <title>Window Border example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/win_border.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="borderexexpl"><title>Explanation</title>
|
|
|
|
<para>
|
|
Don't scream. I know it's a big example. But I have to explain some important
|
|
things here :-). This program creates a rectangular window that can be moved
|
|
with left, right, up, down arrow keys. It repeatedly creates and destroys
|
|
windows as user press a key. Don't go beyond the screen limits. Checking for
|
|
those limits is left as an exercise for the reader. Let's dissect it by line by line.
|
|
</para>
|
|
|
|
<para>
|
|
The <literal remap="tt">create_newwin()</literal> function creates a window
|
|
with <literal remap="tt">newwin() </literal> and displays a border around it
|
|
with box. The function <literal remap="tt"> destroy_win()</literal> first
|
|
erases the window from screen by painting a border with ' ' character and then
|
|
calling <literal remap="tt">delwin()</literal> to deallocate memory related
|
|
to it. Depending on the key the user presses, starty or startx is changed and a
|
|
new window is created.
|
|
</para>
|
|
|
|
<para>
|
|
In the destroy_win, as you can see, I used wborder instead of box. The reason is
|
|
written in the comments (You missed it. I know. Read the code :-)). wborder
|
|
draws a border around the window with the characters given to it as the 4 corner
|
|
points and the 4 lines. To put it clearly, if you have called wborder as below:
|
|
<programlisting>
|
|
wborder(win, '|', '|', '-', '-', '+', '+', '+', '+');
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
it produces some thing like
|
|
</para>
|
|
|
|
<programlisting>
|
|
+------------+
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
+------------+
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="otherstuff"><title>The other stuff in the example</title>
|
|
<para>
|
|
You can also see in the above examples, that I have used the variables COLS,
|
|
LINES which are initialized to the screen sizes after initscr(). They can be
|
|
useful in finding screen dimensions and finding the center co-ordinate of the
|
|
screen as above. The function <literal remap="tt">getch()</literal> as usual
|
|
gets the key from keyboard and according to the key it does the corresponding
|
|
work. This type of switch- case is very common in any GUI based programs.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="otherborderfuncs"><title>Other Border functions</title>
|
|
<para>
|
|
Above program is grossly inefficient in that with each press of a key, a window
|
|
is destroyed and another is created. So let's write a more efficient program
|
|
which uses other border related functions.
|
|
</para>
|
|
|
|
<para>
|
|
The following program uses <literal remap="tt">mvhline()</literal> and
|
|
<literal remap="tt">mvvline()</literal> to achieve similar effect. These two
|
|
functions are simple. They create a horizontal or vertical line of the specified
|
|
length at the specified position.
|
|
</para>
|
|
|
|
<example id="botbo"><title> More border functions</title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/other_border.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="color"><title>Colors</title>
|
|
<sect2 id="colorbasics"><title> The basics </title>
|
|
<para>
|
|
Life seems dull with no colors. Curses has a nice mechanism to handle colors.
|
|
Let's get into the thick of the things with a small program.
|
|
</para>
|
|
<example id="bsico"> <title> A Simple Color example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/simple_color.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
As you can see, to start using color, you should first call the function
|
|
<literal remap="tt"> start_color()</literal>. After that, you can use color
|
|
capabilities of your terminals using various functions. To find out whether a
|
|
terminal has color capabilities or not, you can use
|
|
<literal remap="tt">has_colors()</literal> function, which returns FALSE if
|
|
the terminal does not support color.
|
|
</para>
|
|
|
|
<para>
|
|
Curses initializes all the colors supported by terminal when start_color() is
|
|
called. These can be accessed by the define constants like
|
|
<literal remap="tt">COLOR_BLACK </literal> etc. Now to actually start using
|
|
colors, you have to define pairs. Colors are always used in pairs. That means
|
|
you have to use the function <literal remap="tt">init_pair() </literal> to
|
|
define the foreground and background for the pair number you give. After that
|
|
that pair number can be used as a normal attribute with <literal remap="tt">
|
|
COLOR_PAIR()</literal>function. This may seem to be cumbersome at first.
|
|
But this elegant solution allows us to manage color pairs very easily. To
|
|
appreciate it, you have to look into the source code of "dialog", a utility
|
|
for displaying dialog boxes from shell scripts. The developers have defined
|
|
foreground and background combinations for all the colors they might need and
|
|
initialized at the beginning. This makes it very easy to set attributes just by
|
|
accessing a pair which we already have defined as a constant.
|
|
</para>
|
|
|
|
<para>
|
|
The following colors are defined in <literal remap="tt">curses.h</literal>.
|
|
You can use these as parameters for various color functions.
|
|
<programlisting>
|
|
COLOR_BLACK 0
|
|
COLOR_RED 1
|
|
COLOR_GREEN 2
|
|
COLOR_YELLOW 3
|
|
COLOR_BLUE 4
|
|
COLOR_MAGENTA 5
|
|
COLOR_CYAN 6
|
|
COLOR_WHITE 7
|
|
</programlisting>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="changecolordefs"><title>Changing Color Definitions </title>
|
|
|
|
<para>
|
|
The function <literal remap="tt">init_color()</literal>can be used to change
|
|
the rgb values for the colors defined by curses initially. Say you wanted to
|
|
lighten the intensity of red color by a minuscule. Then you can use this
|
|
function as
|
|
</para>
|
|
|
|
<programlisting>
|
|
init_color(COLOR_RED, 700, 0, 0);
|
|
/* param 1 : color name
|
|
* param 2, 3, 4 : rgb content min = 0, max = 1000 */
|
|
</programlisting>
|
|
|
|
<para>
|
|
If your terminal cannot change the color definitions, the function returns ERR.
|
|
The function <literal remap="tt">can_change_color()</literal> can be used to
|
|
find out whether the terminal has the capability of changing color content or
|
|
not. The rgb content is scaled from 0 to 1000. Initially RED color is defined
|
|
with content 1000(r), 0(g), 0(b).
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="colorcontent"><title>Color Content </title>
|
|
<para>
|
|
The functions <literal remap="tt">color_content()</literal> and
|
|
<literal remap="tt">pair_content()</literal> can be used to find the color
|
|
content and foreground, background combination for the pair.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="keys"> <title>Interfacing with the key board</title>
|
|
|
|
<sect2 id="keysbasics"><title>The Basics </title>
|
|
|
|
<para>
|
|
No GUI is complete without a strong user interface and to interact with the
|
|
user, a curses program should be sensitive to key presses or the mouse actions
|
|
done by the user. Let's deal with the keys first.
|
|
</para>
|
|
|
|
<para>
|
|
As you have seen in almost all of the above examples, it's very easy to get key
|
|
input from the user. A simple way of getting key presses is to use
|
|
<literal remap="tt">getch()</literal> function. The cbreak mode should be
|
|
enabled to read keys when you are interested in reading individual key hits
|
|
rather than complete lines of text (which usually end with a carriage return).
|
|
keypad should be enabled to get the Functions keys, arrow keys etc. See the
|
|
initialization section for details.
|
|
</para>
|
|
|
|
<para>
|
|
<literal remap="tt">getch()</literal> returns an integer corresponding to the
|
|
key pressed. If it is a normal character, the integer value will be equivalent
|
|
to the character. Otherwise it returns a number which can be matched with the
|
|
constants defined in <literal remap="tt">curses.h</literal>. For example if
|
|
the user presses F1, the integer returned is 265. This can be checked using the
|
|
macro KEY_F() defined in curses.h. This makes reading keys portable and easy to
|
|
manage.
|
|
</para>
|
|
|
|
<para>
|
|
For example, if you call getch() like this
|
|
</para>
|
|
|
|
<programlisting>
|
|
int ch;
|
|
|
|
ch = getch();
|
|
</programlisting>
|
|
|
|
<para>
|
|
getch() will wait for the user to press a key, (unless you specified a timeout)
|
|
and when user presses a key, the corresponding integer is returned. Then you can
|
|
check the value returned with the constants defined in curses.h to match against
|
|
the keys you want.
|
|
</para>
|
|
|
|
<para>
|
|
The following code piece will do that job.
|
|
</para>
|
|
|
|
<programlisting>
|
|
if(ch == KEY_LEFT)
|
|
printw("Left arrow is pressed\n");
|
|
</programlisting>
|
|
|
|
<para>
|
|
Let's write a small program which creates a menu which can be navigated by up
|
|
and down arrows.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="simplekeyex"> <title>A Simple Key Usage example </title>
|
|
<example id="bsike"><title> A Simple Key Usage example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/simple_key.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="mouse"> <title>Interfacing with the mouse </title>
|
|
|
|
<para>
|
|
Now that you have seen how to get keys, lets do the same thing from mouse.
|
|
Usually each UI allows the user to interact with both keyboard and mouse.
|
|
</para>
|
|
|
|
<sect2 id="mousebasics"> <title> The Basics </title>
|
|
|
|
<para>
|
|
Before you do any thing else, the events you want to receive have to be enabled
|
|
with <literal remap="tt">mousemask()</literal>.
|
|
</para>
|
|
|
|
<programlisting>
|
|
mousemask( mmask_t newmask, /* The events you want to listen to */
|
|
mmask_t *oldmask) /* The old events mask */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The first parameter to above function is a bit mask of events you would like to
|
|
listen. By default, all the events are turned off. The bit mask <literal
|
|
remap="tt"> ALL_MOUSE_EVENTS</literal> can be used to get all the events.
|
|
</para>
|
|
|
|
<para>
|
|
The following are all the event masks:
|
|
</para>
|
|
|
|
<programlisting>
|
|
Name Description
|
|
---------------------------------------------------------------------
|
|
BUTTON1_PRESSED mouse button 1 down
|
|
BUTTON1_RELEASED mouse button 1 up
|
|
BUTTON1_CLICKED mouse button 1 clicked
|
|
BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked
|
|
BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked
|
|
BUTTON2_PRESSED mouse button 2 down
|
|
BUTTON2_RELEASED mouse button 2 up
|
|
BUTTON2_CLICKED mouse button 2 clicked
|
|
BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked
|
|
BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked
|
|
BUTTON3_PRESSED mouse button 3 down
|
|
BUTTON3_RELEASED mouse button 3 up
|
|
BUTTON3_CLICKED mouse button 3 clicked
|
|
BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked
|
|
BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked
|
|
BUTTON4_PRESSED mouse button 4 down
|
|
BUTTON4_RELEASED mouse button 4 up
|
|
BUTTON4_CLICKED mouse button 4 clicked
|
|
BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked
|
|
BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked
|
|
BUTTON_SHIFT shift was down during button state change
|
|
BUTTON_CTRL control was down during button state change
|
|
BUTTON_ALT alt was down during button state change
|
|
ALL_MOUSE_EVENTS report all button state changes
|
|
REPORT_MOUSE_POSITION report mouse movement
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="gettingevents"> <title> Getting the events </title>
|
|
<para>
|
|
Once a class of mouse events have been enabled, getch() class of functions
|
|
return KEY_MOUSE every time some mouse event happens. Then the mouse event can
|
|
be retrieved with <literal remap="tt">getmouse()</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The code approximately looks like this:
|
|
</para>
|
|
|
|
<programlisting>
|
|
MEVENT event;
|
|
|
|
ch = getch();
|
|
if(ch == KEY_MOUSE)
|
|
if(getmouse(&event) == OK)
|
|
. /* Do some thing with the event */
|
|
.
|
|
.
|
|
</programlisting>
|
|
|
|
<para>
|
|
getmouse() returns the event into the pointer given to it. It's a structure
|
|
which contains
|
|
</para>
|
|
|
|
<programlisting>
|
|
typedef struct
|
|
{
|
|
short id; /* ID to distinguish multiple devices */
|
|
int x, y, z; /* event coordinates */
|
|
mmask_t bstate; /* button state bits */
|
|
}
|
|
</programlisting>
|
|
|
|
<para>
|
|
The <literal remap="tt">bstate</literal> is the main variable we are
|
|
interested in. It tells the button state of the mouse.
|
|
</para>
|
|
|
|
<para>
|
|
Then with a code snippet like the following, we can find out what happened.
|
|
</para>
|
|
|
|
<programlisting>
|
|
if(event.bstate & BUTTON1_PRESSED)
|
|
printw("Left Button Pressed");
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="mousetogether"> <title> Putting it all Together </title>
|
|
|
|
<para>
|
|
That's pretty much interfacing with mouse. Let's create the same menu and enable
|
|
mouse interaction. To make things simpler, key handling is removed.
|
|
</para>
|
|
|
|
<example id="bmome"> <title> Access the menu with mouse !!! </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/mouse_menu.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="miscmousefuncs"> <title> Miscellaneous Functions </title>
|
|
|
|
<para>
|
|
The functions mouse_trafo() and wmouse_trafo() can be used to convert to mouse
|
|
co-ordinates to screen relative co-ordinates. See curs_mouse(3X) man page for details.
|
|
</para>
|
|
|
|
<para>
|
|
The mouseinterval function sets the maximum time (in thousands of a
|
|
second) that can elapse between press and release events in order for
|
|
them to be recognized as a click. This function returns the previous
|
|
interval value. The default is one fifth of a second.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="screen"><title>Screen Manipulation</title>
|
|
<para>
|
|
In this section, we will look into some functions, which allow us to manage the
|
|
screen efficiently and to write some fancy programs. This is especially
|
|
important in writing games.
|
|
</para>
|
|
|
|
<sect2 id="getyx"><title>getyx() functions </title>
|
|
<para>
|
|
|
|
The function <literal remap="tt">getyx()</literal> can be used to find out
|
|
the present cursor co-ordinates. It will fill the values of x and y co-ordinates
|
|
in the arguments given to it. Since getyx() is a macro you don't have to pass
|
|
the address of the variables. It can be called as
|
|
</para>
|
|
|
|
<programlisting>
|
|
getyx(win, y, x);
|
|
/* win: window pointer
|
|
* y, x: y, x co-ordinates will be put into this variables
|
|
*/
|
|
</programlisting>
|
|
|
|
<para>
|
|
The function getparyx() gets the beginning co-ordinates of the sub window
|
|
relative to the main window. This is some times useful to update a sub window.
|
|
When designing fancy stuff like writing multiple menus, it becomes difficult to
|
|
store the menu positions, their first option co-ordinates etc. A simple solution
|
|
to this problem, is to create menus in sub windows and later find the starting
|
|
co-ordinates of the menus by using getparyx().
|
|
</para>
|
|
|
|
<para>
|
|
The functions getbegyx() and getmaxyx() store current window's beginning and
|
|
maximum co-ordinates. These functions are useful in the same way as above in
|
|
managing the windows and sub windows effectively.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="screendump"><title>Screen Dumping </title>
|
|
<para>
|
|
While writing games, some times it becomes necessary to store the state of the
|
|
screen and restore it back to the same state. The function scr_dump() can be
|
|
used to dump the screen contents to a file given as an argument. Later it can be
|
|
restored by scr_restore function. These two simple functions can be used
|
|
effectively to maintain a fast moving game with changing scenarios.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="windowdump"><title>Window Dumping </title>
|
|
<para>
|
|
To store and restore windows, the functions
|
|
<literal remap="tt">putwin()</literal> and <literal remap="tt">getwin()
|
|
</literal> can be used. <literal remap="tt">putwin()</literal> puts
|
|
the present window state into a file, which can be later restored by
|
|
<literal remap="tt">getwin()</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
The function <literal remap="tt">copywin()</literal> can be used to copy a
|
|
window completely onto another window. It takes the source and destination
|
|
windows as parameters and according to the rectangle specified, it copies the
|
|
rectangular region from source to destination window. It's last parameter
|
|
specifies whether to overwrite or just overlay the contents on to the
|
|
destination window. If this argument is true, then the copying is
|
|
non-destructive.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="misc"><title>Miscellaneous features</title>
|
|
|
|
<para>
|
|
Now you know enough features to write a good curses program, with all bells and
|
|
whistles. There are some miscellaneous functions which are useful in various
|
|
cases. Let's go headlong into some of those.
|
|
</para>
|
|
|
|
<sect2 id="cursset"><title>curs_set() </title>
|
|
<para>
|
|
This function can be used to make the cursor invisible. The parameter to this
|
|
function should be
|
|
</para>
|
|
|
|
<programlisting>
|
|
0 : invisible or
|
|
1 : normal or
|
|
2 : very visible.
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="templeave"><title>Temporarily Leaving Curses mode </title>
|
|
|
|
<para>
|
|
Some times you may want to get back to cooked mode (normal line buffering mode)
|
|
temporarily. In such a case you will first need to save the tty modes with a
|
|
call to <literal remap="tt">def_prog_mode()</literal> and then call
|
|
<literal remap="tt">endwin()</literal> to end the curses mode. This will
|
|
leave you in the original tty mode. To get back to curses once you are done,
|
|
call <literal remap="tt">reset_prog_mode() </literal>. This function returns
|
|
the tty to the state stored by <literal remap="tt">def_prog_mode()
|
|
</literal>. Then do refresh(), and you are back to the curses mode. Here
|
|
is an example showing the sequence of things to be done.
|
|
</para>
|
|
|
|
<example id="btele"> <title> Temporarily Leaving Curses Mode </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/temp_leave.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="acsvars"><title>ACS_ variables </title>
|
|
|
|
<para>
|
|
If you have ever programmed in DOS, you know about those nifty characters in
|
|
extended character set. They are printable only on some terminals. NCURSES
|
|
functions like <literal remap="tt">box()</literal> use these characters. All
|
|
these variables start with ACS meaning alternative character set. You might have
|
|
noticed me using these characters in some of the programs above. Here's an example
|
|
showing all the characters.
|
|
</para>
|
|
|
|
<example id="bacsvars"> <title> ACS Variables Example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/basics/acs_vars.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="otherlib"><title> Other libraries </title>
|
|
|
|
<para>
|
|
Apart from the curses library, there are few text mode libraries, which provide
|
|
more functionality and a lot of features. The following sections explain three
|
|
standard libraries which are usually distributed along with curses.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="panels"><title> Panel Library</title>
|
|
|
|
<para>
|
|
Now that you are proficient in curses, you wanted to do some thing big. You
|
|
created a lot of overlapping windows to give a professional windows-type look.
|
|
Unfortunately, it soon becomes difficult to manage these. The multiple
|
|
refreshes, updates plunge you into a nightmare. The overlapping windows create
|
|
blotches, whenever you forget to refresh the windows in the proper order.
|
|
</para>
|
|
|
|
<para>
|
|
Don't despair. There's an elegant solution provided in panels library. In the
|
|
words of developers of ncurses
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>
|
|
When your interface design is such that windows may dive deeper into the
|
|
visibility stack or pop to the top at runtime, the resulting book-keeping can be
|
|
tedious and difficult to get right. Hence the panels library.
|
|
</emphasis>
|
|
</para>
|
|
|
|
<para>
|
|
If you have lot of overlapping windows, then panels library is the way to go. It
|
|
obviates the need of doing series of wnoutrefresh(), doupdate() and relieves the
|
|
burden of doing it correctly(bottom up). The library maintains information about
|
|
the order of windows, their overlapping and update the screen properly. So why
|
|
wait? Let's take a close peek into panels.
|
|
</para>
|
|
|
|
<sect2 id="panelbasics"><title> The Basics </title>
|
|
<para>
|
|
Panel object is a window that is implicitly treated as part of a deck including
|
|
all other panel objects. The deck is treated as a stack with the top panel being
|
|
completely visible and the other panels may or may not be obscured according to
|
|
their positions. So the basic idea is to create a stack of overlapping panels
|
|
and use panels library to display them correctly. There is a function similar to
|
|
refresh() which, when called , displays panels in the correct order. Functions
|
|
are provided to hide or show panels, move panels, change its size etc.. The
|
|
overlapping problem is managed by the panels library during all the calls to
|
|
these functions.
|
|
</para>
|
|
|
|
<para>
|
|
The general flow of a panel program goes like this:
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Create the windows (with newwin()) to be attached to the panels.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Create panels with the chosen visibility order. Stack them up according to the
|
|
desired visibility. The function new_panel() is used to created panels.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Call update_panels() to write the panels to the virtual screen in correct
|
|
visibility order. Do a doupdate() to show it on the screen.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Mainpulate the panels with show_panel(), hide_panel(), move_panel() etc. Make
|
|
use of helper functions like panel_hidden() and panel_window(). Make use of user
|
|
pointer to store custom data for a panel. Use the functions set_panel_userptr()
|
|
and panel_userptr() to set and get the user pointer for a panel.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
When you are done with the panel use del_panel() to delete the panel.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Let's make the concepts clear, with some programs. The following is a simple
|
|
program which creates 3 overlapping panels and shows them on the screen.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="compilepanels"><title> Compiling With the Panels Library </title>
|
|
|
|
<para>
|
|
To use panels library functions, you have to include panel.h and to link the
|
|
program with panels library the flag -lpanel should be added along with
|
|
-lncurses in that order.
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <panel.h>
|
|
.
|
|
.
|
|
.
|
|
|
|
compile and link: gcc <program file> -lpanel -lncurses
|
|
</programlisting>
|
|
|
|
<example id="ppasi"><title> Panel basics</title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/panels/panel_simple.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
As you can see, above program follows a simple flow as explained. The windows
|
|
are created with newwin() and then they are attached to panels with new_panel().
|
|
As we attach one panel after another, the stack of panels gets updated. To put
|
|
them on screen update_panels() and doupdate() are called.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id ="panelbrowsing"> <title> Panel Window Browsing </title>
|
|
<para>
|
|
A slightly complicated example is given below. This program creates 3
|
|
windows which can be cycled through using tab. Have a look at the code.
|
|
</para>
|
|
|
|
<example id="ppabr"><title> Panel Window Browsing Example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/panels/panel_browse.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="userptrusing"><title> Using User Pointers </title>
|
|
<para>
|
|
In the above example I used user pointers to find out the next window in the
|
|
cycle. We can attach custom information to the panel by specifying a user
|
|
pointer, which can point to any information you want to store. In this case I
|
|
stored the pointer to the next panel in the cycle. User pointer for a panel can
|
|
be set with the function <literal remap="tt"> set_panel_userptr()</literal>.
|
|
It can be accessed using the function <literal remap="tt">panel_userptr()
|
|
</literal> which will return the user pointer for the panel given as
|
|
argument. After finding the next panel in the cycle It's brought to the top by
|
|
the function top_panel(). This function brings the panel given as argument to
|
|
the top of the panel stack.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="panelmoveresize"><title> Moving and Resizing Panels </title>
|
|
<para>
|
|
The function <literal remap="tt">move_panel()</literal> can be used to move a
|
|
panel to the desired location. It does not change the position of the panel in
|
|
the stack. Make sure that you use move_panel() instead mvwin() on the window
|
|
associated with the panel.
|
|
</para>
|
|
|
|
<para>
|
|
Resizing a panel is slightly complex. There is no straight forward function
|
|
just to resize the window associated with a panel. A solution to resize a panel
|
|
is to create a new window with the desired sizes, change the window associated
|
|
with the panel using replace_panel(). Don't forget to delete the old window. The
|
|
window associated with a panel can be found by using the function
|
|
panel_window().
|
|
</para>
|
|
|
|
<para>
|
|
The following program shows these concepts, in supposedly simple program. You
|
|
can cycle through the window with <TAB> as usual. To resize or move the
|
|
active panel press 'r' for resize 'm' for moving. Then use arrow keys to resize
|
|
or move it to the desired way and press enter to end your resizing or moving.
|
|
This example makes use of user data to get the required data to do the
|
|
operations.
|
|
</para>
|
|
|
|
<example id="ppare"><title> Panel Moving and Resizing example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/panels/panel_resize.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Concentrate on the main while loop. Once it finds out the type of key pressed,
|
|
it takes appropriate action. If 'r' is pressed resizing mode is started. After
|
|
this the new sizes are updated as the user presses the arrow keys. When the user
|
|
presses <ENTER> present selection ends and panel is resized by using the
|
|
concept explained. While in resizing mode the program doesn't show how the
|
|
window is getting resized. It's left as an exercise to the reader to print a
|
|
dotted border while it gets resized to a new position.
|
|
</para>
|
|
|
|
<para>
|
|
When the user presses 'm' the move mode starts. This is a bit simpler than
|
|
resizing. As the arrow keys are pressed the new position is updated and
|
|
pressing of <ENTER> causes the panel to be moved by calling the function
|
|
move_panel().
|
|
</para>
|
|
|
|
<para>
|
|
In this program the user data which is represented as PANEL_DATA, plays very
|
|
important role in finding the associated information with a panel. As written in
|
|
the comments, the PANEL_DATA stores the panel sizes, label, label color and a
|
|
pointer to the next panel in the cycle.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="panelshowhide"><title> Hiding and Showing Panels </title>
|
|
|
|
<para>
|
|
A Panel can be hidden by using the function hide_panel(). This function merely
|
|
removes it form the stack of panels, thus hiding it on the screen once you do
|
|
update_panels() and doupdate(). It doesn't destroy the PANEL structure
|
|
associated with the hidden panel. It can be shown again by using the
|
|
show_panel() function.
|
|
</para>
|
|
|
|
<para>
|
|
The following program shows the hiding of panels. Press 'a' or 'b' or 'c' to
|
|
show or hide first, second and third windows respectively. It uses a user data
|
|
with a small variable hide, which keeps track of whether the window is hidden or
|
|
not. For some reason the function
|
|
<literal remap="tt">panel_hidden()</literal> which tells whether a panel is
|
|
hidden or not is not working. A bug report was also presented by Michael Andres
|
|
<ulink url="http://www.geocrawler.com/archives/3/344/1999/9/0/2643549/"> here
|
|
</ulink>
|
|
</para>
|
|
|
|
<example id="ppahi"><title> Panel Hiding and Showing example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/panels/panel_hide.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="panelabove"><title> panel_above() and panel_below() Functions </title>
|
|
<para>
|
|
The functions <literal remap="tt">panel_above()</literal> and
|
|
<literal remap="tt">panel_below()</literal> can be used to find out the panel
|
|
above and below a panel. If the argument to these functions is NULL, then they
|
|
return a pointer to bottom panel and top panel respectively.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="menus"><title> Menus Library </title>
|
|
<para>
|
|
The menus library provides a nice extension to basic curses, through which you
|
|
can create menus. It provides a set of functions to create menus. But they have
|
|
to be customized to give a nicer look, with colors etc. Let's get into the
|
|
details.
|
|
</para>
|
|
|
|
<para>
|
|
A menu is a screen display that assists the user to choose some subset of a
|
|
given set of items. To put it simple, a menu is a collection of items from which
|
|
one or more items can be chosen. Some readers might not be aware of multiple
|
|
item selection capability. Menu library provides functionality to write menus
|
|
from which the user can chose more than one item as the preferred choice. This
|
|
is dealt with in a later section. Now it is time for some rudiments.
|
|
</para>
|
|
|
|
<sect2 id="menubasics"><title> The Basics </title>
|
|
<para>
|
|
To create menus, you first create items, and then post the menu to the display.
|
|
After that, all the processing of user responses is done in an elegant function
|
|
menu_driver() which is the work horse of any menu program.
|
|
</para>
|
|
|
|
<para>
|
|
The general flow of control of a menu program looks like this.
|
|
<orderedlist>
|
|
<listitem><para>Initialize curses</para></listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Create items using new_item(). You can specify a name and description for the
|
|
items.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Create the menu with new_menu() by specifying the items to be attached with.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Post the menu with menu_post() and refresh the screen.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Process the user requests with a loop and do necessary updates to menu with
|
|
menu_driver.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Unpost the menu with menu_unpost()</para></listitem>
|
|
<listitem><para>Free the memory allocated to menu by free_menu()</para>
|
|
</listitem>
|
|
<listitem><para>Free the memory allocated to the items with free_item() </para>
|
|
</listitem>
|
|
<listitem><para>End curses </para> </listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
Let's see a program which prints a simple menu and updates the current selection
|
|
with up, down arrows.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="compilemenus"><title> Compiling With the Menu Library </title>
|
|
|
|
<para>
|
|
To use menu library functions, you have to include menu.h and to link the
|
|
program with menu library the flag -lmenu should be added along with -lncurses
|
|
in that order.
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <menu.h>
|
|
.
|
|
.
|
|
.
|
|
|
|
compile and link: gcc <program file> -lmenu -lncurses
|
|
</programlisting>
|
|
|
|
<example id="mmesi"> <title>Menu Basics </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_simple.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
This program demonstrates the basic concepts involved in creating a menu using
|
|
menus library. First we create the items using new_item() and then attach them
|
|
to the menu with new_menu() function. After posting the menu and refreshing the
|
|
screen, the main processing loop starts. It reads user input and takes
|
|
corresponding action. The function menu_driver() is the main work horse of the
|
|
menu system. The second parameter to this function tells what's to be done with
|
|
the menu. According to the parameter, menu_driver() does the corresponding task.
|
|
The value can be either a menu navigational request, an ascii character, or a
|
|
KEY_MOUSE special key associated with a mouse event.
|
|
</para>
|
|
|
|
<para>
|
|
The menu_driver accepts following navigational requests.
|
|
<programlisting>
|
|
|
|
REQ_LEFT_ITEM Move left to an item.
|
|
REQ_RIGHT_ITEM Move right to an item.
|
|
REQ_UP_ITEM Move up to an item.
|
|
REQ_DOWN_ITEM Move down to an item.
|
|
REQ_SCR_ULINE Scroll up a line.
|
|
REQ_SCR_DLINE Scroll down a line.
|
|
REQ_SCR_DPAGE Scroll down a page.
|
|
REQ_SCR_UPAGE Scroll up a page.
|
|
REQ_FIRST_ITEM Move to the first item.
|
|
REQ_LAST_ITEM Move to the last item.
|
|
REQ_NEXT_ITEM Move to the next item.
|
|
REQ_PREV_ITEM Move to the previous item.
|
|
REQ_TOGGLE_ITEM Select/deselect an item.
|
|
REQ_CLEAR_PATTERN Clear the menu pattern buffer.
|
|
REQ_BACK_PATTERN Delete the previous character from the pattern buffer.
|
|
REQ_NEXT_MATCH Move to the next item matching the pattern match.
|
|
REQ_PREV_MATCH Move to the previous item matching the pattern match.
|
|
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
Don't get overwhelmed by the number of options. We will see them slowly one
|
|
after another. The options of interest in this example are REQ_UP_ITEM and
|
|
REQ_DOWN_ITEM. These two options when passed to menu_driver, menu driver
|
|
updates the current item to one item up or down respectively.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="menudriver"><title> Menu Driver: The work horse of the menu system</title>
|
|
|
|
<para>
|
|
As you have seen in the above example, menu_driver plays an important role in
|
|
updating the menu. It is very important to understand various options it takes
|
|
and what they do. As explained above, the second parameter to menu_driver() can
|
|
be either a navigational request, a printable character or a KEY_MOUSE key.
|
|
Let's dissect the different navigational requests.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_LEFT_ITEM and REQ_RIGHT_ITEM</emphasis></para>
|
|
<para>
|
|
A Menu can be displayed with multiple columns for more than one item. This can
|
|
be done by using the <literal remap="tt">menu_format()</literal>function.
|
|
When a multi columnar menu is displayed these requests cause the menu driver to
|
|
move the current selection to left or right.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para><emphasis>REQ_UP_ITEM and REQ_DOWN_ITEM </emphasis> </para>
|
|
<para>
|
|
These two options you have seen in the above example. These options when given,
|
|
makes the menu_driver to move the current selection to an item up or down.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para> <emphasis>REQ_SCR_* options</emphasis> </para>
|
|
<para>
|
|
The four options REQ_SCR_ULINE, REQ_SCR_DLINE, REQ_SCR_DPAGE, REQ_SCR_UPAGE are
|
|
related to scrolling. If all the items in the menu cannot be displayed in the
|
|
menu sub window, then the menu is scrollable. These requests can be given to the
|
|
menu_driver to do the scrolling either one line up, down or one page down or up
|
|
respectively.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para><emphasis>REQ_FIRST_ITEM, REQ_LAST_ITEM, REQ_NEXT_ITEM and
|
|
REQ_PREV_ITEM </emphasis> </para>
|
|
<para>
|
|
These requests are self explanatory.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para> <emphasis>REQ_TOGGLE_ITEM</emphasis> </para>
|
|
<para>
|
|
This request when given, toggles the present selection. This option is to be
|
|
used only in a multi valued menu. So to use this request the option O_ONEVALUE
|
|
must be off. This option can be made off or on with set_menu_opts().
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para> <emphasis>Pattern Requests </emphasis></para>
|
|
<para>
|
|
Every menu has an associated pattern buffer, which is used to find the nearest
|
|
match to the ascii characters entered by the user. Whenever ascii characters are
|
|
given to menu_driver, it puts in to the pattern buffer. It also tries to find
|
|
the nearest match to the pattern in the items list and moves current selection
|
|
to that item. The request REQ_CLEAR_PATTERN clears the pattern buffer. The
|
|
request REQ_BACK_PATTERN deletes the previous character in the pattern buffer.
|
|
In case the pattern matches more than one item then the matched items can be
|
|
cycled through REQ_NEXT_MATCH and REQ_PREV_MATCH which move the current
|
|
selection to the next and previous matches respectively.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem><para> <emphasis>Mouse Requests</emphasis></para>
|
|
<para>
|
|
In case of KEY_MOUSE requests, according to the mouse position an action is
|
|
taken accordingly. The action to be taken is explained in the man page as,
|
|
</para>
|
|
<programlisting>
|
|
<emphasis>
|
|
If the second argument is the KEY_MOUSE special key, the
|
|
associated mouse event is translated into one of the above
|
|
pre-defined requests. Currently only clicks in the user
|
|
window (e.g. inside the menu display area or the decora­
|
|
tion window) are handled. If you click above the display
|
|
region of the menu, a REQ_SCR_ULINE is generated, if you
|
|
doubleclick a REQ_SCR_UPAGE is generated and if you
|
|
tripleclick a REQ_FIRST_ITEM is generated. If you click
|
|
below the display region of the menu, a REQ_SCR_DLINE is
|
|
generated, if you doubleclick a REQ_SCR_DPAGE is generated
|
|
and if you tripleclick a REQ_LAST_ITEM is generated. If
|
|
you click at an item inside the display area of the menu,
|
|
the menu cursor is positioned to that item.
|
|
</emphasis>
|
|
</programlisting>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Each of the above requests will be explained in the following lines with several
|
|
examples whenever appropriate.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="menuwindows"><title> Menu Windows </title>
|
|
<para>
|
|
Every menu created is associated with a window and a sub window. The menu window
|
|
displays any title or border associated with the menu. The menu sub window
|
|
displays the menu items currently available for selection. But we didn't specify
|
|
any window or sub window in the simple example. When a window is not specified,
|
|
stdscr is taken as the main window, and then menu system calculates the sub
|
|
window size required for the display of items. Then items are displayed in the
|
|
calculated sub window. So let's play with these windows and display a menu with
|
|
a border and a title.
|
|
</para>
|
|
|
|
<example id="mmewi"><title> Menu Windows Usage example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_win.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
This example creates a menu with a title, border, a fancy line separating title
|
|
and the items. As you can see, in order to attach a window to a menu the
|
|
function set_menu_win() has to be used. Then we attach the sub window also. This
|
|
displays the items in the sub window. You can also set the mark string which
|
|
gets displayed to the left of the selected item with set_menu_mark().
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="scrollmenus"><title> Scrolling Menus </title>
|
|
<para>
|
|
If the sub window given for a window is not big enough to show all the items,
|
|
then the menu will be scrollable. When you are on the last item in the present
|
|
list, if you send REQ_DOWN_ITEM, it gets translated into REQ_SCR_DLINE and the
|
|
menu scrolls by one item. You can manually give REQ_SCR_ operations to do
|
|
scrolling. Let's see how it can be done.
|
|
</para>
|
|
|
|
<example id="mmesc"><title> Scrolling Menus example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_scroll.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
<para>
|
|
This program is self-explanatory. In this example the number of choices has been
|
|
increased to ten, which is larger than our sub window size which can hold 6
|
|
items. This message has to be explicitly conveyed to the menu system with the
|
|
function set_menu_format(). In here we specify the number of rows and columns we
|
|
want to be displayed for a single page. We can specify any number of items to be
|
|
shown, in the rows variables, if it is less than the height of the sub window.
|
|
If the key pressed by the user is a PAGE UP or PAGE DOWN, the menu is scrolled a
|
|
page due to the requests (REQ_SCR_DPAGE and REQ_SCR_UPAGE) given to
|
|
menu_driver().
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="multicolumn"><title> Multi Columnar Menus </title>
|
|
<para>
|
|
In the above example you have seen how to use the function set_menu_format(). I
|
|
didn't mention what the cols variable (third parameter) does. Well, If your sub
|
|
window is wide enough, you can opt to display more than one item per row. This
|
|
can be specified in the cols variable. To make things simpler, the following
|
|
example doesn't show descriptions for the items.
|
|
</para>
|
|
|
|
<example id="mmemuco"> <title> Milt Columnar Menus Example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_multi_column.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
<para>
|
|
Watch the function call to set_menu_format(). It specifies the number of columns
|
|
to be 3, thus displaying 3 items per row. We have also switched off the showing
|
|
descriptions with the function menu_opts_off(). There are couple of functions
|
|
set_menu_opts(), menu_opts_on() and menu_opts() which can be used to manipulate
|
|
menu options. The following menu options can be specified.
|
|
</para>
|
|
|
|
<programlisting>
|
|
O_ONEVALUE
|
|
Only one item can be selected for this menu.
|
|
|
|
O_SHOWDESC
|
|
Display the item descriptions when the menu is
|
|
posted.
|
|
|
|
O_ROWMAJOR
|
|
Display the menu in row-major order.
|
|
|
|
O_IGNORECASE
|
|
Ignore the case when pattern-matching.
|
|
|
|
O_SHOWMATCH
|
|
Move the cursor to within the item name while pat­
|
|
tern-matching.
|
|
|
|
O_NONCYCLIC
|
|
Don't wrap around next-item and previous-item,
|
|
requests to the other end of the menu.
|
|
</programlisting>
|
|
|
|
<para>
|
|
All options are on by default. You can switch specific attributes on or off with
|
|
menu_opts_on() and menu_opts_off() functions. You can also use set_menu_opts()
|
|
to directly specify the options. The argument to this function should be a OR ed
|
|
value of some of those above constants. The function menu_opts() can be used to
|
|
find out a menu's present options.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="multivaluemenus"><title> Multi Valued Menus </title>
|
|
<para>
|
|
You might be wondering what if you switch off the option O_ONEVALUE. Then the
|
|
menu becomes multi-valued. That means you can select more than one item. This
|
|
brings us to the request REQ_TOGGLE_ITEM. Let's see it in action.
|
|
</para>
|
|
|
|
<example id="mmeto"><title> Multi Valued Menus example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_toggle.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
<para>
|
|
Whew, A lot of new functions. Let's take them one after another. Firstly, the
|
|
REQ_TOGGLE_ITEM. In a multi-valued menu, the user should be allowed to select
|
|
or un select more than one item. The request REQ_TOGGLE_ITEM toggles the present
|
|
selection. In this case when space is pressed REQ_TOGGLE_ITEM request is sent to
|
|
menu_driver to achieve the result.
|
|
</para>
|
|
|
|
<para>
|
|
Now when the user presses <ENTER> we show the items he presently selected.
|
|
First we find out the items associated with the menu using the function
|
|
menu_items(). Then we loop through the items to find out if the item is selected
|
|
or not. The function item_value() returns TRUE if an item is selected. The
|
|
function item_count() returns the number of items in the menu. The item name can
|
|
be found with item_name(). You can also find the description associated with an
|
|
item using item_description().
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="menuopt"><title> Menu Options </title>
|
|
|
|
<para>
|
|
Well, by this time you must be itching for some difference in your menu, with
|
|
lots of functionality. I know. You want Colors !!!. You want to create nice
|
|
menus similar to those text mode <ulink
|
|
url="http://www.jersey.net/~debinjoe/games/">dos games</ulink>. The functions
|
|
set_menu_fore() and set_menu_back() can be used to change the attribute of the
|
|
selected item and unselected item. The names are misleading. They don't change
|
|
menu's foreground or background which would have been useless.
|
|
</para>
|
|
|
|
<para>
|
|
The function set_menu_grey() can be used to set the display attribute for the
|
|
non-selectable items in the menu. This brings us to the interesting option for
|
|
an item the one and only O_SELECTABLE. We can turn it off by the function
|
|
item_opts_off() and after that the item is not selectable. It's like a grayed
|
|
item in those fancy windows menus. Let's put these concepts in practice with
|
|
this example
|
|
</para>
|
|
|
|
<example id="mmeat"><title> Menu Options example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_attrib.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="menuuserptr"><title> The useful User Pointer </title>
|
|
<para>
|
|
We can associate a user pointer with each item in the menu. It works the same
|
|
way as user pointer in panels. It's not touched by menu system. You can store
|
|
any thing you like in that. I usually use it to store the function to be
|
|
executed when the menu option is chosen (It's selected and may be the user
|
|
pressed <ENTER>);
|
|
</para>
|
|
|
|
<example id="mmeus"><title> Menu User Pointer Usage </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/menus/menu_userptr.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="forms"><title> Forms Library </title>
|
|
|
|
<para>
|
|
Well. If you have seen those forms on web pages which take input from users and
|
|
do various kinds of things, you might be wondering how would any one create such
|
|
forms in text mode display. It's quite difficult to write those nifty forms in
|
|
plain ncurses. Forms library tries to provide a basic frame work to build and
|
|
maintain forms with ease. It has lot of features(functions) which manage
|
|
validation, dynamic expansion of fields etc.. Let's see it in full flow.
|
|
</para>
|
|
|
|
<para>
|
|
A form is a collection of fields; each field can be either a label(static text)
|
|
or a data-entry location. The forms also library provides functions to divide
|
|
forms into multiple pages.
|
|
</para>
|
|
|
|
<sect2 id="formbasics"><title> The Basics </title>
|
|
|
|
<para>
|
|
Forms are created in much the same way as menus. First the fields related to the
|
|
form are created with new_field(). You can set options for the fields, so that
|
|
they can be displayed with some fancy attributes, validated before the field
|
|
looses focus etc.. Then the fields are attached to form. After this, the form
|
|
can be posted to display and is ready to receive inputs. On the similar lines to
|
|
menu_driver(), the form is manipulated with form_driver(). We can send requests
|
|
to form_driver to move focus to a certain field, move cursor to end of the field
|
|
etc.. After the user enters values in the fields and validation done, form can
|
|
be unposted and memory allocated can be freed.
|
|
</para>
|
|
|
|
<para>
|
|
The general flow of control of a forms program looks like this.
|
|
|
|
<orderedlist>
|
|
<listitem><para>Initialize curses</para> </listitem>
|
|
|
|
<listitem><para>Create fields using new_field(). You can specify the height and
|
|
width of the field, and its position on the form.</para> </listitem>
|
|
|
|
<listitem><para>Create the forms with new_form() by specifying the fields to be
|
|
attached with.</para> </listitem>
|
|
|
|
<listitem><para>Post the form with form_post() and refresh the screen.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Process the user requests with a loop and do necessary updates
|
|
to form with form_driver.</para> </listitem>
|
|
|
|
<listitem><para>Unpost the menu with form_unpost()</para> </listitem>
|
|
|
|
<listitem><para>Free the memory allocated to menu by free_form()</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Free the memory allocated to the items with free_field()</para> </listitem>
|
|
|
|
<listitem><para>End curses</para> </listitem>
|
|
|
|
</orderedlist>
|
|
</para>
|
|
|
|
<para>
|
|
As you can see, working with forms library is much similar to handling menu
|
|
library. The following examples will explore various aspects of form
|
|
processing. Let's start the journey with a simple example. first.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="compileforms"><title> Compiling With the Forms Library </title>
|
|
|
|
<para>
|
|
To use forms library functions, you have to include form.h and to link the
|
|
program with forms library the flag -lform should be added along with -lncurses
|
|
in that order.
|
|
</para>
|
|
|
|
<programlisting>
|
|
#include <form.h>
|
|
.
|
|
.
|
|
.
|
|
|
|
compile and link: gcc <program file> -lform -lncurses
|
|
</programlisting>
|
|
|
|
<example id="ffosi"><title> Forms Basics </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/forms/form_simple.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Above example is pretty straight forward. It creates two fields with
|
|
<literal remap="tt">new_field()</literal>. new_field() takes height, width,
|
|
starty, startx, number of offscreen rows and number of additional working
|
|
buffers. The fifth argument number of offscreen rows specifies how much of the
|
|
field to be shown. If it is zero, the entire field is always displayed otherwise
|
|
the form will be scrollable when the user accesses not displayed parts of the
|
|
field. The forms library allocates one buffer per field to store the data user
|
|
enters. Using the last parameter to new_field() we can specify it to allocate
|
|
some additional buffers. These can be used for any purpose you like.
|
|
</para>
|
|
|
|
<para>
|
|
After creating the fields, back ground attribute of both of them is set to an
|
|
underscore with set_field_back(). The AUTOSKIP option is turned off using
|
|
field_opts_off(). If this option is turned on, focus will move to the next
|
|
field in the form once the active field is filled up completely.
|
|
</para>
|
|
|
|
<para>
|
|
After attaching the fields to the form, it is posted. Here on, user inputs are
|
|
processed in the while loop, by making corresponding requests to form_driver.
|
|
The details of all the requests to the form_driver() are explained later.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="playfields"><title> Playing with Fields </title>
|
|
<para>
|
|
Each form field is associated with a lot of attributes. They can be manipulated
|
|
to get the required effect and to have fun !!!. So why wait?
|
|
</para>
|
|
|
|
<sect3 id="fetchinfo"><title> Fetching Size and Location of Field </title>
|
|
|
|
<para>
|
|
The parameters we have given at the time of creation of a field can be retrieved
|
|
with field_info(). It returns height, width, starty, startx, number of offscreen
|
|
rows, and number of additional buffers into the parameters given to it. It is a
|
|
sort of inverse of new_field().
|
|
</para>
|
|
|
|
<programlisting>
|
|
int field_info( FIELD *field, /* field from which to fetch */
|
|
int *height, *int width, /* field size */
|
|
int *top, int *left, /* upper left corner */
|
|
int *offscreen, /* number of offscreen rows */
|
|
int *nbuf); /* number of working buffers */
|
|
</programlisting>
|
|
</sect3>
|
|
|
|
<sect3 id="movefield"><title> Moving the field </title>
|
|
|
|
<para>
|
|
The location of the field can be moved to a different position with
|
|
move_field().
|
|
</para>
|
|
|
|
<programlisting>
|
|
int move_field( FIELD *field, /* field to alter */
|
|
int top, int left); /* new upper-left corner */
|
|
</programlisting>
|
|
|
|
<para>
|
|
As usual, the changed position can be queried with field_infor().
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="justifyfield"><title> Field Justification </title>
|
|
|
|
<para>
|
|
The justification to be done for the field can be fixed using the function
|
|
set_field_just().
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_just(FIELD *field, /* field to alter */
|
|
int justmode); /* mode to set */
|
|
int field_just(FIELD *field); /* fetch justify mode of field */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The justification mode valued accepted and returned by these functions are
|
|
NO_JUSTIFICATION, JUSTIFY_RIGHT, JUSTIFY_LEFT, or JUSTIFY_CENTER.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="fielddispattrib"><title> Field Display Attributes </title>
|
|
<para>
|
|
As you have seen, in the above example, display attribute for the fields can be
|
|
set with set_field_fore() and setfield_back(). These functions set foreground
|
|
and background attribute of the fields. You can also specify a pad character
|
|
which will be filled in the unfilled portion of the field. The pad character is
|
|
set with a call to set_field_pad(). Default pad value is a space. The functions
|
|
field_fore(), field_back, field_pad() can be used to query the present
|
|
foreground, background attributes and pad character for the field. The following
|
|
list gives the usage of functions.
|
|
</para>
|
|
|
|
<programlisting>
|
|
|
|
int set_field_fore(FIELD *field, /* field to alter */
|
|
chtype attr); /* attribute to set */
|
|
|
|
chtype field_fore(FIELD *field); /* field to query */
|
|
/* returns foreground attribute */
|
|
|
|
int set_field_back(FIELD *field, /* field to alter */
|
|
chtype attr); /* attribute to set */
|
|
|
|
chtype field_back(FIELD *field); /* field to query */
|
|
/* returns background attribute */
|
|
|
|
int set_field_pad(FIELD *field, /* field to alter */
|
|
int pad); /* pad character to set */
|
|
|
|
chtype field_pad(FIELD *field); /* field to query */
|
|
/* returns present pad character */
|
|
|
|
</programlisting>
|
|
|
|
<para>
|
|
Though above functions seem quite simple, using colors with set_field_fore() may
|
|
be frustrating in the beginning. Let me first explain about foreground and
|
|
background attributes of a field. The foreground attribute is associated with
|
|
the character. That means a character in the field is printed with the attribute
|
|
you have set with set_field_fore(). Background attribute is the attribute used
|
|
to fill background of field, whether any character is there or not. So what
|
|
about colors? Since colors are always defined in pairs, what is the right way to
|
|
display colored fields? Here's an example clarifying color attributes.
|
|
</para>
|
|
|
|
<example id="ffoat"> <title> Form Attributes example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/forms/form_attrib.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Play with the color pairs and try to understand the foreground and background
|
|
attributes. In my programs using color attributes, I usually set only the
|
|
background with set_field_back(). Curses simply doesn't allow defining
|
|
individual color attributes.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="fieldoptionbits"><title> Field Option Bits </title>
|
|
<para>
|
|
There is also a large collection of field option bits you can set to control
|
|
various aspects of forms processing. You can manipulate them with these
|
|
functions:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_opts(FIELD *field, /* field to alter */
|
|
int attr); /* attribute to set */
|
|
|
|
int field_opts_on(FIELD *field, /* field to alter */
|
|
int attr); /* attributes to turn on */
|
|
|
|
int field_opts_off(FIELD *field, /* field to alter */
|
|
int attr); /* attributes to turn off */
|
|
|
|
int field_opts(FIELD *field); /* field to query */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The function set_field_opts() can be used to directly set attributes of a field
|
|
or you can choose to switch a few attributes on and off with field_opts_on() and
|
|
field_opts_off() selectively. Anytime you can query the attributes of a field
|
|
with field_opts(). The following is the list of available options. By default,
|
|
all options are on.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry><term> O_VISIBLE </term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether the field is visible on the screen. Can be used
|
|
during form processing to hide or pop up fields depending on the value
|
|
of parent fields.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term> O_ACTIVE </term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether the field is active during forms processing (i.e.
|
|
visited by form navigation keys). Can be used to make labels or derived
|
|
fields with buffer values alterable by the forms application, not the user.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term> O_PUBLIC</term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether data is displayed during field entry. If this option is
|
|
turned off on a field, the library will accept and edit data in that field,
|
|
but it will not be displayed and the visible field cursor will not move.
|
|
You can turn off the O_PUBLIC bit to define password fields.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term> O_EDIT </term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether the field's data can be modified. When this option is
|
|
off, all editing requests except <literal remap="tt">REQ_PREV_CHOICE
|
|
</literal> and <literal remap="tt">REQ_NEXT_CHOICE</literal>will
|
|
fail. Such read-only fields may be useful for help messages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term> O_WRAP </term>
|
|
<listitem>
|
|
<para>
|
|
Controls word-wrapping in multi-line fields. Normally, when any
|
|
character of a (blank-separated) word reaches the end of the current line, the
|
|
entire word is wrapped to the next line (assuming there is one). When this
|
|
option is off, the word will be split across the line break.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term> O_BLANK </term>
|
|
<listitem>
|
|
<para>
|
|
Controls field blanking. When this option is on, entering a character at
|
|
the first field position erases the entire field (except for the just-entered
|
|
character).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term> O_AUTOSKIP </term>
|
|
<listitem>
|
|
<para>
|
|
Controls automatic skip to next field when this one fills. Normally,
|
|
when the forms user tries to type more data into a field than will fit,
|
|
the editing location jumps to next field. When this option is off, the
|
|
user's cursor will hang at the end of the field. This option is ignored
|
|
in dynamic fields that have not reached their size limit.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry><term> O_NULLOK </term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether validation is applied to
|
|
blank fields. Normally, it is not; the user can leave a field blank
|
|
without invoking the usual validation check on exit. If this option is
|
|
off on a field, exit from it will invoke a validation check.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term> O_PASSOK </term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether validation occurs on every exit, or only after
|
|
the field is modified. Normally the latter is true. Setting O_PASSOK
|
|
may be useful if your field's validation function may change during
|
|
forms processing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry><term> O_STATIC </term>
|
|
<listitem>
|
|
<para>
|
|
Controls whether the field is fixed to its initial dimensions. If you
|
|
turn this off, the field becomes dynamic and will
|
|
stretch to fit entered data.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
A field's options cannot be changed while the field is currently selected.
|
|
However, options may be changed on posted fields that are not current.
|
|
</para>
|
|
|
|
<para>
|
|
The option values are bit-masks and can be composed with logical-or in
|
|
the obvious way. You have seen the usage of switching off O_AUTOSKIP option.
|
|
The following example clarifies usage of some more options. Other options
|
|
are explained where appropriate.
|
|
</para>
|
|
|
|
<example id="ffoop"> <title> Field Options Usage example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/forms/form_options.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
This example, though useless, shows the usage of options. If used properly, they
|
|
can present information very effectively in a form. The second field being not
|
|
O_PUBLIC, does not show the characters you are typing.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="fieldstatus"><title> Field Status </title>
|
|
|
|
<para>
|
|
The field status specifies whether the field has got edited or not. It is
|
|
initially set to FALSE and when user enters something and the data buffer gets
|
|
modified it becomes TRUE. So a field's status can be queried to find out whether
|
|
it has been modified or not. The following functions can assist in those
|
|
operations.
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_status(FIELD *field, /* field to alter */
|
|
int status); /* status to set */
|
|
|
|
int field_status(FIELD *field); /* fetch status of field */
|
|
</programlisting>
|
|
|
|
<para>
|
|
It's better to check the field's status only after leaving the field, as
|
|
data buffer might not have been updated yet as the validation is still due. To
|
|
guarantee that right status is returned, call field_status() either (1) in the
|
|
field's exit validation check routine, (2) from the field's or form's
|
|
initialization or termination hooks, or (3) just after a REQ_VALIDATION request
|
|
has been processed by the forms driver
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="fielduserptr"><title> Field User Pointer </title>
|
|
|
|
<para>
|
|
Every field structure contains one pointer that can be used by the user for
|
|
various purposes. It is not touched by forms library and can be used for any
|
|
purpose by the user. The following functions set and fetch user pointer.
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_userptr(FIELD *field,
|
|
char *userptr); /* the user pointer you wish to associate */
|
|
/* with the field */
|
|
|
|
char *field_userptr(FIELD *field); /* fetch user pointer of the field */
|
|
</programlisting>
|
|
</sect3>
|
|
|
|
<sect3 id="variablesizefields"><title> Variable-Sized Fields </title>
|
|
<para>
|
|
If you want a dynamically changing field with variable width, this is the
|
|
feature you want to put to full use. This will allow the user to enter more data
|
|
than the original size of the field and let the field grow. According to the
|
|
field orientation it will scroll horizontally or vertically to incorporate the
|
|
new data.
|
|
</para>
|
|
|
|
<para>
|
|
To make a field dynamically growable, the option O_STATIC should be turned off.
|
|
This can be done with a
|
|
<programlisting>
|
|
field_opts_off(field_pointer, O_STATIC);
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
But it's usually not advisable to allow a field to grow infinitely. You can set
|
|
a maximum limit to the growth of the field with
|
|
<programlisting>
|
|
int set_max_field(FIELD *field, /* Field on which to operate */
|
|
int max_growth); /* maximum growth allowed for the field */
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The field info for a dynamically growable field can be retrieved by
|
|
<programlisting>
|
|
int dynamic_field_info( FIELD *field, /* Field on which to operate */
|
|
int *prows, /* number of rows will be filled in this */
|
|
int *pcols, /* number of columns will be filled in this*/
|
|
int *pmax) /* maximum allowable growth will be filled */
|
|
/* in this */
|
|
</programlisting>
|
|
Though field_info work as usual, it is advisable to use this function to get the
|
|
proper attributes of a dynamically growable field.
|
|
</para>
|
|
|
|
<para>
|
|
Recall the library routine new_field; a new field created with height set to one
|
|
will be defined to be a one line field. A new field created with height greater
|
|
than one will be defined to be a multi line field.
|
|
</para>
|
|
|
|
<para>
|
|
A one line field with O_STATIC turned off (dynamically growable field) will
|
|
contain a single fixed row, but the number of columns can increase if the user
|
|
enters more data than the initial field will hold. The number of columns
|
|
displayed will remain fixed and the additional data will scroll horizontally.
|
|
</para>
|
|
|
|
<para>
|
|
A multi line field with O_STATIC turned off (dynamically growable field) will
|
|
contain a fixed number of columns, but the number of rows can increase if the
|
|
user enters more data than the initial field will hold. The number of rows
|
|
displayed will remain fixed and the additional data will scroll vertically.
|
|
</para>
|
|
|
|
<para>
|
|
The above two paragraphs pretty much describe a dynamically growable field's
|
|
behavior. The way other parts of forms library behaves is described below:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem><para>
|
|
The field option O_AUTOSKIP will be ignored if the option O_STATIC is off and
|
|
there is no maximum growth specified for the field. Currently, O_AUTOSKIP
|
|
generates an automatic REQ_NEXT_FIELD form driver request when the user types in
|
|
the last character position of a field. On a growable field with no maximum
|
|
growth specified, there is no last character position. If a maximum growth is
|
|
specified, the O_AUTOSKIP option will work as normal if the field has grown to
|
|
its maximum size.
|
|
</para></listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The field justification will be ignored if the option O_STATIC is off.
|
|
Currently, set_field_just can be used to JUSTIFY_LEFT, JUSTIFY_RIGHT,
|
|
JUSTIFY_CENTER the contents of a one line field. A growable one line field will,
|
|
by definition, grow and scroll horizontally and may contain more data than can
|
|
be justified. The return from field_just will be unchanged.
|
|
</para></listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The overloaded form driver request REQ_NEW_LINE will operate the same way
|
|
regardless of the O_NL_OVERLOAD form option if the field option O_STATIC is off
|
|
and there is no maximum growth specified for the field. Currently, if the form
|
|
option O_NL_OVERLOAD is on, REQ_NEW_LINE implicitly generates a REQ_NEXT_FIELD
|
|
if called from the last line of a field. If a field can grow without bound,
|
|
there is no last line, so REQ_NEW_LINE will never implicitly generate a
|
|
REQ_NEXT_FIELD. If a maximum growth limit is specified and the O_NL_OVERLOAD
|
|
form option is on, REQ_NEW_LINE will only implicitly generate REQ_NEXT_FIELD if
|
|
the field has grown to its maximum size and the user is on the last line.
|
|
</para></listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The library call dup_field will work as usual; it will duplicate the field,
|
|
including the current buffer size and contents of the field being duplicated.
|
|
Any specified maximum growth will also be duplicated.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
The library call link_field will work as usual; it will duplicate all field
|
|
attributes and share buffers with the field being linked. If the O_STATIC field
|
|
option is subsequently changed by a field sharing buffers, how the system reacts
|
|
to an attempt to enter more data into the field than the buffer will currently
|
|
hold will depend on the setting of the option in the current field.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
The library call field_info will work as usual; the variable nrow will contain
|
|
the value of the original call to new_field. The user should use
|
|
dynamic_field_info, described above, to query the current size of the buffer.
|
|
</para></listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
Some of the above points make sense only after explaining form driver. We will
|
|
be looking into that in next few sections.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="formwindows"><title> Form Windows </title>
|
|
<para>
|
|
The form windows concept is pretty much similar to menu windows. Every form is
|
|
associated with a main window and a sub window. The form main window displays
|
|
any title or border associated or whatever the user wishes. Then the sub window
|
|
contains all the fields and displays them according to their position. This
|
|
gives the flexibility of manipulating fancy form displaying very easily.
|
|
</para>
|
|
|
|
<para>
|
|
Since this is pretty much similar to menu windows, I am providing an example
|
|
with out much explanation. The functions are similar and they work the same way.
|
|
</para>
|
|
|
|
<example id="ffowi"><title> Form Windows Example </title>
|
|
<programlisting><inlinemediaobject><imageobject>
|
|
<imagedata format="linespecific"
|
|
fileref="resources/ncurses_programs/forms/form_win.c">
|
|
</imageobject></inlinemediaobject></programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="filedvalidate"><title> Field Validation </title>
|
|
<para>
|
|
By default, a field will accept any data input by the user. It is possible to
|
|
attach validation to the field. Then any attempt by the user to leave the field,
|
|
while it contains data that doesn't match the validation type will fail. Some
|
|
validation types also have a character-validity check for each time a character
|
|
is entered in the field.
|
|
</para>
|
|
|
|
<para>
|
|
Validation can be attached to a field with the following function.
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
FIELDTYPE *ftype, /* type to associate */
|
|
...); /* additional arguments*/
|
|
</programlisting>
|
|
Once set, the validation type for a field can be queried with
|
|
<programlisting>
|
|
FIELDTYPE *field_type(FIELD *field); /* field to query */
|
|
</programlisting>
|
|
</para>
|
|
|
|
<para>
|
|
The form driver validates the data in a field only when data is entered by the
|
|
end-user. Validation does not occur when
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>
|
|
the application program changes the field value by calling set_field_buffer.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
linked field values are changed indirectly -- by changing the field to which
|
|
they are linked
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The following are the pre-defined validation types. You can also specify custom
|
|
validation, though it's a bit tricky and cumbersome.
|
|
</para>
|
|
|
|
<bridgehead>TYPE_ALPHA</bridgehead>
|
|
<para>
|
|
This field type accepts alphabetic data; no blanks, no digits, no special
|
|
characters (this is checked at character-entry time). It is set up with:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ALPHA, /* type to associate */
|
|
int width); /* maximum width of field */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The width argument sets a minimum width of data. The user has to enter at-least
|
|
width number of characters before he can leave the field. Typically
|
|
you'll want to set this to the field width; if it's greater than the
|
|
field width, the validation check will always fail. A minimum width
|
|
of zero makes field completion optional.
|
|
</para>
|
|
|
|
<bridgehead>TYPE_ALNUM</bridgehead>
|
|
|
|
<para>
|
|
This field type accepts alphabetic data and digits; no blanks, no special
|
|
characters (this is checked at character-entry time). It is set up with:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ALNUM, /* type to associate */
|
|
int width); /* maximum width of field */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The width argument sets a minimum width of data. As with
|
|
TYPE_ALPHA, typically you'll want to set this to the field width; if it's
|
|
greater than the field width, the validation check will always fail. A
|
|
minimum width of zero makes field completion optional.
|
|
</para>
|
|
|
|
<bridgehead>TYPE_ENUM</bridgehead>
|
|
<para>
|
|
This type allows you to restrict a field's values to be among a specified
|
|
set of string values (for example, the two-letter postal codes for U.S.
|
|
states). It is set up with:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_ENUM, /* type to associate */
|
|
char **valuelist; /* list of possible values */
|
|
int checkcase; /* case-sensitive? */
|
|
int checkunique); /* must specify uniquely? */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The valuelist parameter must point at a NULL-terminated list of
|
|
valid strings. The checkcase argument, if true, makes comparison
|
|
with the string case-sensitive.
|
|
</para>
|
|
|
|
<para>
|
|
When the user exits a TYPE_ENUM field, the validation procedure tries to
|
|
complete the data in the buffer to a valid entry. If a complete choice string
|
|
has been entered, it is of course valid. But it is also possible to enter a
|
|
prefix of a valid string and have it completed for you.
|
|
</para>
|
|
|
|
<para>
|
|
By default, if you enter such a prefix and it matches more than one value
|
|
in the string list, the prefix will be completed to the first matching
|
|
value. But the checkunique argument, if true, requires prefix
|
|
matches to be unique in order to be valid.
|
|
</para>
|
|
|
|
<para>
|
|
The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be particularly
|
|
useful with these fields.
|
|
</para>
|
|
|
|
<bridgehead>TYPE_INTEGER</bridgehead>
|
|
|
|
<para>
|
|
This field type accepts an integer. It is set up as follows:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_INTEGER, /* type to associate */
|
|
int padding, /* # places to zero-pad to */
|
|
int vmin, int vmax); /* valid range */
|
|
</programlisting>
|
|
|
|
<para>
|
|
Valid characters consist of an optional leading minus and digits.
|
|
The range check is performed on exit. If the range maximum is less
|
|
than or equal to the minimum, the range is ignored.
|
|
</para>
|
|
|
|
<para>
|
|
If the value passes its range check, it is padded with as many leading
|
|
zero digits as necessary to meet the padding argument.
|
|
</para>
|
|
|
|
<para>
|
|
A TYPE_INTEGER value buffer can conveniently be interpreted with the C library
|
|
function atoi(3).
|
|
</para>
|
|
|
|
<bridgehead>TYPE_NUMERIC</bridgehead>
|
|
<para>
|
|
This field type accepts a decimal number. It is set up as follows:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_NUMERIC, /* type to associate */
|
|
int padding, /* # places of precision */
|
|
int vmin, int vmax); /* valid range */
|
|
</programlisting>
|
|
|
|
<para>
|
|
Valid characters consist of an optional leading minus and digits. possibly
|
|
including a decimal point. The range check is performed on exit. If the
|
|
range maximum is less than or equal to the minimum, the range is
|
|
ignored.
|
|
</para>
|
|
|
|
<para>
|
|
If the value passes its range check, it is padded with as many trailing
|
|
zero digits as necessary to meet the padding argument.
|
|
</para>
|
|
|
|
<para>
|
|
A TYPE_NUMERIC value buffer can conveniently be interpreted with the C library
|
|
function atof(3).
|
|
</para>
|
|
|
|
<bridgehead>TYPE_REGEXP</bridgehead>
|
|
<para>
|
|
This field type accepts data matching a regular expression. It is set up
|
|
as follows:
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_field_type(FIELD *field, /* field to alter */
|
|
TYPE_REGEXP, /* type to associate */
|
|
char *regexp); /* expression to match */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The syntax for regular expressions is that of regcomp(3).
|
|
The check for regular-expression match is performed on exit.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="formdriver"><title> Form Driver: The work horse of the forms system </title>
|
|
<para>
|
|
As in the menu system, form_driver() plays a very important role in forms
|
|
system. All types of requests to forms system should be funneled through
|
|
form_driver().
|
|
</para>
|
|
|
|
<programlisting>
|
|
int form_driver(FORM *form, /* form on which to operate */
|
|
int request) /* form request code */
|
|
</programlisting>
|
|
|
|
<para>
|
|
As you have seen some of the examples above, you have to be in a loop looking
|
|
for user input and then decide whether it's a field data or a form request. The
|
|
form requests are then passed to form_driver() to do the work.
|
|
</para>
|
|
|
|
<para>
|
|
The requests roughly can be divided into following categories. Different
|
|
requests and their usage is explained below:
|
|
</para>
|
|
|
|
<sect3 id="pagenavreq"><title> Page Navigation Requests </title>
|
|
<para>
|
|
These requests cause page-level moves through the form, triggering display of a
|
|
new form screen. A form can be made of multiple pages. If you have a big form
|
|
with lot of fields and logical sections, then you can divide the form into
|
|
pages. The function set_new_page() to set a new page at the field specified.
|
|
</para>
|
|
|
|
<programlisting>
|
|
int set_new_page(FIELD *field,/* Field at which page break to be set or unset */
|
|
bool new_page_flag); /* should be TRUE to put a break */
|
|
</programlisting>
|
|
|
|
<para>
|
|
The following requests allow you to move to different pages
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_NEXT_PAGE</emphasis> Move to the next form page.
|
|
</para> </listitem>
|
|
|
|
<listitem><para><emphasis>REQ_PREV_PAGE</emphasis> Move to the previous
|
|
form page.</para></listitem>
|
|
|
|
<listitem><para><emphasis>REQ_FIRST_PAGE</emphasis> Move to the first form page.
|
|
</para> </listitem>
|
|
|
|
<listitem><para><emphasis>REQ_LAST_PAGE</emphasis> Move to the last form page.
|
|
</para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
These requests treat the list as cyclic; that is, REQ_NEXT_PAGE from the
|
|
last page goes to the first, and REQ_PREV_PAGE from the first page goes to
|
|
the last.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="interfieldnavreq"> <title> Inter-Field Navigation Requests</title>
|
|
<para>
|
|
These requests handle navigation between fields on the same page.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_NEXT_FIELD</emphasis>
|
|
Move to next field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_PREV_FIELD</emphasis>
|
|
Move to previous field. </para></listitem>
|
|
<listitem><para><emphasis>REQ_FIRST_FIELD</emphasis>
|
|
Move to the first field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_LAST_FIELD</emphasis>
|
|
Move to the last field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SNEXT_FIELD</emphasis>
|
|
Move to sorted next field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SPREV_FIELD</emphasis>
|
|
Move to sorted previous field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SFIRST_FIELD</emphasis>
|
|
Move to the sorted first field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SLAST_FIELD</emphasis>
|
|
Move to the sorted last field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_LEFT_FIELD</emphasis>
|
|
Move left to field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_RIGHT_FIELD</emphasis>
|
|
Move right to field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_UP_FIELD</emphasis>
|
|
Move up to field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_DOWN_FIELD</emphasis>
|
|
Move down to field. </para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
These requests treat the list of fields on a page as cyclic; that is,
|
|
REQ_NEXT_FIELD from the last field goes to the first, and REQ_PREV_FIELD
|
|
from the first field goes to the last. The order of the fields for these
|
|
(and the REQ_FIRST_FIELD and REQ_LAST_FIELD requests) is simply the order of
|
|
the field pointers in the form array (as set up by new_form() or
|
|
set_form_fields()
|
|
</para>
|
|
|
|
<para>
|
|
It is also possible to traverse the fields as if they had been sorted in
|
|
screen-position order, so the sequence goes left-to-right and top-to-bottom.
|
|
To do this, use the second group of four sorted-movement requests.
|
|
</para>
|
|
|
|
<para>
|
|
Finally, it is possible to move between fields using visual directions up,
|
|
down, right, and left. To accomplish this, use the third group of four
|
|
requests. Note, however, that the position of a form for purposes of these
|
|
requests is its upper-left corner.
|
|
</para>
|
|
|
|
<para>
|
|
For example, suppose you have a multi-line field B, and two single-line
|
|
fields A and C on the same line with B, with A to the left of B and C to the
|
|
right of B. A REQ_MOVE_RIGHT from A will go to B only if A, B, and C all
|
|
share the same first line; otherwise it will skip over B to C.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="intrafieldnavreq"><title> Intra-Field Navigation Requests </title>
|
|
<para>
|
|
These requests drive movement of the edit cursor within the currently
|
|
selected field.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_NEXT_CHAR</emphasis>
|
|
Move to next character. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_PREV_CHAR</emphasis>
|
|
Move to previous character. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_NEXT_LINE</emphasis>
|
|
Move to next line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_PREV_LINE</emphasis>
|
|
Move to previous line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_NEXT_WORD</emphasis>
|
|
Move to next word. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_PREV_WORD</emphasis>
|
|
Move to previous word. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_BEG_FIELD</emphasis>
|
|
Move to beginning of field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_END_FIELD</emphasis>
|
|
Move to end of field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_BEG_LINE</emphasis>
|
|
Move to beginning of line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_END_LINE</emphasis>
|
|
Move to end of line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_LEFT_CHAR</emphasis>
|
|
Move left in field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_RIGHT_CHAR</emphasis>
|
|
Move right in field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_UP_CHAR</emphasis>
|
|
Move up in field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_DOWN_CHAR</emphasis>
|
|
Move down in field. </para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Each word is separated from the previous and next characters by whitespace.
|
|
The commands to move to beginning and end of line or field look for the
|
|
first or last non-pad character in their ranges.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="scrollreq"><title> Scrolling Requests </title>
|
|
<para>
|
|
Fields that are dynamic and have grown and fields explicitly created with
|
|
offscreen rows are scrollable. One-line fields scroll horizontally;
|
|
multi-line fields scroll vertically. Most scrolling is triggered by editing
|
|
and intra-field movement (the library scrolls the field to keep the cursor
|
|
visible). It is possible to explicitly request scrolling with the following
|
|
requests:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_SCR_FLINE</emphasis>
|
|
Scroll vertically forward a line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_BLINE</emphasis>
|
|
Scroll vertically backward a line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_FPAGE</emphasis>
|
|
Scroll vertically forward a page. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_BPAGE</emphasis>
|
|
Scroll vertically backward a page. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_FHPAGE</emphasis>
|
|
Scroll vertically forward half a page. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_BHPAGE</emphasis>
|
|
Scroll vertically backward half a page. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_FCHAR</emphasis>
|
|
Scroll horizontally forward a character. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_BCHAR</emphasis>
|
|
Scroll horizontally backward a character. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_HFLINE</emphasis>
|
|
Scroll horizontally one field width forward. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_HBLINE</emphasis>
|
|
Scroll horizontally one field width backward. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_HFHALF</emphasis>
|
|
Scroll horizontally one half field width forward. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_SCR_HBHALF</emphasis>
|
|
Scroll horizontally one half field width backward. </para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
For scrolling purposes, a page of a field is the height of its visible part.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="editreq"> <title> Editing Requests </title>
|
|
<para>
|
|
When you pass the forms driver an ASCII character, it is treated as a
|
|
request to add the character to the field's data buffer. Whether this is an
|
|
insertion or a replacement depends on the field's edit mode (insertion is
|
|
the default.
|
|
</para>
|
|
|
|
<para>
|
|
The following requests support editing the field and changing the edit mode:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_INS_MODE</emphasis>
|
|
Set insertion mode. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_OVL_MODE</emphasis>
|
|
Set overlay mode. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_NEW_LINE</emphasis>
|
|
New line request (see below for explanation). </para> </listitem>
|
|
<listitem><para><emphasis>REQ_INS_CHAR</emphasis>
|
|
Insert space at character location. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_INS_LINE</emphasis>
|
|
Insert blank line at character location. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_DEL_CHAR</emphasis>
|
|
Delete character at cursor. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_DEL_PREV</emphasis>
|
|
Delete previous word at cursor. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_DEL_LINE</emphasis>
|
|
Delete line at cursor. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_DEL_WORD</emphasis>
|
|
Delete word at cursor. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_CLR_EOL</emphasis>
|
|
Clear to end of line. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_CLR_EOF</emphasis>
|
|
Clear to end of field. </para> </listitem>
|
|
<listitem><para><emphasis>REQ_CLR_FIELD</emphasis>
|
|
Clear entire field. </para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The behavior of the REQ_NEW_LINE and REQ_DEL_PREV requests is complicated
|
|
and partly controlled by a pair of forms options. The special cases are
|
|
triggered when the cursor is at the beginning of a field, or on the last
|
|
line of the field.
|
|
</para>
|
|
|
|
<para>
|
|
First, we consider REQ_NEW_LINE:
|
|
</para>
|
|
|
|
<para>
|
|
The normal behavior of REQ_NEW_LINE in insert mode is to break the current
|
|
line at the position of the edit cursor, inserting the portion of the
|
|
current line after the cursor as a new line following the current and moving
|
|
the cursor to the beginning of that new line (you may think of this as
|
|
inserting a newline in the field buffer).
|
|
</para>
|
|
|
|
<para>
|
|
The normal behavior of REQ_NEW_LINE in overlay mode is to clear the current
|
|
line from the position of the edit cursor to end of line. The cursor is then
|
|
moved to the beginning of the next line.
|
|
</para>
|
|
|
|
<para>
|
|
However, REQ_NEW_LINE at the beginning of a field, or on the last line of a
|
|
field, instead does a REQ_NEXT_FIELD. O_NL_OVERLOAD option is off, this
|
|
special action is disabled.
|
|
</para>
|
|
|
|
<para>
|
|
Now, let us consider REQ_DEL_PREV:
|
|
</para>
|
|
|
|
<para>
|
|
The normal behavior of REQ_DEL_PREV is to delete the previous character. If
|
|
insert mode is on, and the cursor is at the start of a line, and the text on
|
|
that line will fit on the previous one, it instead appends the contents of
|
|
the current line to the previous one and deletes the current line (you may
|
|
think of this as deleting a newline from the field buffer).
|
|
</para>
|
|
|
|
<para>
|
|
However, REQ_DEL_PREV at the beginning of a field is instead treated as a
|
|
REQ_PREV_FIELD.
|
|
</para>
|
|
|
|
<para>
|
|
If the O_BS_OVERLOAD option is off, this special action is disabled and the
|
|
forms driver just returns E_REQUEST_DENIED.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="orderreq"> <title> Order Requests </title>
|
|
<para>
|
|
If the type of your field is ordered, and has associated functions for
|
|
getting the next and previous values of the type from a given value, there
|
|
are requests that can fetch that value into the field buffer:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>REQ_NEXT_CHOICE</emphasis>
|
|
Place the successor value of the current value in the buffer.
|
|
</para> </listitem>
|
|
<listitem><para><emphasis>REQ_PREV_CHOICE</emphasis>
|
|
Place the predecessor value of the current value in the buffer.
|
|
</para> </listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Of the built-in field types, only TYPE_ENUM has built-in successor and
|
|
predecessor functions. When you define a field type of your own (see Custom
|
|
Validation Types), you can associate our own ordering functions.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="appliccommands"> <title> Application Commands </title>
|
|
<para>
|
|
Form requests are represented as integers above the curses value greater than
|
|
KEY_MAX and less than or equal to the constant MAX_COMMAND. A value within this
|
|
range gets ignored by form_driver(). So this can be used for any purpose by the
|
|
application. It can be treated as an application specific action and take
|
|
corresponding action.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="tools"><title> Tools and Widget Libraries</title>
|
|
<para>
|
|
Now that you have seen the capabilities of ncurses and its sister libraries, you
|
|
are rolling your sleeves up and gearing for a project that heavily manipulates
|
|
screen. But wait.. It can be pretty difficult to write and maintain complex GUI
|
|
widgets in plain ncurses or even with the additional libraries. There are some
|
|
ready-to-use tools and widget libraries that can be used instead of writing your
|
|
own widgets. You can use some of them, get ideas from the code, or even extend
|
|
them.
|
|
</para>
|
|
|
|
<sect2 id="cdk"><title> CDK (Curses Development Kit) </title>
|
|
<para>
|
|
In the author's words
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>
|
|
CDK stands for 'Curses Development Kit' and it currently contains 21 ready
|
|
to use widgets which facilitate the speedy development of full screen
|
|
curses programs.
|
|
</emphasis>
|
|
</para>
|
|
|
|
<para>
|
|
The kit provides some useful widgets, which can be used in your programs
|
|
directly. It's pretty well written and the documentation is very good. The
|
|
examples in the examples directory can be a good place to start for beginners.
|
|
The CDK can be downloaded from <ulink
|
|
url="http://invisible-island.net/cdk/">http://invisible-island.net/cdk/</ulink>
|
|
. Follow the instructions in
|
|
README file to install it.
|
|
</para>
|
|
|
|
<sect3 id="widgetlist"><title> Widget List </title>
|
|
|
|
<para>
|
|
The following is the list of widgets provided with cdk and their description.
|
|
</para>
|
|
|
|
<programlisting>
|
|
Widget Type Quick Description
|
|
===========================================================================
|
|
Alphalist Allows a user to select from a list of words, with
|
|
the ability to narrow the search list by typing in a
|
|
few characters of the desired word.
|
|
Buttonbox This creates a multiple button widget.
|
|
Calendar Creates a little simple calendar widget.
|
|
Dialog Prompts the user with a message, and the user
|
|
can pick an answer from the buttons provided.
|
|
Entry Allows the user to enter various types of information.
|
|
File Selector A file selector built from Cdk base widgets. This
|
|
example shows how to create more complicated widgets
|
|
using the Cdk widget library.
|
|
Graph Draws a graph.
|
|
Histogram Draws a histogram.
|
|
Item List Creates a pop up field which allows the user to select
|
|
one of several choices in a small field. Very useful
|
|
for things like days of the week or month names.
|
|
Label Displays messages in a pop up box, or the label can be
|
|
considered part of the screen.
|
|
Marquee Displays a message in a scrolling marquee.
|
|
Matrix Creates a complex matrix with lots of options.
|
|
Menu Creates a pull-down menu interface.
|
|
Multiple Line Entry A multiple line entry field. Very useful
|
|
for long fields. (like a description
|
|
field)
|
|
Radio List Creates a radio button list.
|
|
Scale Creates a numeric scale. Used for allowing a user to
|
|
pick a numeric value and restrict them to a range of
|
|
values.
|
|
Scrolling List Creates a scrolling list/menu list.
|
|
Scrolling Window Creates a scrolling log file viewer. Can add
|
|
information into the window while its running.
|
|
A good widget for displaying the progress of
|
|
something. (akin to a console window)
|
|
Selection List Creates a multiple option selection list.
|
|
Slider Akin to the scale widget, this widget provides a
|
|
visual slide bar to represent the numeric value.
|
|
Template Creates a entry field with character sensitive
|
|
positions. Used for pre-formatted fields like
|
|
dates and phone numbers.
|
|
Viewer This is a file/information viewer. Very useful
|
|
when you need to display loads of information.
|
|
===========================================================================
|
|
</programlisting>
|
|
|
|
<para>
|
|
A few of the widgets are modified by Thomas Dickey in recent versions.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="cdkattract"><title> Some Attractive Features </title>
|
|
<para>
|
|
Apart from making our life easier with readily usable widgets, cdk solves one
|
|
frustrating problem with printing multi colored strings, justified strings
|
|
elegantly. Special formatting tags can be embedded in the strings which are
|
|
passed to CDK functions. For Example
|
|
</para>
|
|
|
|
<para>
|
|
If the string
|
|
</para>
|
|
|
|
<programlisting>
|
|
"</B/1>This line should have a yellow foreground and a blue
|
|
background.<!1>"
|
|
</programlisting>
|
|
|
|
<para>
|
|
given as a parameter to newCDKLabel(), it prints the line with yellow foreground
|
|
and blue background. There are other tags available for justifying string,
|
|
embedding special drawing characters etc.. Please refer to the man page
|
|
cdk_display(3X) for details. The man page explains the usage with nice examples.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="cdkconclusion"><title> Conclusion </title>
|
|
<para>
|
|
All in all, CDK is a well-written package of widgets, which if used properly can
|
|
form a strong frame work for developing complex GUI.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="dialog"><title> The dialog </title>
|
|
<para>
|
|
Long long ago, in September 1994, when few people knew linux, Jeff Tranter wrote
|
|
an <ulink url="http://www2.linuxjournal.com/lj-issues/issue5/2807.html">article
|
|
</ulink> on dialog in Linux Journal. He starts the article with these words..
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>
|
|
Linux is based on the Unix operating system, but also features a number of
|
|
unique and useful kernel features and application programs that often go beyond
|
|
what is available under Unix. One little-known gem is "dialog", a utility for
|
|
creating professional-looking dialog boxes from within shell scripts. This
|
|
article presents a tutorial introduction to the dialog utility, and shows
|
|
examples of how and where it can be used
|
|
</emphasis>
|
|
</para>
|
|
|
|
<para>
|
|
As he explains, dialog is a real gem in making professional-looking dialog boxes
|
|
with ease. It creates a variety of dialog boxes, menus, check lists etc.. It is
|
|
usually installed by default. If not, you can download it from <ulink
|
|
url="http://invisible-island.net/dialog/">Thomas Dickey</ulink>'s site.
|
|
</para>
|
|
|
|
<para>
|
|
The above-mentioned article gives a very good overview of its uses and
|
|
capabilites. The man page has more details. It can be used in variety of
|
|
situations. One good example is building of linux kernel in text mode. Linux
|
|
kernel uses a modified version of dialog tailored for its needs.
|
|
</para>
|
|
|
|
<para>
|
|
dialog was initially designed to be used with shell scripts. If you want to use
|
|
its functionality in a c program, then you can use libdialog. The documentation
|
|
regarding this is sparse. Definitive reference is the dialog.h header file which
|
|
comes with the library. You may need to hack here and there to get the required
|
|
output. The source is easily customizable. I have used it on a number of
|
|
occasions by modifying the code.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="perlcurses"><title> Perl Curses Modules CURSES::FORM and CURSES::WIDGETS</title>
|
|
<para>
|
|
The perl module Curses, Curses::Form and Curses::Widgets give access to curses
|
|
from perl. If you have curses and basic perl is installed, you can get these
|
|
modules from <ulink url="http://www.cpan.org/modules/01modules.index.html"> CPAN
|
|
All Modules page</ulink>. Get the three zipped modules in the Curses category.
|
|
Once installed you can use these modules from perl scripts like any other
|
|
module. For more information on perl modules see perlmod man page. The above
|
|
modules come with good documentation and they have some demo scripts to test the
|
|
functionality. Though the widgets provided are very rudimentary, these modules
|
|
provide good access to curses library from perl.
|
|
</para>
|
|
|
|
<para>
|
|
Some of my code examples are converted to perl by Anuradha Ratnaweera and they
|
|
are available in the <literal remap="tt">perl</literal> directory.
|
|
</para>
|
|
|
|
<para>
|
|
For more information see man pages Curses(3) , Curses::Form(3) and
|
|
Curses::Widgets(3). These pages are installed only when the above modules are
|
|
acquired and installed.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="justforfun"> <title>Just For Fun !!!</title>
|
|
|
|
<para>
|
|
This section contains few programs written by me just for fun. They don't
|
|
signify a better programming practice or the best way of using ncurses. They are
|
|
provided here so as to allow beginners to get ideas and add more programs to
|
|
this section. If you have written a couple of nice, simple programs in curses
|
|
and want them to included here, contact <ulink url="mailto:ppadala@gmail.com">
|
|
me</ulink>.
|
|
</para>
|
|
|
|
<sect2 id="gameoflife"><title>The Game of Life</title>
|
|
<para>
|
|
Game of life is a wonder of math. In
|
|
<ulink url="http://www.math.com/students/wonders/life/life.html">
|
|
Paul Callahan</ulink>'s words
|
|
</para>
|
|
|
|
<programlisting>
|
|
<emphasis>
|
|
The Game of Life (or simply Life) is not a game in the conventional sense. There
|
|
are no players, and no winning or losing. Once the "pieces" are placed in the
|
|
starting position, the rules determine everything that happens later.
|
|
Nevertheless, Life is full of surprises! In most cases, it is impossible to look
|
|
at a starting position (or pattern) and see what will happen in the future. The
|
|
only way to find out is to follow the rules of the game.
|
|
</emphasis>
|
|
</programlisting>
|
|
|
|
<para>
|
|
This program starts with a simple inverted U pattern and shows how wonderful
|
|
life works. There is a lot of room for improvement in the program. You can let
|
|
the user enter pattern of his choice or even take input from a file. You can
|
|
also change rules and play with a lot of variations. Search on <ulink
|
|
url="http://www.google.com">google</ulink> for interesting information on game
|
|
of life.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>File Path: JustForFun/life.c</emphasis>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="magic"><title>Magic Square</title>
|
|
<para>
|
|
Magic Square, another wonder of math, is very simple to understand but very
|
|
difficult to make. In a magic square sum of the numbers in each row, each column
|
|
is equal. Even diagnol sum can be equal. There are many variations which have
|
|
special properties.
|
|
</para>
|
|
|
|
<para>
|
|
This program creates a simple magic square of odd order.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>File Path: JustForFun/magic.c</emphasis>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="hanoi"> <title> Towers of Hanoi </title>
|
|
<para>
|
|
The famous towers of hanoi solver. The aim of the game is to move the disks on
|
|
the first peg to last peg, using middle peg as a temporary stay. The catch is
|
|
not to place a larger disk over a small disk at any time.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>File Path: JustForFun/hanoi.c</emphasis>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="queens"> <title> Queens Puzzle </title>
|
|
<para>
|
|
The objective of the famous N-Queen puzzle is to put N queens on a N X N chess
|
|
board without attacking each other.
|
|
</para>
|
|
|
|
<para>
|
|
This program solves it with a simple backtracking technique.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>File Path: JustForFun/queens.c</emphasis>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="shuffle"> <title>Shuffle </title>
|
|
<para>
|
|
A fun game, if you have time to kill.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>File Path: JustForFun/shuffle.c</emphasis>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="tt"> <title>Typing Tutor </title>
|
|
<para>
|
|
A simple typing tutor, I created more out of need than for ease of use. If you
|
|
know how to put your fingers correctly on the keyboard, but lack practice, this
|
|
can be helpful.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>File Path: JustForFun/tt.c</emphasis>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="ref"> <title>References</title>
|
|
<itemizedlist>
|
|
<listitem><para>NCURSES man pages </para> </listitem>
|
|
<listitem><para>NCURSES FAQ at <ulink
|
|
url="http://invisible-island.net/ncurses/ncurses.faq.html">
|
|
http://invisible-island.net/ncurses/ncurses.faq.html</ulink>
|
|
</para> </listitem>
|
|
<listitem><para>Writing programs with NCURSES by Eric Raymond and Zeyd M.
|
|
Ben-Halim at
|
|
<ulink
|
|
url="http://invisible-island.net/ncurses/ncurses-intro.html">http://invisible-island.net/ncurses/ncurses-intro.html</ulink> - somewhat
|
|
obsolete. I was inspired by this document and the structure of this HOWTO
|
|
follows from the original document</para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
</article>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-namecase-general:t
|
|
sgml-general-insert-case:lower
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:nil
|
|
sgml-parent-document:nil
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|