cforms.tex

CForms, by Lars Berntzon (Stockholm, Sweden), is a tool for building interactive forms-driven applic

	    \subsubsection{pic\_clear} Clear all fields for picture.
		\synopsys{int pic\_clear(struct picture *)}\\
		If picture is NULL current picture is cleared.

	    \subsubsection{pic\_leave} Leave current picture after current
		event has finished.
		\synopsys{int pic\_leave(void)}

	    \subsubsection{picture} Get picture with name.
		\synopsys{struct picture *picture(char *fmt, ...)}\\
		Returns a pointer to a picture with the name generated
		with 'fmt' and its arguments the same way that printf works.

	\subsection{Field functions}
	    \subsubsection{field} Get field with name
		\synopsys{struct field *field(char *fmt, ...)}\\
		Returns a pointer to a field with the name generated
		with 'fmt' and its arguments the same way that printf works.

		If the field name is prepended by the picture name and a
		colon, i.e.  "picture:field", a field can be found in another
		picture than current picture.
		
	    \subsubsection{fld\_isempty} Check if field is empty, i.e.
		full of spaces, tabs or null.
		\synopsys{int fld\_isempty(struct field *)}\\
		Returns TRUE or FALSE condition.

	    \subsubsection{fld\_first} Find first field of picture.
		\synopsys{struct field *fld\_first(void)}

	    \subsubsection{fld\_last} Find last field of picture.
		\synopsys{struct field *fld\_last(void)}

	    \subsubsection{fld\_next} Find next field for picture.
		\synopsys{struct field *fld\_next(struct field *)}\\
		Returns the field after field given by argument (or
		current field if NULL).
		
	    \subsubsection{fld\_previous} Find previous field for picture.
		\synopsys{struct field *fld\_previous(struct field *)}\\
		Returns the field berfore field given by argument (or
		current field if NULL).

	    \subsubsection{fld\_left} Find left field.
		\synopsys{struct field *fld\_left(struct field *)}\\
		Returns the field to the left of the field given by argument
		(or current field if NULL).

	    \subsubsection{fld\_right} Find right field.
		\synopsys{struct field *fld\_right(struct field *)}\\
		Returns the field to the right of the field given by argument
		(or current field if NULL).

	    \subsubsection{fld\_up} Find field above current.
		\synopsys{struct field *fld\_up(struct field *)}\\
		Returns the field above the field given by argument
		(or cur\-rent.\-field if\- NULL).

	    \subsubsection{fld\_down} Find field below current.
		\synopsys{struct field *fld\_down(struct field *)}\\
		Returns the field below the field given by argument
		(or current \-field if\- NULL).

	    \subsubsection{fld\_set} Set value for field.
		\synopsys{int fld\_set(struct field *, char *)}\\
		If field is NULL set value for current field.

	    \subsubsection{fld\_nset} Set value for field but max n chars.
		\synopsys{int fld\_nset(struct field *, char *)}\\
		If field is NULL set value for current.field.

	    \subsubsection{fld\_get} Get value of field.
		\synopsys{char *fld\_get(struct field *)}\\
		If field is NULL get value for current field.

	    \subsubsection{fld\_get\_trimmed} Get value of field with trimmed blanks.
		\synopsys{char *fld\_get(struct field *)}\\
		This routine works like {\em fld\_get} exept that leading and trailing blanks
		is removed in the returned string.
		If field is NULL get value for current field.

	    \subsubsection{fld\_len} Return length of field.
		\synopsys{int fld\_len(struct field *)}\\
		If field is NULL return length for current field.
		
	    \subsubsection{fld\_name} Return name of a field.
		\synopsys{char *fld\_name(struct field *)}\\
		If field is NULL return name of current field.
		
	    \subsubsection{fld\_ismodified} Return true if field has been
		modified since last fld\_set or fld\_nset.
		\synopsys{int fld\_ismodified(struct field *)}\\
		If field is NULL return modified for current field.
		
	    \subsubsection{fld\_touch} Make field not modified.
		\synopsys{int fld\_touch(struct field *)}\\
		If field is NULL touch current field.

	    \subsubsection{fld\_sattr} Set attributed for a field.
		\synopsys{int fld\_sattr(struct field *, unsigned long)}\\
		The attributes are only added to the field, to remove attributes
		one must use {\em fld\_cattr()}.
		If field is NULL use current field.
		Possible attributes are:
		\begin{itemize}
		\item[FLD\_HIGHLIGHT] - Turn on highlighting of field.
		\item[FLD\_PROTECTED] - Make field insensitive for input.
		\item[FLD\_FORBIDDEN] - Make field illegal to move to. If the field modified is current field 
					then result is undefined.
		\item[FLD\_INVISIBLE] - Make field invisible.
		\end{itemize}

            \subsubsection{fld\_cattr} Clear attributed for a field.
                \synopsys{int fld\_sattr(struct field *, unsigned long)}\\
                If field is NULL use current field.
                Attributes are same as for {\em fld\_sattr()}.

 	\subsection{General functions}
 	    \subsubsection{message} Give message (line 24).
		\synopsys{int message(char *fmt, ...)}

	    \subsubsection{strequ} Compare two strings, but case insensitive. 
		Otherwhise the same functionality as strcmp().
		\synopsys{int strequ(char *s1, char *s2)}

	\subsection{Global variables}
	    Theese two global variables exists for backward compability only, 
	    if current field or current picture is to be referenced a NULL
	    pointer can always be used instead.
	    \subsubsection{current.picture} Allways points to current picture
		(can be NULL).
		\synopsys{struct picture *current.picture}

	    \subsubsection{current.field} Allways points to current field
		(can be NULL).
		\synopsys{struct field *current.field}

\section{How to compile and install CForms}

When you have unpacked the CForms archive you just do cd to the directory
where you unpacked it and change the DEST-variable in the Makefile.src to
where you want CForms installed. Then the {\em Configure} script must run.
After that you should do a 'make' followed by an 'make install'.
Don't make any changes in the Makefile, do it in the Makefile.src and rerun 
Configure instead.

You can also compile the example application in the example subdirectory
by doing 'make example', check it out to see what an application might look
like.

\section{How to compile CForms applications}

Lets say you just installed CForms with DEST set to {\em /usr/local},
that means that the CForms compiler resides in /usr/local/bin, the
cforms include file resides in /usr/local/include and the library
libcforms.a in /usr/local/lib, then this is how to compile a CForms
application:

First you run the CForms compiler, {\em cfc}, on your inputfiles:
    \begin{verbatim}
	cfc form1.frm
	cfc form2.frm
    \end{verbatim}

This will generate the c-code output files, {\em form1.c} and {\em form2.c}.
Those files must now be linked with the cforms linker {\em cfl}, just do:
    \begin{verbatim}
	cfl form1.frm form2.frm
    \end{verbatim}
This will produce the cforms linkage file {\em cforms.c}
What the linker does is simply putting together a list of all modules that
should be used from the application.
Now the system native c-compiler should be used to compile all those files
(including the cforms.c file)
plus all other files that should go along with the application:
    \begin{verbatim}
	cc -o <yourapp> -I/usr/local/include -L/usr/local/lib \
		 cforms.c form1.c form2.c -lcforms -lcurses -lterminfo
    \end{verbatim}
Observe that the -L flag must be there because the cforms library is in
/usr/\-local/\-lib.

Now you should be able to run you application.

\section{CForms formulas in object libraries}

It is possible to use pictures that has previously been compiled into object
libraries, in that case the modules from those libraries must be presented to
the cforms linker and to do this the name of the library module must be known
by the programmer.
The reason only the name has to be known is that the name of the module defines
a global varaible inside the library and {\em cfl} uses only the name of the
module and not the contents.

The first step in making a library is to run {\em cfc} on the forms file, this
produces the c-file. Compile this and put it into a library.

This example shows how the module {\em file\_browser} is put into a library:

\begin{verbatim}
    cfc file_browser.frm
    cc -c -I/usr/local/include file_browser.c
    ar r libfile.a file_browser.o
\end{verbatim}

Now the module is in the library libfile.a, if another application wants to
use pictures from this module it must first  add the text file\_browser.frm
to the argument list of {\em cfl}. Finally the actual library must be linked
with the application.

This example show the application {\em user\_menu} calls upon the
{\em file\_browser} module.
\begin{verbatim}
    cfc user_menu.frm
    cfl user_menu.frm file_browser.frm
    cc -o user_menu user_menu.o -L/usr/local/lib libfile.a \
        -lcforms -lcurses -lterminfo
\end{verbatim}
Also note that even if only one module is to be used the cfl must be
invoked for this single file to generate the {\em cforms.c} file.

