This is en/akfavatar-en.info, produced by makeinfo version 4.11 from en/akfavatar-en.texinfo. INFO-DIR-SECTION Miscellaneous START-INFO-DIR-ENTRY * AKFAvatar: (akfavatar-en). A graphical avatar. END-INFO-DIR-ENTRY 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 (C) 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.  File: akfavatar-en.info, Node: Top, Next: Overview, Up: (dir) AKFAvatar ********* 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 (C) 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. * Menu: * Overview:: Overview of AKFAvatar * Installation:: How to install AKFAvatar * Using avatarsay:: Using the tool `avatarsay' * Using gnome-akfavatar:: Using it under GNOME * Programming:: Programming with AKFAvatar * Pascal reference:: Reference for Pascal * C reference:: the C header file `akfavatar.h' * Concept Index:: Index of this documentation  File: akfavatar-en.info, Node: Overview, Next: Installation, Prev: Top, Up: Top 1 Overview of AKFAvatar *********************** 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. 1. You can use the program `avatarsay' as a text-terminal, just like `xterm', but being much more fun. In contrast to `xterm' it might even run without an x-server. (Under Windows this function is not available.) 2. You can use it as wrapper for your textmode programs. (Under Windows this function is not available.) 3. The command `avatarsay' can be used as a fancy text-viewer, more or less like `more' or `less'. It is not suited for long, complicated texts, but rather for short and funny stuff. 4. But the command `avatarsay' can do much more than that. It can be used as a simple scripting language for making demos that you can show for example at an information booth or in a shop's window. 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. 5. Then there is the library `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! 1.1 General usage (keys) ======================== 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 +, for example when it runs in fullscreen mode. Often you can also stop the program by pressing the key. But this key might be reserved for other things, for example in the terminal-mode of `avatarsay'. You can press the 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 + or ++ to toggle between the fullscreen and the window mode. Often you can also simply use the key , 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 key before you minimize the window.  File: akfavatar-en.info, Node: Installation, Next: Using avatarsay, Prev: Overview, Up: Top 2 How to install AKFAvatar ************************** 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' 2.1 Requirements ================ Needed ------ * SDL-1.2.x (version 1.2.11 or higher recommended) The 1.3 series is _not_ backward compatible! `http://libsdl.org/download-1.2.php' You need the "Runtime Libraries" as well as the "Development Libraries"! Of course SDL needs a graphical environment to run in. For example the X-Window-System or a Linux framebuffer-device... * An ANSI-C Compiler (gcc or others) `http://gcc.gnu.org/' * Entries for "linux" and "linux-m" in the terminal database. 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. Recommended ----------- * SDL_image `http://www.libsdl.org/projects/SDL_image/' There the Runtime Libraries are sufficient SDL_image in turn needs other libraries: libz, libpng, libjpeg, libtiff Without SDL_image you can only use uncompressed BMP images. SDL_image can be installed after the installation of this package. * iconv on a lot of systems that is already included Optional -------- * GNU-Pascal or Free Pascal `http://www.gnu-pascal.de/' `http://www.freepascal.org/' 2.2 Installation ================ Compiling --------- 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. Compiling -- special cases .......................... 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. Testing ------- 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 key. On some systems you can toggle between window and fullscreen mode using the key . Another useful key is the 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'... The script `lrun' ................. 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. Installing ---------- 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'. Special targets ............... 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). Trouble-shooting ---------------- * Problem: the system can't find the library `libakfavatar.so' 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. * Problem: some characters are not shown correctly with `avatarsay' Solution: There are different character sets. Try to use the parameters `--utf-8' or `--latin1'. Other systems ------------- BSD ... AKFAvatar is known to be compilable with FreeBSD 6.2. To get iconv support, install `libiconv' and use `./configure --with-iconv'. Windows ....... 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.  File: akfavatar-en.info, Node: Using avatarsay, Next: Using gnome-akfavatar, Prev: Installation, Up: Top 3 Using the tool `avatarsay' **************************** This chapter explains the various uses of the tool `avatarsay'. * Menu: * Text-terminal:: Using `avatarsay' as fancy text-terminal * Text-viewer:: Using `avatarsay' as fancy text-viewer * Make your text executable:: How to turn your text into a program * Different avatar image:: Using a different avatar image * Invoking avatarsay:: Command line interface * Commands for avatarsay:: Advanced features of `avatarsay' * Pipes:: Pipes  File: akfavatar-en.info, Node: Text-terminal, Next: Text-viewer, Up: Using avatarsay 3.1 Using `avatarsay' as fancy text-terminal ============================================ 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. 3.1.1 frontend for text-console programs ---------------------------------------- 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. 3.1.2 the terminal-type ----------------------- 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: * It does _not_ mean, that the code is limited to systems, that use Linux as kernel. It was successfully tested on FreeBSD and should run fairly well on other POSIX-compatible systems also. * It does _not_ mean, that the variable `TERM' should be changed on other systems. Leave it as it is. But the system should have entries for `linux' and `linux-m' in its terminal database(s). * It does _not_ mean, that I have used code from Linux. I just read the manpage `console_codes' and the Terminfo and Termcap entries and some other documents to get information. * It does _not_ mean, that the terminal is not compliant to standards. In fact, the console emulation of the kernel Linux is very compatible to `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. 3.1.3 extensions ---------------- 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 h' switches the slowprint-mode on `CSI ? 56 l' switches the slowprint-mode off (default) further extensions are planned.  File: akfavatar-en.info, Node: Text-viewer, Next: Make your text executable, Prev: Text-terminal, Up: Using avatarsay 3.2 Using `avatarsay' as fancy text-viewer. =========================================== 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.  File: akfavatar-en.info, Node: Make your text executable, Next: Different avatar image, Prev: Text-viewer, Up: Using avatarsay 3.3 How to turn your text into a program ======================================== 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.  File: akfavatar-en.info, Node: Different avatar image, Next: Invoking avatarsay, Prev: Make your text executable, Up: Using avatarsay 3.4 Using a different avatar image ================================== 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 *note Commands for avatarsay::. Which file-formats AKFAvatar supports depends on which libraries you have installed. Uncompressed `BMP' images are always supported. 3.4.1 Transparent avatar background ----------------------------------- 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.  File: akfavatar-en.info, Node: Invoking avatarsay, Next: Commands for avatarsay, Prev: Different avatar image, Up: Using avatarsay 3.5 Invoking `avatarsay' ======================== 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' show a short summary about the invocation of `avatarsay' `--version' `-v' show the version of the command `--terminal' `-t' terminal mode, ie. run a shell in the balloon `--execute' `-x' `-e' execute program in the balloon A program name must be given. Options after the program name are options for the executed program. `--nocolor' `-b' no color for executed programs and the terminal mode `--window' `-w' try to run the program in a window (default) `--fullscreen' `-f' try to run the program in fullscreen mode `--fullfullscreen' `-F' like `-f', but use the current display size This 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=NAME' the input data is encoded in the encoding NAME It 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' the input data is encoded in Latin-1 `--utf-8' `--utf8' `-u8' `-u' the input data is encoded in `UTF-8' `--once' `-1' run only once (don't loop) `--popup' `-p' popup, ie. don’t move the avatar in Use this for a fast popup text. Use the command `.stop' to also get a fast end. `--no-delay' `-n' don't delay the text output `--raw' `-r' output raw text (don't handle any commands or striplines) `--ignoreeof' `-i' ignore end of file conditions; use this when the input is not a file 3.5.1 Environment variables --------------------------- The command `avatarsay' supports the following environment variables: `AVATARIMAGE' image file with an avatar with the full path `DATADIR' the directory, where images and audio files are located (has no influence on the environment variable `AVATARIMAGE') `LC_ALL' `LC_CTYPE' `LANG' these variables influence the default encoding and the language `SHELL' the shell for the terminal-mode `HOME' the starting directory for the teminal-mode 3.5.2 Configuration file ------------------------ 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 *Note Different avatar image::.  File: akfavatar-en.info, Node: Commands for avatarsay, Next: Pipes, Prev: Invoking avatarsay, Up: Using avatarsay 3.6 Commands for `avatarsay' ============================ 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. `.datadir DIRECTORY' with this command you can set the directory, where images and sound files are located The data directory can also be set with the environment variable `AVATARDATADIR'. The command has precedence over the environment variable. `.avatarimage IMAGEFILE' with this command you can use a different image for the avatar. *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. `.encoding ENCODINGNAME' sets the encoding of the text; such as `ISO-8859-1' or `UTF-8' *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'. `.backgroundcolor #COLOR-DEFINITION' set a different background color 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 `.left-to-right' `.right-to-left' changes the text direction; this is useful if you have text written in Hebrew or Yiddish (Arabic is not supported) You can only switch the text-direction on a line by line basis. Different text directions inside of one line is not supported. `.flip' flip the page; the same effect as with a stripline `.clear' clears the text-area; unlike `.flip' it doesn't wait, but clears it immediately `.pause' a longer pause; the avatar is shown without the balloon for some time `.image IMAGEFILE' shows an image for a while (without the avatar) 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. `.audio AUDIOFILE' plays an audio file 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. `.waitaudio' wait until the audio output ends This can be used to synchronize the recorded and the written text to some extend. `.effectpause' short pause while the text stays visible 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. `.back NUMBER' delete the last NUMBER of characters 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. `.read' reserved for later versions `.end' end of the text The avatar moves out. Anything behind the `.end' command is ignored. `.stop' stops the output immediately The avatar is not moved out, but the text ends immediately. Anything behind the `.stop' command is ignored.  File: akfavatar-en.info, Node: Pipes, Prev: Commands for avatarsay, Up: Using avatarsay 3.7 Pipes ========= 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.  File: akfavatar-en.info, Node: Using gnome-akfavatar, Next: Programming, Prev: Using avatarsay, Up: Top 4 Using it under GNOME ********************** 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. * Menu: * GNOME Requirements:: What you need to use `gnome-akfavatar' * GNOME Main-menu:: The main-menu of `gnome-akfavatar'  File: akfavatar-en.info, Node: GNOME Requirements, Next: GNOME Main-menu, Up: Using gnome-akfavatar 4.1 What you need to use `gnome-akfavatar'. =========================================== 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'.  File: akfavatar-en.info, Node: GNOME Main-menu, Prev: GNOME Requirements, Up: Using gnome-akfavatar 4.2 The main-menu of `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 textfile' You get a file selection box and you can choose a text-file or a demo, which is then opened in `avatarsay'. A "demo" is a text-file, which uses commands for `avatarsay' (*note Commands for avatarsay::). `create or edit a demo' can be used to create a new demo or edit an existing one. When you enter a filename which doesn't exist yet, the file is created with an appropriate `#!'-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 manpage' you are prompted to enter the name of a manpage you want to view. If you want to see a manpage from a special section, you can enter the section number in front of the name separated by a space. For example `6 intro' shows the intro manpage of section 6. `show the output of a command' shows the output of a command in `avatarsay'. This is only for commands which print something to the standard output or standard error channel. It is not for interactive commands or commands that use curses. `change avatar image' lets you select a different avatar image. *Note Different avatar image::. This setting is only used for the current session unless you use the item "save settings". `fullscreen or window mode' click on `Okay' 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 settings' saves the settings, that is the avatar image and whether to run in fullscreen or window mode. Note: these settings are just for `gnome-akfavatar'; they have no influence when you call `avatarsay' directly or any other program using the AKFAvatar library. `help for AKFAvatar' shows this document in the help-browser of GNOME `Website' opens the homepage for AKFAvatar in a web-browser. `Exit' exit the program. Note: you can also exit the program by clicking on `Cancel' or the `close' button of the window or pressing the -key.  File: akfavatar-en.info, Node: Programming, Next: Pascal reference, Prev: Using gnome-akfavatar, Up: Top 5 Programming with AKFAvatar **************************** 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 (http://www.gnu-pascal.de/) and Free Pascal (http://www.freepascal.org/) 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. * Menu: * Pascal:: How to program the avatar in Pascal  File: akfavatar-en.info, Node: Pascal, Up: Programming 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 stops the program immediately. If you need the -key for something else, you can set the variable `CheckEsc' to `false'. The program also stops when + 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 *note Pascal reference::.  File: akfavatar-en.info, Node: Pascal reference, Next: C reference, Prev: Programming, Up: Top Anhang A 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);  File: akfavatar-en.info, Node: C reference, Next: Concept Index, Prev: Pascal reference, Up: Top Anhang B C reference ******************** The following is the C header file `akfavatar.h': /* * AKFAvatar library - for giving your programs a graphical Avatar * Copyright (c) 2007 Andreas K. Foerster * * 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 . */ /* $Id: akfavatar-en.info,v 1.5 2008/06/15 09:37:39 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 #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 */  File: akfavatar-en.info, Node: Concept Index, Prev: C reference, Up: Top Index ***** [index] * Menu: * #!: Make your text executable. (line 10) * avatarsay: Using avatarsay. (line 6) * change the avatar: Different avatar image. (line 6) * command line tool: Using avatarsay. (line 6) * commands for avatarsay: Commands for avatarsay. (line 6) * configuration file for avatarsay: Invoking avatarsay. (line 127) * console based programs: Text-terminal. (line 24) * different avatar: Different avatar image. (line 6) * exchange the avatar: Different avatar image. (line 6) * executable text: Make your text executable. (line 6) * frontend: Text-terminal. (line 24) * fullscreen mode: Overview. (line 57) * GNOME: Using gnome-akfavatar. (line 6) * iconv: Installation. (line 79) * installation: Installation. (line 6) * keys: Overview. (line 47) * lrun: Installation. (line 126) * menu of gnome-akfavatar: GNOME Main-menu. (line 6) * other commands, using avatarsay with: Pipes. (line 6) * overview: Overview. (line 6) * Pascal: Pascal. (line 6) * Pascal reference: Pascal reference. (line 6) * pausing (Pause key): Overview. (line 54) * pipes: Pipes. (line 6) * programming: Programming. (line 6) * QVGA: Installation. (line 79) * reader: Text-viewer. (line 6) * reference for C: C reference. (line 6) * reference for Pascal: Pascal reference. (line 6) * requirements for gnome-akfavatar: GNOME Requirements. (line 6) * stopping: Overview. (line 47) * stripline: Text-viewer. (line 18) * switching fullscreen/window: Overview. (line 57) * tearline: Text-viewer. (line 18) * text-terminal: Text-terminal. (line 6) * text-viewer: Text-viewer. (line 6) * toggle fullscreen/window: Overview. (line 57) * transparency (avatar image): Different avatar image. (line 38) * trouble-shooting: Installation. (line 161) * VGA: Installation. (line 79) * viewer: Text-viewer. (line 6) * window mode: Overview. (line 57) * window usage: Overview. (line 63) * wrapper: Text-terminal. (line 24)  Tag Table: Node: Top780 Node: Overview1849 Node: Installation4943 Node: Using avatarsay12099 Node: Text-terminal12772 Node: Text-viewer16310 Node: Make your text executable17589 Node: Different avatar image18930 Node: Invoking avatarsay21563 Node: Commands for avatarsay24609 Node: Pipes29553 Node: Using gnome-akfavatar30514 Node: GNOME Requirements30973 Node: GNOME Main-menu31859 Node: Programming34511 Node: Pascal35367 Node: Pascal reference43451 Node: C reference49785 Node: Concept Index65750  End Tag Table  Local Variables: coding: US-ASCII End: