Dies ist die Bedienungsanleitung für AKFAvatar (Version 0.15.1, 2008-06-15).
AKFAvatar ist ein lustiger Terminal-Emulator, ein Text-Betrachter, eine Skript-Sprache um Demos zu erstellen und eine Programmbibliothek um dafür Programme in C oder Pascal zu schreiben.Homepage: http://akfavatar.nongnu.org/
Copyright © 2007, 2008 Andreas K. Förster, http://akfoerster.de/
Vervielfältigung und Verbreitung dieser Anleitung, mit oder ohne Veränderungen, sind ohne Gebühr in jeglicher Form erlaubt, solange der Copyright Vermerk sowie dieser Hinweis erhalten bleiben.
AKFAvatar ist ein graphisches Programm und eine Bibliothek, bei denen ein Avatar auf dem Bildschirm erscheint und dem Benutzer Sachen in einer Sprechblase mitteilt. Man kann auch Audio-Aufnahmen abspielen lassen, so dass der Benutzer sogar hören kann, was der Avatar sagt.
AKFAvatar kann auf verschiedene Arten eingesetzt werden. Ich liste sie hier kurz auf, angefangen von der einfachsten bis zur kompliziertesten für fortgeschrittene Benutzer.
Das ist nicht gerade für lange und komplizierte Texte geeignet, sondern eher für kurze, lustige Sachen.
Keine Angst, das klingt viel komplizierter als es ist. Vielleicht sollte ich eher sagen, man kann seine Texte mit gelegentlichen Befehlen aufpeppen. Dann kann man das Ausführungs-Bit bei seiner... “Text-Datei” setzen, und schon ist es ausführbar.
libakfavatar, die man von
kompilierenden Sprachen aus verwenden kann. Zur Zeit werden Free Pascal,
GNU-Pascal und C unterstützt. Insbesondere die Sprache Pascal
ist für Anfänger geeignet, die programmieren lernen wollen. Die Bibliothek ist
so einfach zu verwenden, wie Kommandozeilen-Programme zu schreiben — es macht
aber wesentlich mehr Spaß!
Wenn ein AKFAvatar-Programm in einem Fenster läuft, kann man natürlich einfach den Schließen-Knopf des Fenster-Managers betätigen, um es zu beenden. Man kann das Programm aber auch jederzeit mit der Tastenkombination <Alt>+<Q> abbrechen, zum Beispiel, wenn es im Vollbild-Modus läuft. Meistens kann man das Programm auch einfach mit der <Esc>-Taste beenden. Diese Taste kann jedoch auch für andere Aufgaben reserviert sein, zum Beispiel im Terminal-Modus von avatarsay.
Man kann jederzeit die <Pause>-Taste betätigen, um die Programmausführung anzuhalten. Durch den Druck auf eine andere Taste, kann die Pause wieder aufgehoben werden.
Auf manchen Systemen kann man die Tastenkombinationen <Alt>+<Enter> oder <Strg>+<Alt>+<F> verwenden um zwischen der Darstellung im Fenster oder der Vollbild-Darstellung hin und her zu schalten. Häufig kann man dazu auch einfach die Taste <F11> drücken. Diese Taste kann jedoch auch für andere Aufgaben reserviert sein, zum Beispiel im Terminal-Modus von avatarsay.
Wenn AKFAvatar in einem Fenster läuft, kann man die Fenstergröße verändern, wenn man will. Die Größe des Inhaltes wird dadurch aber nicht verändert, sondern der Inhalt wird lediglich auf dem Fenster zentriert. Man kann das Fenster nicht unter eine bestimmte Mindestgröße verkleinern. Man kann das Fenster natürlich auch maximieren. Wenn man das Fenster minimiert, läuft das Programm übrigens weiter. Man sollte also vielleicht die <Pause>-Taste drücken, bevor man das Fenster minimiert.
Obwohl auch Pakete mit Binärdateien zur Verfügung stehen, sollte man AKFAvatar vom Quelltext-Paket installieren um das vollständige Potential der Software ausnutzen zu können.
Dieses Kapitel beschreibt die Installation für posix-kompatible Betriebssysteme, hauptsächlich für GNU/Linux. Es gibt ein paar Hinweise für andere Systeme am Ende dieses Kapitels.
Kurz gesagt: ‘./configure && make && make install’
Natürlich benötigt SDL eine grafische Umgebung. Zum Beispiel das X-Window-System oder einen Linux Framebuffer...
Dies ist auch auf Systemen erforderlich, welche nicht auf dem Kernel Linux basieren, aber nicht unter Windows. Unter Debian und davon abgeleiteten Distributionen muss hierfür das Paket “ncurses-term” installiert sein.
Ohne SDL_image kann man nur unkomprimierte BMP Dateien verwenden. SDL_image kann auch nach der Installation dieses Paketes noch nachinstalliert werden.
Zunächst sollte man ‘./configure’ aufrufen. Wenn das klappt, kann man ‘make’ eingeben, um die ausführbaren Programme zu kompilieren. Es werden zwei Varianten von avatarsay kompiliert: 1. “avatarsay” ist statisch mit der Bibliothek verlinkt. Das kann man verwenden, um das Programm auszuprobieren, ohne dass man erst die Bibliothek installieren muss. 2. “avatarsay-d” ist dynamisch mit der Bibliothek verlinkt und wird nur funktionieren, wenn man zuvor die Bibliothek installiert hat. Diese Variante wird für die Installation verwendet.
Auf einigen Systeme muss man den Parameter --with-iconv bei
./configure mit angeben, um vollständige iconv Unterstützung zu
erhalten (iconv ist ein Zeichenkodierungs-Konverter). Diese Parameter wird
nicht benötigt, wenn bereits die SDL so konfiguriert wurde, dass sie ein
externes iconv verwendet. Auf manchen Systemen ist dies jedoch nicht der
Fall, obwohl ein iconv existiert (zum Beispiel, weil evtl. verschiedene
Implementierungen existieren).
Diese Software (AKFAvatar) versucht den richtigen Namen für die interne
Kodierung von wchar_t zu erraten. Das klappt aber nicht in jedem
Fall. Man kann dann diese Information zusammen mit dieser Option angeben,
und zwar folgendermaßen: ‘--with-iconv=UCS-4LE’. Auf vielen Systemen
kann man mit dem Befehl iconv -l eine Liste erhalten. Wenn
`WCHAR_T” oder “wchar_t” auf dieser Liste steht, sollte man es damit
versuchen.
Wenn man weiß, dass SDL_image auf jeden Fall installiert ist, kann man den Parameter --enable-link-sdl-image angeben. Dadurch wird die Bibliothek direkt mit SDL_image verlinkt, anstatt dass diese zur Laufzeit nachgeladen werden muss.
Um ältere SDL-Versionen auf dem Ziel-Computer zu unterstützen, könnte es notwendig sein, den Parameter --with-oldsdl bei ./configure zu verwenden. Das ist jedoch nicht notwendig, wenn man das Programm nur auf dem selben Computer verwenden will, auf dem man es kompiliert.
Wenn man es auf Geräten mit einer kleinen Anzeige verwenden will, kann man
den Parameter --enable-size=vga oder --enable-size=qvga
mit configure verwenden. Der Wert vga steht dabei für eine Auflösung
von 640*480 Pixeln, während qvga für ganz kleine Anzeigen mit 320*240
Pixeln geeignet ist. De Größe qvga ist dabei nicht gerade schön, es
ist gerade so eben noch lesbar und unterstützt weniger Zeichen.
Das Programm avatarsay ist ein Text-Betrachter und eine simple Skript-Sprache. Man kann sich zum Beispiel die Installations-Anleitung mit diesem Programm folgendermaßen ansehen: ‘./avatarsay INSTALL’.
Man kann avatarsay jederzeit mit der Taste <Esc> beenden. Auf einigen Systemen kann man zwischen dem Vollbild-Modus und dem Fenster-Modus mit der Taste <F11> umschalten. Auch die <Pause>-Taste ist hier sehr nützlich.
In dem Paket befinden sich ein paar Beispiel-Skripte. Zum Beispiel sollte man mal ‘./fsdemo-de’ ausprobieren. Man kann die Datei fsdemo-de in einem Text-Editor öffnen, um sich anzusehen, wie man so etwas selber umsetzen kann...
Man kann es auch als ein lustiges Manpage-Leseprogramm einsetzen. Hierfür gibt man zum Beispiel den Befehl ‘avtman man’ ein...
Dynamisch gelinkte Programme setzen normalerweise voraus, dass die Bibliotheken auf dem System schon installiert sind. Das Skript lrun kann verwendet werden, um Programme zu starten, wenn die Bibliothek noch nicht installiert ist. Es sucht die Bibliotheken auch in dem Verzeichnis, in dem es sich selber befindet, sowie im aktuellen Verzeichnis. Man kann es wie folgt verwenden: ‘./lrun example’ findet die Bibliothek im aktuellen Verzeichnis. Oder beispielsweise vom Pascal Unterverzeichnis aus ‘../lrun multiply’ findet die Bibliothek im übergeordneten Verzeichnis (wo sich lrun selber befindet).
Bei GNU+Linux sollte man zunächst sicher stellen, dass /usr/local/lib
in der Datei /etc/ld.so.conf aufgeführt ist; entweder direkt, oder
indirekt. Ebenso sollte man sicher stellen, dass /usr/local/bin
in der PATH Umgebungsvariablen mit eingetragen ist.
Nun sollte man sich als root einloggen und ‘make install’ eingeben um das Ganze nach /usr/local zu installieren. Falls man wenig Speicherplatz auf der Festplatte hat, kann man stattdessen auch ‘make install-strip’ verwenden. Das installiert die Binärdateien ohne Debugger-Informationen.
Wenn man das Ganze später wieder deinstallieren will, kann man dann den Befehl ‘make uninstall’ verwenden.
Mit dem Befehl ‘make example’ kann man das Programm example.c kompilieren. Die Datei example.c ist ein Beispiel, das man als Ausgangspunkt für eigene Programme verwenden kann. Das Programm wird dynamisch verlinkt, das bedeutet, dass die Bibliothek bereits installiert sein muss. Wenn man es ausprobieren will, ohne dass die Bibliothek installiert ist, kann man das Skript lrun verwenden (siehe oben).
Lösung: zunächst kann man versuchen das Verzeichnis /usr/local/lib,
oder wohin man das auch immer installiert hat, bei der Umgebungs-Variablen
LD_LIBRARY_PATH mit aufzuführen:
‘export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib’.
Als dauerhaftere Lösung sollte man sicher stellen, dass /usr/local/lib direkt oder indirekt in der Datei /etc/ld.so.conf aufgeführt ist. Dann sollte man mit root-Rechten den Befehl ldconfig aufrufen.
Lösung: Es gibt verschiedene Zeichensatz-Kodierungen. Man könnte versuchen die Parameter --utf-8 oder --latin1 mit anzugeben.
AKFAvatar ist mit FreeBSD 6.2 kompilierbar. Um iconv-Unterstützung zu
erhalten, muss man libiconv installiert haben und
‘./configure --with-iconv’ verwenden.
Windows wird nur teilweise unterstützt. Ich stelle Binärdateien zur Verfügung, die mit einem Crosscompiler erstellt wurden. Da ich es nie direkt unter Windows selber kompiliert habe, kann ich dazu wenig sagen. Tut mir Leid.
Für solche Systeme wird ein iconv-Ersatz in der SDL verwendet.
Der Zeichensatz Windows-1252 (häufig als “ANSI” bezeichnet, er hat aber
nichts mit ANSI zu tun) wird nicht vollständig unterstützt. Dieser
Zeichensatz ist jedoch teilweise kompatibel zu dem Standard ISO-8859-1,
welcher unterstützt wird. Einige Zeichen entsprechen jedoch nicht dem
Standard. Falls diese Zeichen unbedingt benötigt werden, kann man den
Text als UTF-8 abspeichern, welches ebenfalls unterstützt wird.
Dieses Kapitel erklärt die verschiedenen Anwendungsbereiche des Werkzeugs avatarsay.
Das Programm avatarsay kann auf posix-kompatiblen Systemen (nicht unter Windows) als lustiges Text-Terminal und als ein Frontend für Textkonsolen-Programme verwendet werden.
Man kann im Hauptmenü den Punkt “Terminal-Modus” auswählen, oder man kann den Befehl avatarsay mit der Option --terminal, oder kurz -t aufrufen. Damit bekommt man eine Terminal-Sitzung mit der Shell, welche auf dem System für das Benutzerkonto eingerichtet ist. Falls man keine Farben in der Sprechblase mag, kann man außerdem die Option --nocolor, oder kurz -b verwenden.
Falls man eine andere Shell oder ein anderes Startverzeichnis bevorzugt, kann man über die Umgebungsvariablen SHELL, beziehungsweise HOME andere Werte einstellen. Das Programm kommt aber auch damit klar, wenn diese Umgebungsvariablen nicht gesetzt sind.
Man kann avatarsay als Benutzeroberfläche für Textkonsolen-Programme verwenden. Dazu verwende man die Option --execute, oder kurz -x, gefolgt vom Namen des auszuführenden Programmes. Man kann dies natürlich auch mit der Option --nocolor kombinieren. Optionen, die nach dem Programmnamen angegeben werden, werden an das aufgerufene Programm weitergeleitet. Das bedeutet, dass die Reihenfolge der Optionen wichtig ist.
Zum Beispiel, um sich mit Hilfe von ssh in einen anderen Rechner einzuloggen:
avatarsay --execute ssh example.net
um eine E-Mail mit dem Programm mutt zu schreiben:
avatarsay -bx mutt pal@example.net
um die E-Mail mit einem Mailprogramm auf dem anderen Rechner zu erstellen:
avatarsay -bx ssh -t example.net mutt pal
Zu beachten: Wenn man ssh auf diese Weise einsetzt, muss man die Option -t bei ssh mit angeben.
um mit dem Programm lynx im Web zu surfen:
avatarsay -bx lynx
Wie man sieht, kann man wirklich ziemlich ausgefallene Sachen damit machen.
Das Programm avatarsay simuliert die Text-Konsole des Kernels Linux.
Darum wird die Umgebungsvariable TERM entweder auf linux oder auf
linux-m eingestellt.
Da dieses Verhalten für einige Verwirrungen sorgen könnte, versuche ich hier mal zu erklären, was das nicht bedeutet:
linux und linux-m in seiner
Terminal-Datenbank haben.
console_codes gelesen, sowie die Einträge in
Terminfo und Termcap Datenbanken verglichen und einige andere Anleitungen
gelesen, um mir Informationen zu beschaffen.
ANSI X3.64 (ECMA-48). Aber es werden einige Teile
weggelassen und andere Sachen hinzugefügt, wie zum Beispiel Tastatur-Codes.
Darum ist die Einstellung linux wirklich die richtige.
Die Terminal-Emulation von avatarsay unterstützt
Erweiterungen, die weder in ANSI X3.64 (ECMA-48) vorkommen,
noch von der Terminal-Emulation von Linux unterstützt werden.
Um diese Erweiterungen in eigenen Programmen zu verwenden, wird empfohlen,
zunächst zu überprüfen, ob die Umgebungsvariable AKFAVTTERM gesetzt
ist.
CSI ? 56 hCSI ? 56 lWeitere Erweiterungen sind geplant.
Das Programm avatarsay kann als lustiger Text-Betrachter verwendet werden. Wenn man eine Text-Datei hat, sagen wir mal MeinText, dann kann man sie sich mit dem Befehl ‘avatarsay MeinText’ ansehen. Ausprobieren! Sofort! ;-)
Das ist doch einfach, oder? Wenn die Textdatei nicht richtig für das
verwendete System kodiert ist, könnte man Probleme bei Zeichen bekommen
haben, die in ASCII nicht vorkommen, wie die deutschen
Umlaute (ä, ü, ü, ß).
Nun, es gibt wie gesagt verschiedene Kodierungen dafür. Die am
meisten verwendeten Kodierungen für deutsche Texte sind
ISO-8859-1 (auch bekannt als Latin-1) und UTF-8.
Wenn man also Probleme mit deutschen Umlauten oder anderen Zeichen
hat, kann man mal den Parameter --encoding=UTF-8 oder
--encoding=ISO-8859-1 ausprobieren —
Wie in diesem Beispiel: ‘avatarsay --encoding=ISO-8859-1 MeinText’.
Nun, manchmal möchte man nicht, dass der Text in einem kontinuierlichen
Textfluss dargestellt wird. Man kann seinen Text deshalb mit Trennlinien
strukturieren. Eine Trennlinie ist eine Zeile wie diese: ‘---------’.
Die Zeile muss in der aller ersten Spalte beginnen und sie muss mindestens
drei aufeinander folgende Bindestriche (U+002D) umfassen. Natürlich
kann man auch mehr als drei benutzen. Wenn avatarsay auf eine solche
Trennlinie stößt, wartet es es eine Weile und fängt dann eine neue Seite an.
Man muss nicht unbedingt immer den Befehl avatarsay von Hand eingeben um seine Texte damit zu betrachten. Man kann auch den Text selbst in ein “Programm” verwandeln. Wie das funktioniert hängt vom verwendeten Betriebssystem ab.
Auf einem POSIX-kompatiblen System, wie dem GNU-System kann man eine spezielle Zeile an den Anfang der Datei einfügen. Diese Zeile sieht zum Beispiel so aus: ‘#! /usr/local/avatarsay’. Natürlich sollte man darauf achten, dass man den richtigen Pfad angibt. Dies muss die aller erste Zeile der Datei sein. Man kann eine oder mehrere Leerzeilen nach dieser Zeile einfügen — diese werden ignoriert. Danach muss man das Ausführungs-Bit bei der Text-Datei setzen. Das geht folgendermaßen: ‘chmod +x MeinText’. Schon ist der Text selbst ausführbar. Er akzeptiert fast alle Parameter, die auch avatarsay akzeptiert.
Auf Systemen wie Windows oder ReactOS funktioniert diese Zeile nicht — sie schadet aber auch nicht. Auf diesen Systemen muss man einen anderen Trick anwenden. Man könnte die Datei so umbenennen, dass sie eine spezielle Datei-Endung bekommt; zum Beispiel .avt. Nun muss man sein System so konfigurieren, dass die Datei-Endung .avt mit dem Programm avatarsay.exe verknüpft wird. Dann kann man auf seinen Text doppelklicken und er wird ausgeführt.
Bisher haben wir immer ein und denselben Avatar gesehen — ein Gnu. Aber nicht jeder mag Gnus oder das, was man sagen will entspricht nicht dem GNU-Projekt. — Nun, das ist nur der Vorgabe-Avatar. Man kann ihn austauschen.
Es gibt verschiedene Methoden um den Avatar bei avatarsay auszutauschen:
Man kann es allgemein einstellen, dass der Aufruf von avatarsay immer den neuen Avatar verwendet. Dies kann man entweder über eine Umgebungsvariable erreichen, oder indem man eine systemweite Konfigurationsdatei erstellt.
Nun, zuerst sollte man die Umgebungsvariable ausprobieren. Das ist
einfach. Die Variable heißt AVATARIMAGE. Zum Beispiel mit der
GNU bash kann man die Variable folgendermaßen setzen:
‘export AVATARIMAGE=/usr/local/share/pixmaps/meinavatar.bmp’.
Wichtig: Man sollte immer den vollständigen Pfad angeben!
Wenn man eine Konfigurationsdatei verwenden will, erstellt man eine Datei mit dem Namen /etc/avatarsay und folgendem Inhalt:
AVATARIMAGE=/usr/local/share/pixmaps/meinavatar.bmp
Oder man kann das Bild für den Avatar auf einer Text-für-Text Basis austauschen, indem man einen Befehl in der Text-Datei verwendet. Das wird in Befehle für avatarsay näher erläutert.
Welche Bilddatei-Formate von AKFAvatar unterstützt werden, hängt davon
ab, welche Bibliotheken auf dem System installiert sind. Unkomprimierte
BMP-Bilder werden immer unterstützt.
Das Avatar-Bild sollte natürlich einen transparenten Hintergrund haben. Leider unterstützen die meisten Bild-Formate keine Transparenz. Darum verwendet AKFAvatar einen Trick. Wenn das Avatar-Bild keine Transparenz hat, dann wird der erste Farbwert im Bild genommen, das ist der Farbwert in der oberen linken Ecke, und dieser Farbwert wird als transparent deklariert. Wenn man ein Bild für die Verwendung als Avatar vorbereiten will, sollte man also darauf achten, dass die obere linke Ecke “leer” ist und man sollte darauf achten, eine Hintergrund-Farbe zu wählen, die in dem Teil des Bildes, der sichtbar sein soll, nicht vorkommt. Man muss außerdem darauf achten, dass der Hintergrund “glatt” ist und nur einen einzigen Farbwert ohne jegliche Schattierungen erhält. Wegen dieser Voraussetzung ist übrigens das JPEG-Format nicht geeignet. Man kann nämlich in diesem Format niemals einen wirklich “glatten” Hintergrund bekommen.
Wenn man Bildformate verwenden kann, die Transparenz unterstützen, dann sollte man dies auch verwenden. AKFAvatar wird dann nicht in die Transparenz eingreifen. Es ist jedoch zu beachten, dass der oben beschriebene Trick immer angewendet wird, wenn das Bild keine Transparenz hat, unabhängig davon, ob das Bildformat Transparenz unterstützen würde.
Das genaue Aufruf-Format für avatarsay ist:
avatarsay [Optionen] [Text-Dateien]
avatarsay [Optionen] --execute Programm [Programm-Optionen]
Wenn Text-Dateien nur ein - ist, dann liest das Programm von der Standard-Eingabe (stdin) und es läuft nicht in einer Schleife.
Das Programm avatarsay unterstützt die folgenden Optionen:
--help-h--version-v--terminal-t--execute-x-eEs muss ein Programmname angegeben werden. Optionen hinter dem Programmnamen
gelten für das aufzurufende Programm.
--nocolor-b--window-w--fullscreen-f--fullfullscreen-FDiese Option ist auch nützlich, wenn es nur einen Vollbild-Modus gibt,
aber die Bildschirm-Auflösung nicht umgestellt werden kann; zum Beispiel
mit dem VESA-Framebuffer des Kernels Linux.
Diese Option wird erst ab SDL Version 1.2.10 oder neuer unterstützt.
--encoding=NameWelche Kodierungen unterstützt werden, hängt von der
iconv-Implementierung des Systems ab. Auf einigen Systemen kann man
eine Liste mit dem Befehl iconv -l bekommen.
--latin1-l--utf-8--utf8-u8-uUTF-8 kodiert
--once-1--popup-pDies kann man für schnelle Popup-Texte verwenden.
Um das Programm auch wieder schnell zu beenden, kann man den Befehl
.stop verwenden.
--no-delay-n--raw-r--ignoreeof-iDer Befehl avatarsay unterstützt die folgenden Umgebungsvariablen:
AVATARIMAGEDATADIRAVATARIMAGE)
LC_ALLLC_CTYPELANGSHELLHOME
Über eine Konfigurationsdatei namens /etc/avatarsay kann man ebenfalls
Werte für AVATARIMAGE und DATADIR festlegen.
Beispiel:
AVATARIMAGE=/usr/local/share/pixmaps/meinavatar.bmp
AVATARDATADIR=/usr/local/share/akfavatar
Siehe auch Anderes Avatar-Bild.
Das Programm avatarsay versteht ein paar wenige Befehle. Damit kann man seine “ausführbaren Texte” noch weiter aufpeppen.
Eine Zeile, die mit einer Raute (#, U+0023) beginnt,
ist ein Kommentar. Diese Zeilen werden von dem Programm einfach
ignoriert. Achtung: Im Gegensatz zu anderen Skript-Sprachen
dürfen vor der Raute noch nicht mal Leerzeichen stehen.
Man kann seinen Text mit Trennlinien strukturieren. Eine Trennlinie ist
eine Zeile wie diese: ‘---------’. Die Zeile muss in der aller
ersten Spalte beginnen und sie muss mindestens drei aufeinander folgende
Bindestriche (U+002D) umfassen. Natürlich kann man auch mehr als
drei benutzen.
Ein Befehl für avatarsay fängt mit einem Punkt
(U+002E) in der aller ersten Spalte einer neuen Zeile an.
Das Daten-Verzeichnis kann auch mit der Umgebungsvariablen
AVATARDATADIR eingestellt werden. Der Befehl hat Vorrang
vor der Umgebungsvariablen.
Achtung: Dieser Befehl muss benutzt werden, bevor der eigentliche Text anfängt.
Das Avatar-Bild kann auch mit der Umgebungsvariablen AVATARIMAGE eingestellt werden. Der Befehl hat Vorrang vor der Umgebungsvariablen.
Welche Bilddatei-Formate von AKFAvatar unterstützt werden, hängt davon
ab, welche Bibliotheken auf dem System installiert sind. Unkomprimierte
BMP-Bilder werden immer unterstützt.
Achtung: Dieser Befehl muss ziemlich am Anfang der Datei stehen. Man kann die Kodierung nicht mehr innerhalb des Textes verändern. (Das war in früheren Versionen noch möglich.)
Dieser Befehl kann nur bei ASCII-kompatiblen Kodierungen verwendet
werden, wie zum Beispiel die ISO-8859-Familie oder UTF-8.
Die Kodierungen UTF-16 (UCS2) und UTF-32 (UCS4)
können nicht auf diese Weise definiert werden. Diese Kodierungen werden
in der Regel jedoch automatisch erkannt. (Ältere Versionen von
avatarsay konnten mit diesen Kodierungen gar nicht umgehen.)
Welche Kodierungen unterstützt werden, hängt von der
iconv-Implementierung des Systems ab. Auf einigen Systemen kann man
eine Liste mit dem Befehl iconv -l bekommen.
Die Farb-Definition muss als sechs stellige Hexadezimalzahl
angegeben werden, mit jeweils zwei Ziffern für rot,
grün und blau. Der Vorgabe-Wert ist ‘#CCCCCC’.
Achtung: Dieser Befehl muss benutzt werden, bevor der eigentliche
Text anfängt.
Man kann die Text-Richtung nur Zeile für Zeile ändern. Verschiedene
Text-Richtungen innerhalb einer Zeile werden nicht unterstützt.
Das Bild wird auf dem Bildschirm zentriert. Wenn das Bild größer als der Bildschirm ist, wird der Bildschirm auf dem Bild zentriert.
Man kann eine Trennlinie nach diesem Befehl einfügen, wenn man will. Die Trennlinie hat dann keine Auswirkung.
Welche Bilddatei-Formate von AKFAvatar unterstützt werden, hängt davon
ab, welche Bibliotheken auf dem System installiert sind. Unkomprimierte
BMP-Bilder werden immer unterstützt.
Der Text wird weiterhin angezeigt. Auf diese Weise kann man eine Audio Datei mit dem aufgenommenen Text abspielen, während gleichzeitig der Text auf dem Bildschirm erscheint.
Derzeit werden nur WAV-Dateien mit PCM- oder
ADPCM-Kodierung unterstützt.
Dies kann dafür verwendet werden, um den aufgenommenen Text mit dem
geschriebenen Text halbwegs zu synchronisieren.
Wenn man eine Kunstpause innerhalb einer Zeile einlegen will, kann man die
vorhergehende Zeile mit einem umgekehrten Schrägstrich (\,
U+005C) beenden, so dass das Zeilenende keine Auswirkung auf die
Ausgabe hat.
Die vorhergehende Zeile muss mit einem umgekehrten Schrägstrich (\,
U+005C) beendet worden sein. Man kann diesen Befehl nach dem Befehl
.effectpause verwenden, um einen schönen Effekt zu erzielen.
Der Avatar bewegt sich aus dem Bild.
Alles nach dem .end-Befehl wird ignoriert.
Der Avatar wird nicht aus dem Bild bewegt, sondern die Textausgabe wird sofort beendet.
Alles nach dem .stop-Befehl wird ignoriert.
Man muss nicht immer feststehende Texte schreiben um AKFAvatar zu benutzen.
Man kann den Befehl avatarsay auch dafür verwenden um sich die
Ausgabe anderer Befehle anzeigen zu lassen. Hierfür kann man einen einzelnen
Bindestrich (-, U+002D) als Option angeben.
Am besten versucht man das in eine Fenster-basierten Umgebung, wo man ein Fenster für die Eingabe-Zeile hat und avatarsay in einem anderen Fenster dargestellt wird.
Man kann zum Beispiel mal folgendes ausprobieren:
‘echo "Hallo du. Wie geht's?" | avatarsay -’. Das Gnu erscheint und
sagt diese Worte. Man sollte aber vorsichtig mit der Verwendung von
Ausrufungszeichen sein, einige Shells haben damit Probleme.
Man kann sich aber auch die Ausgabe von anderen Befehlen mit
avatarsay ansehen. Als Beispiel das: ‘df | avatarsay -’,
oder das: ‘dir | avatarsay -’. Man könnte sogar diese Anleitung auf
folgende Weise lesen:
‘makeinfo --plaintext akfavatar-de.texinfo | avatarsay -’,
aber das ist wohl etwas zu langatmig.
Dieses Kapitel erklärt die Verwendung des Skriptes gnome-akfavatar. Es handelt sich dabei um eine einfache Benutzeroberfläche für den Befehl avatarsay, bei der einige Funktionen über ein Menü abrufbar sind.
Bei dem Befehl gnome-akfavatar handelt es sich um ein Shell-Skript, er benötigt also eine Bourne-Shell. Er wurde mit der GNU bash getestet, aber jede andere POSIX-kompatible Bourne-Shell sollte auch funktionieren.
Dann benötigt er das Programm avatarsay. Das wird über den
PATH gesucht und im aktuellen Verzeichnis.
Für die sichtbare Oberfläche benutzt er das Programm zenity.
Als Text-Editor wird gedit benötigt und als Hilfe-Browser wird
yelp verwendet. Diese Befehle müssen über den PATH
abrufbar sein. Das sind aber alles Programme, die zu GNOME
gehören, und somit schon vorinstalliert sein sollten.
Da der Befehl avatarsay auch im aktuellen Verzeichnis gesucht wird, braucht das Paket nicht unbedingt installiert zu werden. Aber die Anleitung muss installiert sein, damit man sie aus gnome-akfavatar heraus aufrufen kann.
Wenn man gnome-akfavatar aufruft, bekommt man ein Menü, aus welchem man auswählen kann, was man damit tun will.
Man bekommt die folgenden Menüpunkte:
show a demo or textfile (ein Demo oder eine Text-Datei anzeigen)create or edit a demo (ein Demo erstellen oder bearbeiten)#!-Zeile angelegt.
Wenn man ein anderes Avatar-Bild eingestellt hat bevor man diesen Menüpunkt
verwendet hat, wird auch ein passender .avatarimage-Befehl mit
eingefügt. Das Ausführungs-Bit wird bei der erstellten Datei gesetzt.
Anmerkung: Das alles wird nur für neu angelegte Dateien gemacht,
nicht für Dateien, die vorher schon existiert haben.
show a manpage (eine Manpage anzeigen)show the output of a command (zeige die Ausgabe eines Befehls)change avatar image (ändere das Avatar-Bild)fullscreen or window mode (Vollbild- oder Fenster-Modus)Okay klickt, wird der Vollbild-Modus aktiviert,
wenn man auf Cancel/Abbrechen klickt, wird der
Fenster-Modus ausgewählt.
Diese Einstellung gilt erstmal nur für die aktuelle Sitzung, es sei denn,
man verwendet den Menüpunkt save settings.
save settings (speichere Einstellungen)help for AKFAvatar (Hilfe für AKFAvatar)WebsiteExit (beenden)Abbrechen
klickt oder auf den Schließen-Knopf des Fensters, oder indem man die
<Esc>-Taste drückt.
Wenn man anfangen will programmieren zu lernen, ist Pascal eine sehr gute Wahl als Einstiegssprache. Leider ist Pascal jedoch nicht sehr weit verbreitet. Dennoch haben wir mit GNU-Pascal und Free Pascal zwei sehr gute Freie Software Implementierungen zur Verfügung, die auf vielen verschiedenen Plattformen einsetzbar sind.
Es wäre durchaus auch möglich gewesen, das Ganze komplett in Pascal zu schreiben. Aber C ist viel weiter verbreitet und das hat seine Konsequenzen. Jedes moderne System bringt in der Regel bereits einen C-Compiler mit und fast jede andere Programmiersprache kann Bibliotheken, die in C geschrieben wurden verwenden.
Man kann AKFAvatar für Pascal-Programme verwenden.
Zunächst einmal muss die Bibliothek bereits auf dem System installiert sein. Man benötigt außerdem die Datei akfavatar.pas. Die Datei wird normalerweise nicht automatisch installiert, da es kein Standard-Verzeichnis dafür gibt. Wenn sie sich aber im aktuellen Verzeichnis befindet, wird sie dennoch gefunden.
In dem Paket mit den Quelltexten findet man unter anderem die Skripte gpcavatar und fpcavatar im Unterverzeichnis pascal/. Wenn man zum Beispiel GNU-Pascal (gpc) hat, kann man folgendes eingeben: ‘./gpcavatar example.pas’ Damit sollte das Programm example kompiliert werden.
Auf diese Weise kann man jedes Pascal-Programm, das nur die Standard-Eingabe/Ausgabe verwendet kompilieren. Es sind keine Änderungen am Quelltext des Pascal-Programmes nötig!
Wenn man eine neue Seiten anfangen will, kann man einfach den Befehl page; verwenden.
Na? Das ist doch einfach, oder?
Hinweis: Wenn das Programm die Unit CRT verwendet, muss man
Äanderngen am Quelltext vornehmen. Das wird weiter unten beschrieben.
Erstmal sollte man sich die Skripte gpcavatar und fpcavatar ansehen. Am Anfang dieser Skripte befinden sich einige Variablen, die man an seine Bedürfnisse anpassen sollte. Dann kann man die Skripte nach /usr/local/bin kopieren, so dass man sie von überall her aufrufen kann. Die Datei akfavatar.pas sollte man dahin kopieren, wo man seine persönlichen Units haben möchte. Man sollte sicher stellen, dass dieses Verzeichnis auch in den Skripten mit aufgelistet ist.
Es ist auch möglich Programme mit AKFAvatar zu verwenden, die auf der Unit
CRT basieren. Dafür sind aber Veränderungen am Programm notwendig.
Die Skripte gpcavatar und fpcavatar definieren beide das Symbol
AKFAVATAR, so dass man {$IfDef AKFAVATAR} oder
{$IfNDef AKFAVATAR} verwenden kann, um zu kontrollieren, was passiert,
wenn man es mit oder ohne AKFAvatar kompiliert.
Um sicher zu stellen, dass das Programm immer noch mit der Unit CRT
funktioniert, kann man folgendes verwenden:
‘{$IfNDef AKFAVATAR} uses CRT; {$EndIf}’. Das Programm
multiply.pas ist ein Beispiel für diese Methode.
AKFAvatar unterstützt die meisten Befehle und Variablen wie die originale
CRT Unit. Zum Beispiel der Befehl ClrScr löscht den
Text-Bereich (nicht den ganzen Bildschirm!), ClrEol löscht den
Rest der Zeile. Man kann den Befehl GotoXY(x, y);
verwenden um an eine bestimmte Stelle innerhalb des Text-Bereiches zu
springen. Die Funktionen WhereX und WhereY geben
Auskunft über die aktuelle Position.
Achtung: Die Breite der Anzeige umfasst 80 Zeichen wie bei einem
Text-Terminal, aber die Höhe ist meist wesentlich geringer. Man kann die
Dimensionen des Text-Bereiches über die Funktion ScreenSize.x
und ScreenSize.y herausfinden. Der Avatar wird nun angezeigt, wenn
er vorher noch nicht sichtbar war. Wenn man also ein anderes Avatar-Bild oder
eine andere Hintergrundfarbe einstellen will, muss man das vor der Abfrage
der Größe tun.
Man kann den Befehl TextColor(color); verwenden, um die Text-Farbe zu verändern. Man kann sogar die Hintergrund-Farbe des Textes mit dem Befehl TextBackground(color); verändern. Aber das sieht nicht so gut aus wie auf einem Text-Terminal.
Sogar die Variable TextAttr wird vollständig unterstützt wie
in der originalen CRT-Unit. Aber diese Variable sollte nach Möglichkeit
vermieden werden.
Die Befehle HighVideo und LowVideo werden unterstützt,
aber etwas anders, als in der CRT-Unit. HighVideo schaltet
den Fettduck ein und LowVideo schaltet den Fettdruck wieder aus.
Diese Befehle verändern nicht die Farbe, wie dies in der CRT-Unit
geschieht. Das sollte man im Hinterkopf behalten, wenn man diese Befehle mit
Aufrufen von TextColor kombiniert.
Mit Underlined(true); kann man den Unterstreichen-Modus anschalten und mit Underlined(false); wieder abschalten.
Um zurück auf die “normale” Text-Darstellung zu schalten, sollte man den
Befehl NormVideo; verwenden. Die “normale” Text-Farbe ist
bei AKFAvatar eine ganz andere als mit der CRT-Unit. Durch
Verwendung dieses Befehles kann man also sicher gehen, dass man mit
beidem ein vernünftiges Ergebnis bekommt. NormVideo; schaltet
auch den Fettdruck und das Unterstreichen aus.
Die Funktion ReadKey wartet auf einen Tastendruck und gibt den Code der gedrückten Taste wieder. Um heraus zu finden ob eine Taste gedrückt wurde ohne das Programm zu blockieren, kann man die Funktion KeyPressed verwenden.
Achtung:
Funktionstasten werden noch nicht unterstützt. Die Taste <Esc>
beendet das Programm. Wenn man die <Esc>-Taste für etwas anderes
benötigt, kann man die Variable CheckEsc auf false setzen.
Das Programm wird auch beendet, wenn <Strg>+<C> gedrückt wird.
Um das zu verhindern, kann man die Variable CheckBreak auf
false setzen. Die Variable CheckBreak ist kompatibel
zur CRT-Unit, während CheckEsc eine Erweiterung ist.
Es gibt noch eine Menge zusätzlicher Befehle, die nicht kompatibel zur
CRT-Unit sind.
Mit dem folgenden Befehl kann man ein anderes Bild für den Avatar einstellen:
{$IfDef AKFAVATAR}
AvatarImageFile ('/usr/local/share/pixmaps/human-peasant.bmp');
{$EndIf}
Das ist natürlich nur ein Beispiel.
Dieser Befehl muss verwendet werden, bevor irgendeine Ausgabe oder Eingabe
stattfindet! Die Größe des Avatar-Bildes hat auch Einfluss auf die Größe des
Text-Bereiches. Darum muss der Befehl auch verwendet werden, bevor man die
Funktion ScreenSize verwendet.
Wenn man die Hintergrund-Farbe des Fensters (also nicht des Text-Bereiches) verändern will, kann man den Befehl setBackgroundColor(rot, grün, blau); am Anfang des Programmes verwenden. Die Werte für rot, grün und blau repräsentieren die Farbintensität dieses Farbanteils. Man kann jede darstellbare Farbe mit diesen drei Werten zusammen mischen. Der Maximalwert beträgt 255 ($FF). Zum Beispiel ‘setBackgroundColor(0, 0, 100);’ stellt einen dunkel-blauen Hintergrund ein.
Man kann in seinem Programm festlegen welche Zeichensatz-Kodierung man
verwendet. Wenn man noch ein altes System hat, das auf dem Latin-1
Zeichensatz basiert, kann man den Befehl
setEncoding ('ISO-8859-1'); einsetzen. Falls man mit mehreren
Zeichensätzen gleichzeitig hantieren muss, kann man den Befehl auch
mehrfach verwenden. Unterschiedliche Zeichensätze können im Text-Bereich
gleichzeitig dargestellt werden. (Intern wird ein Unicode-Zeichensatz
verwendet.)
Es gibt auch Zeichen für hebräische oder jiddische Texte. Um diese
zu verwenden muss man die Text-Richtung ändern. Dass kann man mit
den Befehlen setTextDirection (RightToLeft); und
setTextDirection (LeftToRight); tun. Man sollte aber
darauf achten, dass man vor oder nach Verwendung dieser Befehle eine
neue Zeile oder eine neue Seite anfängt. Unterschiedliche
Text-Richtungen innerhalb einer Zeile zu verwenden wird nicht
unterstützt.
Die Eingabe und Ausgabe wird über die üblichen Pascal-Befehle gehandhabt (Read, ReadLn, Write, WriteLn, Page). Man kann die vollständige Pascal Syntax für diese Befehle ausnutzen. Zum Beispiel: ‘WriteLn ('Pi ist ', Pi:0:8, ' und so weiter.');’
Wenn man einen Seitenumbruch auslösen will, kann man den Befehl page; verwenden. Tatsächlich handelt es sich dabei auch um einen Befehl aus Standard-Pascal, der aber selten benutzt wird; so selten, dass er in Free Pascal sogar ganz weggelassen wurde. Aber meine Unit definiert ihn auch für Free Pascal. Normalerweise wird page; dafür verwendet um eine neue Seite bei einem Drucker anzufordern.
Man kann den Text-Bereich auch mit dem Befehl ClrScr; löschen.
Im Gegensatz zu page; wartet der Befehl ClrScr; nicht
erst, sondern löscht den Text-Bereich sofort. Man kann den Cursor mit dem
Befehl GotoXY (x, y); an jede beliebige Stelle bewegen. Man
kann die Position des Cursors mit den Funktionen WhereX und
WhereY heraus finden. Die Koordinaten 1, 1 bezeichnen die
obere linke Ecke (unabhängig von der Text-Richtung). Man kann die
Maximalwerte mit ScreenSize.x und ScreenSize.y heraus
finden. All diese Namen wurden gewählt, um eine gewisse Kompatibilität
zur CRT-Unit zu bekommen. Ungeachtet ihrer Bezeichnungen
verwalten sie nicht den Bildschirm, sondern nur den Text-Bereich.
Wenn man Warnungen Fehlermeldungen oder Debug-Informationen ausgeben will
sollte man stderr verwenden. (Das funktioniert nicht unter Windows
oder ReactOS)
Zum Beispiel: ‘WriteLn (stderr, 'Error: ', AvatarGetError);’
Nun, die Funktion AvatarGetError holt eine Fehlermeldung von
der Bibliothek ein.
Der Befehl ShowAvatar; zeigt nur den Avatar ohne die Sprechblase.
Die Befehle MoveAvatarIn; oder MoveAvatarOut; bewegen
den Avatar heraus beziehungsweise herein. Der Befehl
Delay (500); wartet ungefähr 500 Millisekunden. Falls man eine
Angabe in Sekunden bevorzugt, kann man folgendes verwenden:
Delay (seconds(0.5));.
Eine vollständige Übersicht über alle Pascal-Befehle und Funktionen findet man in Pascal Referenz.
Der folgende Text zeigt das interface der 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);
Es folgt der Inhalt der C Header Datei 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-de.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 */