\section{Keys}
Theese are the keys that can be used in event routines, note that capital
letter are doubles:
   \begin{tabbing}
    CLEAR: Sent by clear screen or erase key.xx\= \kill
    UNDERSCORE: Underscore	\> PLUS: Plus sign \\
    MINUS: Minus sign		\> AT: At sign \\
    HASH: hash mark		\> DOLLAR: Dollar sign \\
    SLASH: Slash sign		\> ASTERISK: Star \\
    TILDE: Tilde sign		\> BANG: Exclamation mark \\
    EQUAL: Equal sign		\> PERCENT: Precent sign \\
    AMPERSAND: And or Ampersand sign	\> LPAR: Left parentesis \\
    RPAR: Right parentesis	\> LBRACKET: Left bracket \\
    RBRACKET: Right breacket	\> LBRACE: Left brace \\
    RBRACE: Right brace		\> QUOTE: Souble quote \\
    SPACE: Space bar 		\> BLANK: Space bar  \\
    QUESTION: Question mark	\> ESC: Escape  \\
    BS: Backspace 		\> CR: Carriage return  \\
    TAB: Tab 			\> BREAK: break key (unreliable)  \\
    DOWN: Sent by terminal down arrow key \> UP: Sent by terminal up arrow key  \\
    LEFT: Sent by terminal left arrow key \> RIGHT: Sent by terminal right arrow key  \\
    HOME: Sent by home key. 	\> BACKSPACE: Sent by backspace key  \\
    F0 - F20: Function keys	\> DL: Sent by delete line key.  \\
    IL: Sent by insert line. 	\> DC: Sent by delete character key.  \\
    IC: Sent by ins char/enter ins mode key. \> EIC: Sent by rmir or smir in insert mode.  \\
    CLEAR: Sent by clear screen or erase key.\> EOS: Sent by clear-to-end-of-screen key.  \\
    EOL: Sent by clear-to-end-of-line key.\> SF: Sent by scroll-forward/down key  \\
    SR: Sent by scroll-backward/up key\> NPAGE: Sent by next-page key  \\
    PPAGE: Sent by previous-page key\> STAB: Sent by set-tab key  \\
    CTAB: Sent by clear-tab key	\> CATAB: Sent by clear-all-tabs key.  \\
    ENTER: Enter/send 		\> SRESET: soft (partial) reset \\
    RESET: reset or hard reset 	\> PRINT: print or copy  \\
    LL: Sent by home-down key 	\> A1: Upper left of keypad  \\
    A3: Upper right of keypad 	\> B2: Center of keypad  \\
    C1: Lower left of keypad 	\> C3: Lower right of keypad  \\
    BTAB: Back tab key 		\> BEG: beg(inning) key  \\
    CANCEL: cancel key 		\> CLOSE: close key  \\
    COMMAND: cmd (command) key 	\> COPY: copy key  \\
    CREATE: create key 		\> END: end key  \\
    EXIT: exit key 		\> FIND: find key  \\
    HELP: help key 		\> MARK: mark key  \\
    MESSAGE: message key 	\> MOVE: move key  \\
    OPTIONS: options key 	\> PREVIOUS: previous object key  \\
    REDO: redo key 		\> REFERENCE: ref(erence) key  \\
    REFRESH: refresh key 	\> REPLACE: replace key  \\
    RESTART: restart key 	\> RESUME: resume key  \\
    SAVE: save key 		\> SBEG: shifted beginning key  \\
    SCANCEL: shifted cancel key \> SCOMMAND: shifted command key  \\
    SCOPY: shifted copy key 	\> SCREATE: shifted create key  \\
    SDC: shifted delete char key\> SDL: shifted delete line key  \\
    SELECT: select key 		\> SEND: shifted end key  \\
    SEOL: shifted clear line key\> SEXIT: shifted exit key  \\
    SFIND: shifted find key 	\> SHELP: shifted help key  \\
    SHOME: shifted home key 	\> SIC: shifted input key  \\
    SLEFT: shifted left arrow key\> SMESSAGE: shifted message key  \\
    SMOVE: shifted move key 	\> SNEXT: shifted next key  \\
    SOPTIONS: shifted options key \> SPREVIOUS: shifted prev key  \\
    SPRINT: shifted print key 	\> SREDO: shifted redo key  \\
    REPLACE: shifted replace key\> NEXT: next object key \\
    SRIGHT: shifted right arrow	\> SRSUME: shifted resume key \\
    SSAVE: shifted save key	\> SSUSPEND: shifted suspend key \\
    SUNDO: shifted undo key	\> SUSPEND: suspend key \\
    UNDO: Undo key		\> MOUSE: Mouse event \\
    OPEN: open key		\> ANY: Any key \\
    AA - ZZ: Capital letters	\> a - z: lower case characters. \\
    \end{tabbing}
	
\newpage
\tableofcontents

\end{document}