cforms.tex

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

% LATEX Documentation for CForms
% By Lars Berntzon
% @(#) cforms.tex,v 1.10 1993/07/21 00:02:44 lasse Exp
%
\newcommand{\synopsys}[1]{\verb!\newline
Synopsys: {#1}!
}

\documentstyle{article}
\title{CForms v
\input patchlevel
}
\author{Lars Berntzon, E-Mail: [e-mail]}
\begin{document}
\maketitle

\section{Introduction}

	CForms is a formular manager for building applications to be used for
	many types of terminals though it uses the {\em curses} library.
	CForms is built up by a language that consists of the objects: modules,
	pictures, fields, literals and events. This language is the compiled
	with a compiler called {\em cfc} an all compiled files are finally
	linked with a linker called {\em cfl}.

	An application is built by one or more modules that contains one or more
	pictures that handles the various functions in the application.
	Each picture may contain any number of fields and text literal
	that describes the appearance of the picture.

	Fields are defined by their name and are shaped by their type,
	size, special attributes and event handling functions.

	CForms may be intermixed with C-code modules in any way.


\section{Language description}

	The language is not case sensitive exept thoose parts
	that are pure C-code (in events- and ccode statements).

	
\subsection{Viewports}

	To create a picture you first need to create a viewport, wich 
	describes the size and position on the real screen where the picture
	should appear. A viewport is defined by its name, wich later should
	be referenced by the picture. Several pictures may share the same
	viewport.

	Syntax for a viewport is:
	\begin{verbatim}
        VIEWPORT <name> {
            POS <column>, <row>;
            SIZE <width>, <height>;
        }
	\end{verbatim}

	Example:
	\begin{verbatim}
        Viewport stdscreen {
            Pos 1,1;
            Size 80, 24;
        }
	\end{verbatim}


\subsection{CCode}
	The CCode statement introduces a C-code block that may contain any
	code such as global variables, functions, preprocessor statements.
	This means that there is no need to have separated form-files and
	C-files with support functions. Ccodes may only be used in outer
	scopes, i.e. not inside pictures, literals or fields.

	Syntax for Ccode is:
        \begin{verbatim}
        CCODE {
            <Any C code>
        }
        \end{verbatim}

	Example:
        \begin{verbatim}
        CCode {
            cleanup()
            {
                free_all_mem();
                cforms_end();
                exit();
            }
        }
        \end{verbatim}


\subsection{Pictures}

	A picture is what shows up on the terminal when the application is
	running. Pictures contains fields - which are places for input or
	output, literals - which are static texts and events -
	events doesn't show but defines C-code functions to be called when
	certain things happens. Events specified in pictures are actually
	used by fields, but they are automatically specified for all fields
	in that pictures (unless specifically turned off), in other worlds a
	default event for all fields.

	A pictures is defined by its name, and the first picture to be started
	in the application is determined in the main routine (or a descendant)
	through the function {\em pic\_call}.

	A picture can also have modifiers, currently the only modifier available
	is the word {\em Frame} will cause a border to be drawn around the
	picture, note that this will scrink the effective area of the picture.

	Syntax for a picture is:
	\begin{verbatim}
        PICTURE <picture-name> VIEWPORT <viewport-name> {
            <literals>   \
            <fields>      > in any order
            <modifier>   |
            <events>     /
        }
	\end{verbatim}

	Example:
	\begin{verbatim}
        Picture main Viewport stdscreen {
            Literal 10, 10, "Welcome, enter your name: ";
            Frame;
            Field Name {
                Pos +0, +1;
                Type Char(10);
            }
        }
	\end{verbatim}


\subsection{Fields}

	Fields are placesholders in pictures that may be used to input from
	operator and/or as output from the application. A field may be of
	many kind of types and sizes. Fields can also contain events that
	will be called when the specified event occurs. It is also possible
	to specify literal text to appear immediately before and immediately
	after the actual field, this makes it possible to have text belonging
	to fields that are not depending of the fields position.

	The position of a field may be specified in absolute- or relative 
	coordinates. For relative coordinates the column- and row number is
	prefixed by a minus or a plus sign meaning positive or negative
	relative position. A position can also be specified as {\em Center}
	as either the row or column value which will center the field and the
	word {\em Max} wich will place the field at the border of the picture
	(rightmost column or lowest line).
	Finally it is possible to specify a couple of modifiers for the field
	that modifies adjustment, visibility, protection e.t.c.


	Valid types for a field is:
	\begin{itemize}
	   \item{INT} Field may only contain digits.
	   \item{ALNUM} Field may only contain alphanumeric characters.
	   \item{CHAR} Field may contain any printable character.
	\end{itemize}
	The size of a field is by default 1, but may be altered as a number
	within brackets after the type.

	Valid modifiers are:
	\begin{itemize}
	    \item{PROTECTED}	- Field may not be altered.
	    \item{FORBIDDEN}	- Field may not be be moved to.
	    \item{UPPERCASE}	- All alpha characters are in uppercase.
	    \item{HIGHLIGHT}	- Field is highlighted.
	    \item{INVISIBLE}	- Field is invisible.
	\end{itemize}

	Syntax for a field is:
	\begin{verbatim}
        FIELD <name> {
            <type> [(<size>)];
            POS [+-]<column>, [+-]<row>;
            LVALUE "<left value>";
            RVALUE "<right value>";
            [MODIFIER;]
        }
	\end{verbatim}
	Example:
	\begin{verbatim}
        Field adress {
            Pos 20, +1;
            Type Char(20);
            LValue "Adress: ";
            Uppercase;
        }
	\end{verbatim}

\subsection{Literals}

	Literals is static text to be visualized in the picture, literals
	is below fields if a collission should occur. The same position
	coordinates can be used as for fields (ex. Center).
	Syntax of a literal is:
	\begin{verbatim}
        Literal [+-]<column>, [+-]<row>, "<text>";
	\end{verbatim}
	Example:
	\begin{verbatim}
        Literal +0, +1, "List of persons";
	\end{verbatim}

\subsection{Events}

	Events are used to define functions keys and other special cases for eg.
	refresh display and so on. An event is specified by its event type
	and either a block of C-code to execute when the event occurres, or the
	word 'forget' wich means that the specified event should be disabled for
	this field.

	Type of events is:
	\begin{itemize}
	   \item[KEY] A key has been pressed. An event of the type KEY must 
		      be followed by the name of the key, later in this
		      document you will find a list of all valid keys. The
		      special key ANY means any key and the variable
		      {\em event\_code} contains the value of that key.
	   \item[REFRESH] Refresh the picture.
	   \item[DRAW] Only available from pictures, is called.
	    	       when a pictures is first drawn.
	   \item[ENTRY] When field is entered.
	   \item[EXIT] When field is left.
	   \item[PREVIOUS] When trying to move to the left of the field.
	   \item[NEXT] When trying to move to the right of the field.
	\end{itemize}
	    

	Syntax for an event is:
	\begin{verbatim}
        [GLOBAL] EVENT <type> [<type modifier>] {
            <C-code statements>
        }
	\end{verbatim}
	or
	\begin{verbatim}
        [GLOBAL] EVENT <type> [<type modifier>] FORGET;
	\end{verbatim}
	Example:
	\begin{verbatim}
        Event Entry {
            fld_set(NULL, "X");
        }

        Event Key DOWN  {
            fld_move(fld_down(NULL));
        }
	\end{verbatim}

	The keywork {\em GLOBAL} may only be specified for events outside
	fields and pictures and if it is this event handler will be active 
	for all pictures in the application unless overridden by more local
	event handlers including the {\em FORGET} type.

	
\section{EVENT and CCODE programing}


	For all event- and ccode blocks the developer can use a set
	library functions that comes with cforms. Most functions returning
	integers returns either OK or FAIL exept for those like fld\_len that
	returns the value expected. Those returning pointers return NULL
	uppon failure.
	This is a list and a description of all functions:	    
	\subsection{Start/stop functions}
 	    \subsubsection{cforms\_init} Initiate CForms, this must be done
		before any cforms functions can be called.
	        \synopsys{int cforms\_init(void)}

	    \subsubsection{cforms\_end} Stop CForms.
		\synopsys{int cforms\_end(void)}

	    \subsubsection{cforms\_refresh} Refresh the CForms screen.
		\synopsys{void cforms\_system(void)}

	    \subsubsection{cforms\_system} Run a operating system command.
		\synopsys{int cforms\_system(const char *command, const char *prompt)} \\
		This will run a operating system command without destroying
		the screen. Before the command is executed the screen is cleared
		and upon completion the screen will be redrawn. If the
		{\em prompt} is not NULL then the routine will also print the
		prompt and waint until user presses the return key.

 	\subsection{Picture functions}
 	    \subsubsection{pic\_call} Call picture.
	       \synopsys{int pic\_call(struct picture *, field *)}\\
		Where picture is a pointer to the picture to call and field
		is where the cursor lands on, NULL means the first field in
		picture.