5.1 How to program with AKFAvatar in Pascal

You can use AKFAvatar for your Pascal programs.

First of all the library must already be installed on your system. You also need the file akfavatar.pas. That file usually is not automatically installed, because there is no standard directory for that. But it is found, if it simply is in the current directory.

5.1.1 Simple use cases

In the source-package you will find the scripts gpcavatar and fpcavatar in the subdirectory pascal/. If you have GNU-Pascal (gpc) just try this: ‘./gpcavatar example.pas’ This should compile a program example.

You can compile any pascal program, that just uses plain standard input/output like this. There are no changes to the source-code of the pascal program necessary!

If you want to start a new page, simply use the command page;.

That is easy, isn't it?

     Note: If the program uses the CRT unit, you have to make
     changes to your program as described below.

5.1.2 Installing

Have a look into the scripts gpcavatar and fpcavatar. There are some variables you should adapt to your needs. Copy the scripts into /usr/local/bin, so you can use them from anywhere. Copy the file akfavatar.pas to where you want to have your personal units and make sure that directory is listed in the scripts.

5.1.3 Advanced use

It is also possible to port programs, which use the CRT unit with AKFAvatar. But then you have to make changes to your program.

The scripts gpcavatar and fpcavatar both define the symbol AKFAVATAR, so you can use {$IfDef AKFAVATAR} or {$IfNDef AKFAVATAR} to control what to do when it it compiled with AKFAvatar or without.

To make sure your program can still be used with the CRT unit, you can make something like this: ‘{$IfNDef AKFAVATAR} uses CRT; {$EndIf}’. The program multiply.pas is an example for this technique.

AKFAvatar supports most commands and variables from the original CRT unit. For example the command ClrScr clears the text-area (not the whole screen!), ClrEol clears the rest of the line. You can use the command GotoXY(x, y); to go to a special position inside the text-area, or use the functions WhereX and WhereY to find out the current position.

     Attention: The width of the display is 80 characters as
     with a terminal display, but the height is often much smaller.
     You can find out the dimensions of the text-area with
     ScreenSize.x and ScreenSize.y.  The avatar is shown, when it
     wasn't visible yet.  So if you want to change the avatar-image or the
     background color, you have to do it, before asking for the size.

You can use the command TextColor(color); to change the color of the text. You can even set the background color of the text with the command TextBackground(color);, but that doesn't look as good as on a text-terminal.

Even the variable TextAttr is fully supported as in the original CRT unit. But it is better to avoid the use of that.

The commands HighVideo and LowVideo are supported, althogh with a slightly different meaning. HighVideo switches bold font on and LowVideo switches bold font off. They do not change the color as with the CRT unit. Please keep that in mind, when you combine them with calls to TextColor.

With Underlined(true); you can switch underlined mod on and Underlined(false); you can switch it off.

To switch back to the “normal” text-attributes, you should use the command NormVideo;. The “normal” text-color is different when you use it with AKFAvatar or with the CRT unit. So with this command you can ensure, that you get the desired result with both. NormVideo; also switches the bold- and the underlined-mode off.

The function ReadKey waits for a key to be pressed and returns the code of the pressed key. To find out, whether a key was pressed without blocking the program, you can use the function KeyPressed.

     Attention:
     Function keys are not supported yet.  The key <Esc> stops the
     program immediately.  If you need the <Esc>-key for something
     else, you can set the variable CheckEsc to false.
     The program also stops when <Ctrl>+<C> is pressed.  You can
     set the variable CheckBreak to false to avoid that.
     The variable CheckBreak is compatible to the CRT unit,
     while CheckEsc is an extension.

There are many additional commands, which are not compatible to the CRT unit.

You can use a different image for the avatar with the command

{$IfDef AKFAVATAR}
  AvatarImageFile ('/usr/local/share/pixmaps/human-peasant.bmp');
{$EndIf}

If you want to change the background color of the window (not the text-area), you can use the command setBackgroundColor(red, green, blue); at the beginning of the program. The value for red, green and blue represent the intensity of that color. You can mix up any possible color with these 3 values. The maximum is 255 ($FF). For example ‘setBackgroundColor(0, 0, 100);’ sets a dark blue background color.

You can define in your program which charset encoding you use. If you have an old system based on the Latin-1 charset, use the command setEncoding ('ISO-8859-1');. If you have to handle with different charsets at the same time, you can repeat this command whenever you want to change it. Different charsets can be visible in the text-area at the same time. (Internally a Unicode charset is used.)

There are also characters for Hebrew or Yiddish texts. To use them you have to change the text direction. You can do this with the command setTextDirection (RightToLeft); and setTextDirection (LeftToRight);. Please make sure that you start a new line or page before or after using this command. Mixing different text directions in one line is not supported.

The input/output is done with the common Pascal commands (Read, ReadLn, Write, WriteLn, Page). You can use the full Pascal formatting-syntax. For example: ‘WriteLn ('Pi is ', Pi:0:8, ' and so on.');’

If you want to enforce a new page, use the command page;. This is in fact also a Standard-Pascal command, which is seldom used; so seldom, that it is even missing in Free Pascal. But my unit defines it also for Free Pascal. Normally the command page; is used to get a new page on a printer.

You can also clear the text-area with the command ClrScr;. Unlike page; the command ClrScr; doesn't wait, but clears the text-area immediately. You can put the cursor in a deliberate position with the command GotoXY (x, y);. You find out, where the cursor is with the functions WhereX or WhereY. The coordinates 1, 1 is in the upper left corner (independent from the text direction). You can find the maximum positions with ScreenSize.x and ScreenSize.y. All these names where chosen to get some compatibility with the CRT unit. Actually they don't handle the screen, but only the text-area!

If you want to print warnings, error messages or debugging information to the text-terminal, use the file-descriptor stderr. (This doesn't work on Windows or ReactOS systems.) For example: ‘WriteLn (stderr, 'Error: ', AvatarGetError);’ Well, the function AvatarGetError gets an error message from the library.

The command ShowAvatar; shows only the avatar without the balloon. The commands MoveAvatarIn; or MoveAvatarOut; move the avatar in or out. The Command Delay (500); waits approximately for 500 milliseconds. If you prefer the scale in seconds use Delay (seconds(0.5));.

A full reference for the Pascal language can be found in Pascal reference.