Dokumentation verbessert

src/schule/ngb/zm/Zeichenmaschine.java

@@ -126,7 +126,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Erstellt eine neue Zeichenmaschine mit Standardwerten für Titel und
 	 * Größe.
 	 * <p>
-	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr Details.
+	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr
+	 * Details.
 	 */
 	public Zeichenmaschine() {
 		this(APP_NAME + " " + APP_VERSION);
@@ -136,7 +137,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Erstellt eine neue Zeichenmaschine mit Standardwerten für Titel und
 	 * Größe.
 	 * <p>
-	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr Details.
+	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr
+	 * Details.
 	 *
 	 * @param run_once {@code true} beendet die Zeichenmaschine nach einem
 	 * 	Aufruf von {@code draw()}.
@@ -149,7 +151,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Erstellt eine neue Zeichenmaschine mit dem angegebene Titel und
 	 * Standardwerten für die Größe.
 	 * <p>
-	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr Details.
+	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr
+	 * Details.
 	 *
 	 * @param title Der Titel, der oben im Fenster steht.
 	 */
@@ -161,7 +164,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Erstellt eine neue Zeichenmaschine mit dem angegebene Titel und
 	 * Standardwerten für die Größe.
 	 * <p>
-	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr Details.
+	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr
+	 * Details.
 	 *
 	 * @param title Der Titel, der oben im Fenster steht.
 	 * @param run_once {@code true} beendet die Zeichenmaschine nach einem
@@ -175,7 +179,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Erstellt eine neue zeichenmaschine mit einer Leinwand der angegebenen
 	 * Größe und dem angegebenen Titel.
 	 * <p>
-	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr Details.
+	 * Siehe {@link #Zeichenmaschine(int, int, String, boolean)} für mehr
+	 * Details.
 	 *
 	 * @param width Breite der {@link Zeichenleinwand Zeichenleinwand}.
 	 * @param height Höhe der {@link Zeichenleinwand Zeichenleinwand}.
@@ -192,15 +197,15 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Die Zeichenmaschine öffnet automatisch ein Fenster mit einer
 	 * {@link Zeichenleinwand}, die {@code width} Pixel breit und {@code height}
 	 * Pixel hoch ist. Die Leinwand hat immer eine Mindestgröße von 100x100
-	 * Pixeln und kann nicht größer als der aktuelle Bildschirm werden.
+	 * Pixeln und kann nicht größer als der aktuelle Bildschirm werden. Das
-	 * Das Fenster bekommt den angegebenen Titel.
+	 * Fenster bekommt den angegebenen Titel.
 	 * <p>
 	 * Falls {@code run_once} gleich {@code false} ist, werden
 	 * {@link #update(double)} und {@link #draw()} entsprechend der
-	 * {@link #framesPerSecond} kontinuierlich aufgerufen.
+	 * {@link #framesPerSecond} kontinuierlich aufgerufen. Falls das Programm
-	 * Falls das Programm als Unterklasse der Zeichenmaschine verfasst wird,
+	 * als Unterklasse der Zeichenmaschine verfasst wird, dann kann auch,
-	 * dann kann auch, {@code update(double)} überschrieben werden, damit die
+	 * {@code update(double)} überschrieben werden, damit die Maschine nicht
-	 * Maschine nicht automatisch beendet.
+	 * automatisch beendet.
 	 *
 	 * @param width Breite der {@link Zeichenleinwand Zeichenleinwand}.
 	 * @param height Höhe der {@link Zeichenleinwand Zeichenleinwand}.
@@ -380,7 +385,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Gibt den aktuellen {@link Options.AppState Zustand} der Zeichenmaschine zurück.
+	 * Gibt den aktuellen {@link Options.AppState Zustand} der Zeichenmaschine
+	 * zurück.
 	 *
 	 * @return Der Zustand der Zeichenmaschine.
 	 */
@@ -425,8 +431,9 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Pausiert die Ausführung von {@link #update(double)} und {@link #draw()}
 	 * nach dem nächsten vollständigen Frame.
 	 * <p>
-	 * Die Zeichenmaschine wechselt in den Zustand {@link Options.AppState#PAUSED},
+	 * Die Zeichenmaschine wechselt in den Zustand
-	 * sobald der aktuelle Frame beendet wurde.
+	 * {@link Options.AppState#PAUSED}, sobald der aktuelle Frame beendet
+	 * wurde.
 	 */
 	public final void pause() {
 		pause_pending = true;
@@ -445,6 +452,7 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 
 	/**
 	 * Prüft, ob die Zeichenmaschine gerade pausiert ist.
+	 *
 	 * @return
 	 */
 	public final boolean isPaused() {
@@ -455,10 +463,10 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Stoppt die Zeichenmaschine.
 	 * <p>
 	 * Nachdem der aktuelle Frame gezeichnet wurde wechselt die Zeichenmaschine
-	 * in den Zustand {@link Options.AppState#STOPPED} und ruft {@link #teardown()}
+	 * in den Zustand {@link Options.AppState#STOPPED} und ruft
-	 * auf. Nachdem {@code teardown()} ausgeführt wurde wechselt der Zustand zu
+	 * {@link #teardown()} auf. Nachdem {@code teardown()} ausgeführt wurde
-	 * {@link Options.AppState#TERMINATED}. Das Zeichenfenster bleibt weiter
+	 * wechselt der Zustand zu {@link Options.AppState#TERMINATED}. Das
-	 * geöffnet.
+	 * Zeichenfenster bleibt weiter geöffnet.
 	 */
 	public final void stop() {
 		running = false;
@@ -489,8 +497,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Beendet das Programm. Falls {@code exit} gleich {@code true} ist,
+	 * Beendet das Programm. Falls {@code exit} gleich {@code true} ist, wird
-	 * wird die komplette VM beendet.
+	 * die komplette VM beendet.
 	 *
 	 * @param exit Ob die VM beendet werden soll.
 	 * @see System#exit(int)
@@ -505,6 +513,27 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 		}
 	}
 
+	/**
+	 * Interne Methode um die Größe der Zeichenfläche zu ändern.
+	 * <p>
+	 * Die Methode berücksichtigt nicht den Zustand des Fensters (z.B.
+	 * Vollbildmodus) und geht davon aus, dass die aufrufende Methode
+	 * sichergestellt hat, dass eine Änderung der Größe der Zeichenfläche
+	 * zulässig und sinnvoll ist.
+	 *
+	 * @param width Neue Breite der Zeichenleinwand.
+	 * @param height Neue Höhe der Zeichenleinwand.
+	 * @see #setSize(int, int)
+	 * @see #setFullscreen(boolean)
+	 */
+	private void changeSize( int width, int height ) {
+		if( canvas != null ) {
+			canvas.setSize(width, height);
+		}
+		this.width = Math.min(Math.max(width, 100), screenWidth);
+		this.height = Math.min(Math.max(height, 100), screenHeight);
+	}
+
 	/**
 	 * Ändert die Größe der {@link Zeichenleinwand}.
 	 *
@@ -518,11 +547,7 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 			initialHeight = Math.min(Math.max(height, 100), screenHeight);
 			setFullscreen(false);
 		} else {
-			if( canvas != null ) {
+			changeSize(width, height);
-				canvas.setSize(width, height);
-			}
-			this.width = Math.min(Math.max(width, 100), screenWidth);
-			this.height = Math.min(Math.max(height, 100), screenHeight);
 
 			//frame.setSize(width, height);
 			frame.pack();
@@ -566,8 +591,7 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Fügt der {@link Zeichenleinwand} eine weitere {@link Layer Ebene}
+	 * Fügt der {@link Zeichenleinwand} eine weitere {@link Layer Ebene} hinzu.
-	 * hinzu.
 	 *
 	 * @param layer Die neue Ebene.
 	 */
@@ -614,9 +638,9 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Gibt die {@link ColorLayer Ebene} mit der Hintergrundfarbe zurück. Gibt es
+	 * Gibt die {@link ColorLayer Ebene} mit der Hintergrundfarbe zurück. Gibt
-	 * keine solche Ebene, so wird eine erstellt und der {@link Zeichenleinwand}
+	 * es keine solche Ebene, so wird eine erstellt und der
-	 * hinzugefügt.
+	 * {@link Zeichenleinwand} hinzugefügt.
 	 * <p>
 	 * In der Regel sollte dies dieselbe Ebene sein wie {@link #background}.
 	 *
@@ -632,8 +656,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Gibt die Standard-{@link DrawingLayer Zeichenebene} zurück. Gibt es
+	 * Gibt die Standard-{@link DrawingLayer Zeichenebene} zurück. Gibt es keine
-	 * keine solche Ebene, so wird eine erstellt und der {@link Zeichenleinwand}
+	 * solche Ebene, so wird eine erstellt und der {@link Zeichenleinwand}
 	 * hinzugefügt.
 	 * <p>
 	 * In der Regel sollte dies dieselbe Ebene sein wie {@link #drawing}.
@@ -650,8 +674,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Gibt die Standard-{@link ShapesLayer Formenebene} zurück. Gibt es
+	 * Gibt die Standard-{@link ShapesLayer Formenebene} zurück. Gibt es keine
-	 * keine solche Ebene, so wird eine erstellt und der {@link Zeichenleinwand}
+	 * solche Ebene, so wird eine erstellt und der {@link Zeichenleinwand}
 	 * hinzugefügt.
 	 * <p>
 	 * In der Regel sollte dies dieselbe Ebene sein wie {@link #shapes}.
@@ -727,9 +751,9 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 
 	/**
 	 * Erstellt eine Momentanaufnahme des aktuellen Inhalts der
-	 * {@link Zeichenleinwand} und erstellt daraus eine {@link ImageLayer Bildebene}.
+	 * {@link Zeichenleinwand} und erstellt daraus eine
-	 * Die Ebene wird automatisch der {@link Zeichenleinwand} vor dem
+	 * {@link ImageLayer Bildebene}. Die Ebene wird automatisch der
-	 * {@link #background} hinzugefügt.
+	 * {@link Zeichenleinwand} vor dem {@link #background} hinzugefügt.
 	 *
 	 * @return Die neue Bildebene.
 	 */
@@ -815,8 +839,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Zeigt den Mauszeiger wieder an, falls er zuvor {@link #hideCursor() versteckt}
+	 * Zeigt den Mauszeiger wieder an, falls er zuvor
-	 * wurde.
+	 * {@link #hideCursor() versteckt} wurde.
 	 * <p>
 	 * Nach dem Aufruf gilt {@code cursorVisible == true}.
 	 * <p>
@@ -855,6 +879,7 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * <pre>
 	 *     setCursor(Cursor.HAND_CURSOR);
 	 * </pre>
+	 *
 	 * @param pPredefinedCursor Eine der Cursor-Konstanten.
 	 * @see Cursor
 	 */
@@ -863,13 +888,14 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	}
 
 	/**
-	 * Setzt den Mauszeiger auf das übergebenen Cursor-Objekt.
+	 * Setzt den Mauszeiger auf das übergebenen Cursor-Objekt. Wenn
-	 * Wenn {@code pCursor} {@code null} ist, wird der Mauszeiger unsichtbar
+	 * {@code pCursor} {@code null} ist, wird der Mauszeiger unsichtbar gemacht
-	 * gemacht (dies ist dasselbe wie der Aufruf von {@link #hideCursor()}).
+	 * (dies ist dasselbe wie der Aufruf von {@link #hideCursor()}).
+	 *
 	 * @param pCursor Ein Cursor-Objekt oder {@code null}.
 	 * 	<p>
-	 * Nach Aufruf der Methode kann über {@link #cursorVisible} abgefragt werden,
+	 * 	Nach Aufruf der Methode kann über {@link #cursorVisible} abgefragt
-	 * ob der Cursor zurzeit sichtbar ist oder nicht.
+	 * 	werden, ob der Cursor zurzeit sichtbar ist oder nicht.
 	 */
 	public final void setCursor( Cursor pCursor ) {
 		if( pCursor == null && cursorVisible ) {
@@ -896,7 +922,8 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 */
 
 	/**
-	 * Die Settings werden einmal beim Erstellten der Zeichenmaschine aufgerufen.
+	 * Die Settings werden einmal beim Erstellten der Zeichenmaschine
+	 * aufgerufen.
 	 * <p>
 	 * {@code settings()} wird nur selten benötigt, wenn das Zeichenfenster
 	 */
@@ -921,9 +948,9 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 	 * Aktualisierungen abhängig von der echten Verzögerung zwischen zwei Frames
 	 * zu berechnen.
 	 * <p>
-	 * {@code delta} wird in Sekunden angegeben. Um eine Form zum Beispiel
+	 * {@code delta} wird in Sekunden angegeben. Um eine Form zum Beispiel um
-	 * um {@code 50} Pixel pro Sekunde in {@code x}-Richtung zu bewegen,
+	 * {@code 50} Pixel pro Sekunde in {@code x}-Richtung zu bewegen, kann so
-	 * kann so vorgegangen werden:
+	 * vorgegangen werden:
 	 * <pre>
 	 * shape.move(50*delta, 0.0);
 	 * </pre>
@@ -937,23 +964,24 @@ public class Zeichenmaschine extends Constants implements MouseInputListener, Ke
 
 	/**
 	 * {@code draw()} wird einmal pro Frame aufgerufen. Bei einer
-	 * {@link #getFramesPerSecond() Framerate} von 60 also in etwa 60-Mal
+	 * {@link #getFramesPerSecond() Framerate} von 60 also in etwa 60-Mal pro
-	 * pro Sekunde. In der {@code draw}-Methode wird der Inhalt der Ebenen
+	 * Sekunde. In der {@code draw}-Methode wird der Inhalt der Ebenen
 	 * manipuliert und deren Inhalte gezeichnet. Am Ende des Frames werden alle
 	 * Ebenen auf die {@link Zeichenleinwand} übertragen.
 	 * <p>
-	 * {@code draw()} stellt die wichtigste Methode für eine Zeichenmaschine dar,
+	 * {@code draw()} stellt die wichtigste Methode für eine Zeichenmaschine
-	 * da hier die Zeichnung des Programms erstellt wird.
+	 * dar, da hier die Zeichnung des Programms erstellt wird.
 	 */
 	public void draw() {
 		running = !stop_after_update;
 	}
 
 	/**
-	 * {@code teardown()} wird aufgerufen, sobald die Schleife des Hauptprogramms
+	 * {@code teardown()} wird aufgerufen, sobald die Schleife des
-	 * beendet wurde. Dies passiert entweder nach dem ersten Durchlauf (wenn keine
+	 * Hauptprogramms beendet wurde. Dies passiert entweder nach dem ersten
-	 * eigene {@link #update(double)} erstellt wurde), nach dem Aufruf von
+	 * Durchlauf (wenn keine eigene {@link #update(double)} erstellt wurde),
-	 * {@link #stop()} oder nachdem das {@link Zeichenfenster} geschlossen wurde.
+	 * nach dem Aufruf von {@link #stop()} oder nachdem das
+	 * {@link Zeichenfenster} geschlossen wurde.
 	 * <p>
 	 * In {@code teardown()} kann zum Beispiel der Abschlussbildschirm eines
 	 * Spiels oder der Abspann einer Animation angezeigt werden, oder mit