\documentclass[10pt,a4paper]{article}
\usepackage{url}
\usepackage{a4wide}
\usepackage{ngerman}
\usepackage[utf8]{inputenc}
\usepackage{tex2page}
\usepackage{ifpdf}

\texonly
\ifpdf
\usepackage[pdftex,colorlinks,backref,pagebackref]{hyperref}
\hypersetup {
  pdftitle={Concurrent Programming --- Toy-Window API-Referenz}
  pdfauthor={Eric Knauel, Michael Sperber}
  colorlinks=true
  \usepackage{thumbpdf} 
}
\fi
\endtexonly

\newcommand{\dtquote}[1]{"`#1"'}

\begin{document}

\title{Toy-Window API Referenz}
\maketitle

\noindent Dieses Dokument beschreibt die API der Implementierung des
ConcurrentML Toy-Window-Systems~\cite{Reppy1999} für Scheme~48 und
Scsh.

\section{Modul \texttt{toy-geometry}}

\begin{itemize}
  
\item\texttt{(make-point x y) => point} 
  
  stellt einen Wert her, der einen Punkt oder einen Vektor
  repräsentiert.  Der Ursprung ist dabei in der oberen linken Ecke,
  die Y-Achse wächst nach unten.
  
\item\texttt{(point+ point1 point2) => point} 
  
  addiert zwei Punkte koordinatenweise.
  
\item\texttt{(point- point1 point2) => point} 
  
  subtrahiert zwei Punkte koordinatenweise.
  
\item\texttt{(point<? point1 point2) => boolean} 
  
  vergleicht zwei Punkte koordinatenweise.
  
\item\texttt{(make-rectangle x y width height) => rectangle}

  stellt einen Wert her, der ein Rechteck repräsentiert.
  
\item\texttt{(rectangle-origin rectangle) => point} 
  
  liefert den Ursprungs des Rechteck.
  
\item\texttt{(rectangle-x rectangle) => int} 
  
  liefert die X-Koordinate des Ursprungs des Rechtecks.
  
\item\texttt{(rectangle-y rectangle) => int} 
  
  liefert die Y-Koordinate des Ursprungs des Rechtecks.
  
\item\texttt{(rectangle-width rectangle) => int} 
  
  liefert die Breite des Rechtecks.
  
\item\texttt{(rectangle-height rectangle) => int} 
  
  liefert die Höhe des Rechtecks.
  
\item\texttt{(point-in-rectangle? point rectangle) => boolean}

  testet, ob ein Punkt innerhalb eines Rechtecks liegt.
  
\item\texttt{(rectangle+ rectangle point) => rectangle} 
  
  liefert ein Rechteck, das gegenüber rectangle um \texttt{point}
  verschoben ist.
  
\item\texttt{(rectangle- rectangle point) => rectangle} 
  
  liefert ein Rechteck, das gegenüber \texttt{rectangle} um
  -\texttt{point} verschoben ist.
  
\item\texttt{(rectangle-within rectangle1 rectangle2) =>
    rectangle} 
  
  liefert ein Rechteck der Größe von \texttt{rectangle2}, das ggf.
  verschoben ist, um so gut wie möglich innerhalb von
  \texttt{rectangle1} zu passen.
\end{itemize}

\section{Modul \texttt{toy-display-system}}

\subsection{Bitmaps}

Ein Parameter mit dem Namen \texttt{raster-op} bezeichnet eine
logische Verknüpfungsoperation zwischen den Pixeln der Quelle und des
Ziels.  Die möglichen Operationen werden durch die Symbole
\texttt{copy}, \texttt{xor}, \texttt{or}, \texttt{and}, \texttt{clear}
und \texttt{set}.

\begin{itemize}
  
\item\texttt{(make-bitmap bitmap rectangle) => bitmap} 
  
  erzeugt eine neue Bitmap auf dem Schirm, die ein Kind von
  \texttt{bitmap} ist und sich im Rechteck \texttt{rectangle} (relativ
  zu \texttt{bitmap}) befindet.  Die Bitmap ist dabei zunächst unter
  den Kindern von \texttt{bitmap} (den \dtquote{Geschwistern}) ganz
  vorn.
  
\item\texttt{(bitmap-to-front! bitmap)} 
  
  rückt \texttt{bitmap} unter den Geschwistern ganz nach vorn.
  
\item\texttt{(bitmap-to-back! bitmap)} 
  
  rückt \texttt{bitmap} unter den Geschwistern ganz nach hinten.
  
\item\texttt{(bitmap-move! bitmap point)} 
  
  verschiebt \texttt{bitmap} (relativ) um \texttt{point}.
  
\item\texttt{(bitmap-delete! bitmap)} 

  löscht die Bitmap \texttt{bitmap}.
  
\item\texttt{(bitmap-clear bitmap)} 

  löscht den Inhalt von \texttt{bitmap}.
  
\item\texttt{(bitmap-draw-line bitmap raster-op point1
    point2)} 

  zeichnet eine Linie von \texttt{point1} nach \texttt{point2}.
  
\item\texttt{(bitmap-draw-rectangle bitmap raster-op rectangle)}
  
  zeichnet ein Rechteck, das gegenüber \texttt{rectangle} nach rechts und
  unten um einen Punkt größer ist.
  
\item\texttt{(bitmap-fill-rectangle bitmap raster-op texture
    rectangle)} 
  
  füllt ein Rechteck der Größe von \texttt{rectangle} mit der Textur
  \texttt{texture}.  Die (für den Moment) einzig sinnvolle Textur ist
  \texttt{texture-solid}.
  
\item\texttt{(bitmap-bitblt bitmap1 raster-op point1 bitmap2
    rectangle1}) 
  
  kopiert ein Rechteck aus \texttt{bitmap1} der Größe von
  \texttt{rectangle1} nach \texttt{bitmap2} an die Stelle
  \texttt{point1}.  Quelle und Ziel werden mit \texttt{raster-op}
  verknüpft.
  
\item\texttt{(bitmap-draw-text bitmap raster-op point text)}
  
  malt den Text \texttt{text} an die Stelle \texttt{point}.  Dabei ist
  \texttt{point} links und auf der Höhe der Basislinie.
  
\item\texttt{(bitmap-text-size bitmap text) => width height
    ascent} 
  
  ermittelt die Größe des Textes \texttt{text}.  Dabei ist
  \texttt{ascent} die Höhe des Textes oberhalb der Basislinie.
\end{itemize}

\subsection{Initialisierung}

\begin{itemize}
  
\item\texttt{(make-display label width height) => bitmap
    mouse-channel keyboard-channel} 
  
  initialisiert das Display-System, erzeugt ein X-Fenster der Breite
  \texttt{width} und der Höhe \texttt{height} mit Titel \texttt{label}
  und liefert eine Bitmap für das gesamte Fenster sowie synchrone
  Kanäle für Maus- und Tastatur-Ereignisse zurück.
\end{itemize}

\subsection{Maus-Messages}

\begin{itemize}
  
\item\texttt{(mouse-message-up? message) => boolean} 
  
  stellt fest, ob der Mausknopf oben ist.
  
\item\texttt{(mouse-message-down? message) => boolean} 
  
  stellt fest, ob der Mausknopf unten ist.
  
\item\texttt{(mouse-message-position message) => point} 
  
  liefert die Position der Maus zurück.
  
\item\texttt{(mouse-message-translate point message) =>
    mouse-message} 
  
  transformiert die Positionskoordinaten von \texttt{message} relativ
  zu \texttt{point}
\end{itemize}


\subsection{Tastatur-Messages}

\begin{itemize}
\item\texttt{(key-message-down? message) => boolean}

  stellt fest, ob die Taste unten ist.

\item\texttt{(key-message-keycode message) => integer}

  liefert den X11-Keycode der Taste.

\item\texttt{(key-message-string message) => string}

  liefert den String für die gedrückte Taste oder einen leeren String
  für Steuertasten.
\end{itemize}

\section{Modul \texttt{toy-window-system}}

\begin{itemize}
  
\item\texttt{(make-widget-env bitmap mouse-channel keyboard-channel
    control-in-channel\\ control-out-channel) => widget-env}
  
  liefert ein Widget-Environment.  \texttt{Control-out-channel} ist
  ein asynchroner Kanal, die restlichen Kanäle sind synchron.
  
\item\texttt{(make-vanilla-widget-env bitmap) => widget-env}

  erzeugt ein Widget-Environment mit frischen Kanälen.
  
\item\texttt{(widget-env-bitmap widget-env) => bitmap} 
  
  liefert die Bitmap eines Widget-Environments.
  
\item\texttt{(widget-env-mouse-channel widget-env) => channel}
  
  liefert den Maus-Kanal eines Widget-Environments.
  
\item\texttt{(widget-env-keyboard-channel widget-env) => channel}

  liefert den Tastatur-Kanal eines Widget-Environments.
  
\item\texttt{(widget-env-control-in-channel widget-env) =>
    channel} 
  
  liefert den Kontroll-Eingangs-Kanal eines Widget-Environments.
  
\item\texttt{(widget-env-control-out-channel widget-env) =>
    async-channel} 
  
  liefert den Kontroll-Ausgangs-Kanal eines Widget-Environments.
  
\item\texttt{(make-channel-sink channel)} 
  
  stellt einen Abfluß für den synchronen Kanal \texttt{channel} her,
  der alle ankommenden Werte abholt und wegwirft.
  
\item\texttt{(realize-widget bitmap rectangle realization-proc) =>
    value }
  
  erzeugt ein frisches Widget-Environment innerhalb der Eltern-Bitmap
  \texttt{bitmap} an Position \texttt{rectangle} und übergibt dieses
  an \texttt{realization-proc}.  Dessen Rückgabewert gibt auch
  \texttt{realize-widget} zurück.
  
\item\texttt{(make-window-system label width height) => widget-env}
  
  initialisiert das Window-System (ruft also \texttt{make-display}
  auf), erzeugt ein initiales Widget-Environment für das gesamte
  Fenster und gibt dieses zurück.

\item\texttt{(control-message? thing) => boolean}
  
  Überprüft ob \texttt{thing} ein Control-Message-Record ist.

\item\texttt{(control-message-type ctrl-msg) => symbol)}
  
  Liefert den Typ einer Kontroll-Nachricht als Symbol zurück.  Da es
  bisher nur einen Typ Kontroll-Nachrichten gibt (für das Löschen
  eines Widgets), gibt diese Funktion immer \texttt{'delete} zurück.

\end{itemize}

\section{Modul \texttt{toy-button}}

\begin{itemize}
  
\item\texttt{(make-button label thunk widget-env) =>
    widget-env} 
  
  stellt innerhalb von \texttt{widget-env} einen Knopf mit
  Beschriftung \texttt{label} her; bei Betätigung wird \texttt{thunk}
  aufgerufen.

\end{itemize}

\section{Modul \texttt{toy-frame}}

\begin{itemize}
  
\item\texttt{(make-frame realize widget-env) => frame value}
  
  malt innerhalb von \texttt{widget-env} einen Rahmen um ein anderes
  Widget, an das es alle Nachrichten weitergibt.  Das andere Widget
  muß von \texttt{realize} erzeugt werden, das als Parameter ein
  eigenes Widget-Environment übergeben bekommt.  Zurückgegeben werden
  ein Wert, der das Frame repräsentiert, sowie der Rückgabewert von
  \texttt{realize}.
\end{itemize}

\bibliographystyle{plain}
\bibliography{toy-window}

\end{document}
