\chapter{Erste Schritte mit der libCUI}

\section{''Hallo CUI world!''}

    Um nicht mit der guten alten Tradition von Programmierb"uchern zu brechen,
    soll auch diese Einf"uhrung mit dem obligatorischen ''Hallo World'' Programm
    beginnen:
    
\begin{verbatim}
#include <cui.h>

void quit(void)
{
   WindowEnd();
}

int main(void)
{
   WindowStart(TRUE, TRUE);
   atexit(quit);

   MessageBox(WindowGetDesktop(),
              "Hallo World\n"
              "This is my first libcui program!",
              "Message",
              MB_OK);

   return 0;
}
\end{verbatim}

   Zun"achst wird die Datei ''cui.h'' eingebunden, die alle Funktionsprototypen,
   Datentypen und Konstanten der libCUI bekannt macht. In der ''main''-Routine
   wird dann "uber den Funktionsaufruf ''WindowStart'' in den curses-Modus gewechselt,
   wobei die beiden Parameter sowohl den Farbmodus, als auch die Mauseingabe
   aktivieren.

\begin{verbatim}
   void WindowStart(int color, int mouse);
\end{verbatim}
   
   Anschlie"send wird "uber ''atexit'' eine Exit-Routine angemeldet, die in 
   jedem Fall daf"ur sorgt, dass der curses-Modus auch wieder korret "uber ''WindowEnd''
   beendet wird und alle von der libCUI verwalteten Datenstrukturen freigegeben
   werden. Zu guter letzt wird "uber ''MessageBox'' ein Meldungsfenster angezeigt, das eine 
   zweizeilige Meldung ausgibt.
   
   Das Programm mogelt sich zugegebenerma"sen um die eigentliche Fensterprogrammierung
   herum, indem die fertige Dialogklasse ''MessageBox'' verwendet wird um Text
   auszugeben. Zu einem sp"ateren Zeitpunkt wird darauf jedoch noch wesentlich ausf"uhrlicher 
   eingegangen.
   

