% Appendix to UC developer guide

\chapter{Appendix}

\section{Vergleich zum SRS}
In diesem Abschnitt vergleichen wir die Ziele, die wir uns im SRS gesteckt haben, mit dem Endprodukt. Es folgt eine Liste mit Punkten, die genau so umgesetzt wurden, wie sie im SRS standen. Danach folgt eine Liste mit Punkten, die "uberhaupt nicht, oder nicht so wie im SRS vorgesehen, umgesetzt wurden.

\subsection{erreichte Punkte}

\subsubsection{Benutzeroberfl"ache}
\begin{description}
\item [Arbeitsfl"achen:] Die Arbeitsfl"achen wurden wie im SRS vorgesehen umgesetzt. Der Arbeitsfl"ache {\bf AA} entspricht der Workspace 0. Leider kamen wir nichtmehr dazu eine Suchfunktion zu implementieren und daher macht es auch keinen Sinn, dass der Spieler die Workspaces selbst benennen kann. Infolge Platzmangels (zuwenig Platz f"ur die Buttons) haben wir die Anzahl der Workspaces auf drei beschr"ankt.
\item [Spielfl"ache:] Die Spielfl"ache wurde wie im SRS vorgesehen umgesetzt. Man kann ein Puzzle-Teil aus einem Workspace in die Spielfl"ache ziehen. Falls das Puzzle-Teil am richtigen Ort ist, bleibt es dort liegen, ansonsten springt es zur"uck in den Workspace.
\item [Gamemenu:] Das Gamemenu beinhaltet die Funktionen, welche im SRS vorgesehen waren. Zudem haben wir noch vier weitere Funktionen hinzugef"ugt. Die ``neuen'' Funktionen sind Resume Game, Load Game, Save Game, Credits. Die Funktion Resume Game bewirkt, dass man zur"uck ins Spiel gelangt, aus dem heraus man mit der Taste ESC das Menu aufgerufen hat. Die Funktion Load Game erm"oglicht es ein zuvor gespeichertes Puzzle-Spiel zu laden und daran weiterzuspielen. Die Funktion Save Game erm"oglicht es das laufende Puzzle-Spiel zu speichern. Die Funktion Credits wechselt zu einem Bildschirm, in dem die Namen der Entwickler des Spiels, sowie Danksagungen an verschiedene Personen die in irgendeiner Weise an der Produktion des Spiels beteiligt waren, angezeigt werden. Wir mussten feststellen, dass es fu"r die Funktion Options keine Verwendung im Gamemenu gibt, da es von der Userseite her keine Einstellungen zu machen gibt.
\end{description}

\subsubsection{Funktionen}
\begin{description}
\item [Speichern / Laden:] Die Funktionen Speichern und Laden wurden, bis auf das Schnellspeichern mittels dr"ucken der Tasten Ctrl + S w"ahrend des spielens, wie im SRS vorgesehen umgesetzt.
\item [Teile drehen:] Die Funktion Teile drehen zu k"onnen wurde wie im SRS beschreiben umgesetzt.
\item [Maussteuerung:] Wie im SRS vorgesehen ist das gesamte Spiel mit der Maus steuerbar.
\item [Hintergrundmusik:] Abgesehen davon, dass der Spieler seine Musik nicht im Menu unter Optionen angeben kann, haben wir die Idee der Hintergrundmusik welche w"ahrend dem Spielen ert"ont wie im SRS beschrieben umgesetzt. Zus"atzlich zum im SRS beschriebenen Button zum ein und ausschalten der Musik, haben wir noch eine Playersteuerung eingebaut, die entweder mit der Tastatur oder mit der Maus bedient werden kann.
\item [Hilfefunktion:] Die Hilfefunktion wurde nicht exakt wie im SRS vorgesehen umgesetzt, ist aber immerhin vorhanden. Es gibt zwei Abweichungen vom SRS im Zusammenhang mit dieser Funktion. Erstens ist die Funktion nicht auf eine bestimmte Anzahl Benutzungen beschr"ankt. Zweitens wird diese Funktion mit der Taste c (anstatt Ctrl + h) oder dem entsprechenden Button ausgel"ost.
\end{description}

\subsubsection{Spielmodis}
\begin{description}
\item [Quadrat-Modus] Den Quadrat-Modus haben wir wie im SRS beschriben umgesetzt. Der Spieler kann selbst angeben in wieviele quadratische Teile das Bild zerschnitten werden soll. Zus"atzlich kann der Spieler auch selbst das Bild w"ahlen welches er zerschneiden und zusammensetzen m"ochte.
\end{description}

\subsection{nicht erreichte Punkte}

\subsubsection{Benutzeroberfl"ache}
\begin{description}
\item [Menubar:] Das einzige Element der Menubar, das wir umgesetzt haben ist der Button zum aus- bzw. einschalten der Hintergrundmusik. Da wir keine Suchfunktion implementiert haben, ist die Menubar "uberfl"ussig geworden.
\item [Hauptarbeitsfl"ache:] Etwas wie die Hauptarbeitsfl"ache gibt es in unserer Implementation nicht, da diese ohne Suchfunktion keinen Nutzen hat.
\end{description}

\subsubsection{Funktionen}
\begin{description}
\item [Scrollfunktion:] Wir haben keine Scrollfunktion implementiert, da wir keine Zeit mehr hatten. Falls nun zuviele Puzzle-Teile vorhanden sind um alle im Workspace anzuzeigen werden sie "uber den Workspce hinaus gezeichnet.
\item [Suchfunktion:] Wir haben keine Suchfunktion implementiert, da wir keine Zeit dazu hatten. Zudem ist die Suchfunktion f"ur quadratische Puzzle-Teile nicht so wichtig wie f"ur Puzzle-Teile mit K"opfen.
\end{description}

\subsubsection{Spielmodis}
\begin{description}
\item [ETH-Modus:] Der ETH-Modus so wie er im SRS beschrieben wurde existiert in unserer Implementation nicht. Es gibt verschiedene predefined Modi, welche im Zusammenhang mit der 150-Jahr-Feier der ETH stehen.
\item [Kopf-Modus:] Der Kopf-Modus ist schwieriger zu implementieren als der Quadrat-Modus. Deshalb haben wir mit der Implementation des Quadrat-Modus begonnen. F"ur den Kopf-Modus blieb uns keine Zeit mehr.
\end{description}

\subsection{Fazit}
Dass wir die Spezifikationen aus dem SRS nicht vollst"andig umzusetzten vermochten, liegt einerseits sicherlich daran, dass wir beim Schreiben des SRS noch keine Ahnung von ESDL hatten. Andererseits ist es unm"oglich alle Schwierigkeiten (programmiertechnischer oder designspezifischer Art) vorherzusehen. Dadurch haben wir uns beim Schreiben des SRS, was den Aufwand und somit die ben"otigte Zeit angeht, schlichtweg "ubersch"atzt.
\vspace*{1cm}

\section{Entwicklung des Projekts}
Das Projekt UC - Under Construction wurde im Rahmen der Software Architecture Vorlesung (Bertrand Meyer) im Sommersemester 2005 in einem knapp gehaltenen Zeitfenster entwickelt.
\subsection{Entwicklungsumgebung}
Als Entwicklungsumgebung wurde Eiffel55 und ESDL verwendet (siehe Installation). Unter Linux funktionierte zwar Eiffel korrekt, jedoch konnten wir ESDL (nach langem Basteln) immer noch nicht zum Laufen bringen. EWG und GOBO konnten problemlos installiert werden. Bei SDL mussten auch diverse Libraries hinzugef"ugt werden (siehe ESDL developer.txt). Beim kompilieren der ESDL  libraries traten dann aber Fehler auf, die ich nicht beseitigen konnte. Deshalb entwickelten wir ausschliesslich unter Windows. Es w"are aber theoretisch m"oglich ESDL unter Linux zu installieren (das haupts"achliche Problem lag, so glaube ich, dass die Umgebungsvariablen nicht korrekt gesetzt wurden, was unterdessen aber wahrscheinlich klar geworden ist). 

Damit wir gemeinsam an unserem Projekt arbeiten konnten, benutzten wir das in der Vorlesung vorgeschlagene CVS System. Teilweise direkt in der Konsole ausgef"uhrt, andererseits gibt es auf der Entwicklungsplattform Eclipse auch eine nette CVS Funkton, mit der man das Projekt verwalten konnte. Zum Teil kamen auch andere graphische Front-Ends zum Einsatz.

\subsection{Start}
Nachdem wir unsere Idee ein wenig diskutiert hatten, entwickelten wir nach Vorgabe aus der Vorlesung unser SRS (Software Requirement Specifications, siehe srs.pdf). Nachdem die Installation von ESDL geklappt hatte (Windows) begannen wir mit dem Arbeiten an unserem Projekt. Ein von uns erstelltes BON-Diagram (uc\_bon\_diagram.png) sollte uns graphisch aufzeigen wie in etwa welche Klassen ben"otigt werden und wie diese Klassen aufgebaut sind.

Danach begannen wir einzeln an gewissen Teilen zu arbeiten. 

\subsection{Arbeitsverteilung}
Eine genaue Arbeitsverteilung gab es zun"achst nicht. Jeder arbeitete gerade an einem Teil, der ihm Spass machte. Derjenige war dann aber auch daf"ur verantwortlich dass sein Teil gut in das ganze System passte und funktionierte. Irgendwie ging dieses Schema bis jetzt gut auf. Alle haben viel am Projekt gearbeitet, jeder hat eine Ahnung was der andere gemacht hat und was dessen Klassen so grob f"ur Funktionen bereitstellen. 

\subsection{Probleme}
Im Laufe des Projekts traten auch einige Probleme auf. Bei der Diskussion, wie wir unser Puzzle programmieren stiessen wir schon auf einige Probleme. Wir wussten nicht wie es m"oglich w"are ein Fancy Puzzle zu machen (siehe Weiterentwicklungsm"oglichkeiten - Fancy Puzzle Part). Wir beschlossen zuerst unser Projekt nur f"ur eckige Teile zu machen. Wenn Zeit bleibt kann dann immer noch erweitert werden. Ebenfalls mussten f"ur unser Projekt Buttons und Texteingabefelder entwickelt werden, um die Kommunikation zwischen User und Programm nicht nur auf Tasten zu beschr"anken und damit der User etwas eingeben kann (Textfeld), zum Beispiel das Bild, das er f"ur ein neues Puzzle erstellen will.

Einige Probleme hatten wir auch mit dem CVS. Manchmal kam es vor, dass mehrere Personen an derselben Klasse arbeiteten und es deshalb Konflikte beim commit gab. Dies versuchten wir zu verhindern, indem wir immer wieder besprachen, wer gerade was macht. Nach einem Update im CVS wurde dann gerade ein Mail an das ganze Team geschickt. Das CVS hatte auch diverse Bilder ``verschrottet''. Beim ersten mal hochladen geht nichts schief. Wenn man jedoch ein Bild "andert und dieses commitet, so wird irgendwie von CVS was ins Bild geschrieben und das Bild ist dann kaputt. Also mussten wir immer das Bild l"oschen und dann wieder hinzuf"ugen. W"ahrend dem Arbeiten mit dem CVS haben wir festgestellt, dass man Dateien wie Bilder oder PDF-Dateien als binaries kennzeichnen kann. Solche Dateien werden vom CVS dann nicht ``abge"andert''. Um Dateien als binaries zu kennzeichnen mussten wir jedoch ausschliesslich das CVS-Plugin von Eclipse benutzen, da wir nicht herausgefunden haben wie man dies in der Kommandozeilen-version von CVS tut.

Beim Programmieren mussten wir auch kleine "Anderungen an ESDL vornehmen (siehe diverse hacks), um die gew"unschten Funktionen zu haben.

Im grossen und ganzen kann man aber sagen, dass wir gut zurechtkamen.

\vspace*{1cm}

\section{Testing}
F"ur das Testen bleibt meistens nicht mehr allzu viel Zeit "ubrig. Es k"onnte durchaus sein, dass unser Programm ab und zu mal einen Sch"onheitsfehler beinhalten kann.

Allerdings wurden die geschriebenen Klassen laufend wieder getestet und sollten stabil laufen.
\subsection{Bekannte Bugs}
Diese Liste beinhaltet Fehler, die nach dem Beenden der Programmierphase noch entdeckt wurden, oder Fehler die wir schon w"ahrend dem Programmieren kannten aber nicht beheben konnten.
\begin{itemize}
\item W"ahrend dem spielen werden Teilchen die gedreht wurden durch den Cheaterbutton nicht richtig postitioniert.
\item Beim Drehen eines Teilchens entsteht ein schmaler schwarzer Rand um das gedrehte Teilchen herum.
\item Wenn ein Spiel gespeichert wird und schon ein gespeichertes file existiert crasht das game.
\item Wenn man w"ahrend dem das Preview-Bild (Auge-Button) angezeigt wird das Spiel mit ESC unterbricht und dann im Menu auf resume Game geht, verschwindet das angezeigte Preview-Bild nichtmehr.
\item Wenn man beim User-defined Mode eine negative Anzahl Teilchen angibt, st"urtzt das Programm ab (Fehlermeldung : sqrt: DOMAIN error).
\item Wenn man beim User-definde Mode null als Anzahl Teilchen angibt, st"urtzt das Programm ab.
\item Wenn man w"ahrend dem spielen, w"ahrend dem ein anderer Workspace als der Workspace 0 ausgew"ahlt ist, das Spiel mit ESC unterbricht und dann im Menu resume Game anklickt, wird Workspace 0 als aktiver Workspace markiert (Button ist braun statt gelb) obwohl der Workspace, den man vor dem Spielunterbruch angew"ahlt hatte, noch der aktive Workspace ist.
\item ...
\end{itemize}

\vspace*{1cm}

\section{Weiterentwicklungsm"oglichkeiten}
\subsection{Sound}
Aus unserer anf"anglichen Idee, dass der Spieler im Hintergrund Musik abspielen kann, ist inzwischen ein ganzer Music Player entstanden. Jener kann aber nur .ogg files abspielen. Man k"onnte nun den Player erweitern, auch mp3s oder andere Formate, abzuspielen. Dies kann aber zur"uckgehen bis auf die SDL libraries (siehe ESDL\_MIXER, ESDL\_AUDIO\_CONSTANTS). Wir hatten zuwenig Zeit um uns l"anger damit zu besch"aftigen.
\subsection{Modus}
Urspr"unglich hatten wir im Sinn mehrere Modi zu machen. Wenn der Spieler ein neues Spiel kreiert, dann h"atte er die M"oglichkeit auszuw"ahlen. Der Spieler kann zwar jetzt keine Modi ausw"ahlen, jedoch kann er mit der Einstellung der Anzahl Teilchen die Schwierigkeit bestimmen. Die vordefinierten Einstellungen dienen als Ersatz dieser Funktion.
\subsection{Fancy Puzzle Part}
Im jetztigen UC gibt es nur viereckige Puzzle Teilchen. Man k"onnte aber auch solche mit K"opfen und L"ocher implementieren. Dazu m"usste man zus"atzlich in einem Puzzle Teilen beim zerschneiden speichern, wo K"opfe, wo L"ocher sind. Um so ein Fancy Teil zu verwirklichen k"onnte man ein Puzzle Teil gr"osser machen und rundherum eine als transparent definierte Farbe nehmen. Oder man l"adt das Puzzle Teil anders und zeichnet vom benachbarten Puzzle Teil noch den Kopf dran. F"ur diese verschiedenen Implementationen (quad, fancy) hatten wir in unserem SRS Klassen vorgesehen, die deferred features besitzen.
\subsection{Join von mehreren Puzzle Teilen}
Uns kam auch die Idee, das man nicht nur auf der Spielfl"ache die Puzzle Teile zusammensetzen k"onnte, sondern auch gerade in einem workspace. W"urden 2 Teile zusammenpassen so w"urden diese einfach zu einem neuen Teil verschmelzen.
\subsection{Scrollfunktionen}
Wenn man sehr viele Teile hat oder grosse Bilder, dann gibt es ein Problem mit der Darstellung. Es k"onnen unm"oglich alle Puzzleteile auf dem Bild dargestellt werden. Eventuell hat auch das Puzzle kein Platz auf dem Screen. Man k"onnte deshalb f"ur die einzelnen Workspaces das Scrollen implementieren. F"ahrt man an einen Rand des workspaces (unten, oben) so bewegt sich der workspace in die gew"unschte Richtung soweit m"oglich.
\subsection{Zoom}
Im Zusammenhang mit den obigen Scrollfunktionen k"onnte man auch Zoom hinzuf"ugen, um grosse Puzzlebilder ganz anzeigen zu k"onnen.
\subsection{Filter / Search}
Man k"onnte einen Filter oder eine Suche einbauen, um die Puzzle Teile zu sortieren. Man k"onnte nach Rand oder Ecken suchen. (bei Fancy Teilen auch nach K"opfen oder L"ocher). Das Resultat der Suche k"onnte man in einem neuen workspace darstellen, oder man k"onnte den Filter direkt auf den workspace anwenden um so die gew"unschten Teile zu erhalten. Ebenso w"are eine Sortierung nach Farbe vorstellbar. Dies w"are jedoch schwierig zu realisieren. Es m"usste irgendwie einen Farbwert aus allen Farbwerten berechnet werden. Die Zuteilung k"onnte eventuell nicht dem entsprechen, was der Spieler von der Zuteilungsfunktion erwartet.

\vspace*{1cm}

\section{Wiederverwendbarkeit}
\subsection{Music-Player}
Die Klasse music\_player.e bietet einen kompletten Player f"ur Musik. Auf Grund der fehlenden Unterst"utzung durch ESDL spielt dieser im Moment ausschliesslich .ogg-Files. Sobald die anderen Formate aber von der Library unterst"utzt werden, kann der Player auch f"ur diese Formate verwendet werden.

Wie man ein Gui f"ur den Player implementieren k"onnte, sieht man im PSW, das einige Buttons f"ur die Steuerung des Players bereitstellt.

\subsection{Gui-Elemente}
Die Klassen button.e und  text\_field.e bieten sehr allgemeine Gui-Elemente an, die problemlos wiederverwendet werden k"onnen und vielseitige Einstellungsm"oglichkeiten bieten. 

\subsection{Zufalls-Generator}
Die Klasse random\_number\_generator.e stellt allgemeine Zufallsfunktionen zur Verf"ugung, welche den Umgang mit dem von der Eiffel-Library zur Verf"ugung gestellten Zufallsgenerator vereinfachen.

\subsection{Mausunterst"utzung im Menu}
Weiterhin wurde die Klasse menu.e vom UC-Team mit Maussteuerung erweitert.

\subsection{Behandlung von Key- und anderen Events}
Die Struktur der Agents zur Behandlung der Events, insbesondere der Key-Events kann f"ur andere Anwendungen einfach angepasst werden. 

\subsection{Weiteres}
Siehe auch \emph{spezielle Klassen}.

\vspace*{1cm}

\section{Special Thanks to}
\begin{itemize}
\item Benno Baugartner for a cool Assistance
\item Sandro Blum for the sound at the presentation (visit: sound.selenic.net)
\end{itemize}
