From fc5ed14c7793a50dfd966b0ca65e6899a2cad97f Mon Sep 17 00:00:00 2001 From: hneemann Date: Sun, 10 Apr 2016 12:26:34 +0200 Subject: [PATCH] added some documentation --- .../neemann/digital/core/ObservableValue.java | 128 ++++++++++++++++-- .../digital/draw/elements/VisualElement.java | 118 +++++++++++++--- .../neemann/digital/draw/graphics/Style.java | 2 +- .../neemann/digital/draw/shapes/LEDShape.java | 2 +- .../java/de/neemann/digital/lang/Lang.java | 9 +- .../de/neemann/digital/lang/package-info.java | 6 + 6 files changed, 236 insertions(+), 29 deletions(-) create mode 100644 src/main/java/de/neemann/digital/lang/package-info.java diff --git a/src/main/java/de/neemann/digital/core/ObservableValue.java b/src/main/java/de/neemann/digital/core/ObservableValue.java index 028aedd17..9b5fdd783 100644 --- a/src/main/java/de/neemann/digital/core/ObservableValue.java +++ b/src/main/java/de/neemann/digital/core/ObservableValue.java @@ -16,10 +16,23 @@ public class ObservableValue extends Value { private final boolean supportsHighZ; private boolean bidirectional; + /** + * Creates a new instance + * + * @param name the name of this value + * @param bits the number of bits + */ public ObservableValue(String name, int bits) { this(name, bits, false); } + /** + * Creates a new instance. + * + * @param name the name of this value + * @param bits the number of bits + * @param highZ if true this value can be a high impedance value + */ public ObservableValue(String name, int bits, boolean highZ) { super(bits, highZ); mask = (1L << bits) - 1; @@ -28,16 +41,32 @@ public class ObservableValue extends Value { supportsHighZ = highZ; } + /** + * Adds an observer to this value. + * + * @param observer the observer to add + * @return this for call chaining + */ public ObservableValue addObserver(Observer observer) { if (observer != null) observers.add(observer); return this; } + /** + * Removes an observer from this value. + * + * @param observer the observer to use + */ public void removeObserver(Observer observer) { observers.remove(observer); } + /** + * Removes al observers from the given class + * + * @param observerClass the class of observers to remove + */ public void removeObserver(Class observerClass) { Iterator it = observers.iterator(); while (it.hasNext()) { @@ -46,23 +75,38 @@ public class ObservableValue extends Value { } } - + /** + * Fires a has changed event to all observers + */ public void hasChanged() { for (Observer l : observers) { l.hasChanged(); } } + /** + * @return the number of bits of this value + */ public int getBits() { return bits; } + /** + * returns the actual value + * + * @return the value + */ public long getValue() { // if (highZ) // throw new HighZException(this); return value; } + /** + * returns the actual value as a string + * + * @return the value as string + */ public String getValueString() { if (highZ) return "?"; @@ -71,6 +115,12 @@ public class ObservableValue extends Value { } } + /** + * converts a value to a minimal hex string + * + * @param value the value + * @return the string representation + */ public static String getHexString(long value) { String s = Long.toHexString(value).toUpperCase(); if (s.length() == 1) @@ -89,7 +139,11 @@ public class ObservableValue extends Value { } } - + /** + * Sets the value and fires a event if value has changed. + * + * @param value the new value + */ public void setValue(long value) { value = getValueBits(value); if (this.value != value) { @@ -99,18 +153,43 @@ public class ObservableValue extends Value { } } + /** + * Returns the value as a bool. + * + * @return the boolean + */ public boolean getBool() { return getValue() != 0; } + /** + * Sets a bool value. + * + * @param bool the boolean to set + */ public void setBool(boolean bool) { setValue(bool ? 1 : 0); } + /** + * reduces a given value to the number of bits used by this value. + * + * @param value the value to reduce + * @return the reduced value + */ public long getValueBits(long value) { return value & mask; } + /** + * checks if the given number of bits is the same used by this value. + * It is a convenience method to make this check simpler to code. + * + * @param bits the number of bits + * @param node the node to add to the exception if one is thrown + * @return this for chained calls + * @throws BitsException thrown if bit numbers do not match + */ public ObservableValue checkBits(int bits, Node node) throws BitsException { if (this.bits != bits) { throw new BitsException(Lang.get("err_needs_N0_bits_found_N2_bits", bits, this.bits), node, this); @@ -118,10 +197,18 @@ public class ObservableValue extends Value { return this; } + /** + * @return true if this value is a high z value + */ public boolean isHighZ() { return highZ; } + /** + * Sets the highZ state of this value + * + * @param highZ the new highZ state + */ public void setHighZ(boolean highZ) { if (this.highZ != highZ) { this.highZ = highZ; @@ -138,37 +225,58 @@ public class ObservableValue extends Value { @Override public String toString() { - return name + "{" + - "value=" + getValueString() + - ", setBits=" + bits + - '}'; + return name + "{" + + "value=" + getValueString() + + ", setBits=" + bits + + '}'; } + /** + * @return the name of this value + */ public String getName() { return name; } + /** + * @return the numbers of observers + */ public int observerCount() { return observers.size(); } + /** + * @return teturns true if the value could become a highZ value + */ public boolean supportsHighZ() { return supportsHighZ; } - public boolean isHighZIgnoreBurn() { - return highZ; - } - + /** + * Returns the value and does not throw a highZ exception. + * Should be used if the value is needed to create a graphical representation to + * avoid the graphical representation is causing exceptions. + * + * @return the actual value. + */ public long getValueIgnoreBurn() { return value; } + /** + * Makes this value a bidirectional value. + * + * @param bidirectional true if value is bidirectional + * @return this for chained calls + */ public ObservableValue setBidirectional(boolean bidirectional) { this.bidirectional = bidirectional; return this; } + /** + * @return true if value is bidirectional + */ public boolean isBidirectional() { return bidirectional; } diff --git a/src/main/java/de/neemann/digital/draw/elements/VisualElement.java b/src/main/java/de/neemann/digital/draw/elements/VisualElement.java index 72c7ab8d4..c641a44d0 100644 --- a/src/main/java/de/neemann/digital/draw/elements/VisualElement.java +++ b/src/main/java/de/neemann/digital/draw/elements/VisualElement.java @@ -17,6 +17,9 @@ import java.awt.*; import java.awt.image.BufferedImage; /** + * This class is used to store the visual representation of an element. + * Instances of this class are also used to store a circuit to disk. + * * @author hneemann */ public class VisualElement implements Drawable, Moveable, AttributeListener { @@ -32,12 +35,23 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { private Vector pos; private int rotate; + /** + * creates a new instance + * The name of the element is the name which is given to the Library to get the {@link de.neemann.digital.core.element.ElementTypeDescription} + * + * @param elementName the name of the element + */ public VisualElement(String elementName) { this.elementName = elementName; elementAttributes = new ElementAttributes(); pos = new Vector(0, 0); } + /** + * Creates a copy of the given VisualElement + * + * @param proto the VisualElement to copy + */ public VisualElement(VisualElement proto) { this.elementName = proto.elementName; this.elementAttributes = new ElementAttributes(proto.elementAttributes); @@ -45,51 +59,95 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { this.rotate = proto.rotate; } + /** + * Returns the name of the element. + * The name of the element is the name which is given to the Library to get the {@link de.neemann.digital.core.element.ElementTypeDescription} + * + * @return the name of the element + */ public String getElementName() { return elementName; } + /** + * @return the elements attributes + */ public ElementAttributes getElementAttributes() { elementAttributes.addListener(this); return elementAttributes; } + /** + * @return the position of this element + */ public Vector getPos() { return pos; } + /** + * Sets the position of this element + * + * @param pos the position + * @return this for chained calls + */ public VisualElement setPos(Vector pos) { this.pos = pos; minMax = null; return this; } + /** + * Checks if the given point is within the bounding box of the shape of this element. + * + * @param p a position + * @return true if p is inside the bounding box of the shape of this element. + */ public boolean matches(Vector p) { GraphicMinMax m = getMinMax(); - return (m.getMin().x <= p.x) && - (m.getMin().y <= p.y) && - (p.x <= m.getMax().x) && - (p.y <= m.getMax().y); + return (m.getMin().x <= p.x) + && (m.getMin().y <= p.y) + && (p.x <= m.getMax().x) + && (p.y <= m.getMax().y); } + /** + * Checks if the given bounding box contains the bounding box of the shape of this element. + * + * @param min upper left corner of the bounding box + * @param max lower right corner of the bounding box + * @return true if the given box completely contains this element + */ public boolean matches(Vector min, Vector max) { GraphicMinMax m = getMinMax(); - return (min.x <= m.getMin().x) && - (m.getMax().x <= max.x) && - (min.y <= m.getMin().y) && - (m.getMax().y <= max.y); + return (min.x <= m.getMin().x) + && (m.getMax().x <= max.x) + && (min.y <= m.getMin().y) + && (m.getMax().y <= max.y); } - + /** + * @return the rotation of this element + */ public int getRotate() { return rotate; } + /** + * sets the rotation of this element + * + * @param rotate the new value in the range 0-3 + */ public void setRotate(int rotate) { this.rotate = rotate; minMax = null; } + /** + * Returns the shape of this element. + * The there is no shape the {@link ShapeFactory} is requested for the shape. + * + * @return the shape + */ public Shape getShape() { if (shape == null) shape = shapeFactory.getShape(elementName, elementAttributes); @@ -103,8 +161,8 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { shape.drawTo(gr, highLight); for (Pin p : shape.getPins()) - gr.drawCircle(p.getPos().add(-PIN, -PIN), p.getPos().add(PIN, PIN) - , p.getDirection() == Pin.Direction.input ? Style.WIRE : Style.WIRE_OUT); + gr.drawCircle(p.getPos().add(-PIN, -PIN), p.getPos().add(PIN, PIN), + p.getDirection() == Pin.Direction.input ? Style.WIRE : Style.WIRE_OUT); if (highLight && minMax == null && !(graphic instanceof GraphicMinMax)) getMinMax(); @@ -124,6 +182,9 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { return new TransformRotate(pos, rotate); } + /** + * @return the bounding box of the shape of this element + */ public GraphicMinMax getMinMax() { if (minMax == null) { GraphicMinMax mm = new GraphicMinMax(); @@ -139,6 +200,13 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { minMax = null; } + /** + * Create an icon from this element. + * Is used to create the icons in the element menu + * + * @param maxHeight the maximum hight + * @return the icon ore null if the maximum height is exceeded. + */ public ImageIcon createIcon(int maxHeight) { GraphicMinMax mm = getMinMax(); @@ -161,6 +229,9 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { return new ImageIcon(bi); } + /** + * @return the pins of this element + */ public Pins getPins() { Shape shape = getShape(); Transform tr = createTransform(); @@ -186,6 +257,13 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { interactor = getShape().applyStateMonitor(ioState, guiObserver); } + /** + * Is called if this element is clicked by the mouse. + * the call is delegated to the {@link Interactor} of the {@link Shape} + * + * @param cc the calling {@link CircuitComponent} + * @param pos the position + */ public void clicked(CircuitComponent cc, Point pos) { if (interactor != null) interactor.clicked(cc, pos, ioState, element); @@ -207,16 +285,24 @@ public class VisualElement implements Drawable, Moveable, AttributeListener { return elementName; } + /** + * Sets the concrete element created. + * The value is given to the {@link Interactor} if the shape is clicked. + * + * @param element the element + */ public void setElement(Element element) { this.element = element; } - public Element getElement() { - return element; - } - + /** + * Sets the shape factory of this element. + * + * @param shapeFactory the {@link ShapeFactory} + * @return this for chained calls + */ public VisualElement setShapeFactory(ShapeFactory shapeFactory) { this.shapeFactory = shapeFactory; return this; } -} \ No newline at end of file +} diff --git a/src/main/java/de/neemann/digital/draw/graphics/Style.java b/src/main/java/de/neemann/digital/draw/graphics/Style.java index 069cd2c3f..74ee60e8b 100644 --- a/src/main/java/de/neemann/digital/draw/graphics/Style.java +++ b/src/main/java/de/neemann/digital/draw/graphics/Style.java @@ -77,7 +77,7 @@ public class Style { public static Style getWireStyle(ObservableValue value) { if (value == null || value.getBits() > 1) return WIRE; - if (value.isHighZIgnoreBurn()) return WIRE_HIGHZ; + if (value.isHighZ()) return WIRE_HIGHZ; if (value.getValueIgnoreBurn() == 1) return WIRE_HIGH; else return WIRE_LOW; diff --git a/src/main/java/de/neemann/digital/draw/shapes/LEDShape.java b/src/main/java/de/neemann/digital/draw/shapes/LEDShape.java index 0c25fd6ee..0140dc5fd 100644 --- a/src/main/java/de/neemann/digital/draw/shapes/LEDShape.java +++ b/src/main/java/de/neemann/digital/draw/shapes/LEDShape.java @@ -47,7 +47,7 @@ public class LEDShape implements Shape { if (ioState != null) { fill = false; ObservableValue value = ioState.getInput(0); - if (!value.isHighZIgnoreBurn() && (value.getValue() != 0)) + if (!value.isHighZ() && (value.getValue() != 0)) fill = true; } diff --git a/src/main/java/de/neemann/digital/lang/Lang.java b/src/main/java/de/neemann/digital/lang/Lang.java index a54b53bd3..fb220601d 100644 --- a/src/main/java/de/neemann/digital/lang/Lang.java +++ b/src/main/java/de/neemann/digital/lang/Lang.java @@ -8,12 +8,19 @@ import java.util.ResourceBundle; /** * @author hneemann */ -public class Lang { +public final class Lang { private static class InstanceHolder { static final Lang INSTANCE = new Lang(); } + /** + * gets an internationalized string + * + * @param key the key + * @param params optional parameters + * @return the internationalized string + */ public static String get(String key, Object... params) { return InstanceHolder.INSTANCE.getKey(key, params); } diff --git a/src/main/java/de/neemann/digital/lang/package-info.java b/src/main/java/de/neemann/digital/lang/package-info.java new file mode 100644 index 000000000..6515eb19c --- /dev/null +++ b/src/main/java/de/neemann/digital/lang/package-info.java @@ -0,0 +1,6 @@ +/** + * simple internationalization class + * + * @author hneemann + */ +package de.neemann.digital.lang;