\marklabel{build}{\section{"ubersetzen von libCUI Anwendungen}}

    Damit ein libCUI-Programm lauff"ahig ist, muss es mit der Biblithek bei der
    "ubersetzung verkn"upft (gelinkt) werden. Dies funktioniert sebstverst"andlich
    nur dann, wenn sich die Entwicklungsdateien (headers and libraries) der libCUI
    auf dem Build-System befinden.
    
    Das Linken kann auf zwei Arten erfolgen: dynamisch und statisch. Bei der 
    dynamischen Verkn"upfung werden lediglich Verweise auf eine gemeinsame
    Bibliotheksdatei in dem erzeugten Programm hinterlegt. Diese m"ussen sp"ater vom
    Programm-Loader des Betriebsystems aufgel"ost werden, bevor das Programm
    zur Ausf"uhrung kommen kann. Der Vorteil dabei ist, 
    dass alle Programme eine gemeinsame Bibliothek verwenden und damit Resourcen
    schonen. Zudem kommen bei einem Update der Bibliothek alle Programme zugleich
    in den Genuss von Fehlerkorrekturen, solange sich das Interface der Bibliothek
    nicht ver"andert hat.
    
    Beim statischen Linken wird der verwendete Code der Bibliothek in das
    Programm "ubernommen, wodurch deutlich gr"o"sere Bin"ardateien erzeugt werden.
    Diese haben dann aber den Vorteil, dass sie von konzeptionellen "Anderungen
    der Bibliothek unabh"angig sind und auch auf Systemen funktionieren, auf denen
    die libCUI nicht als gemeinsame Datei vorliegt. Zum momentanen Zeitpunkt wird
    zum statischen Linken geraten, da sich die libCUI noch in einem recht fr"uhen
    Entwicklungsstadium befindet.
    
\subsection{Dynamisches Linken}

\begin{verbatim}
gcc -Wall -Wstrict-prototypes -o hallo.o hallo.c
gcc -o hallo hallo.o -lcui
\end{verbatim}

Hier wird in zwei Schritten zun"achst die Datei hallo.c "ubersetzt und anschlie"send
mit der Bibliothek libCUI zu einem ausf"uhrbaren Programm verlinkt. Bei nur einer
Code-Datei kann dies auch in einem einzelnen Schritt erfolgen:

\begin{verbatim}
gcc -Wall -Wstrict-prototypes -o hallo hallo.c -lcui
\end{verbatim}

\subsection{Statisches Linken}

\begin{verbatim}
gcc -Wall -Wstrict-prototypes -o hallo.o hallo.c
gcc -o hallo hallo.o /usr/lib/libcui.a -lcurses
\end{verbatim}

Hier wird in zwei Schritten zun"achst die Datei hallo.c "ubersetzt und anschlie"send
mit der Bibliothek libCUI zu einem ausf"uhrbaren Programm verlinkt. Dabei wird die
statische Bibliotheksdatei ''/usr/lib/libcui.a'' einfach in die Liste der zu
verlinkenden Module aufgenommen wodurch sie vom Linker fest eingebunden. Zu beachten
ist jetzt allerdings, dass zur Aufl"osung der curses-Funktionen, die curses-Library
ebenfalls angegeben werden muss.

Bei nur einer Code-Datei kann das auch in einem einzelnen Schritt erfolgen:

\begin{verbatim}
gcc -Wall -Wstrict-prototypes -o hallo hallo.c /usr/lib/libcui.a \
    -lcurses
\end{verbatim}
	
\section{Das Ergebnis}
Egal ob nun statisch oder dynamisch gelinkt wurde, sollte sich nach dem obigen
Beispiel eine Datei ''hallo'' im aktuellen Verzeichnis befinden, die sich mit

\begin{verbatim}
eis # ./hallo
\end{verbatim}

ausf"uhren l"asst. Das Ergebnis ist ein Programm, dass die Meldung ''Hallo World'', 
''This is my first libcui program!'' in einem Meldungsfenster vor einem (blauen) 
Hintergrund ausgibt. 
Das  Meldungsfenster besitzt eine Schaltf"ache "uber die das Fenster entweder mit der
Leertaste oder der Enter-Taste geschlossen werden kann. Falls die Konsole
die Maus unterst"utzt, kann das Fenster auch mit diesem Eingabeger"at geschlossen
werden. Zudem l"asst sich die MessageBox durch Ziehen der Maus auf dem Fensterrahmen
im sichtbaren Bereich verschieben.

Wird die Gr"o"se des Konsolenfensters ge"andert, wird das Meldungsfenster in
der Fenstermitte zentriert.

\begin{figure}
  \includegraphics[width=6in]{pics/halloworld1.png}
\end{figure}
%\graphic{center}{width=150mm}{./halloworld1.png}{Hello World}


\section{Allgemeine Hinweise}

\subsection{Koordinatensysteme}
    Vergleichbar mit g"angigen Fenstersystemen wird bei Koordinatenangaben innerhalb der
    libCUI eine \(x, y\)-Reihenfolge eingehalten. Demgegen"uber nennt die curses-
    Bibliothek die y-Koordinate zuerst, also \(y, x\). Dies mag zu einiger Verwirrung
    f"uhren, denn immer wenn mit curses-Routinen zur Textausgabe gearbeitet wird,
    ist dieser Unterschied zu beachten.
    
    Um die Programmierung in dieser Hinsicht zu erleichtern wird die libCUI zu einem
    sp"ateren Zeitpunkt Makro-Definitionen erhalten, die die Curses-Routinen so erscheinen
    lassen, als seien sie innerhalb der libCUI definiert. Dabei werden die Koordinaten
    entsprechend getauscht werden.

\subsection{Mausunterst"utzung}
    Damit die Maus auf der Textkonsole funktioniert, muss die zugrundeliegende
    curses- Bibliothek mit Mausunterst"utzung (z.B. f"ur den gpm-Mouse Daemon) "ubersetzt
    worden sein. Dies ist oftmals nicht der Fall.
    In Terminal-Fenstern unter X11 (KDE- / Gnome- Terminal), sowie im ssh Client PuTTY
    ist die Mausunterst"utzung i.d.R enthalten. Allerdings ist es dem Autor nicht 
    gelungen, auch die Mouse-Move Ereignisse sichtbar zu machen. Diese Eigenschaft
    muss in den Tiefen der terminfo-Dateien verborgen sein. Sachdienliche Hinweise
    sind stets willkommen... :-)
