Subversion Repositories shark

%----------------------------------------------------------------------------
\chapter{The Console Library}
%----------------------------------------------------------------------------

The output on the screen in text mode is supported by a group of functions that
act on the whole screen and modify, each time, the cursor's position. Since such
functions are not reentrant, they must be used in mutual exclusion.

In order to use the library for displaying on the screen, the
``\texttt{cons.h}'' file must be included. This file contains the values for
the usable colors whose symbolic names are listed below: \texttt{BLACK, BLUE,
GREEN, CYAN, RED, MAGENTA, BROWN, GRAY, LIGHTGRAY, LIGHTBLUE, LIGHTGREEN,
LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW, WHITE}.

Two global read-only variables \texttt{cons\_columns} and \texttt{cons\_rows}
contain the number of screen columns and the number of screen rows,
respectively. They can be used to write applications that are indipendent from
the screen dimensions.

\vspace{7mm}

\begin{intest}
CPUTC, CPUTS, CPRINTF \index{cputc()}\index{cputs()}\index{cprintf()}
\end{intest}

\begin{description}
\item [\textbf{void cputc(char c); }]
\item [\textbf{void cputs(char {*}s); }]
\item [\textbf{int cprintf(char {*}fmt,... ); }]
\item [\textbf{Description:}] \texttt{cputc}, \texttt{cupts} and \texttt{cprintf} are used
to print on the screen a character, a string, or a formatted string,
respectively. In the latter case, the standard C I/O formatting conventions are
used.
\item [\textbf{Warning:}]since these functions modify the cursor position, they are not
reentrant, and must be used in a mutually exclusive fashion.
\end{description}

\begin{intest}
PUTC\_XY, PUTS\_XY, PRINTF\_XY, GETC\_XY \index{putc\_xy()} \index{puts\_xy()}
\index{printf\_xy()} \index{getc\_xy()}
\end{intest}

\begin{description}
\item [\textbf{void putc\_xy(int x,int y,char attr,char c) }]
\item [\textbf{void puts\_xy(int x,int y,char attr,char {*}s) }]
\item [\textbf{int printf\_xy(int x,int y,char attr,char {*}fmt,...) }]
\item [\textbf{char getc\_xy(int x,int y,char {*}attr,char {*}c) }]
\item [\textbf{Description:}] These functions are similar to the previously defined ones;
the only difference is that since they're reentrant can be used concurrently by
multiple tasks (the others cannot be used for this purpose because they modify
the cursor's state). \texttt{getc\_xy} is used to read the charcater and its
attribute at a specific position on the screen.
\end{description}

\begin{intest}
CLEAR, \_CLEAR, SCROLL, \_SCROLL \index{clear()} \index{\_clear()}
\index{\_scroll()}
\end{intest}

\begin{description}
\item [\textbf{void \_clear(char c,char attr,int x1,int y1,int x2,int y2) }]
\item [\textbf{void clear(void) }]
\item [\textbf{void \_scroll(char attr,int x1,int y1,int x2,int y2) }]
\item [\textbf{void scroll(void) }]
\item [\textbf{Description:}] the \texttt{clear} and \texttt{scroll} functions are used
for clearing the screen and for scrolling it upwards. They are based on the
\texttt{\_clear()} and \texttt{\_scroll()} functions used for clearing or
scrolling a window (defined by \texttt{x1, y1, x2, y2}) by filling the area with
\texttt{attr} color and, in the case of \texttt{\_clear}, with character
\texttt{c} as well.
\end{description}

\begin{intest}
SET\_ACTIVE\_PAGE, SET\_VISUAL\_PAGE,\\
GET\_ACTIVE\_PAGE, GET\_VISUAL\_PAGE
\index{set\_active\_page()} \index{set\_visual\_page()}
\index{get\_active\_page()} \index{get\_visual\_page()}
\end{intest}

\begin{description}
\item [\textbf{void set\_active\_page(int page) }]
\item [\textbf{void set\_visual\_page(int page) }]
\item [\textbf{int get\_active\_page(void) }]
\item [\textbf{int get\_visual\_page(void) }]
\item [\textbf{Description:}] The video cards working in text mode use the CGA hardware
scheme. In this scheme, every screen occupies 4000 bytes (80 columns x 25 rows;
each position is associated with two bytes, one for codifying the character and
another for codifying the color). The video card memory is in general bigger,
therefore multiple screen pages can be used simultaneously. The currently
visualized screen is called the \texttt{visual page}, whereas the screen the
output is directed to is called the \texttt{active page}. The cited functions
are essentially used for handling, at a given instant, the visual page or the
active page. SUGGESTION: if the active page or the visual page are modified,
they should be restored to the original (0) value on exit; the same is true for
the cursor.
\end{description}

\begin{intest}
PLACE, CURSOR, CURSOR\_INFO
\index{place()} \index{cursor()} \index{cursor\_info()}
\end{intest}

\begin{description}
\item [\textbf{void place(int x, int y) }]
\item [\textbf{void cursor(int start\_scanline, int end\_scanline) }]
\item [\textbf{void cursor\_info(int {*}x, int {*}y) }]
\item [\textbf{Description:}] These functions are used for handling the cursor. More
specifically, \texttt{place} sets the cursor position (\texttt{x} belongs to the
range 0\ldots{}79, \texttt{y} to 0\ldots{}24).
\end{description}

\begin{intest}
CURSOR\_BLOB, CURSOR\_STD, CURSOR\_OFF
\index{cursor\_blob()} \index{cursor\_std()} \index{cursor\_off()}
\end{intest}

\begin{description}
\item [\textbf{void cursor\_blob(void) }]
\item [\textbf{void cursor\_std(void) }]
\item [\textbf{void cursor\_off(void) }]
\item [\textbf{Description:}] These macros call the \texttt{cursor()} function to set the
cursor shape to be a big rectangle, the standard underscore, or invisible.
\end{description}