\documentclass[german, 10pt, a4paper]{scrreprt}

\usepackage[ngerman]{babel}	% Babel for languages
\usepackage[ansinew]{inputenc} % for german umlaute

\usepackage{amsmath}		% use AMS packages
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{amsthm}

% use listings for drawing code
\usepackage{listings}

\usepackage{graphicx} 

\usepackage{fancyhdr}		% fancy headers package

% Listings konfigurieren
\lstset{
  language=Eiffel,
  basicstyle=\small,
  tabsize=4,
  showtabs=false,
  showspaces=false,
  showstringspaces=false,
  breaklines=true,
  breakindent=0pt}

% informations about the document
\title{Development Guide\\Under Construction}
\author{Stefan Hildenbrand\\Florian Keusch\\Markus Neidhart\\Beat Steiger}
%\date{14.04.05}

\addtolength{\textheight}{100pt}
\begin{document}
\makeatletter
\begin{titlepage}%
    \thispagestyle{empty}
    
    \begin{center}
    \textsf{Software Architecture, Sommersemester 2005, ETH Z\"urich}
     \rule[.8em]{.9\textwidth}{0.5pt}
     \vskip 3em
     {\titlefont {\Huge UC - Developer Guide}\par}
     \vskip 3em
    \includegraphics{uc_logo}
    \vskip 3em
    \rule{.9\textwidth}{0.5pt}
    \vskip 1.5em
   {\titlefont\huge Under Construction}
   \vskip 1em
   \rule{.9\textwidth}{0.5pt}
   \vskip 2.5em
   \textsf{ {\large Stefan Hildenbrand}
     \vskip 0.5em
    {\large Florian Keusch}
    \vskip 0.5em
    {\large Markus Neidhart}
    \vskip 0.5em
    {\large Beat Steiger}
    \vskip 2em}
    \end{center}
    \end{titlepage}
\makeatother

\tableofcontents

\chapter{Einf"uhrung}
\section{Zweck des Dokuments}
Dieses Dokument ist das Entwickler Handbuch zum Spiel ''Under Construction'' und richtet sich haupts"achlich an Entwickler und Weiterentwickler dieses Spiels. Durch dieses Dokument soll der Leser informiert werden "uber den Aufbau unseres Projekts, "uber verwendete Patterns, "uber Wiederverwendbarkeit einzelner Klassen, und auch Details des Sourcecodes werden aufgelistet.
%%\vspace*{1cm}
\section{Zweck des Softwareprodukts}
Unsere Software ist ein Puzzlepiel und heisst ``Under Construction'', kurz UC. Das Spiel wird:
\begin{enumerate}
\item ein geladenes Bild in kleine Teile zerlegen.
\item dem Spieler die M"oglichkeit geben, selbst ein beliebiges Bild zu laden.
\item dem Spieler die M"oglichkeit geben, die Anzahl der Teile und somit den Schwierigkeitsgrad zu bestimmen.
\item einen ETH-Modus bieten, der ein Bild der ETH l"adt und es in 150 Teile zerlegt.
\item 3 Arbeitsfl"achen zur Verf"ugung stellen, auf denen der Spieler seine Teile sortieren kann.
\item Sound kann abgespielt werden.
\end{enumerate}
Das Ziel des Spiels ist es, alle Teile so aneinanderzureihen, dass wieder das urspr"ungliche Bild entsteht, also das Puzzle zu l"osen.
%%\vspace*{1cm}
\section{Erl"auterungen zu Begriffen}
\begin{description}
\item[Spielfl"ache] Teil des Displays, der als Ablage f"ur diejenigen Teile dient, die das fertige Ursprungsbild ergeben.
\item[Arbeitsfl"ache (workspaces)] Teil des Displays, um noch nicht zur Spielfl"ache hinzugef"ugte Teile zu sortieren.
\item[play window] (grahisch) Ist das gesamte Fenster, in dem der Spieler seine Puzzleteile zusammensetzt oder den Player steuern kann. (dazu geh"ort also Spielfl"ache und Arbeitsfl"ache)
\item[Puzzle Start Window PSW] Ist jene Klasse, die das ganze PuzzleSpiel initialisiert und managt.
\end{description}

%%\vspace*{1cm}
\section{Referenzen}
\begin{itemize}
\item Eiffel, http://www.eiffel.com
\item ESDL, http://eiffelsdl.sourceforge.net
\item http://se.inf.ethz.ch/download/games/developer/
\item ESDL, http://eiffelsdl.sourceforge.net
\item EWG: Eiffel wrapper generator: http://ewg.sf.net/
\item Gobo: http://www.gobosoft.com/eiffel/gobo/
\item SDL: http://libsdl.org/
\item Chair of Software Engineering: http://se.inf.ethz.ch/
\item VIS Forum: http://forum.vis.ethz.ch
\end{itemize}

\section{Entwickler}
Die Entwickler dieses Projekts sind:\\
\begin{center}
\begin{tabular}{ll}
{\bf \Large Stefan Hildenbrand} & stefanhi@student.ethz.ch\\
{\bf \Large Florian Keusch} & fkeusch@student.ethz.ch\\
{\bf \Large Beat Steiger} & steigebe@student.ethz.ch\\
{\bf \Large Markus Neidhart} & nemarkus@student.ethz.ch\\
\end{tabular}
$ $\\
$ $\\
$ $\\
Alle sind zu erreichen unter: uc@floesen.ch\\
\end{center}

Dieses Projekt wurde entwickelt im Rahmen der Vorlesung Software Architecture, die an der ETH Z"urich im Sommersemester 05 gehalten wurde.\\

\section{"Ubersicht "uber das restliche Dokument}
Im restlichen Teil dieses Dokuments wird auf die Installation von allen ben"otigten Teilen eingegangen. Die Funktionen werden erkl"art und Abh"angigkeiten aufgelistet. Weiterhin werden die features und requirements aller unserer Klassen aufgelistet. Deren Abh"angigkeiten werden im BON-Diagram graphisch dargestellt.

\chapter{Installation}
\section{Eiffel}
Um das Spiel zu entwickeln wir das Eiffel Studio (www.eiffel.com) ben"otigt.
F"ur die Entwicklung dieses Projekts wurde vorwiegend Eiffel Version 5.5 unter Windows verwendet. F"ur die Entwicklung haben wir den freien bcb compiler verwendet (bei der Installation von Eiffel kann ausgew"ahlt werden). Unter Linux wurde das Spiel nicht getestet. Es ist jedoch m"oglich dieselbe Funktionalit"at unter Linux zu erreiche, wenn erst mal das ganze ESDL mitsamt den ben"otigten libraries installiert wurde. (Dazu ben"otigt man die Linux Version von ESDL, die cvs sourcen von ewg und gobo, ev auch noch sdl libraries. Zur Installation unter Linux beachte das file developer.txt (zu ESDL) und diverse Foren im Internet)\\

\section{ESDL}
Im Spiel ben"otigt wurde die Version 0.6.0 von EDSL. Zu finden unter:\\
http://se.inf.ethz.ch/download/games/developer/\\
Weiterhin wird gobo und ewg ben"otigt. (die aber unter Windows automatisch installiert werden (ESDL). Ebenso sollten die Umgebungsvariablen automatisch gesetzt werden.)
\section{Umgebungsvariablen}
Damit alles richtig funktioniert, sollten etwa folgende Umgebungsvariablen gesetzt sein:
\begin{itemize}
\item ESDL=\$ESDL
\item EWG=C:\$ESDL/dependency/ewg
\item GOBO=C:\$ESDL/dependency/gobo
\item GOBO\_CC=bcb
\item GOBO\_EIFFEL=ise
\item ISE\_C\_COMPILER=bcb
\item ISE\_EIFFEL=\$EIFFEL
\item Path=\$EDSL/dependency/sdl/lib
\item Path=\$ESDL/dependency/ewg/bin
\item Path=\$ESDL/dependency/gobo/bin
\item SDL=\$ESDL/dependency/sdl
\item SDL\_HEADER=\$ESDL/dependency/sdl/include
\end{itemize}
Wobei \$ESDL der Pfad ist, der auf das ESDL directory zeigt. \$EIFFEL ist der Pfad, in dem Eiffel installiert wurde.


\section{diverse hacks}
\subsection{Mixer f"ur der Sound}
Um den Mixer zu includen muss man das gesamte ESDL neu zu kompilieren. Zuerst noch die Umgebungsvariablen "uberpr"ufen, dann folgende Schritte durchf"uhren (Achtung, hier wurde der compiler bcb verwendet, sonst anpassen):
\begin{enumerate}
\item neuste ESDL Version downloaden (hier wurde: esdl\_bcb\_0.6.0.exe verwendet). 
\item neue esdl version installieren falls n"otig
\item in der Datei \$ESDL/library/manual\_wrapper/c/include/esdl.h
   den auskommentierten SDL\_mixer.h einbinden.
\item neu kompilieren (im ordner \$ESDL/library)
\begin{enumerate}
\item \emph{geant clobber} 
\item \emph{geant clean} ($\rightarrow$ alles wird gel"oscht)
\item \emph{geant install} ($\rightarrow$ kompilierung wird vorbereitet)
\item \emph{geant c\_build\_library\_ise} (oder so "ahnlich, je nach compiler)\\ ($\rightarrow$ wird neu kompiliert)
\end{enumerate}
Durch eingeben des Befehls \emph{geant} werden alle m"oglichen Befehle aufgelistet.
\item alles sollte nun funktionieren ;-)
\end{enumerate}
Damit man keine c-compilation Fehler kriegt, muss eventuell zus"atzlich im Eiffelstudio bei project $\rightarrow$ project settings unter dem register externals das object-file \emph{\$(SDL)/lib/SDL\_mixer.lib} hinzugef"ugt werden
%%\vspace*{1cm}

\subsection{Alpha Kanal f"ur Bilder}
Um 32bit Bilder mit Alphakanal laden zu k"onnen, m"ussen Bugs in den zwei
Klassen ESDL\_BITMAP\_FACTORY und ESDL\_SURFACE korrigiert werden. Danach
werden TGA und PNG Bilder mit Transparenz korrekt dargestellt (In BMPs
wird der Alphakanal nicht erkannt/gelesen).\\
(siehe auch http://forum.vis.ethz.ch/thread.php?threadid=6135)\\
$ $\\
Aenderungen sind mit ***** markiert:\\
$ $\\
\begin{verbatim}
Klasse ESDL_BITMAP_FACTORY
Feature create_bitmap_from_image
	

if temp_image_pointer /= default_pointer then
    image_pointer := sdl_display_format_alpha_external (temp_image_pointer)
                     *********************************
    sdl_free_surface_external (temp_image_pointer)
    if image_pointer /= default_pointer then
      create last_bitmap.make_from_pointer (image_pointer)
    end
end



Klasse ESDL_SURFACE
Feature gl_texture
	

if
    texture_modified
then
    saved_flags := flags & (Esdl_srcalpha | Esdl_rleaccelok)
    saved_alpha := pixel_format.alpha
    if
        saved_flags & Esdl_srcalpha = Esdl_srcalpha
    then
        error := sdl_set_alpha_external (current.item, 0, 0)
    end                                  ************
        -- blit to surface with correct (power of 2) dimensions
    surf_tex_.blit_surface (current, 0, 0)
        -- restore the alpha blending attributes
    if
        saved_flags & Esdl_srcalpha = Esdl_srcalpha
    then
        error := sdl_set_alpha_external (current.item, saved_flags, saved_alpha)
    end                                  ************



Klasse ESDL_SURFACE
Feature gl_texture_mipmap
\end{verbatim}	
$ $\\
Gleiche "Anderung wie in Feature gl\_texture (gleiche 2 Stellen, jeweils
\$current durch current.item ersetzen)\\


\chapter{Implementation}
% allgemein + einzelne Klassen
\section{Funktionsbeschreibung}
\subsection{Mausevents}
\begin{itemize}
\item Puzzleteile k"onnen mit der linken Maustaste bewegt werden. Der Spieler zieht ein passendes Teil vom Workspace in den Spielraum. Wenn dieses Teil passt, dann schnappt es ein, sonst spickt es zur"uck in den Workspace. Befindet sich das Teilchen noch immer "uber einem Workspace, wird es an der entsprechenden Stelle einsortiert. Ebenfalls reagieren die Buttons auf ein Teilchen, das "uber ihnen `fallen gelassen' wird.
\item Mit der rechten Maustaste wird ein Puzzleteil um 90 Grad gedreht. Durch 4 mal klicken erh"alt man also wieder das urspr"ungliche Puzzleteilchen.
\item durch Klicken auf einen Button wird das zugeh"orige event Ausgel"ost und der Button blinkt kurz auf.
\item Wenn ein Button mit der Maus "uberfahren wird, so "andert sich dessen Hintergrundfarbe.
\item Wenn auf ein Textfeld geklickt wird, so erscheint dort ein blinkender Cursor. Dann ist das Textfeld bereit f"ur die Eingabe. Durch weggklicken auf irgendeine andere Fl"ache wird der Focus verschoben.
\end{itemize}
%%\vspace*{1cm}

\subsection{Keyevents}
\begin{itemize}
\item Mit der Taste ESC wird das jeweilige Fenster verlassen. Ist der Spieler im Hauptmenu wird damit das Spiel beendet.
\item Mit der Taste p (pause/resume) wird der Musikplayer angehalten, respektive er wird fortgesetzt.
\item Die Taste s (stopp) stoppt den Musikplayer.
\item Durch Druck der Taste q wird das Program sofort verlassen.
\item Die Taste b (back) spielt das vorherige Lied in der Playliste ab.
\item Die Taste n (next) spielt das n"achste Lied ab.
\item Die Taste down bewirkt, dass sich im Menu die Auswahl um eins nach unten bewegt. Im play window kann damit die Lautst"arke erh"oht werden.
\item Die Taste up bewirkt, dass sich im Menu die Auswahl um eins nach oben bewegt. Im play window kann damit die Lautst"arke gesenkt werden.
\item Die Taste m (mute) schaltet den Ton aus. Der Player l"auft aber im Hintergrund weiter. Durch ein 2tes mal dr"ucken schlatet der Ton wieder ein.
\item Die Taste t (title) schaltet die Anzeige des Titels aus / ein.
\item Die Taste c (cheat) setzt ein Puzzle Teilchen an die richtige Stelle.
\item Die Taste i (image) zeigt das ganze Bild (L"osung) f"ur 3 Sekunden an.
\item Die Taste r (reset) formatiert die workspaces neu.
\item Mit den Tasten 0 bis 2 k"onnen die 3 workspaces angew"ahlt werden.
\item Die Taste d (delete) l"oscht das aktuelle angeklickte Puzzle Teil aus dem workspace. Falls keines angeklickt ist werden alle Puzzle Teile aus dem workspace gel"oscht.
\item Enter aktiviert die aktuelle Menuauswahl im Menu (Wenn nur eine Auswahl, dann wird die ausgel"ost).
\end{itemize}
%%\vspace*{1cm}

\subsection{Buttons (play window)}
Im play window befinden sich diverse Buttons mit den folgenden Funktionen:
\begin{itemize}
\item workspace Buttons repr"asentieren den jeweiligen Workspace. Durch einen Klick darauf wird derjenige Workspace angezeigt. Schiebt man ein Puzzle Teil "uber den Button so wird diese Teil in diesen Workspace verschoben.
\item Player Buttons dienen zur Steuerung des Musik Players.
\item Der Cheat Button (Zauberstab) setzt ein Puzzle Teilchen an die richtige Stelle im Puzzle.
\item Der Bild Button (Auge) zeigt das Bild (die fertige L"osung) f"ur 3 Sekunden an.
\end{itemize}

\subsection{New Game}
Hier kann der Spieler ein neues Puzzle erstellen. Es gibt 2 verschiedene Varianten. Der Spieler kann ein vordefiniertes Puzzle aufw"ahlen, oder kann selber das Bild und Anzahl Teile bestimmen: In einem Textfeld werden Namen des Bildes angegeben und Anzahl Teile. (z.b. \emph{hello\_world.gif}, das Bild muss sich im Ordner image befinden). Alle Bildformate k"onnen ausgew"ahlt werden, die von der Klasse ESDL\_BITMAP\_FACTORY unterst"utzt werden. Die Informationen, die dort angegeben werden, werden als Strings an das PUZZLE\_START\_WINDOW weitergeleitet. Dort wird das ganze Puzzle kreiert und initialisiert. (alle .ogg files im Ordner sound werden per default abgespielt)
%%\vspace*{1cm}

\subsection{Resume Game}
Wenn der Spieler aus dem play window gegangen ist, kann er mit dieser Auswahl das angefangene Spiel fortsetzen. Dabei wird die vorher kreierte Scene einfach durch das Menu weitergereicht, um den Spielstand im Hintergrund zu sichern (siehe: Umgehen mit verschiedenen Szenen).
%%\vspace*{1cm}

\subsection{Save Game}
Hier hat der User die M"oglichkeit ein bereits angefangenes Puzzle zu speichern, um ein andermal weiterspielen zu k"onnen. Implementiert wurde dies etwa so:\\
Man das PSW dem UC\_INTERFACE "ubergeben (siehe: Umgehen mit verschiedenen Szenen). Dann wird dieses jedoch bei Klick auf Save\_game weitergereicht an die Klasse Save\_game, wo das Puzzlebild und die Anzahl Puzzleteile in ein Textfile geschrieben werden (aus PSW extrahiert). Dies reicht, da ein cutter ein bestimmtes Bild mit einer bestimmten Anzahl Teilen immer gleich cuttet, somit sind auch die puzzle\_parts immer die gleichen. Was aber zu speichern ist: welche puzzle\_part\_views in welchen Workspaces liegen und welche Eigenschaften sie haben (locked, orientation, x, y, zugeh"origes puzzle\_part). Deshalb wird jeder Workspace via Loop durchlaufen (ein Workspace ist dabei ein ESDL\_DRAWABLE\_CONTAINER, also eine Liste mit drawables) und von jedem puzzle\_part\_view diese Informationen gespeichert.
%%\vspace*{1cm}

\subsection{Load Game}
Hier hat der User die M"oglichkeit ein bereits gespeichertes Puzzle zu laden und weiterzuspielen. Das Laden wurde folgendermassen implementiert:\\
Zuerst wird vom Textfile Bildname und Anzahl Teile gelesen und via cutter gebastelt. Dann wird jeder workspace wieder zusammengebaut, indem er erst mal komplett kreiert wird von einem puzzle (cutter.last\_puzzle). Dann sind aber alle parts als puzzle\_part\_views drinn, was nicht sein muss. Also wird wipe\_out aufgerufen und alle puzzle\_part\_views wieder rausgeworfen (nur Parameter wie Breite und H"ohe,... sollen gespeichert bleiben). Dann werden alle puzzle\_part\_views im jeweiligen Workspace ausgelesen und kreiert, anschliessend in den workspace gelegt. Sind alle workspaces soweit gemacht, dann wird ein PSW erstellt. Dieses darf aber "ahnlich wie bei Resume Game jetzt nicht einfach inizialize\_scene aufrufen, da sonst alle workspaces wieder "uberschrieben werden. Stattdessen wird eine Funktion initialize\_loaded aufgerufen, welche nur jene funktionen aufruft, die nicht load-spezifisch sind (also z.B. die Menge puzzle\_parts\_in\_row f"ur alle workspaces richtig setzen oder image und Anzahl Teile vom cutter holen, usw). Danach hat existiert ein korrektes PSW, welches dem entspricht, das man abgespeichert hat. Nun wird dieses als last\_scene von UC\_INTERFACE gespeichert und der Rest ist identisch zum resume\_game (siehe: Umgehen mit verschiedenen Szenen).
%%\vspace*{1cm}

\section{Files and Clusters}
\begin{description}
\item[release] eine lauff"ahige kompilierte Version des Projekts mit allen ben"otigten Daten und Bildern
\item[sound] Dies ist der default Ordner, in dem das Programm nach Musik sucht. Ebenfalls befinden sich hier alle Klassen, die etwas mit der Ausgabe des Soundes von UC zu tun haben.
\item[sound$\backslash$applaus] das File applaus im Ordner sound wird abgespielt, wenn das finish\_window ausgel"ost wird, also das Puzzle fertig ist.
\item[image] alle ben"otigten Bilder und Icons, sowie die verwendeten Schriften.
\item[image$\backslash$uc\_logo.png] Bild, das im Menu angezeigt wird
\item[image$\backslash$icon.png] das Applikationsicon das oben links angezeigt wird
\item[cutter] Klassen, die f"ur die Zerlegung der Bilder zust"andig sind
\item[gui\_elements] Klassen, die f"ur die Darstellung des gui ben"otigt werden
\item[model\_view] Klassen die das Puzzle bauen und f"ur die Darstellung der Puzzleteilchen zust"andig sind.
\item[workspace] Klassen, die f"ur einen workspace ben"otigt werden
\item[menus] Klassen, welche die verschiedenen Menus des Spiels erstellen
\item[ise.ace] Das File ise.ace wird ben"otigt um in Eiffel das ganze zu kompilieren. Dieses .ace-File ist f"ur die Windows-Plattform. Um ein .ace-File f"ur eine andere Version zu erhalten, benutze man \emph{geant install}. Die f"ur diesen Befehl notwendigen Files befinden sich ebenfalls im Ordner. Die GOBO-Tools wurden mit ESDL installiert.
\end{description}
%%\vspace*{1cm}


\section{Spezielle Klassen}
\subsection{TEXT\_FIELD.e}
Diese Klasse ist ein Gui Element und stellt ein Eingabefeld zur Verf"ugung. Klickt man auf dieses Textfeld, so beginnt ein Curser zu blinken. Nun kann der User in dieses Textfeld einen beliebigen String eingeben. Ein Textfeld kann benutzt werden, um die Kommunikation zwischen Spieler und Program zu erm"oglichen. Der im Textfeld angegebene String kann im Program weiterverwendet werden (z.b. als Pfadangabe f"ur das Bild das zu laden ist).

Das Textfeld kann f"ur andere Applikation beliebig verwendet und eingebunden werden. Viele features wie: \emph{set\_font, set\_background\_color, set\_cursor\_color, set\_border\_color, set\_border\_width, set\_width, set\_curser\_blinkrate}, \ldots bieten die M"oglichkeit diese Textfeld speziell anzupassen und in eine grafische (ESDL) Applikation einzubinden.
%%\vspace*{1cm}

\subsection{BUTTON.e}
Die Klasse BUTTON.e stellt ein Gui Element Button zur Verf"ugung. Wenn der Spieler auf so einen Button klickt, so kann dadurch ein bestimmtes Ereignis ausgel"ost werden. Wenn der Spieler den Button mit der Maus "uberf"ahrt, so "andert sich seine Farbe. Seine Farbe "andert sich abermals, wenn auf den Button geklickt wird. Der Button kann ebenfalls `aktiviert' werden, dann er wieder eine andere Farbe.

Diese Klasse kann f"ur andere Projekte angepasst und weiterverwendet werden. Mit features wie: \emph{set\_width, set\_height, set\_vertical\_margin, set\_horizontal\_margin, set\_name, set\_normal\_color, set\_prelight\_color, set\_highlight\_color, set\_border\_color, set\_icon, set\_font, set\_corners\_roundes, set\_border\_width}, und weitere, hat man viele M"oglichkeiten einen Button nach belieben anzupassen und in seine graphische Applikation (ESDL) einzubinden.

In unserem Projekt wurde diese Klasse verwendet um den Music Player zus"atzlich mit der Maus steuern zu k"onnen. Ebenfalls haben wir sie gebraucht um die Steuerung der verschiedenen Workspaces zur Verf"ugung zu stellen.

Um die Buttons gut zu animieren ist es von Vorteil in deren Icons transparenten Hintergrund zu haben.
%%\vspace*{1cm}

\subsection{MUSIC\_PLAYER.e}
Diese Klasse stellt einen kompletten Musik Player zur Verf"ugung. Der Musik Player bietet folgende Funktionen: (nachdem er initialisiert wurde: make liest das default sound directory aus und initialisiert den musictrack / nach dem auslesen des sound directories existiert ein container sound\_container, in dem alle abspielbaren Files drin sind)
\begin{itemize}
\item \emph{play} "offnet den aktuellen song und spielt ihn ab
\item \emph{stop} stoppt den player
\item \emph{pause} pausiert den player oder beginnt wieder an der pausierten Stelle zu spielen (falls schon pausiert)
\item \emph{next} spielt den n"achsten song ab
\item \emph{previous} spielt den vorherigen song ab
\item \emph{set\_volume} setzt die Lautst"arke
\item \emph{turn\_up} erh"oht die Lautst"arke um 10
\item \emph{turn\_down} senkt die Lautst"arke um 10
\item \emph{set\_sound\_dir (a\_string: STRING)} setzt ein neues sound directory und liest dieses gleich aus
\item \emph{next\_song} gibt den String des n"achsten songs zur"uck
\item \emph{previous\_song} gibt den String des letzten songs zur"uck
\item \emph{set\_event\_loop (an\_ev\_loop: ESDL\_EVENT\_LOOP)} setzt das Ereiegnis check next auf den event\_loop. Dies wird ben"otigt, um zu "uberpr"ufen, ob das Lied fertig ist. Falls ja, wird automatisch das n"achste abgespielt.
\item \emph{mute} setzt die Lautst"arke auf 0, das Lied spielt aber weiter.
\item diverse status checks (is\_playing, is\_stopped, is\_paused, volume, ...)
\item \emph{song\_title} gibt den gesamten String zur"uck des spielenden Liedes.
\item \emph{song\_title\_cut} gibt den String des Liedes zur"uck ohne Endung und sound directory
\item ...
\end{itemize}
%%\vspace*{1cm}

\subsection{RANDOM\_NUMBER\_GENERATOR.e}
Diese Klasse stellt einige random Funktionen zur Verf"ugung. Sie wird mit der Systemzeit initialisiert (seed) und gibt bei Anforderung immer den n"achsten Zufallswert im verlangten Format (Integer, Integer (mod n), Real, Double, Boolean) zur"uck.
%%\vspace*{1cm}

\subsection{UC\_SHARED\_ITEMS.e}
Viele Klassen unsers Projekts erben von UC\_SHARED\_ITEMS.e. Diese Klasse wurde entwickelt, um auf immer wieder gebrauchte Objekte Zugriff zu haben und damit diese nicht wieder erstellt werden m"ussen. Um die Klasse zu instanzieren werden viele Variablen mit \emph{once} einmal kreiert.
%\vspace*{1cm}

\section{Patterns}
Bei der Entwicklung unseres Projekt verwendeten wir verschiedene Patterns:
\subsection{mvc-pattern}
Das Model-View-Controller-Pattern findet sich in der Implementation der Puzzle-Teilchen. Es gibt einerseits die Klasse puzzle\_part und andererseits die Klasse puzzle\_part\_view. 

Die puzzle\_parts stellen das Modell des Puzzle-Teilchens zur Verf"ugung. Insbesondere bieten sie die rotierten Ansichten des Teilchens an und kennen ihren Platz innerhalb des Puzzles.

Die puzzle\_part\_views dagegen wissen, wo auf dem Screen sie dargestellt werden und welche Rotation gerade aktuell ist. Anfragen "uber die korrekte Position werden an das puzzle\_part weitergereicht und um die Abfrage der Korrekten Rotation erg"anzt.

Es kann mehrere views auf das selbe Teilchen geben, dadurch kann auch Speicherplatz gespart werden. 

Das Pattern konnte nicht konsequent umgesetzt werden, da die views die \emph{draw}-Funktion ebenfalls an das Teilchen weitergeben wird. Somit in diesem Moment die Position auch dem Teilchen selbst bekannt sein muss, damit es sich  richtig auf eine Oberfl"ache zeichnen kann. Ebenfalls bei der Abfrage der korrekten Position muss dem Teilchen seine Position auf der Oberfl"ache bekannt sein.

Trotzdem halten wir das Pattern f"ur gerechtfertigt, insbesondere, da ein Teilchen ja in mehreren Workspaces angezeigt werden kann und daf"ur nur das view kopiert werden muss und nicht das Teilchen selbst.

%%\vspace*{1cm}

\subsection{observer-pattern}
Das observer-Pattern findet durch das ganze Spiel Anwendung. Die von ESDL zur Verf"ugung gestellten Events werden genutzt um entsprechende Handlungen auszuf"uhren.

%%\vspace*{1cm}


\subsection{command-pattern}
Die Behandlung des key-down-events kann als Anwendung des command-Patterns betrachtet werden. Der User fordert eine Aktion an und der erste Agent versucht herauszufinden, welchem weiteren Agent er diese Anforderung weitergeben kann.

%%\vspace*{1cm}
\subsection{abstract-factory-pattern}
Die cutter-Klasse ist als eine Factory implementiert. Man benutzt Singleton-Access auf diese Factory und erstellt damit seine Puzzle-Teilchen. Diese Implementation sollte es erm"oglichen ohne Probleme eine weitere Art von Puzzle-Teilchen (z.B. Teilchen mit anderem Rand) zu erzeugen, die genau gleich verwendet werden k"onnen.

%\vspace*{1cm}


\section{Umgehen mit verschiedenen Szenen}
Das Problem beim Resume war ja in erster Linie, das vorhandene PUZZLE\_START\_WINDOW - wenn man zur"uck ins menu geht - irgendwie mitzuf"uhren. Da PSW eine erweiterte SCENE ist (unter anderem), wird einfach ein PauseMenu aufgerufen, zuerst aber das PSW als last\_scene von UC\_INTERFACE gespeichert. Wenn man dann im Menu auf resume game geht, wird:
\begin{itemize}
\item der event\_loop vom Menu gestoppt
\item als n"achste Szene wieder das PSW gesetzt
\item der event\_loop von PSW wieder zum laufen gebracht
\item eine boolean Variable is\_initialized auf True gesetzt
\end{itemize}
 
Der 4. Punkt ist deshalb notwendig, weil eine ESDL\_APPLICATION ja eine Szene nach der anderen ausf"uhrt. Wenn ich also als n"achste Szene ein PSW setze, wird automatisch das deferred feature initialize\_scene der betreffenden ESDL\_SCENE ausgef"uhrt. Da initialize\_scene von PSW jedoch alles macht (von Bild schneiden "uber workspaces bilden bis Sound neu abspielen). Deshalb wurde die varuable is\_initialized eingef"uhrt, um so die ben"otigten features neu zu initialisieren (aus irgendeinem Grund m"ussen die Buttons neu initialisiert werden und natrlich alle Events) und den Zustand der restlichen so zu behalten.
%\vspace*{1cm}


\section{Klassen}
\input klassen.tex
% for faster processing
%\vspace*{1cm}

%...
\section{BON-Diagram}
\includegraphics[scale=0.2,angle=90]{uc_bon_diagram_final}
\newpage

\appendix
\input appendix.tex






\end{document}
