This is the documentation for AKFAvatar (version 0.15.1, 2008-06-15).
AKFAvatar is a fancy terminal-emultator, a text-viewer, scripting language for making demos, and a library for writing programs in C or Pascal.Homepage: http://akfavatar.nongnu.org/
Copyright © 2007, 2008 Andreas K. Foerster, http://akfoerster.de/
Copying and distribution of this documentation, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.
AKFAvatar is a graphical program and a library, where an avatar appears on the screen, and tells things to the user written in a balloon. There can also be recorded audio files, so that the user even can hear, what it is saying.
AKFAvatar can be used in several different ways. I list them here from the most simple one to the most complicated for advanced users.
It is not suited for long, complicated texts, but rather for short and funny stuff.
Don't worry, it sounds more complicated, than it is. I should rather say, you can spice up your texts with occasional commands. Then you can set the executable bit on your... “text”, and it is executable.
libakfavatar, which you can use from
compiling languages. Currently Free Pascal, GNU-Pascal
and C are supported. Especially the Pascal language is suited for
beginners to learn how to program. The library is simple to use, like writing
command-line programs — but it's much more fun!
When an AKFAvatar program runs in a window, you can of course use the close button of your window manager for stopping the program. You can also always stop the program by pressing the key combination <Alt>+<Q>, for example when it runs in fullscreen mode. Often you can also stop the program by pressing the <Esc> key. But this key might be reserved for other things, for example in the terminal-mode of avatarsay.
You can press the <Pause> key at any time to pause the running process. Press any other key to continue again.
On some systems you can use the key combinations <Alt>+<Enter> or <Crtl>+<Alt>+<F> to toggle between the fullscreen and the window mode. Often you can also simply use the key <F11>, but this key might be reserved for other things, for example in the terminal-mode of avatarsay.
When AKFAvatar runs in a window you can resize the window as you wish. The content doesn't get resized, but it is centered on the window. You cannot resize it beyond a minimal size. You can of course also maximize the window. When you minimize the window the program continues to print the text. So you probably want to press the <Pause> key before you minimize the window.
Although there are binary packages available, you should install AKFAvatar from the source code package to use the software to its full capacity.
This chapter describes the installation for posix compatible operating systems, mainly for GNU/Linux systems. There are some hints for other systems at the end of this chapter.
For short: ‘./configure && make && make install’
Of course SDL needs a graphical environment to run in. For example the X-Window-System or a Linux framebuffer-device...
This is also needed on systems, which don't use the kernel Linux, but not on Windows. On Debian or derived distributions, you must have the package “ncurses-term” installed.
Without SDL_image you can only use uncompressed BMP images. SDL_image can be installed after the installation of this package.
Run ‘./configure’. If that succeeds run ‘make’ to create the binaries. There are two variants of avatarsay being compiled: 1. “avatarsay” has been statically linked with the avatar library. You can use this to test and play around with it before you install it. 2. “avatarsay-d” is dynamically linked and will only work, when the library is installed. This is the variant that gets installed.
On some systems you need the use the parameter --with-iconv with
.configure to get full iconv support (iconv is a charset-encoding
converter). This parameter is not needed, when SDL is already configured to
use an external iconv. But in some cases it is not, although an external
iconv is available (because maybe there is more than one implementation).
This software (AKFAvatar) does an educated guess to get the internal encoding
for wchar_t right. In some cases it might not work. You might then
provide that information with this option, like this
‘--with-iconv=UCS-4LE’. On many systems you can get a list with the
command iconv -l. If “WCHAR_T” or “wchar_t” is on the list,
use that.
If you know that SDL_image is always installed, then you can provide the parameter --enable-link-sdl-image to directly link to it, instead of loading it at runtime.
To support old versions of SDL on a target machine, it might be necessary to use the parameter --with-oldsdl. Note that this is not needed if you just want to run the program on the same machine on which you compile it.
If you want to use it on devices with a small display, use the
parameter --enable-size=vga or --enable-size=qvga with
configure. The value vga means a size of 640*480 pixels, while
qvga is for very small displays with 320*240 pixels. The size
qvga doesn't look good, it is just barely readable and supports less
characters.
The program avatarsay is a text reader and a simple scripting language. Try to view this text with that program: ‘./avatarsay INSTALL’.
You can stop avatarsay any time with the <Esc> key. On some systems you can toggle between window and fullscreen mode using the key <F11>. Another useful key is the <Pause> key.
There are some example scripts in the package. Try to run ‘./fsdemo-en’ or whatever language you prefer. Open fsdemo-en in a text-editor to see how to write such scripts...
You can also use it as a fancy manpage reader. Try ‘avtman man’...
Dynamically linked programs normally need the libraries to be installed on the system. The script lrun can be used to start programs, when the library is not yet installed. It searches the libraries also in the script's directory and in the current directory. Use it like this: ‘./lrun example’ finds the library in the current directory. Or from the Pascal subdirectory ‘../lrun multiply’ will find the library in the parent directory.
On GNU/Linux systems first make sure /usr/local/lib is mentioned in
the file /etc/ld.so.conf; either directly or indirectly. Also make
sure that /usr/local/bin is in your PATH evironment variable.
Now get root privileges and run ‘make install’ to install it in /usr/local. If you are low on disk space, you can instead use ‘make install-strip’. This installs binaries stripped from debugging information.
If you want to uninstall it later, you can use the command ‘make uninstall’.
With the command ‘make example’ you can compile the program example.c. The file example.c is an example, which you can use to start your own programs. The program gets dynamically linked, that means it needs the installed library. If you want to test it without the library being installed, use the script lrun (see above).
Solution: first try to add /usr/local/lib or wherever you
installed it to the environment variable LD_LIBRARY_PATH:
‘export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib’.
As a more permanent solution make sure /usr/local/lib is directly or indirectly included in the file /etc/ld.so.conf. Then run the command ldconfig with root privileges.
Solution: There are different character sets. Try to use the parameters --utf-8 or --latin1.
AKFAvatar is known to be compilable with FreeBSD 6.2. To get iconv support,
install libiconv and use ‘./configure --with-iconv’.
Windows is just partly supported. I provide binaries which are build with a crosscompiler. I haven't compiled them directly under Windows yet, so you're on your own here. I'm sorry.
For systems like these SDL supports a fallback implementation for iconv. The charset Windows-1252 (often called “ANSI” but it has nothing to do with ANSI) is not fully supported. That charset is partly compatible to the ISO-8859-1 standard, which is supported. Some characters are missing then. If you need these characters, save your text as UTF-8, which is also supported.
This chapter explains the various uses of the tool avatarsay.
The program avatarsay can be used as a fancy text-terminal and as a frontend for textconsole programs on posix-compatible systems (not for Windows).
From the main menu you can choose “terminal-mode”, or you can start avatarsay with the option --terminal, or -t for short. This gives you a terminal session with the default shell for your system-account. If you don't like colors being used in the balloon, you can use the option --nocolor, or -b for short.
If you want to use a different shell or starting directory, you can set the environment variables SHELL and HOME to different values. By the way, the program can get the correct values also when these variables are not set.
You can use avatarsay as a frontend for text-console programs. Use the option --execute, or -x for short, followed by the name of the program to execute. You can of course also combine this with the option --nocolor. Options after the programs name are passed to the executed program. That means, the order of the options is important.
For example to log in into another machine, using ssh:
avatarsay --execute ssh example.net
To write an e-mail with the program mutt:
avatarsay -bx mutt pal@example.net
Write the mail with a mail program on the remote machine:
avatarsay -bx ssh -t example.net mutt pal
Note: when you use ssh this way, you have to use the option -t for ssh.
Surf the web with lynx:
avatarsay -bx lynx
As you can see, you can use it to actually do very weird things with it.
The program avatarsay simulates the text-console of the kernel Linux.
So the environment variable TERM is set to either linux or
linux-m.
Because this choice might lead to some confusion, I try to explain, what this does not mean:
linux and linux-m in its terminal database(s).
console_codes and the Terminfo and Termcap entries and some
other documents to get information.
ANSI X3.64 (ECMA-48). But there are things missing and some
things, like key-codes are extra. So the value linux is actually the
right one.
The terminal-emulation of avatarsay supports
extensions, which are not in ANSI X3.64 (ECMA-48)
and which are not supported by the Linux terminal emulation.
To use these extensions in your own program, it is recommended first to check
for the existence of the environment variable AKFAVTTERM.
CSI ? 56 hCSI ? 56 lfurther extensions are planned.
The program avatarsay can be used as a fancy text-viewer. If you have a textfile, say mytext, then you can read it with the command ‘avatarsay mytext’. Try it! Now! ;-)
That is easy, isn't it? Well, if your text file is not encoded in
the right encoding for your system, you might have trouble with
non-ASCII characters. There are different encodings.
The most commonly used encodings are ISO-8859-1 (also known as
Latin-1) and UTF-8.
So if you have trouble with non-English characters, try to use the
parameter --encoding=UTF-8 or --encoding=ISO-8859-1 —
like this: ‘avatarsay --encoding=ISO-8859-1 mytext’.
Now, sometimes you might not want to show the whole in one continuous stream.
So you can structure your text by including a stripline.
A stripline is a line like this: ‘---------’. The line must start
at the very first column and there must be at least three successive
hyphens (U+002D). Of course you can use more than three ones.
When avatarsay sees a stripline, it waits a moment and then it
starts a new page.
You don't always have to use the command avatarsay for viewing your texts. You can turn your text itself into a “program”. How that works depends on your system.
On a POSIX compatible system, such as the GNU system you can put a special line at the beginning of your file. The line looks like this: ‘#! /usr/local/avatarsay’. Of course you have to make sure that you use the correct pathname. This has to be the very first line. You can put one or more empty lines after this line — they are ignored. Then you have to set the executable bit of your text file. That goes like this: ‘chmod +x mytext’. Then your text is executable. It accepts almost all the options that avatarsay accepts.
On systems like Windows or ReactOS this line doesn't work — but it doesn't harm either. On those systems you have to use a different trick. You could rename your file such, that it has a special extension; for example .avt. Now you have to configure your system, that the file extension .avt gets associated with the program avatarsay.exe. Then you can double-click on your “text” and it is executed.
Up to now you have always seen the same avatar — a gnu. Maybe you don't like gnus or what you want the avatar to say doesn't fit the GNU-project. — Well, that is just the default avatar. You can exchange it.
There are different methods to exchange the avatar for avatarsay:
You can change it globally for any use of avatarsay. This can be done either with an environment variable or you can use a system-wide configuration file.
Well, first you might want to try the environment variable. That is simple.
The variable is called AVATARIMAGE. So with the GNU bash you
can set this variable like this:
‘export AVATARIMAGE=/usr/local/share/pixmaps/myavatar.bmp’.
Important: You should always use the full path!
If you want to use a configuration file, create a file named /etc/avatarsay and put something like in this example into it:
AVATARIMAGE=/usr/local/share/pixmaps/myavatar.bmp
If you write a text you want to be shown by avatarsay, you can change the avatar-image on a text-by-text basis, using a command in the text-file. This is explained in Commands for avatarsay.
Which file-formats AKFAvatar supports depends on which libraries you have
installed. Uncompressed BMP images are always supported.
The avatar-image should have a transparent background of course. Well, most image formats don't support transparency at all. Therefore AKFAvatar has a trick. If the avatar-image has no transparency, then it looks up the first color in the image, that is the color in the upper left corner, and defines this color to be transparent. So when you prepare an image as replacement for the avatar, make sure the upper left corner is “empty” and make sure to choose a background color, which doesn't appear in the part of the image which is meant to be visible. Also make sure, that the background is “flat” with only one single color without any variations. Because of this requirement the JPEG format is not appropriate, you cannot get a really flat background in that format.
When you can use image formats which support transparency, then use it. AKFAvatar will not interfere with it then. Note however that the trick explained above is always used when the image has no transparency, independent from the question, whether the image format could have transparency.
The format for running avatarsay is:
avatarsay [options] [textfiles]
avatarsay [options] --execute program [program options]
If textfiles is - then the input is read from stdin and the program doesn't loop.
The program avatarsay supports the following options:
--help-h--version-v--terminal-t--execute-x-eA program name must be given. Options after the program name are options
for the executed program.
--nocolor-b--window-w--fullscreen-f--fullfullscreen-FThis option is also useful when there is only a fullscreen mode, but
switching the screen resolution doesn't work; for example with the
VESA framebuffer device of the kernel Linux
This option is only supported with SDL version 1.2.10 or newer.
--encoding=nameIt depends on your systems iconv implementation, which encodings
are supported. On some systems you can get a list with the command
iconv -l.
--latin1-l--utf-8--utf8-u8-uUTF-8
--once-1--popup-pUse this for a fast popup text.
Use the command .stop to also get a fast end.
--no-delay-n--raw-r--ignoreeof-iThe command avatarsay supports the following environment variables:
AVATARIMAGEDATADIRLC_ALLLC_CTYPELANGSHELLHOME
You can also use a configuration file with the name /etc/avatarsay to
set values for AVATARIMAGE and DATADIR.
for example:
AVATARIMAGE=/usr/local/share/pixmaps/myavatar.bmp
AVATARDATADIR=/usr/local/share/akfavatar
The program avatarsay understands a small set of commands. So you can spice up your “executable texts” even further.
A line starting with a hash sign (#, U+0023) is a
comment. Those lines are simply ignored by the program.
Attention: unlike in other scripting languages there may
even be no whitespace in front of the hash sign.
You can structure your text by including a stripline.
A stripline is a line like this: ‘---------’. The line must start
at the very first column and there must be at least three successive
hypens (U+002D). Of course you can use more than three ones.
A command for avatarsay starts with a dot (U+002E)
in the very first position of a new line.
The data directory can also be set with the environment variable
AVATARDATADIR. The command has precedence over the environment
variable.
Attention: This command has to be used before the text starts
The avatar image can also be set with the environment variable AVATARIMAGE. The command has precedence over the environment variable.
Which file-formats AKFAvatar supports depends on which libraries you have
installed. Uncompressed BMP images are always supported.
Attention: This command has to be used at the beginning of the file. You can no longer change the encoding inside of the text (which was possible in previous versions).
This command can only be used with ASCII compatible encodings,
such as the ISO-8859-series or UTF-8.
The encodings UTF-16 (UCS2) and UTF-32 (UCS4)
can not be set with this command. But these encodings are in most cases
detected automatically. (Earlier versions of avatarsay could not
handle these encodings at all.)
It depends on your systems iconv implementation, which encodings
are supported. On some systems you can get a list with the command
iconv -l.
The color-definition has to be given as six hexadecimal characters;
with two digits each for red, green and blue.
The default value is ‘#CCCCCC’.
Attention: This command has to be used before the text starts
You can only switch the text-direction on a line by line basis. Different
text directions inside of one line is not supported.
The image is centered on the screen. If the image is larger than the screen, the screen is centered on the image.
You can use a stripline after this command if you wish. The stripline doesn't have any effect then.
Which file-formats AKFAvatar supports depends on which libraries you have
installed. Uncompressed BMP images are always supported.
The text continues to be shown, so you can play an audio file with the recorded words of the following text.
Currently only WAV-files with PCM or ADPCM encoding
are supported.
This can be used to synchronize the recorded and the written text to some
extend.
If you want to make an effect-pause within a line, you can end the previous
line with a backslash (\, U+005C), so the line-ending has no
effect for the output.
The previous line has to be ended with a backslash (\, U+005C).
You could use this command after an .effectpause-command for a
nice effect.
The avatar moves out.
Anything behind the .end command is ignored.
The avatar is not moved out, but the text ends immediately.
Anything behind the .stop command is ignored.
You don't always have to write static texts to use AKFAvatar. You can use
the command avatarsay also to show you the output of other commands.
Therefore you can use a single hyphen (-, U+002D) as option.
It is best to try these features in a window based environment, where you have one window for your command line and avatarsay opens up in a separate window.
So try this: ‘echo "Hey pal, what's GNU?" | avatarsay -’. The gnu appears and says that words. Be careful with using the exclamation mark though, some shells have problems with that.
You can also see the output of any other command with avatarsay. For example try this: ‘df | avatarsay -’, or this: ‘dir | avatarsay -’. You could even read this manual this way: ‘makeinfo --plaintext akfavatar.texinfo | avatarsay -’, although that's probably a bit too long.
This chapter explains the use of the tool gnome-akfavatar. It is mainly a frontend for the command avatarsay with some of its functionality presented in a menu.
The command gnome-akfavatar is a shell script, so it needs a Bourne shell. It has been tested with GNU bash, but any POSIX-compatible Bourne shell should be sufficient.
Then it needs the command avatarsay. It is searched in the
PATH and also in the current directory.
For the visible interface it uses the program zenity. As text-editor
it needs gedit and as help browser it uses yelp. These
commands have to be in your PATH. They are usually included with
GNOME.
Since the command avatarsay is also looked up in the current directory the package need not be installed. But the documentation has to be installed in order to view it from gnome-akfavatar.
When you invoke the command gnome-akfavatar you will get a menu from which you can choose what to do.
You get the following menu-items:
show a demo or textfilecreate or edit a demo#!-line. If you chose a different avatar-image before
invoking this item, a command .avatarimage is also included in this
file. The executable bit will be set on the created file. Note: All this is
just be done for new files, not for files which already existed before.
show a manpageshow the output of a commandchange avatar imagefullscreen or window modeOkay to select the fullscreen-mode, or Cancel to
select the window-mode.
This setting is only used for the current session unless you use the item
save settings.
save settingshelp for AKFAvatarWebsiteExitCancel or the close button of the window or pressing the
<Esc>-key.
If you want to learn how to program, Pascal is a very good choice as your first language. But unfortunately Pascal is not so widely spread. Nevertheless, with GNU-Pascal and Free Pascal we have two very good Free Software implementations for Pascal, which are available for many different platforms.
Before you ask: Yes, it would have been possible to write the whole thing in Pascal. But C is more widely spread, and that has its consequences. Every modern system comes with a C compiler and almost every other language can use libraries written in C.
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.
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.
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.
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}
This is of course only an example.
This command must be used before any input/output took place!
The size of the avatar image also influences the size of the text-area.
Thus this must be used, before using the function ScreenSize.
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.
The following text shows the interface of the Pascal unit
akfavatar.pas:
unit akfavatar;
interface
{ length of an output line }
{ input is one less }
const LineLength = 80;
{ Default encoding of the system }
{$IfDef LATIN1}
const DefaultEncoding = 'ISO-8859-1';
{$Else}
const DefaultEncoding = 'UTF-8';
{$EndIf}
{ defaults for SetTextDelay and SetFlipPageDelay }
const
DefaultTextDelay = 75;
DefaultFlipPageDelay = 2700;
{ Colors for TextColor/TextBackground }
{ compatible to the CRT unit }
const
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; { ignored }
{$IfDef FPC}
type LineString = AnsiString;
{$Else}
{ In UTF-8 encoding one char may take up to 4 Bytes }
type LineString = string (4 * LineLength);
type ShortString = string (255);
{$EndIf}
type TextDirection = (LeftToRight, RightToLeft);
type TScreenSize = record x, y: integer end;
{
Text Attributes
mostly compatible to the CRT unit
the "blink-bit" means a bright background color
}
var TextAttr : byte;
{ methods to stop the program }
var
CheckBreak: boolean; { compatible to CRT }
CheckEsc: boolean;
{ compatible to the CRT unit }
var
CheckEof: boolean;
CheckSnow: boolean;
DirectVideo: boolean;
{ for CRT compatiblity, use ScreenSize for new programs }
{ Just for reading! }
{ These variables are only set after the avatar is visible }
var WindMin, WindMax: word;
{ load the Avatar image from a file }
{ must be used before any output took place }
procedure AvatarImageFile(FileName: string);
{ load the Avatar image from memory }
{ must be used before any output took place }
procedure AvatarImageData(data: pointer; size: LongInt);
{ set a different background color (default is grey) }
{ should be used before any output took place }
procedure setBackgroundColor(red, green, blue: byte);
{ change pace of text and page flipping }
procedure setTextDelay(delay: integer);
procedure setFlipPageDelay(delay: integer);
{ change the encoding }
procedure setEncoding(const newEncoding: string);
{ change text direction (for hebrew/yiddish texts) }
{ you should start a new line before or after this command }
procedure setTextDirection(direction: TextDirection);
{ The "Screen" is the textarea }
{ The name is chosen for compatiblity with the CRT unit }
{ This causes the library to be initialized }
{ The avatar-image and the background color must be set before this }
function ScreenSize: TScreenSize;
{ assign text-variable to the avatar }
procedure AssignAvatar(var f: text);
{ the same for CRT compatiblity }
procedure AssignCrt(var f: text);
{ Restore Input/Output system }
{ use this to output help or version information }
procedure RestoreInOut;
{$IfDef FPC}
{ the page command is defined in the Pascal standard,
but missing in FreePascal }
{ action: wait a while and then clear the textfield }
procedure page(var f: text);
procedure page;
{$EndIf}
{ switch cursor on or off }
{ extensions compatible to Free Pascal }
procedure CursorOn;
procedure CursorOff;
{ keyboard handling }
{ partly CRT compatible - only Latin1 chars so far }
function KeyPressed: boolean;
function ReadKey: char;
{ clear the keyboard buffer }
procedure ClearKeys;
{ wait for a key }
procedure WaitKey;
{ wait some time }
{ compatible to CRT unit }
procedure delay(milliseconds: integer);
{ example use: delay (seconds (2.5)); }
function seconds(s: Real): integer;
{ clears the window (not the screen!) }
{ the name was chosen for compatiblity to the CRT unit }
procedure ClrScr;
{ clears rest of the line }
{ compatible to CRT unit }
procedure ClrEol;
{ deletes current line, the rest is scrolled up }
procedure DelLine;
{ inserts a line before the current line, the rest is scrolled down }
procedure InsLine;
{ set the text color }
{ compatible to CRT unit }
procedure TextColor (Color: Byte);
{ set the text background color }
{ compatible to CRT unit, but light colors can be used }
procedure TextBackground (Color: Byte);
{ set black on white text colors, switch bold and underlined off }
{ name compatible to CRT unit, but the colors differ }
procedure NormVideo;
{ switch bold mode on or off }
{ this is different from the CRT unit }
{ be careful, when you combine this with TextColor }
procedure HighVideo;
procedure LowVideo;
{ switch underline mode on or off }
procedure Underlined (onoff: boolean);
{ shows the avatar without the balloon }
procedure ShowAvatar;
{ moves the avatar in or out }
procedure MoveAvatarIn;
procedure MoveAvatarOut;
{ loads image
after that call delay or waitkey
the supported image formats depend on your libraries
uncompressed BMP is always supported
}
function ShowImageFile(FileName: string): boolean;
procedure ShowImageData(data: pointer; size: LongInt);
{ play a short sound as with chr(7) }
procedure Beep;
{ a short visual flash on the screen }
procedure Flash;
{ loads Audio File
currently only WAV files supported
encodings: PCM, MS-ADPCM, IMA-ADPCM }
function LoadSoundFile(const FileName: string): pointer;
function LoadSoundData(data: pointer; size: LongInt): pointer;
procedure FreeSound(snd: pointer);
procedure PlaySound(snd: pointer; loop: boolean);
{ wait until the end of the audio output }
procedure WaitSoundEnd;
{ dummy function, full support planned }
procedure Sound(frequency: integer);
{ stop sound output }
procedure NoSound;
{ handle coordinates (inside the balloon) }
{ compatible to CRT unit }
function WhereX: integer;
function WhereY: integer;
procedure GotoXY(x, y: integer);
procedure Window(x1, y1, x2, y2: Byte);
{ set/get scroll mode }
{ 0 = off (page-flipping), 1 = normal }
procedure SetScrollMode(mode: integer);
function GetScrollMode: integer;
{ get last error message }
function AvatarGetError: ShortString;
{ ignore TextColor TextBackground and so on }
{ compatible with GNU-Pascal's CRT unit }
procedure SetMonochrome(monochrome: boolean);
The following is the C header file akfavatar.h:
/*
* AKFAvatar library - for giving your programs a graphical Avatar
* Copyright (c) 2007 Andreas K. Foerster <info@akfoerster.de>
*
* needed:
* SDL1.2 (recommended: SDL1.2.11 or later (but not 1.3!))
* recommended:
* SDL_image1.2
*
* This file is part of AKFAvatar
*
* AKFAvatar is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* AKFAvatar 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <http://www.gnu.org/licenses/>.
*/
/* $Id: akfavatar-en.html,v 1.6 2008/06/22 13:39:38 akf Exp $ */
#ifndef _akfavatar_h
#define _akfavatar_h
/* SDL redefines main on some systems */
#if defined(__WIN32__) || defined(__MACOS__) || defined(__MACOSX__)
# include "SDL.h"
#endif
/* to get the systems definition of wchar_t */
#include <stddef.h>
#define AKFAVATAR 1
/* maximum linelength */
#define AVT_LINELENGTH 80
/* for avt_initialize */
#define AVT_AUTOMODE -1
#define AVT_WINDOW 0
#define AVT_FULLSCREENNOSWITCH 2
#ifdef AVT_NOSWITCH
# define AVT_FULLSCREEN AVT_FULLSCREENNOSWITCH
#else
# define AVT_FULLSCREEN 1
#endif
/* for _avt_STATUS */
#define AVT_NORMAL 0
#define AVT_QUIT 1
#define AVT_ERROR -1
/* for boolean expressions */
#define AVT_TRUE 1
#define AVT_FALSE 0
#define AVT_MAKE_BOOL(x) ((x) != 0)
/* for avt_set_text_delay and avt_set_flip_page_delay */
#define AVT_DEFAULT_TEXT_DELAY 75
#define AVT_DEFAULT_FLIP_PAGE_DELAY 2700
/* for avt_text_direction */
#define AVT_LEFT_TO_RIGHT 0
#define AVT_RIGHT_TO_LEFT 1
/*
* example: avt_wait(AVT_SECONDS(2.5)) waits 2.5 seconds
*/
#define AVT_SECONDS(x) ((x)*1000)
/*
* makros for marking deprecated functions in this header,
* or possibly unused parameters
*/
#ifdef __GNUC__
# define AVT_DEPRECATED __attribute__ ((__deprecated__))
# define AVT_UNUSED __attribute__ ((__unused__))
#else
# define AVT_DEPRECATED
# define AVT_UNUSED
#endif /* __GNUC__ */
#ifdef __cplusplus
/* *INDENT-OFF* */
extern "C" {
/* *INDENT-ON* */
#endif /* __cplusplus */
/*
* boolean are integers for this library
* to make language bindings more easy
* (you can use stdbool.h in your program, it's compatible)
*/
typedef int avt_bool_t;
/*
* general type for avatar images
* may change in the future!
*/
typedef void avt_image_t;
/*
* general type for audio data
* may change in the future!
*/
typedef void avt_audio_t;
/*
* type for keyhandler
* see avt_register_keyhandler
*/
typedef void (*avt_keyhandler) (int sym, int mod, int unicode);
/*
* type for mousehandler
* see avt_register_mousehandler
*/
typedef void (*avt_mousehandler) (int button, avt_bool_t pressed,
int x, int y);
/* base fnctions */
/*
* initialize the avatar system
* mode is either WINDOW or FULLSCREEN or FULLSCREENNOSWITCH
* the original image is freed in this function!
* the image may be NULL if no avatar should be shown
*/
int avt_initialize (const char *title,
const char *icontitle, avt_image_t * image, int mode);
/*
* quit the avatar system
* can be used with atexit
*/
void avt_quit (void);
/*
* call avt_wait_button (); avt_move_out (); avt_quit ();
* can be used with atexit
*/
void avt_button_quit (void);
/* which version */
const char *avt_version (void);
/* copyright information */
const char *avt_copyright (void);
/* license information */
const char *avt_license (void);
/* is it initialized? */
avt_bool_t avt_initialized (void);
/* 0 = normal; 1 = quit-request; -1 = error */
int avt_get_status (void);
/* set status */
void avt_set_status (int status);
/* get error message */
char *avt_get_error (void);
/*
* set text direction
* the cursor is moved to start of the line
* in a text, you might want to call avt_newline after that
*/
void avt_text_direction (int direction);
/* activate the text cursor? (default: no) */
void avt_activate_cursor (avt_bool_t on);
/*
* get the default avatar image
* use this with avt_initialize
*/
avt_image_t *avt_default (void);
/*
* import an avatar from XPM data
*/
avt_image_t *avt_import_XPM (char **xpm);
/*
* RGB gimp_image
* for importing an avatar
* also uses avt_make_transparent
*/
avt_image_t *avt_import_gimp_image (void *gimp_image);
/*
* import avatar from image data
*/
avt_image_t *avt_import_image_data (void *img, int imgsize);
/*
* import avatar from file
*/
avt_image_t *avt_import_image_file (const char *file);
/*
* free avt_image_t images
* allocated with avt_import_gimp_image or avt_import_imagefile
* (automatically called in avt_initialize)
*/
void avt_free_image (avt_image_t * image);
/*
* make background transparent
* pixel in the upper left corner is supposed to be the background color
*/
avt_image_t *avt_make_transparent (avt_image_t * image);
/*
* define the backgroud color
* values in the range 0x00 .. 0xFF
* can and should be called before avt_initialize
* if the balloon is visible, it is cleared
*/
void avt_set_background_color (int red, int green, int blue);
/*
* change the text color
* values in the range 0x00 .. 0xFF
*/
void avt_set_text_color (int red, int green, int blue);
void avt_set_text_background_color (int red, int green, int blue);
/* set underlined mode on or off */
void avt_underlined (avt_bool_t onoff);
/* get underlined mode */
avt_bool_t avt_get_underlined (void);
/* set bold mode on or off (not recommended) */
void avt_bold (avt_bool_t onoff);
/* get bold mode */
avt_bool_t avt_get_bold (void);
/* set inverse mode on or off */
void avt_inverse (avt_bool_t onoff);
/* get inverse mode */
avt_bool_t avt_get_inverse (void);
/* set default color and switch off bold, underlined, inverse */
void avt_normal_text (void);
/*
* delay time for text-writing
* default: AVT_DEFAULT_TEXT_DELAY
*/
void avt_set_text_delay (int delay);
/*
* delay time for page flipping
* default: AVT_DEFAULT_FLIP_PAGE_DELAY
*/
void avt_set_flip_page_delay (int delay);
/* don't use this anymore, it is about to be removed */
void avt_set_delays (int text, int flip_page) AVT_DEPRECATED;
/*
* reserve single keys (Esc, F11)
* use this with avt_register_keyhandler
*/
void avt_reserve_single_keys (avt_bool_t onoff);
/* just for backward compatiblity, don't use it */
void avt_stop_on_esc (avt_bool_t on) AVT_DEPRECATED;
/* register an external keyhandler */
void avt_register_keyhandler (avt_keyhandler handler);
/* register an external mousehandler
*
* it is only called, when a mouse-button is pressed or released inside
* of the balloon. The coordinates are the character positions.
*/
void avt_register_mousehandler (avt_mousehandler handler);
/*
* switch to fullscreen or window mode
* (experimental!)
*/
void avt_switch_mode (int mode);
/*
* prints a L'\0' terminated string in the balloon
* if there is no balloon, it is drawn
* if there is no avatar, it is shown (not moved in)
* interprets control chars
*/
int avt_say (const wchar_t * txt);
/*
* writes string with given length in the balloon
* the string needn't be terminated and can contain binary zeros
* if there is no balloon, it is drawn
* if there is no avatar, it is shown (not moved in)
* interprets control characters
*/
int avt_say_len (const wchar_t * txt, const int len);
/*
* writes a single character in the balloon
* if there is no balloon, it is drawn
* if there is no avatar, it is shown (not moved in)
* interprets control characters
*/
int avt_put_character (const wchar_t ch);
/* set encoding for mb functions */
int avt_mb_encoding (const char *encoding);
/*
* decode a string into wchar_t
* size in bytes
* returns number of characters in dest (without the termination zero)
* dest must be freed by caller with avt_free
*/
int avt_mb_decode (wchar_t ** dest, const char *src, const int size);
/*
* encode a string from wchar_t
* len is the length
* returns number of characters in dest (without the termination zero)
* dest must be freed by caller with avt_free
* (the size of dest may be much more than needed)
*/
int avt_mb_encode (char **dest, const wchar_t * src, const int len);
/* free memory allocated by this library */
void avt_free (void *ptr);
/*
* like avt_say,
* but converts from a given charset encoding
* (see avt_mb_encoding)
* the text is a 0 terminated C-String
*/
int avt_say_mb (const char *txt);
/*
* the same with a given length
* the string needn't be terminated then
* and can contain binary zeros
*/
int avt_say_mb_len (const char *txt, int len);
/*
* get a character from the keyboard
* only for printable characters, not for function keys
* (ch is just one character, not a string)
*/
int avt_get_key (wchar_t * ch);
/*
* get a menu-key, or mouseclick
* menu_ofset: line, where menu begins
* start_code: first character, like L'1' or L'A'
*/
int
avt_get_menu (wchar_t * ch, int menu_start, int menu_end, wchar_t start_code);
/*
* get string (just one line)
* the maximum length is LINELENGTH-1
* size is the size of s in bytes (not the length)
*
* (I don't use size_t for better compatiblity with other languages)
*/
int avt_ask (wchar_t * s, const int size);
/*
* like avt_ask,
* but converts to a given encoding
*
* for UTF-8 encoding it should have a capacity of
* 4 * LINELENGTH Bytes
*/
int avt_ask_mb (char *s, const int size);
/*
* new line
* same as \n in avt_say
*/
int avt_new_line (void);
/*
* wait a while and then clear the textfield
* same as \f in avt_say
*/
int avt_flip_page (void);
/* update, ie handle events and give some time to other processes */
/* use this in a longer loop in your program */
int avt_update (void);
/* wait a while */
int avt_wait (int milliseconds);
/* wait for a keypress while displaying a button */
int avt_wait_button (void);
/* wait for a keypress (deprecated: use avt_wait_button) */
int avt_wait_key (const wchar_t * message) AVT_DEPRECATED;
/*
* like avt_waitkey,
* but converts from a given charset encoding
* (deprecated: use avt_wait_button)
*/
int avt_wait_key_mb (char *message) AVT_DEPRECATED;
/* functions for extended use */
/*
* set a viewport (sub-area of the textarea)
* upper left corner is 1, 1
*/
void avt_viewport (int x, int y, int width, int height);
/* show an empty screen with the background color */
void avt_clear_screen (void);
/* show just the avatar without the balloon */
void avt_show_avatar (void);
/*
* load image and show it
* if SDL_image isn't available then uncompressed BMP is still supported
* on error it returns AVT_ERROR without changing the status
* if it succeeds call avt_wait or avt_waitkey
*/
int avt_show_image_file (const char *file);
/*
* show image from image data
* if SDL_image isn't available then uncompressed BMP is still supported
* on error it returns AVT_ERROR without changing the status
* if it succeeds call avt_wait or avt_waitkey
*/
int avt_show_image_data (void *img, int imgsize);
/*
* show image from XPM data
* on error it returns AVT_ERROR without changing the status
* if it succeeds call avt_wait or avt_waitkey
*/
int avt_show_image_XPM (char **xpm);
/*
* show gimp image
* on error it returns AVT_ERROR without changing the status
*/
int avt_show_gimp_image (void *gimp_image);
/*
* like avt_show_avatar, but the avatar is moved in
*/
int avt_move_in (void);
/*
* move the avatar out => empty screen
*/
int avt_move_out (void);
/*
* make a short sound, when audio is initialized
* else it is the same as avt_flash
* same as with \a in avt_say
* the sound is actually not a bell ;-)
*/
void avt_bell (void);
/*
* visual flash of the screen
*/
void avt_flash (void);
/*
* clears the viewport
* if there is no balloon yet, it is drawn
*/
void avt_clear (void);
/*
* clears from cursor position down the viewport
* if there is no balloon yet, it is drawn
*/
void avt_clear_down (void);
/*
* clears from cursor position up the viewport
* if there is no balloon yet, it is drawn
*/
void avt_clear_up (void);
/*
* clear end of line
* depending on text direction
*/
void avt_clear_eol (void);
/*
* clear beginning of line
* depending on text direction
*/
void avt_clear_bol (void);
/* clear line */
void avt_clear_line (void);
/* forward one character position
* ie. print a space
*/
int avt_forward (void);
/*
* delete last caracter
*/
void avt_backspace (void);
/* insert spaces at current position (move rest of line) */
void avt_insert_spaces (int num);
/* delete num characters at current position (move rest of line) */
void avt_delete_characters (int num);
/*
* erase num characters from current position
* don't move the cursor or the rest of the line
*/
void avt_erase_characters (int num);
/*
* set scroll mode
* 0 = off (page-flipping), 1 = normal
* (further modes are planned, it is not meant as a boolean)
*/
void avt_set_scroll_mode (int mode);
int avt_get_scroll_mode (void);
/* set newline mode (default: on) */
void avt_newline_mode (avt_bool_t mode);
/* set auto-margin mode (default: on) */
void avt_auto_margin (avt_bool_t mode);
/*
* origin mode
* AVT_FALSE: origin (1,1) is always the top of the textarea
* AVT_TRUE: origin (1,1) is the top of the viewport
*/
void avt_set_origin_mode (avt_bool_t mode);
avt_bool_t avt_get_origin_mode (void);
/*
* handle coordinates
*
* the coordinates start with 1, 1
* in the upper left corner
* and are independent from the text direction
*/
/*
* get position in the viewport
*/
int avt_where_x (void);
int avt_where_y (void);
/* maximum positions (whole text-field) */
int avt_get_max_x (void);
int avt_get_max_y (void);
/*
* put cusor to specified coordinates
*/
void avt_move_x (int x);
void avt_move_y (int y);
void avt_move_xy (int x, int y);
/* save and restore current cursor position */
void avt_save_position (void);
void avt_restore_position (void);
/* go to next or last tab stop */
void avt_next_tab (void);
void avt_last_tab (void);
/* reset tab stops to every eigth column */
void avt_reset_tab_stops (void);
/* clear all tab stops */
void avt_clear_tab_stops (void);
/* set or clear a tab in position x */
void avt_set_tab (int x, avt_bool_t onoff);
/*
* delete num lines, starting from line
* the rest ist scrolled up
*/
void avt_delete_lines (int line, int num);
/*
* insert num lines, starting at line
* the rest ist scrolled down
*/
void avt_insert_lines (int line, int num);
/***********************************************************************/
/* audio stuff */
/* must be called AFTER avt_initialize! */
int avt_initialize_audio (void);
/*
* no longer needed,
* this is executed automatically by avt_quit()
* this function is only there for backward compatiblity
*/
void avt_quit_audio (void);
/*
* loads a wave file
* supported: PCM, MS-ADPCM, IMA-ADPCM
*/
avt_audio_t *avt_load_wave_file (const char *file);
/*
* loads wave data from memory
* must still be freed with avt_free_audio!
*/
avt_audio_t *avt_load_wave_data (void *data, int datasize);
/*
* frees memory of a loaded sound
*/
void avt_free_audio (avt_audio_t * snd);
/*
* plays a sound
*/
int avt_play_audio (avt_audio_t * snd, avt_bool_t doloop);
/*
* wait until the sound ends
* this stops a loop, but still plays to the end of the sound
*/
int avt_wait_audio_end (void);
/* stops audio */
void avt_stop_audio (void);
#ifdef __cplusplus
/* *INDENT-OFF* */
}
#endif /* __cplusplus */
#endif /* _akfavatar_h */