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}