From 9a9a71405065eb326e234dd60d817c319105ebc1 Mon Sep 17 00:00:00 2001 From: "J. Neugebauer" Date: Sun, 17 Jul 2022 16:38:42 +0200 Subject: [PATCH] Javadoc --- src/main/java/schule/ngb/zm/Drawable.java | 2 +- .../schule/ngb/zm/shapes/FilledShape.java | 32 ++-- src/main/java/schule/ngb/zm/shapes/Shape.java | 1 - .../schule/ngb/zm/shapes/StrokedShape.java | 142 ++++++++++++++++-- 4 files changed, 145 insertions(+), 32 deletions(-) diff --git a/src/main/java/schule/ngb/zm/Drawable.java b/src/main/java/schule/ngb/zm/Drawable.java index 0b93f88..fed6e44 100644 --- a/src/main/java/schule/ngb/zm/Drawable.java +++ b/src/main/java/schule/ngb/zm/Drawable.java @@ -18,7 +18,7 @@ public interface Drawable { /** * Wird aufgerufen, um das Objekt auf die Zeichenfläche graphics - * zu draw. + * zu zeichnen. *

* Das Objekt muss dafür Sorge tragen, dass der Zustand der Zeichenfläche * (Transformationsmatrix, Farbe, ...) erhalten bleibt. Das Objekt sollte diff --git a/src/main/java/schule/ngb/zm/shapes/FilledShape.java b/src/main/java/schule/ngb/zm/shapes/FilledShape.java index bc0a0a7..abbc103 100644 --- a/src/main/java/schule/ngb/zm/shapes/FilledShape.java +++ b/src/main/java/schule/ngb/zm/shapes/FilledShape.java @@ -39,7 +39,7 @@ public abstract class FilledShape extends StrokedShape { * Setzt die Füllfarbe auf die angegebene Farbe. * * @param color Die neue Füllfarbe oder {@code null}. - * @see Color#Color(Color) + * @see Color */ public void setFillColor( Color color ) { fillColor = color; @@ -50,7 +50,7 @@ public abstract class FilledShape extends StrokedShape { * auf den angegebenen Wert. 0 is komplett durchsichtig und 255 komplett * deckend. * - * @param color Die neue Füllfarbe oder {@null}. + * @param color Die neue Füllfarbe oder {@code null}. * @param alpha Ein Transparenzwert zwischen 0 und 255. * @see Color#Color(Color, int) */ @@ -136,12 +136,12 @@ public abstract class FilledShape extends StrokedShape { * ({@code fromX}, {@code fromY}) mit der Farbe {@code from} startet und am * Punkt (({@code toX}, {@code toY}) mit der Farbe {@code to} endet. * - * @param fromX - * @param fromY - * @param from - * @param toX - * @param toY - * @param to + * @param fromX x-Koordinate des Startpunktes. + * @param fromY y-Koordinate des Startpunktes. + * @param from Farbe am Startpunkt. + * @param toX x-Koordinate des Endpunktes. + * @param toY y-Koordinate des Endpunktes. + * @param to Farbe am Endpunkt. */ public void setGradient( double fromX, double fromY, Color from, double toX, double toY, Color to ) { setFillColor(from); @@ -158,11 +158,11 @@ public abstract class FilledShape extends StrokedShape { * endet am Rand des durch den Radius beschriebenen Kreises mit der Farbe * {@code to}. * - * @param centerX - * @param centerY - * @param radius - * @param from - * @param to + * @param centerX x-Koordinate des Kreismittelpunktes. + * @param centerY y-Koordinate des Kreismittelpunktes. + * @param radius Radius des Kreises. + * @param from Farbe im Zentrum des Kreises. + * @param to Farbe am Rand des Kreises. */ public void setGradient( double centerX, double centerY, double radius, Color from, Color to ) { setFillColor(from); @@ -180,11 +180,11 @@ public abstract class FilledShape extends StrokedShape { } /** - * Hilfsmethode für Unterklassen, um die angegebene Form mit der gesetzten + * Hilfsmethode für Unterklassen, um die angegebene Form mit der aktuellen * Füllung auf den Grafik-Kontext zu zeichnen. Die Methode verändert * gegebenenfalls die aktuelle Farbe des Grafikobjekts und setzt sie nicht - * auf den Ursprungswert zurück. Dies sollte die aufrufende Unterklasse - * übernehmen. + * auf den Ursprungswert zurück, wie von {@link #draw(Graphics2D)} + * gefordert. Dies sollte die aufrufende Unterklasse übernehmen. * * @param shape Die zu zeichnende Java-AWT Form * @param graphics Das Grafikobjekt. diff --git a/src/main/java/schule/ngb/zm/shapes/Shape.java b/src/main/java/schule/ngb/zm/shapes/Shape.java index 2992b28..01da571 100644 --- a/src/main/java/schule/ngb/zm/shapes/Shape.java +++ b/src/main/java/schule/ngb/zm/shapes/Shape.java @@ -226,7 +226,6 @@ public abstract class Shape extends FilledShape { * Unterklasse. In {@link Rectangle} sieht die Umsetzung beispielsweise so * aus: * 


-	 * @Override
 	 * public Rectangle copy() {
 	 *     return new Rectangle(this);
 	 * }
diff --git a/src/main/java/schule/ngb/zm/shapes/StrokedShape.java b/src/main/java/schule/ngb/zm/shapes/StrokedShape.java
index feb1907..0bdbeb5 100644
--- a/src/main/java/schule/ngb/zm/shapes/StrokedShape.java
+++ b/src/main/java/schule/ngb/zm/shapes/StrokedShape.java
@@ -15,55 +15,162 @@ import java.awt.Stroke;
  */
 public abstract class StrokedShape extends Constants implements Drawable {
 
+	/**
+	 * Aktuelle Farbe der Konturlinie oder {@code null}, wenn die Form ohne
+	 * kontur dargestellt werden soll.
+	 */
 	protected Color strokeColor = DEFAULT_STROKECOLOR;
 
+	/**
+	 * Die Dicke der Konturlinie. Wird nicht kleiner als 0.
+	 */
 	protected double strokeWeight = DEFAULT_STROKEWEIGHT;
 
+	/**
+	 * Die Art der Konturlinie.
+	 */
 	protected Options.StrokeType strokeType = SOLID;
 
+	/**
+	 * Cache für den aktuellen {@code Stroke} der Kontur. Wird nach Änderung
+	 * einer der Kontureigenschaften auf {@code null} gesetzt und beim nächsten
+	 * Zeichnen neu erstellt.
+	 */
 	protected Stroke stroke = null;
 
+	/**
+	 * Gibt die aktuelle Farbe der Konturlinie zurück.
+	 *
+	 * @return Die Konturfarbe oder {@code null}.
+	 */
 	public Color getStrokeColor() {
 		return strokeColor;
 	}
 
+	/**
+	 * Setzt die Farbe der Konturlinie auf die angegebene Farbe.
+	 *
+	 * @param color Die neue Farbe der Konturlinie.
+	 * @see Color
+	 */
 	public void setStrokeColor( Color color ) {
 		this.strokeColor = color;
 	}
 
+	/**
+	 * Setzt die Farbe der Konturlinie auf die angegebene Farbe und setzt die
+	 * Transparenz auf den angegebenen Wert. 0 is komplett durchsichtig und 255
+	 * komplett deckend.
+	 *
+	 * @param color Die neue Farbe der Konturlinie oder {@code null}.
+	 * @param alpha Ein Transparenzwert zwischen 0 und 255.
+	 * @see Color#Color(Color, int)
+	 */
 	public void setStrokeColor( Color color, int alpha ) {
 		setStrokeColor(new Color(color, alpha));
 	}
 
+	/**
+	 * Setzt die Farbe der Konturlinie auf einen Grauwert mit der angegebenen
+	 * Intensität. 0 entspricht schwarz, 255 entspricht weiß.
+	 *
+	 * @param gray Ein Grauwert zwischen 0 und 255.
+	 * @see Color#Color(int)
+	 */
 	public void setStrokeColor( int gray ) {
 		setStrokeColor(gray, gray, gray, 255);
 	}
 
-	public void noStroke() {
-		setStrokeColor(null);
-	}
-
+	/**
+	 * Setzt die Farbe der Konturlinie auf einen Grauwert mit der angegebenen
+	 * Intensität und dem angegebenen Transparenzwert. Der Grauwert 0 entspricht
+	 * schwarz, 255 entspricht weiß.
+	 *
+	 * @param gray Ein Grauwert zwischen 0 und 255.
+	 * @param alpha Ein Transparenzwert zwischen 0 und 255.
+	 * @see Color#Color(int, int)
+	 */
 	public void setStrokeColor( int gray, int alpha ) {
 		setStrokeColor(gray, gray, gray, alpha);
 	}
 
+	/**
+	 * Setzt die Farbe der Konturlinie auf die Farbe mit den angegebenen Rot-,
+	 * Grün- und Blauanteilen.
+	 *
+	 * @param red Der Rotanteil der Farbe zwischen 0 und 255.
+	 * @param green Der Grünanteil der Farbe zwischen 0 und 255.
+	 * @param blue Der Blauanteil der Farbe zwischen 0 und 255.
+	 * @see Color#Color(int, int, int)
+	 * @see https://de.wikipedia.org/wiki/RGB-Farbraum
+	 */
 	public void setStrokeColor( int red, int green, int blue ) {
 		setStrokeColor(red, green, blue, 255);
 	}
 
+	/**
+	 * Setzt die Farbe der Konturlinie auf die Farbe mit den angegebenen Rot-,
+	 * Grün- und Blauanteilen und dem angegebenen Transparenzwert.
+	 *
+	 * @param red Der Rotanteil der Farbe zwischen 0 und 255.
+	 * @param green Der Grünanteil der Farbe zwischen 0 und 255.
+	 * @param blue Der Blauanteil der Farbe zwischen 0 und 255.
+	 * @param alpha Ein Transparenzwert zwischen 0 und 25
+	 * @see Color#Color(int, int, int, int)
+	 * @see https://de.wikipedia.org/wiki/RGB-Farbraum
+	 */
 	public void setStrokeColor( int red, int green, int blue, int alpha ) {
 		setStrokeColor(new Color(red, green, blue, alpha));
 	}
 
+	/**
+	 * Entfernt die Kontur der Form.
+	 */
+	public void noStroke() {
+		setStrokeColor(null);
+	}
+
+	/**
+	 * Setzt die Farbe der Konturlinie auf die Standardwerte zurück.
+	 *
+	 * @see schule.ngb.zm.Constants#DEFAULT_STROKECOLOR
+	 * @see schule.ngb.zm.Constants#DEFAULT_STROKEWEIGHT
+	 * @see schule.ngb.zm.Constants#SOLID
+	 */
+	public void resetStroke() {
+		setStrokeColor(DEFAULT_STROKECOLOR);
+		setStrokeWeight(DEFAULT_STROKEWEIGHT);
+		setStrokeType(SOLID);
+	}
+
+	/**
+	 * Gibt die Dicke der Konturlinie zurück.
+	 *
+	 * @return Die aktuelle Dicke der Linie.
+	 */
 	public double getStrokeWeight() {
 		return strokeWeight;
 	}
 
+	/**
+	 * Setzt die Dicke der Konturlinie. Die Dicke muss größer 0 sein. Wird 0
+	 * übergeben, dann wird keine Kontur mehr angezeigt.
+	 *
+	 * @param weight Die Dicke der Konturlinie.
+	 */
 	public void setStrokeWeight( double weight ) {
-		this.strokeWeight = weight;
+		this.strokeWeight = max(0.0, weight);
 		this.stroke = null;
 	}
 
+	/**
+	 * Gibt die Art der Konturlinie zurück.
+	 *
+	 * @return Die aktuelle Art der Konturlinie.
+	 * @see Options.StrokeType
+	 */
 	public Options.StrokeType getStrokeType() {
 		return strokeType;
 	}
@@ -72,26 +179,23 @@ public abstract class StrokedShape extends Constants implements Drawable {
 	 * Setzt den Typ der Kontur. Erlaubte Werte sind {@link #DASHED},
 	 * {@link #DOTTED} und {@link #SOLID}.
 	 *
-	 * @param type
+	 * @param type Eine der möglichen Konturarten.
+	 * @see Options.StrokeType
 	 */
 	public void setStrokeType( Options.StrokeType type ) {
 		this.strokeType = type;
 		this.stroke = null;
 	}
 
-	public void resetStroke() {
-		setStrokeColor(DEFAULT_STROKECOLOR);
-		setStrokeWeight(DEFAULT_STROKEWEIGHT);
-		setStrokeType(SOLID);
-	}
-
 	@Override
 	public abstract void draw( Graphics2D graphics );
 
 	/**
-	 * Erstellt ein {@link Stroke} Objekt für den Konturtyp.
+	 * Hilfsmethode, um ein {@link Stroke} Objekt mit den aktuellen
+	 * Kontureigenschaften zu erstellen. Der aktuelle {@code Stroke} wird
+	 * zwischengespeichert.
 	 *
-	 * @return
+	 * @return Ein {@code Stroke} mit den passenden Kontureigenschaften.
 	 */
 	protected Stroke createStroke() {
 		// TODO: Used global cached Stroke Objects?
@@ -123,6 +227,16 @@ public abstract class StrokedShape extends Constants implements Drawable {
 		return stroke;
 	}
 
+	/**
+	 * Hilfsmethode für Unterklassen, um die angegebene Form mit den aktuellen
+	 * Kontureigenschaften auf den Grafik-Kontext zu zeichnen. Die Methode
+	 * verändert gegebenenfalls die aktuelle Farbe des Grafikobjekts und setzt
+	 * sie nicht auf den Ursprungswert zurück, wie von {@link #draw(Graphics2D)}
+	 * gefordert. Dies sollte die aufrufende Unterklasse übernehmen.
+	 *
+	 * @param shape Die zu zeichnende Java-AWT Form
+	 * @param graphics Das Grafikobjekt.
+	 */
 	protected void strokeShape( java.awt.Shape shape, Graphics2D graphics ) {
 		if( strokeColor != null && strokeColor.getAlpha() > 0
 			&& strokeWeight > 0.0 ) {