fpc/docs/crt.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA. 
%
\chapter{The CRT unit.}
\label{ch:crtunit}

\FPCexampledir{crtex}
This chapter describes the \var{CRT} unit for Free Pascal, both under \dos
\linux and \windows. The unit was first written for \dos by Florian kl\"ampfl. 
The unit was ported to \linux by Mark May\footnote{Current
e-mail address \textsf{mmay@dnaco.net}}, and enhanced by Micha\"el Van Canneyt
and Peter Vreman. It works on the \linux console, and in xterm and rxvt windows
under X-Windows. The functionality for both is the same, except that under
\linux the use of an early implementation (versions 0.9.1 and earlier of the
compiler) the crt unit automatically cleared the screen at program startup.

There are some caveats when using the CRT unit:
\begin{itemize}
\item Programs using the CRT unit will {\em not} be usable when input/output 
is being redirected on the command-line.

\item For similar reasons they are not usable as CGI-scripts for use with a 
webserver. 

\item The use of the CRT unit and the graph unit may not always be supported. 

\item On \linux or other unix OSes , executing other programs that expect 
special terminal behaviour (using one of the special functions in the linux
unit) will not work. The terminal is set in RAW mode, which will destroy
most terminal emulation settings.
\end{itemize}

This chapter is divided in two sections. 
\begin{itemize}
\item The first section lists the pre-defined constants, types and variables. 
\item The second section describes the functions which appear in the
interface part of the CRT unit.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Types, Variables, Constants
\section{Types, Variables, Constants}
Color definitions :
\begin{verbatim}
  Black = 0;
  Blue = 1;
  Green = 2;
  Cyan = 3;
  Red = 4;
  Magenta = 5;
  Brown = 6;
  LightGray = 7;
  DarkGray = 8;
  LightBlue = 9;
  LightGreen = 10;
  LightCyan = 11;
  LightRed = 12;
  LightMagenta = 13;
  Yellow = 14;
  White = 15;
  Blink = 128;
\end{verbatim}
Miscellaneous constants
\begin{verbatim}
  TextAttr: Byte = $07;
  TextChar: Char = ' ';
  CheckBreak: Boolean = True;
  CheckEOF: Boolean = False;
  CheckSnow: Boolean = False;
  DirectVideo: Boolean = False;
  LastMode: Word = 3;
  WindMin: Word = $0;
  WindMax: Word = $184f;
  ScreenWidth = 80;
  ScreenHeight = 25;
\end{verbatim}
Some variables for compatibility with Turbo Pascal. However, they're not
used by \fpc.
\begin{verbatim}
var
  checkbreak : boolean;
  checkeof : boolean;
  checksnow : boolean;
\end{verbatim}
The following constants define screen modes on a \dos system:
\begin{verbatim}
Const
  bw40 = 0;
  co40 = 1;
  bw80 = 2;
  co80 = 3;
  mono = 7;
\end{verbatim}
The \var{TextAttr} variable controls the attributes with which characters
are written to screen.
\begin{verbatim}
var TextAttr : byte;
\end{verbatim}
The \var{DirectVideo} variable controls the writing to the screen. If it is
\var{True}, the the cursor is set via direct port access. If \var{False},
then the BIOS is used. This is defined under \dos only.
\begin{verbatim}
var DirectVideo : Boolean;
\end{verbatim}
The \var{Lastmode} variable tells you which mode was last selected for the
screen. It is defined on \dos only.
\begin{verbatim}
var lastmode : Word;
\end{verbatim}

% Procedures and functions.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Procedures and Functions}

\begin{procedure}{AssignCrt}
\Declaration
Procedure AssignCrt (Var F: Text);
\Description
\var{AssignCrt} Assigns a file F to the console. Everything written to 
the file F goes to the console instead. If the console contains a window, 
everything is written to the window instead.

\Errors
None.
\SeeAlso
\seep{Window}
\end{procedure}

\FPCexample{ex1}
 
\begin{procedure}{CursorBig}
\Declaration
Procedure CursorBig ;
\Description
Makes the cursor a big rectangle. 
Not implemented on \linux.
\Errors
None.
\SeeAlso
\seep{CursorOn}, \seep{CursorOff}
\end{procedure}

\begin{procedure}{ClrEol}
\Declaration
Procedure ClrEol ;
\Description
 ClrEol clears the current line, starting from the cursor position, to the
end of the window. The cursor doesn't move
\Errors
None.
\SeeAlso
\seep{DelLine}, \seep{InsLine}, \seep{ClrScr}
\end{procedure}

\FPCexample{ex9}
 
\begin{procedure}{ClrScr}
\Declaration
Procedure ClrScr ;
\Description
 ClrScr clears the current window (using the current colors), 
and sets the cursor in the top left
corner of the current window.
\Errors
None.
\SeeAlso
 \seep{Window} 
\end{procedure}

\FPCexample{ex8}
 
\begin{procedure}{CursorOff}
\Declaration
Procedure CursorOff ;
\Description
Switches the cursor off (i.e. the cursor is no
longer visible). 
Not implemented on \linux.
\Errors
None.
\SeeAlso
\seep{CursorOn}, \seep{CursorBig}
\end{procedure}
\begin{procedure}{CursorOn}
\Declaration
Procedure CursorOn ;
\Description
Switches the cursor on. 
Not implemented on \linux.
\Errors
None.
\SeeAlso
\seep{CursorBig}, \seep{CursorOff}
\end{procedure}
\begin{procedure}{Delay}
\Declaration
Procedure Delay (DTime: Word);
\Description
Delay waits a specified number of milliseconds. The number of specified
seconds is an approximation, and may be off a lot, if system load is high.
\Errors
None
\SeeAlso
\seep{Sound}, \seep{NoSound}
\end{procedure}

\FPCexample{ex15}
 
\begin{procedure}{DelLine}
\Declaration
Procedure DelLine ;
\Description
 DelLine removes the current line. Lines following the current line are 
scrolled 1 line up, and an empty line is inserted at the bottom of the
current window. The cursor doesn't move.
\Errors
None.
\SeeAlso
\seep{ClrEol}, \seep{InsLine}, \seep{ClrScr}
\end{procedure}

\FPCexample{ex11}
 
\begin{procedure}{GotoXY}
\Declaration
Procedure GotoXY (X: Byte; Y: Byte);
\Description
 Positions the cursor at \var{(X,Y)}, \var{X} in horizontal, \var{Y} in
vertical direction relative to the origin of the current window. The origin
is located at \var{(1,1)}, the upper-left corner of the window.

\Errors
None.
\SeeAlso
 \seef{WhereX}, \seef{WhereY}, \seep{Window} 
\end{procedure}

\FPCexample{ex6}
 
\begin{procedure}{HighVideo}
\Declaration
Procedure HighVideo ;
\Description
 HighVideo switches the output to highlighted text. (It sets the high
intensity bit of the video attribute)

\Errors
None.
\SeeAlso
 \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
\seep{NormVideo}
\end{procedure}

\FPCexample{ex14}
 
\begin{procedure}{InsLine}
\Declaration
Procedure InsLine ;
\Description
 InsLine inserts an empty line at the current cursor position. 
Lines following the current line are scrolled 1 line down, 
causing the last line to disappear from the window. 
The cursor doesn't move.
\Errors
None.
\SeeAlso
\seep{ClrEol}, \seep{DelLine}, \seep{ClrScr}
\end{procedure}

\FPCexample{ex10}
 
\begin{function}{KeyPressed}
\Declaration
Function KeyPressed  : Boolean;
\Description
 The Keypressed function scans the keyboard buffer and sees if a key has
been pressed. If this is the case, \var{True} is returned. If not,
\var{False} is returned. The \var{Shift, Alt, Ctrl} keys are not reported.
The key is not removed from the buffer, and can hence still be read after
the KeyPressed function has been called.

\Errors
None.
\SeeAlso
\seef{ReadKey}
\end{function}

\FPCexample{ex2}
 
\begin{procedure}{LowVideo}
\Declaration
Procedure LowVideo ;
\Description
 LowVideo switches the output to non-highlighted text. (It clears the high
intensity bit of the video attribute)

\Errors
None.
\SeeAlso
 \seep{TextColor}, \seep{TextBackground}, \seep{HighVideo},
\seep{NormVideo}
\end{procedure}
For an example, see \seep{HighVideo}
\begin{procedure}{NormVideo}
\Declaration
Procedure NormVideo ;
\Description
 NormVideo switches the output to the defaults, read at startup. (The
defaults are read from the cursor position at startup)

\Errors
None.
\SeeAlso
 \seep{TextColor}, \seep{TextBackground}, \seep{LowVideo},
\seep{HighVideo}
\end{procedure}
For an example, see \seep{HighVideo}
\begin{procedure}{NoSound}
\Declaration
Procedure NoSound ;
\Description

Stops the speaker sound.
This call is not supported on all operating systems.
\Errors
None.
\SeeAlso
\seep{Sound}
\end{procedure}

\FPCexample{ex16}
 
\begin{function}{ReadKey}
\Declaration
Function ReadKey  : Char;
\Description

The ReadKey function reads 1 key from the keyboard buffer, and returns this.
If an extended or function key has been pressed, then the zero ASCII code is 
returned. You can then read the scan code of the key with a second ReadKey
call.
\textbf{Remark.} Key mappings under Linux can cause the wrong key to be
reported by ReadKey, so caution is needed when using ReadKey.  

\Errors
None.
\SeeAlso
\seef{KeyPressed}
\end{function}


\FPCexample{ex3}


\begin{procedure}{Sound}
\Declaration
Procedure Sound (hz : word);
\Description
 Sounds the speaker at a frequency of \var{hz}. Under \windows,
 a system sound is played and the frequency parameter is ignored.
 On other operating systems, this routine may not be implemented.
\Errors
None.
\SeeAlso
\seep{NoSound}
\end{procedure}

\begin{procedure}{TextBackground}
\Declaration
Procedure TextBackground (CL: Byte);
\Description

TextBackground sets the background color to \var{CL}. \var{CL} can be one of the
predefined color constants.

\Errors
None.
\SeeAlso
 \seep{TextColor}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}
\end{procedure}

\FPCexample{ex13}
 
\begin{procedure}{TextColor}
\Declaration
Procedure TextColor (CL: Byte);
\Description

TextColor sets the foreground color to \var{CL}. \var{CL} can be one of the
predefined color constants.

\Errors
None.
\SeeAlso
 \seep{TextBackground}, \seep{HighVideo}, \seep{LowVideo},
\seep{NormVideo}
\end{procedure}

\FPCexample{ex12}

\begin{procedure}{TextMode}
\Declaration
procedure TextMode(Mode: Integer);
\Description
\var{TextMode} sets the textmode of the screen (i.e. the number of lines
and columns of the screen). The lower byte is use to set the VGA text mode.

This procedure is only implemented on \dos.
\Errors
None.
\SeeAlso
\seep{Window}
\end{procedure}
 
\begin{function}{WhereX}
\Declaration
Function WhereX  : Byte;
\Description

WhereX returns the current X-coordinate of the cursor, relative to the
current window. The origin is \var{(1,1)}, in the upper-left corner of the
window.

\Errors
None.
\SeeAlso
 \seep{GotoXY}, \seef{WhereY}, \seep{Window} 
\end{function}

\FPCexample{ex7}
 
\begin{function}{WhereY}
\Declaration
Function WhereY  : Byte;
\Description

WhereY returns the current Y-coordinate of the cursor, relative to the
current window. The origin is \var{(1,1)}, in the upper-left corner of the
window.

\Errors
None.
\SeeAlso
 \seep{GotoXY}, \seef{WhereX}, \seep{Window} 
\end{function}

\FPCexample{ex7}
 
\begin{procedure}{Window}
\Declaration
Procedure Window (X1, Y1, X2, Y2: Byte);
\Description
 Window creates a window on the screen, to which output will be sent.
\var{(X1,Y1)} are the coordinates of the upper left corner of the window,
\var{(X2,Y2)} are the coordinates of the bottom right corner of the window.
These coordinates are relative to the entire screen, with the top left
corner equal to \var{(1,1)}
Further coordinate operations, except for the next Window call,
are relative to the window's top left corner.

\Errors
None.
\SeeAlso
\seep{GotoXY}, \seef{WhereX}, \seef{WhereY}, \seep{ClrScr}
\end{procedure}


\FPCexample{ex5}