%% LyX 1.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english]{article}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{graphicx}
\usepackage{setspace}

\makeatletter
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
 \newenvironment{lyxcode}
   {\begin{list}{}{
     \setlength{\rightmargin}{\leftmargin}
     \setlength{\listparindent}{0pt}% needed for AMS classes
     \raggedright
     \setlength{\itemsep}{0pt}
     \setlength{\parsep}{0pt}
     \normalfont\ttfamily}%
    \item[]}
   {\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
\usepackage{listings}
\usepackage{xcolor}

% Eiffel Identifiers or expressions
\newcommand{\eid}[1]{\textsl{{\color[HTML]{000000} #1}}}
% Eiffel Class names
\newcommand{\ecl}[1]{\textsl{{\color[HTML]{3333FF} #1}}}
% Eiffel Keywords
\newcommand{\ekey}[1]{\textbf{{\color[HTML]{333399} #1}}}

\lstset{%
language=OOSC2Eiffel,%
basicstyle=\footnotesize,
numbers=none
}

\usepackage{babel}
\makeatother
\begin{document}

\title{elFractal! Programming Tutorial}


\date{September 2006}


\author{Lars Krapf }

\maketitle

\section{Level 1 - Erste Schritte}


\subsection{Zielsetzung}

Am Ende dieses Abschnitts werden wir folgende Dinge gelernt haben:

\begin{itemize}
\item Arbeiten mit EiffelStudio 
\item Kompilieren und Testen einer Applikation
\item Deklaration und Kreation von Widget-Objekten
\item Konfiguration dieser Widgets mittels Featurecalls
\item Behandlung von Ereignissen wie Mausklicks durch Agenten
\item Auch in Schweden gibt es gute Mathematiker!
\end{itemize}

\subsection{Get Ready!}

\begin{itemize}
\item Starte EiffelStudio 5.7
\item Öffne das elFractal! Tutorial Projekt (Pfad: ??)
\item Öffne die Klasse \emph{EF\_SIMPLE\_PANEL} im \emph{elfractal}-Cluster
\end{itemize}

\subsection{Widgets?! WTF?}

Wikipedia meint: 

\begin{quotation}
Das englische Wort \textbf{widget} steht für ein unbestimmtes, namenloses
technisches Produkt und wird in hypothetischen Beispielen als Platzhalter
verwendet. Es handelt sich um eine Wortschöpfung des Co-Autors George
S. Kaufman der Komödie \char`\"{}Beggar on Horseback\char`\"{} aus
dem Jahre 1924. Dem Helden des Stücks, einem Musiker, wird unter der
Voraussetzung, dass er der Musik abschwört, die Leitung einer Firma
angeboten, welche \textbf{Widgets} produziert. Während des sich daraus
für den Helden ergebenden inneren Konflikts, den er als Alptraum (die
eigentliche Handlung des Stücks) durchlebt, wird zu keinem Zeitpunkt
bedeutet, was genau die Firma herstellt. Die Annahme, \textbf{widget}
sei ein modernes Software-technisches Kunstwort aus window (Fenster)
und gadget (Ding, Gerät), ist nicht korrekt.
\end{quotation}
\begin{description}
\item [...]glücklicherweise finden wir aber noch einen link zu Widget (GUI):
\end{description}
\begin{quotation}
Als \textbf{Widgets} (Fensterkontrollelemente) bezeichnet man die
Interaktionselemente oder Steuerelemente in grafischen Benutzeroberflächen.
Zu den am häufigsten genutzten Steuerelementen gehören Schaltflächen
und Bildlaufleiste. Daneben gibt es eine Vielzahl mehr oder minder
häufig genutzter Steuerelemente.
\end{quotation}
Ok.. Die wollen wir!


\subsection{Ein erstes Widget}

Du findest den Klassentext von EF\_SIMPLE\_PANEL unten. Nun wollen
wir dieses (noch) leere Panel endlich mit Widgets bevölkern.

\begin{lstlisting}[language=OOSC2Eiffel, escapechar=\%, numbers=left]

class

        EF_SIMPLE_PANEL

inherit

        EM_PANEL

        EM_SHARED_THEME

                export {NONE} all end

create

        make

feature -- Initialization

        make(a_display: EF_3D_DISPLAY; a_history: EF_HISTORY) is

                require

                        a_display: a_display /= Void

                do

                        -- Initialize Panel

                        panel_view := a_display

                        panel_history := a_history

                        make_from_dimension(200,570)

                        set_background_color(create {EM_COLOR}.make_with_rgb(225,225,225))

                        --- ### Hier Programmcode für zusätzliche Widgets einfügen (1.4 - 1.8)

                ensure

                        panel_s_not_void: panel_view /= Void and panel_history /= Void

                end

feature -- Widgets

        -- A reference to the 3d panel

        panel_view: EF_3D_DISPLAY

       -- A reference to the history panel

        panel_history: EF_HISTORY

       -- Ein Textbox Widget

        textbox_system: EM_TEXTBOX

       -- ### Hier zusätzliche Widgets deklarieren... (1.4 - 1.8)

feature {NONE} -- Implementation

        compile_event(an_event: EM_MOUSEBUTTON_EVENT) is

                        -- Compile Button has been clicked

                do

                        compile

                end



...

\end{lstlisting}Wir wollen eine Texteingabebox erstellen. Eine solche Klasse gibt
es schon (\emph{EM\_TEXTBOX}). Wir müssen dem Compiler nun zuerst
mitteilen, dass wir gerne ein Objekt dieses Typ verwenden würden,
und bei welchem Namen wir es nennen (Deklaration). Der entsprechende
Programmcode ist schon vorbereitet, wir finden ihn unter den Features
\emph{Widgets} unter dem schönen Namen \emph{textbox\_system}.\\
\includegraphics{textbox.eps}\\
Um dieses Objekt zu erstellen, fügen wir an der markierten Stelle
im Feature \emph{make} folgenden Programmcode hinzu:

\begin{lyxcode}
create~textbox\_system.make\_from\_size(18)
\end{lyxcode}
Das Schlüsselwort \emph{create} weist den Compiler an ein neues Objekt
zu erstellen, die Methode \emph{make\_from\_size} ist eine Creation-Methode
aus \emph{EM\_TEXTBOX} und definiert die Grösse des Eingabefelds:
18 Zeichen.\\
Jetzt fügen wir diese Eingabebox zu unserem Panel hinzu. Das geschieht
mit dem einfachen Befehl:

\begin{lyxcode}
add\_widget(textbox\_system)
\end{lyxcode}
Zeit für einen ersten Test. Wir kompilieren die Applikation (Shortcut:
\emph{F7}) und führen sie aus (Shortcut: \emph{F5}), und - oh Wunder
- unsere Textbox erscheint in der linken, oberen Ecke des Menupanels.\\
Dort wollen wir sie allerdings nicht haben. Wir nutzen die Methode
\emph{set\_position} aus \emph{EM\_COMPONENT} (einer Elternklasse
von \emph{EM\_TEXTBOX}) um sie zu positionieren:

\begin{lyxcode}
textbox\_system.set\_position(33,260)
\end{lyxcode}
Speichern, kompilieren, ausführen. Et Voilà!


\subsection{Ein Widget kommt selten allein...}

Diese Eingabebox fühlt sich nun nicht nur einsam, sie ist so auch
noch vollkommen sinnlos. Das wollen wir natürlich schleunigst ändern,
und spendieren unserer Applikation einen Button.\\
Wir müssen also ein Button-Objekt (\emph{EM\_BUTTON})

\begin{itemize}
\item deklarieren
\item erstellen
\item konfigurieren
\item zum Panel hinzufügen
\end{itemize}
Dies funktioniert analog zu der Texbox im letzten Abschnitt.\\
\includegraphics{button.eps}

Die zu verwendende Creation-Methode heisst \emph{make\_from\_text}
und nimmt als Argument den Anzeigetext des Buttons, einen \emph{STRING}
(eine Zeichenkette), den wir, wie in den meisten Programmiersprachen,
\emph{}in Anführungsstriche setzen. 

\begin{lyxcode}
make\_from\_text({}``Mein~Button'')
\end{lyxcode}
Der Text auf dem Button soll {}``compile'' lauten, und die gewünschten
Koordinaten für den Button sind: \emph{(133,283)}.\\
Wir dürfen nicht vergessen, den Button mittels \emph{add\_widget}
zum Panel hinzuzufügen. Danach ist die Bühne frei für \emph{F7-F5},
mit unserem frischgebackenen Button in der Hauptrolle.


\subsection{Uuuund.. Action!}

Ein Button wär kein Button, würde nicht etwas Spannendes geschehen,
wenn man ihn drückt. Wir müssen also festlegen welche Methode, im
Falle des Ereignisses {}``Mausklick'' (\emph{mouse\_clicked\_event),}
ausgeführt werden soll. In Eiffel tragen wir dazu diese Methode in
die Liste jener ein, die von diesem bestimmten Ereignis informiert
werden wollen (\emph{subscribe}).

\begin{lyxcode}
button\_compile.mouse\_clicked\_event.subscribe(agent~compile\_event)
\end{lyxcode}
\emph{button\_compile} ist dabei der Name, den wir im letzen Abschnitt
für den Button gewählt haben. \emph{agent} ist ein Schlüsselwort,
welches dem Compiler mitteilt, dass das Argument (\emph{compile\_event})
ein Feature ist. Dieses Feature ist in \emph{EF\_SIMPLE\_PANEL} schon
vorhanden, etwas weiter unten im Programmcode. Was es genau tut, können
wir nun ausprobieren. Wir kompilieren und starten das Programm, schreiben
in das Eingabefeld \emph{FLFRRFLF} und drücken den Button. Ohhh...
Was geschieht hier?\\
Wir übergeben dem \emph{panel\_view} den Inhalt unseres Eingabefelds,
und führen dessen Methode \emph{create\_script} aus. \emph{panel\_view}
ist ein \emph{EF\_3D\_PANEL}, und verantwortlich für den Inhalt des
3D-Fensters auf der rechten Seite. Dieses versteht unsere kryptische
Eingabe als die rekursive Definition \emph{F := FLFRRFLF}. Dabei steht

\begin{itemize}
\item \emph{F} für einen einfachen Schritt
\item \emph{L} Drehung nach links
\item \emph{R} Drehung nach rechts
\item \emph{U} Drehung nach oben
\item \emph{D} Drehung nach unten 
\item \emph{{[}} Speichern von Position und Richtung
\item \emph{{]}} Wiederherstellen der gespeicherten Werte
\end{itemize}
Wir testen natürlich gleich auch wildere Definitionen, wie etwa: \emph{F
:= {[}LF{]}DF{[}RF{]}F{[}DDF{]}FR{[}UF{]}.}


\subsection{Rekursiv?}

Wenn wir gemäss der obenstehenden Definition \emph{F} das Wort \emph{FLFRRFLF}
zuweisen, und eben dieses neue \emph{F} auf der rechten Seite wieder
einsetzen erhalten wir eine neue Definition:

\begin{flushleft}\emph{F := FFLFRRFLFLFFLFRRFLFRRFFLFRRFLFLFFLFRRFLF.}\end{flushleft}

\begin{flushleft}Noch einmal?\end{flushleft}

\begin{singlespace}
\begin{flushleft}\emph{F := FLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLFLFLFRRFL}\end{flushleft}

\begin{flushleft}\emph{FLFLFRRFLFRRFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFL}\end{flushleft}

\begin{flushleft}\emph{FRRFLFRRFLFLFLFRRFLFLFLFRRFLFLFLFRRFLFRRFLFRRFL}\end{flushleft}

\begin{flushleft}\emph{FLFLFRRFLFLFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLF}\end{flushleft}

\begin{flushleft}\emph{LFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLFRRFLFRRFLF}\end{flushleft}

\begin{flushleft}\emph{LFLFRRFLFRRFLFRRFLFLFLFRRFLFLFLFRRFLFLFLFRRFLFR}\end{flushleft}

\begin{flushleft}\emph{RFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLFRRFLFRRFLF}\end{flushleft}

\begin{flushleft}\emph{LFLFRRFLFLFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLFR}\end{flushleft}

\begin{flushleft}\emph{RFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLFLFLFRRFLFL}\end{flushleft}

\begin{flushleft}\emph{FLFRRFLFRRFLFRRFLFLFLFRRFLFLFLFRRFLFLFLFRRFLFRR}\end{flushleft}

\begin{flushleft}\emph{FLFRRFLFLFLFRRFLFLFLFRRFLFLFLFRRFLFRRFLFRRFLFLF}\end{flushleft}

\begin{flushleft}\emph{LFRRFLFRRFLFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLFLF}\end{flushleft}

\begin{flushleft}\emph{LFRRFLFLFLFRRFLFRRFLFRRFLFLFLFRRFLF}\textcompwordmark{}.\end{flushleft}
\end{singlespace}

\begin{flushleft}NOCH einmal?\end{flushleft}

\begin{flushleft}Nein! Wir ersparen uns diese 152916 Zeichen, und
wollen lieber wissen, wie das aussieht, wenn wir es zeichnen.\\
Wir können in \emph{panel\_view} die gewünschte Anzahl solcher Schritte
(Iterationen) setzen. Im Feature \emph{compile} finden wir dazu die
verdächtige Zeile\end{flushleft}

\begin{lyxcode}
panel\_view.set\_iterations(0)
\end{lyxcode}
Unser Programmiererherz schlägt schneller, wir müssen dort 4 eintragen!
Ungeduldig kompilieren wir danach das Programm.. starten es.. und
sehen... die berühmte Kochkurve! (Benannt nach dem netten, schwedischen
Mathematiker Helge von Koch).\\
\includegraphics{koch.eps}


\subsection{Benutzerkomfort}

Natürlich können wir nicht von jedem der unser Programm nutzen will,
derartige H4x0rsk1llz erwarten, deshalb sorgen wir nun noch für etwas
Benutzerkomfort. Wir wollen die Applikation um einen Schieberegler
(\emph{EM\_SLIDER}) und ein Dropdown-Menu mit Beispielen (\emph{EM\_COMBOBOX})
erweitern.\\
\includegraphics{iteration_slider.eps} \\
\includegraphics{combobox.eps}\\
Hier die Anforderungen an diese beiden Widgets:

\begin{itemize}
\item Der Schieberegler soll Werte zwischen 0 und 8 annehmen können (\emph{make\_from\_range\_horizontal})
\item Er soll 110 Pixel breit sein (\emph{set\_width}), und an der Position
(\emph{80,230}) erscheinen.
\item Im Feature \emph{compile} soll anstatt des festen Iterationswerts,
derjenige des Schiebereglers übernommen werden. (\emph{current\_value})
\item Das Beispielmenu hat die Koordinaten (\emph{10,30}) und die Dimension
\emph{(180,20}). (\emph{set\_dimension})
\item Bei unserer Combobox ist folgendes zu beachten: Die Klasse \emph{EM\_COMBOBOX}
ist generisch implementiert. Das heisst sie funktioniert nicht nur
für Zeichenketten, sondern auch für andere Arten von Objekten (z.B.
\emph{INTEGER}). Für uns bedeutet das, dass wir bei der Deklaration
angeben müssen, von welchem Typ die Objekte unseres Dropdown-Menus
sind. Dies geschieht mit folgender Syntax: 
\end{itemize}
\begin{lyxcode}
list\_examples:~EM\_COMBOBOX~{[}STRING{]}
\end{lyxcode}
\begin{itemize}
\item Mittels dem Feature \emph{put} aus \emph{EM\_COMBOBOX}, können wir
diese Liste um einige Beispiele erweitern. z.B.: \emph{list\_examples.put({}``F{[}LF{]}{[}RF{]}{[}UF{]}{[}DF{]}F'')}
\item Im Falle des \emph{selection\_changed\_event} soll das Feature \emph{change\_example}
aufgerufen werden.
\end{itemize}
Das Gerüst von \emph{change\_example} ist bereits vorhanden, folgende
Dinge müssen wir allerdings noch implementieren:

\begin{itemize}
\item Der Inhalt des Texteingabefelds soll auf den ausgewählten String gesetzt
werden. Dieser wird \emph{change\_example} als Argument übergeben
und heisst \emph{example\_string}.
\item Der Schieberegler soll auf den Wert 4 zurückgesetzt werden. 
\item Das Feature \emph{compile} soll aufgerufen werden um das Beispiel
gleich darzustellen.
\end{itemize}
Nun fehlen nur noch ein paar Labels (\emph{EM\_LABEL}), da die verwendeten
Widgets nicht unbedingt selbsterklärend sind:

\begin{itemize}
\item {}``F := {}`` vor der Eingabebox
\item {}``Iterations: {}`` oberhalb des Schiebereglers
\item {}``Examples: {}`` oberhalb des Beispielmenus
\end{itemize}

\subsection{Zieleinfahrt}

Die erste Etappe haben wir (mit Koffein statt EPO) bravourös hinter
uns gebracht. Wir fühlen uns mittlerweile in EiffelStudio wie zuhause.
Wir haben gelernt Objekte zu deklarieren und zu erstellen. Wir haben
Features dieser Objekte verwendet um sie zu konfigurieren, und von
ihnen ausgelöste Ereignisse abzufangen und zu verarbeiten (\emph{Eventhandling}).\\
Unsere erste Eiffel-Applikation steht, und sorgt für Stunden entspannter
Familienunterhaltung in langen Winternächten. \\
Nur - wir sind Programmierer, süchtig nach dem Einbau neuer, extravaganter
Features! Wir wollen uns also auf unseren Lorbeeren nicht lange ausruhen,
holen uns einen neuen Kaffee, und widmen uns dem nächsten Schritt.


\section{Level 2 - Implementierung einer History}
\end{document}
