Dokumentation

Die Listener Methoden haben nun sprechendere Namen.
Sound und Mixer akzeptieren nun auch AudioListener.

src/main/java/schule/ngb/zm/layers/DrawingLayer.java

@@ -66,7 +66,7 @@ public class DrawingLayer extends Layer implements Strokeable, Fillable {
 	private final Stack<schule.ngb.zm.shapes.Text> styleStack;
 
 	/**
-	 * Erstellt eine Ebene in der Standardgröße.
+	 * Erstellt eine Zeichenebene in der Standardgröße.
 	 */
 	public DrawingLayer() {
 		super();
@@ -79,7 +79,7 @@ public class DrawingLayer extends Layer implements Strokeable, Fillable {
 	}
 
 	/**
-	 * Erstellt eine Ebene mit der angegebenen Größe.
+	 * Erstellt eine Zeichenebene mit der angegebenen Größe.
 	 *
 	 * @param width Die Breite der Ebene.
 	 * @param height Die Höhe der Ebene.

src/main/java/schule/ngb/zm/layers/ImageLayer.java

@@ -37,46 +37,90 @@ public class ImageLayer extends Layer {
 	protected boolean redraw = true;
 
 	/**
-	 * Erstellt eine Bildebene aus der angegebenen Bildquelle.
+	 * Erstellt eine Bildebene in der Standardgröße aus der angegebenen
+	 * Bildquelle.
 	 *
 	 * @param source Eine Bildquelle.
+	 * @see ImageLoader#loadImage(String)
 	 */
 	public ImageLayer( String source ) {
 		image = ImageLoader.loadImage(source);
 	}
 
+	/**
+	 * Erstellt eine Bildebene in der Standardgröße aus dem angegebenen Bild.
+	 *
+	 * @param image Ein Bild-Objekt.
+	 */
 	public ImageLayer( Image image ) {
 		this.image = image;
 	}
 
+	/**
+	 * Erstellt eine Bildebene in der angegebenen Größe aus dem angegebenen
+	 * Bild.
+	 *
+	 * @param width Breite der Bildebene.
+	 * @param height Höhe der Bildebene.
+	 * @param image Ein Bild-Objekt.
+	 */
 	public ImageLayer( int width, int height, Image image ) {
 		super(width, height);
 		this.image = image;
 	}
 
+	/**
+	 * Setzt das Bild der Ebene auf das angegebene Bild-Objekt.
+	 *
+	 * @param image Ein Bild-Objekt.
+	 */
 	public void setImage( Image image ) {
 		this.image = image;
 		redraw = true;
 	}
 
+	/**
+	 * @return Die x-Koordinate des Bildes in der Ebene.
+	 */
 	public double getX() {
 		return x;
 	}
 
+	/**
+	 * Setzt die {@code x}-Koordinate des BIldes in der Ebene auf den
+	 * angegebenen Wert.
+	 *
+	 * @param pX Die x-Koordinate des Bildes.
+	 */
 	public void setX( double pX ) {
 		this.x = pX;
 		redraw = true;
 	}
 
+	/**
+	 * @return Die y-Koordinate des Bildes in der Ebene.
+	 */
 	public double getY() {
 		return y;
 	}
 
+	/**
+	 * Setzt die {@code y}-Koordinate des BIldes in der Ebene auf den
+	 * angegebenen Wert.
+	 *
+	 * @param pY Die y-Koordinate des Bildes.
+	 */
 	public void setY( double pY ) {
 		this.y = pY;
 		redraw = true;
 	}
 
+	/**
+	 * Löscht die Ebene und zeichnet das Bild neu.
+	 * <p>
+	 * In der Regel muss die Ebene nicht gelöscht werden, da sie automatisch neu
+	 * gezeichnet wird, sobald sich das zugrundeliegende Bild ändert.
+	 */
 	@Override
 	public void clear() {
 		super.clear();

src/main/java/schule/ngb/zm/layers/ShapesLayer.java

@@ -11,7 +11,7 @@ import java.util.*;
 import java.util.function.DoubleUnaryOperator;
 
 /**
- * Ein Layer um {@link Shape} Objekte zu zeichnen.
+ * Eine Ebene um {@link Shape} Objekte zu zeichnen.
  * <p>
  * Ein {@code ShapesLayer} ist eine der drei Standardebenen der
  * {@link schule.ngb.zm.Zeichenmaschine}.
@@ -19,6 +19,9 @@ import java.util.function.DoubleUnaryOperator;
 @SuppressWarnings( "unused" )
 public class ShapesLayer extends Layer {
 
+	/**
+	 *
+	 */
 	protected boolean clearBeforeDraw = true;
 
 	private final List<Shape> shapes;

src/main/java/schule/ngb/zm/layers/TurtleLayer.java

@@ -12,6 +12,12 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.Stack;
 
+/**
+ * Eine Ebene, auf der eine Turtle gesteuert werden kann, die Grafiken plottet.
+ * <p>
+ * Die Turtle verhält sich ähnlich zu ihren Entsprechungen in Logo oder
+ * TigerJython.
+ */
 @SuppressWarnings( "unused" )
 public class TurtleLayer extends Layer implements Strokeable, Fillable {
 

src/main/java/schule/ngb/zm/media/Audio.java

@@ -80,4 +80,19 @@ public interface Audio {
 	 */
 	void dispose();
 
+	/**
+	 * Fügt dem Medium das angegbene Objekt als {@code AudioListener} hinzu, der
+	 * bei Start und Stopp der Wiedergabe informiert werden soll.
+	 *
+	 * @param listener Das zu informierende Objekt.
+	 */
+	void addAudioListener( AudioListener listener );
+
+	/**
+	 * Entfernt den angegebenen {@code AudioListener} vom Medium.
+	 *
+	 * @param listener Das Listener-Objekt.
+	 */
+	void removeAudioListener( AudioListener listener );
+
 }

src/main/java/schule/ngb/zm/media/AudioListener.java

@@ -2,10 +2,33 @@ package schule.ngb.zm.media;
 
 import schule.ngb.zm.util.events.Listener;
 
+/**
+ * Interface für Klassen, die auf das starten und stoppen der Wiedergabe von
+ * {@link Audio}-Objekten reagieren möchten.
+ * <p>
+ * Implementierende Klassen können sich bei einem Auido-Objekt mittels
+ * {@link Audio#addAudioListener(AudioListener)} anmelden und werden über die
+ * jeweilige Methode informiert, sobald die Wiedergabe gestartet oder gestoppt
+ * wird.
+ */
 public interface AudioListener extends Listener<Audio> {
 
-	void start( Audio source );
+	/**
+	 * Wird aufgerufen, sobald die Wiedergabe eines Audio-Objektes startet, dem
+	 * dieses Objekt mittels {@link Audio#addAudioListener(AudioListener)}
+	 * hinzugefügt wurde.
+	 *
+	 * @param source Das Audio-Objekt, dessen Wiedergabe gestartet wurde.
+	 */
+	void playbackStarted( Audio source );
 
-	void stop( Audio source );
+	/**
+	 * Wird aufgerufen, sobald die Wiedergabe eines Audio-Objektes stoppt, dem
+	 * dieses Objekt mittels {@link Audio#addAudioListener(AudioListener)}
+	 * hinzugefügt wurde.
+	 *
+	 * @param source Das Audio-Objekt, dessen Wiedergabe gestoppt wurde.
+	 */
+	void playbackStopped( Audio source );
 
 }

src/main/java/schule/ngb/zm/media/Mixer.java

@@ -1,9 +1,11 @@
 package schule.ngb.zm.media;
 
 import schule.ngb.zm.Constants;
+import schule.ngb.zm.util.events.EventDispatcher;
 import schule.ngb.zm.util.tasks.TaskRunner;
 
 import java.util.ArrayList;
+import java.util.Iterator;
 import java.util.List;
 
 /**
@@ -18,24 +20,14 @@ import java.util.List;
  * Darüber hinaus kann ein Mixer Effekte wie einen
  * {@link #fade(double, int) fadeIn} auf die Medien anwenden.
  */
-public class Mixer implements Audio {
+@SuppressWarnings( "unused" )
+public class Mixer implements Audio, AudioListener {
 
 	private List<AudioWrapper> audios;
 
 	private float volume = 0.8f;
 
-	class AudioWrapper {
-
-		Audio audio;
-
-		float volumeFactor;
-
-		public AudioWrapper( Audio audio, float volumeFactor ) {
-			this.audio = audio;
-			this.volumeFactor = volumeFactor;
-		}
-
-	}
+	EventDispatcher<Audio, AudioListener> eventDispatcher;
 
 	public Mixer() {
 		this.audios = new ArrayList<>(4);
@@ -45,16 +37,61 @@ public class Mixer implements Audio {
 		return "";
 	}
 
-	public void add( Audio pAudio ) {
-		add(pAudio, 1f);
+	private AudioWrapper findWrapper( Audio pAudio ) {
+		for( AudioWrapper aw: audios ) {
+			if( aw.audio == pAudio ) {
+				return aw;
+			}
+		}
+		return null;
 	}
 
+	public boolean contains( Audio pAudio ) {
+		return findWrapper(pAudio) != null;
+	}
+
+	public void add( Audio pAudio ) {
+		add(pAudio, 1);
+	}
+
+	/**
+	 * Fügt ein Audio-Objekt dem Mixer mit dem angegebenen Lautstärke-Faktor
+	 * hinzu.
+	 * <p>
+	 * Der Lautstärke-Faktor setzt die Lautstärke des Audio-Objektes relativ zur
+	 * Lautstärke des Mixers. Bei einem Faktor von 1.0 wird die Lautstärke des
+	 * Mixers übernommen. Bei einem Wert von 0.5 wird das Objekt halb so laut
+	 * abgespielt. Auf diese Weise lässt sich die Lautstärke aller Audio-Objekte
+	 * des Mixers gleichzeitig anpassen, während ihre relative Lautstärke
+	 * zueinander gleich bleibt.
+	 *
+	 * @param pAudio Ein Audio-Objekt.
+	 * @param pVolumeFactor Der Lautstärke-Faktor.
+	 */
 	public void add( Audio pAudio, double pVolumeFactor ) {
+		if( !contains(pAudio) ) {
 			audios.add(new AudioWrapper(pAudio, (float) pVolumeFactor));
+		} else {
+			findWrapper(pAudio).volumeFactor = (float) pVolumeFactor;
+		}
 		pAudio.setVolume(pVolumeFactor * volume);
 	}
 
+	/**
+	 * Entfernt die das angegebene Audio-Objekt aus dem Mixer. Ist das Objekt
+	 * nicht Teil des Mixers, passiert nichts.
+	 *
+	 * @param pAudio Ein Audio-Objekt.
+	 */
 	public void remove( Audio pAudio ) {
+		Iterator<AudioWrapper> it = audios.listIterator();
+		while( it.hasNext() ) {
+			AudioWrapper aw = it.next();
+			if( aw.audio == pAudio ) {
+				it.remove();
+				break;
+			}
+		}
 	}
 
 	public void removeAll() {
@@ -178,4 +215,57 @@ public class Mixer implements Audio {
 		});
 	}
 
+	@Override
+	public void playbackStarted( Audio source ) {
+		if( eventDispatcher != null ) {
+			eventDispatcher.dispatchEvent("start", Mixer.this);
+		}
+	}
+
+	@Override
+	public void playbackStopped( Audio source ) {
+		if( !isPlaying() ) {
+			if( eventDispatcher != null ) {
+				eventDispatcher.dispatchEvent("stop", Mixer.this);
+			}
+		}
+	}
+
+	@Override
+	public void addAudioListener( AudioListener listener ) {
+		initializeEventDispatcher().addListener(listener);
+	}
+
+	@Override
+	public void removeAudioListener( AudioListener listener ) {
+		initializeEventDispatcher().removeListener(listener);
+	}
+
+	/**
+	 * Interne Methode, um den Listener-Mechanismus zu initialisieren. Wird erst
+	 * aufgerufen, soblad sich auch ein Listener registrieren möchte.
+	 * @return
+	 */
+	private EventDispatcher<Audio, AudioListener> initializeEventDispatcher() {
+		if( eventDispatcher == null ) {
+			eventDispatcher = new EventDispatcher<>();
+			eventDispatcher.registerEventType("start", (a,l) -> l.playbackStarted(a));
+			eventDispatcher.registerEventType("stop", (a,l) -> l.playbackStopped(a));
+		}
+		return eventDispatcher;
+	}
+
+	class AudioWrapper {
+
+		Audio audio;
+
+		float volumeFactor;
+
+		public AudioWrapper( Audio audio, float volumeFactor ) {
+			this.audio = audio;
+			this.volumeFactor = volumeFactor;
+		}
+
+	}
+
 }

src/main/java/schule/ngb/zm/media/Music.java

@@ -18,6 +18,7 @@ import java.net.URL;
  * nicht komplett in den Speicher geladen, sondern direkt aus der Audioquelle
  * gestreamt und wiedergegeben.
  */
+@SuppressWarnings("unused")
 public class Music implements Audio {
 
 	// size of the byte buffer used to read/write the audio stream
@@ -276,11 +277,13 @@ public class Music implements Audio {
 		}
 	}
 
-	public void addListener( AudioListener listener ) {
+	@Override
+	public void addAudioListener( AudioListener listener ) {
 		initializeEventDispatcher().addListener(listener);
 	}
 
-	public void removeListener( AudioListener listener ) {
+	@Override
+	public void removeAudioListener( AudioListener listener ) {
 		initializeEventDispatcher().removeListener(listener);
 	}
 
@@ -292,8 +295,8 @@ public class Music implements Audio {
 	private EventDispatcher<Audio, AudioListener> initializeEventDispatcher() {
 		if( eventDispatcher == null ) {
 			eventDispatcher = new EventDispatcher<>();
-			eventDispatcher.registerEventType("start", (a,l) -> l.start(a));
-			eventDispatcher.registerEventType("stop", (a,l) -> l.stop(a));
+			eventDispatcher.registerEventType("start", (a,l) -> l.playbackStarted(a));
+			eventDispatcher.registerEventType("stop", (a,l) -> l.playbackStopped(a));
 		}
 		return eventDispatcher;
 	}

src/main/java/schule/ngb/zm/media/Sound.java

@@ -2,6 +2,7 @@ package schule.ngb.zm.media;
 
 import schule.ngb.zm.util.Log;
 import schule.ngb.zm.util.Validator;
+import schule.ngb.zm.util.events.EventDispatcher;
 import schule.ngb.zm.util.io.ResourceStreamProvider;
 
 import javax.sound.sampled.*;
@@ -54,6 +55,8 @@ public class Sound implements Audio {
 	 */
 	private float volume = 0.8f;
 
+	EventDispatcher<Audio, AudioListener> eventDispatcher;
+
 	/**
 	 * Erstellt einen Sound aus der angegebene Quelle.
 	 *
@@ -235,7 +238,7 @@ public class Sound implements Audio {
 	public synchronized void dispose() {
 		if( audioClip != null ) {
 			if( audioClip.isRunning() ) {
-				audioClip.stop();
+				stop();
 			}
 			audioClip.close();
 			audioClip = null;
@@ -259,8 +262,16 @@ public class Sound implements Audio {
 				audioClip.addLineListener(new LineListener() {
 					@Override
 					public void update( LineEvent event ) {
-						if( event.getType() == LineEvent.Type.STOP ) {
+						if( event.getType() == LineEvent.Type.START ) {
+							if( eventDispatcher != null ) {
+								eventDispatcher.dispatchEvent("start", Sound.this);
+							}
+						} else if( event.getType() == LineEvent.Type.STOP ) {
 							playbackStopped();
+
+							if( eventDispatcher != null ) {
+								eventDispatcher.dispatchEvent("stop", Sound.this);
+							}
 						}
 					}
 				});
@@ -302,12 +313,37 @@ public class Sound implements Audio {
 	 */
 	private void playbackStopped() {
 		playing = false;
+
 		if( disposeAfterPlay ) {
 			this.dispose();
 			disposeAfterPlay = false;
 		}
 	}
 
+	@Override
+	public void addAudioListener( AudioListener listener ) {
+		initializeEventDispatcher().addListener(listener);
+	}
+
+	@Override
+	public void removeAudioListener( AudioListener listener ) {
+		initializeEventDispatcher().removeListener(listener);
+	}
+
+	/**
+	 * Interne Methode, um den Listener-Mechanismus zu initialisieren. Wird erst
+	 * aufgerufen, soblad sich auch ein Listener registrieren möchte.
+	 * @return
+	 */
+	private EventDispatcher<Audio, AudioListener> initializeEventDispatcher() {
+		if( eventDispatcher == null ) {
+			eventDispatcher = new EventDispatcher<>();
+			eventDispatcher.registerEventType("start", (a,l) -> l.playbackStarted(a));
+			eventDispatcher.registerEventType("stop", (a,l) -> l.playbackStopped(a));
+		}
+		return eventDispatcher;
+	}
+
 	private static final Log LOG = Log.getLogger(Sound.class);
 
 }

src/main/java/schule/ngb/zm/shapes/charts/BarChart.java

@@ -9,6 +9,7 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
 
+@SuppressWarnings("unused")
 public class BarChart extends Rectangle {
 
 	public static String DEFAULT_LABEL = "%.2f";
@@ -105,10 +106,10 @@ public class BarChart extends Rectangle {
 	}
 
 	public void addValue( double pValue, Color pColor ) {
-		addValue(pValue, pColor, String.format(DEFAULT_LABEL, pValue));
+		addValue(pValue, String.format(DEFAULT_LABEL, pValue), pColor);
 	}
 
-	public void addValue( double pValue, Color pColor, String pLabel ) {
+	public void addValue( double pValue, String pLabel, Color pColor ) {
 		addValue(new BasicChartValue(pValue, pLabel, pColor));
 	}