Revision: 688
Author: allain.lalonde
Date: Thu Oct 8 21:24:11 2009
Log: Removing lots of javadoc findbugs in the core
http://code.google.com/p/piccolo2d/source/detail?r=688
Modified:
/piccolo2d.java/trunk/core
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PText.java
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PBounds.java
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PObjectOutputStream.java
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPaintContext.java
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPickPath.java
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PUtil.java
=======================================
---
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PText.java
Sun Aug 2 19:41:03 2009
+++
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/nodes/PText.java
Thu Oct 8 21:24:11 2009
@@ -33,6 +33,7 @@
import java.awt.Font;
import java.awt.Graphics2D;
import java.awt.Paint;
+import java.awt.RenderingHints;
import java.awt.font.LineBreakMeasurer;
import java.awt.font.TextAttribute;
import java.awt.font.TextLayout;
@@ -505,6 +506,9 @@
}
final float offset = (float) (getWidth() - tl.getAdvance()) *
horizontalAlignment;
+
+
System.out.println(g2.getRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING));
+
System.out.println(g2.getRenderingHint(RenderingHints.KEY_ANTIALIASING));
tl.draw(g2, x + offset, y);
y += tl.getDescent() + tl.getLeading();
=======================================
---
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PBounds.java
Tue Aug 4 09:04:02 2009
+++
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PBounds.java
Thu Oct 8 21:24:11 2009
@@ -86,11 +86,27 @@
isEmpty = aBounds.isEmpty();
}
+ /**
+ * Constructs a PBounds object with the given center point and the
specified
+ * insets.
+ *
+ * @param aCenterPoint resulting center point of the PBounds object
+ * @param insetX distance from left and right the center should be
+ * @param insetY distance from top and bottom the center should be
+ */
public PBounds(final Point2D aCenterPoint, final double insetX, final
double insetY) {
this(aCenterPoint.getX(), aCenterPoint.getY(), 0, 0);
inset(insetX, insetY);
}
+ /**
+ * Constructs a PBounds object at the given coordinates with the given
dimensions.
+ *
+ * @param x left of bounds
+ * @param y top of bounds
+ * @param width width of bounds
+ * @param height height of bounds
+ */
public PBounds(final double x, final double y, final double width,
final double height) {
super(x, y, width, height);
isEmpty = false;
@@ -251,8 +267,8 @@
* Changes the origin of these bounds. And flags it as non-empty.
*
* @param x new x component of bounds
- * @param y new y componet of the bounds
- * @return
+ * @param y new y component of the bounds
+ * @return the modified PBounds with its new origin
*/
public PBounds setOrigin(final double x, final double y) {
this.x = x;
=======================================
---
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PObjectOutputStream.java
Mon Aug 3 19:46:04 2009
+++
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PObjectOutputStream.java
Thu Oct 8 21:24:11 2009
@@ -70,25 +70,55 @@
private boolean writingRoot;
private final HashMap unconditionallyWritten;
- public static byte[] toByteArray(final Object aRoot) throws
IOException {
+ /**
+ * Transform the given object into an array of bytes.
+ *
+ * @param object
+ * @return array of bytes representing the given object
+ * @throws IOException
+ */
+ public static byte[] toByteArray(final Object object) throws
IOException {
final ByteArrayOutputStream out = new ByteArrayOutputStream();
final PObjectOutputStream zout = new PObjectOutputStream(out);
- zout.writeObjectTree(aRoot);
+ zout.writeObjectTree(object);
return out.toByteArray();
}
+ /**
+ * Constructs a PObjectOutputStream that wraps the provided
OutputStream.
+ *
+ * @param out underlying outputstream that will receive the serialized
+ * objects
+ *
+ * @throws IOException
+ */
public PObjectOutputStream(final OutputStream out) throws IOException {
super(out);
unconditionallyWritten = new HashMap();
}
- public void writeObjectTree(final Object aRoot) throws IOException {
+ /**
+ * Writes the provided object to the underlying stream like an
ordination
+ * ObjectOutputStream except that it does not record duplicates at all.
+ *
+ * @param object object to be serialized
+ *
+ * @throws IOException
+ */
+ public void writeObjectTree(final Object object) throws IOException {
writingRoot = true;
- recordUnconditionallyWritten(aRoot); // record pass
- writeObject(aRoot); // write pass
+ recordUnconditionallyWritten(object); // record pass
+ writeObject(object); // write pass
writingRoot = false;
}
+ /**
+ * Writes the given object, but only if it was not in the object tree
+ * multiple times.
+ *
+ * @param object object to write to the stream.
+ * @throws IOException
+ */
public void writeConditionalObject(final Object object) throws
IOException {
if (!writingRoot) {
throw new RuntimeException(
@@ -103,6 +133,12 @@
}
}
+ /**
+ * Resets the ObjectOutputStream clearing any memory about objects
already
+ * being written while it's at it.
+ *
+ * @throws IOException
+ */
public void reset() throws IOException {
super.reset();
unconditionallyWritten.clear();
=======================================
---
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPaintContext.java
Wed Aug 5 18:13:48 2009
+++
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPaintContext.java
Thu Oct 8 21:24:11 2009
@@ -180,32 +180,51 @@
/**
* Removes the camera at the top of the camera stack.
- *
- * @param aCamera absolute not used in any way
*/
public void popCamera() {
cameraStack.pop();
}
+ /**
+ * Returns the camera at the top of the camera stack.
+ *
+ * @return
+ */
public PCamera getCamera() {
return (PCamera) cameraStack.peek();
}
- public void pushClip(final Shape aClip) {
+ /**
+ * Pushes the given clip to the pain context.
+ *
+ * @param clip clip to be pushed
+ */
+ public void pushClip(final Shape clip) {
final Shape currentClip = graphics.getClip();
clipStack.push(currentClip);
- graphics.clip(aClip);
- final Rectangle2D newLocalClip = aClip.getBounds2D();
+ graphics.clip(clip);
+ final Rectangle2D newLocalClip = clip.getBounds2D();
Rectangle2D.intersect(getLocalClip(), newLocalClip, newLocalClip);
localClipStack.push(newLocalClip);
}
- public void popClip(final Shape aClip) {
+ /**
+ * Removes the topmost clipping region from the clipping stack.
+ *
+ * @param clip not used in this method
+ */
+ public void popClip(final Shape clip) {
final Shape newClip = (Shape) clipStack.pop();
graphics.setClip(newClip);
localClipStack.pop();
}
+ /**
+ * Pushes the provided transparency onto the transparency stack if
+ * necessary. If the transparency is fully opaque, then it does
nothing.
+ *
+ * @param transparency transparency to be pushed onto the transparency
stack
+ */
public void pushTransparency(final float transparency) {
if (transparency == 1.0f) {
return;
@@ -222,6 +241,11 @@
graphics.setComposite(newComposite);
}
+ /**
+ * Removes the topmost transparency if the given transparency is not
opaque (1f).
+ *
+ * @param transparency transparency to be popped
+ */
public void popTransparency(final float transparency) {
if (transparency == 1.0f) {
return;
@@ -230,28 +254,35 @@
graphics.setComposite(c);
}
- public void pushTransform(final PAffineTransform aTransform) {
- if (aTransform != null) {
- final Rectangle2D newLocalClip = (Rectangle2D)
getLocalClip().clone();
- aTransform.inverseTransform(newLocalClip, newLocalClip);
- transformStack.push(graphics.getTransform());
- localClipStack.push(newLocalClip);
- graphics.transform(aTransform);
- }
+ /**
+ * Pushed the provided transform onto the transform stack.
+ *
+ * @param transform
+ */
+ public void pushTransform(final PAffineTransform transform) {
+ if (transform == null) {
+ return;
+ }
+
+ final Rectangle2D newLocalClip = (Rectangle2D)
getLocalClip().clone();
+ transform.inverseTransform(newLocalClip, newLocalClip);
+ transformStack.push(graphics.getTransform());
+ localClipStack.push(newLocalClip);
+ graphics.transform(transform);
}
/**
* Pops the topmost Transform from the top of the transform if the
passed in
* transform is not null.
*
- * @param aTransform transform that should be at the top of the stack
+ * @param transform transform that should be at the top of the stack
*/
- public void popTransform(final PAffineTransform aTransform) {
- if (aTransform != null) {
+ public void popTransform(final PAffineTransform transform) {
+ if (transform != null) {
graphics.setTransform((AffineTransform) transformStack.pop());
localClipStack.pop();
}
- }
+ }
/**
* Return the render quality used by this paint context.
=======================================
---
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPickPath.java
Mon Aug 3 19:46:04 2009
+++
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PPickPath.java
Thu Oct 8 21:24:11 2009
@@ -96,26 +96,46 @@
CURRENT_PICK_PATH = this;
}
+ /**
+ * Returns the bounds of the entire PickPath taken as a whole.
+ *
+ * @return bounds of the entire PickPath
+ */
public PBounds getPickBounds() {
return (PBounds) pickBoundsStack.peek();
}
+ /**
+ * Determines if the passed node has been excluded from being a member
of
+ * the pickpath.
+ *
+ * @param node node being tested
+ * @return true if node is acceptable to the path
+ */
public boolean acceptsNode(final PNode node) {
- if (excludedNodes != null) {
- return !excludedNodes.containsKey(node);
- }
- return true;
+ return excludedNodes == null || !excludedNodes.containsKey(node);
}
// ****************************************************************
// Picked Nodes
// ****************************************************************
- public void pushNode(final PNode aNode) {
- nodeStack.push(aNode);
+ /**
+ * Pushes the provided node to the top of the pick path.
+ *
+ * @param node node to be added to the pick path
+ */
+ public void pushNode(final PNode node) {
+ nodeStack.push(node);
}
- public void popNode(final PNode aNode) {
+ /**
+ * Removes the topmost node from the node stack.
+ *
+ * @param node completely unused in this method, but is passed in so
that
+ * subclasses may be informed of it.
+ */
+ public void popNode(final PNode node) {
nodeStack.pop();
}
@@ -197,6 +217,11 @@
return bottomCamera;
}
+ /**
+ * Returns a reference to the node stack. Be Careful!
+ *
+ * @return the node stack
+ */
public PStack getNodeStackReference() {
return nodeStack;
}
@@ -205,6 +230,13 @@
// Path Transform
// ****************************************************************
+ /**
+ * Returns the resulting scale of applying the transforms of the
entire pick
+ * path. In essence it gives you the scale at which interaction is
+ * occurring.
+ *
+ * @return scale at which interaction is occurring.
+ */
public double getScale() {
PTS[0] = 0;// x1
PTS[1] = 0;// y1
@@ -222,22 +254,41 @@
return Point2D.distance(PTS[0], PTS[1], PTS[2], PTS[3]);
}
- public void pushTransform(final PAffineTransform aTransform) {
- transformStack.push(new PTuple(getPickedNode(), aTransform));
- if (aTransform != null) {
+ /**
+ * Adds the transform to the pick path's transform. This is used when
+ * determining the context of the current interaction.
+ *
+ * @param transform transform to be added to applied to the pickpath.
+ */
+ public void pushTransform(final PAffineTransform transform) {
+ transformStack.push(new PTuple(getPickedNode(), transform));
+ if (transform != null) {
final Rectangle2D newPickBounds = (Rectangle2D)
getPickBounds().clone();
- aTransform.inverseTransform(newPickBounds, newPickBounds);
+ transform.inverseTransform(newPickBounds, newPickBounds);
pickBoundsStack.push(newPickBounds);
}
}
- public void popTransform(final PAffineTransform aTransform) {
+ /**
+ * Pops the top most transform from the pick path.
+ *
+ * @param transform unused in this method
+ */
+ public void popTransform(final PAffineTransform transform) {
transformStack.pop();
- if (aTransform != null) {
+ if (transform != null) {
pickBoundsStack.pop();
}
}
+ /**
+ * Calculates the context at which the given node is being interacted
with.
+ *
+ * @param nodeOnPath a node currently on the pick path. An exception
will be
+ * thrown if the node cannot be found.
+ *
+ * @return Transform at which the given node is being interacted with.
+ */
public PAffineTransform getPathTransformTo(final PNode nodeOnPath) {
final PAffineTransform aTransform = new PAffineTransform();
@@ -255,13 +306,15 @@
throw new RuntimeException("Node could not be found on pick path");
}
- // ****************************************************************
- // Process Events - Give each node in the pick path, starting at
- // the bottom most one, a chance to handle the event.
- // ****************************************************************
-
- public void processEvent(final PInputEvent aEvent, final int type) {
- aEvent.setPath(this);
+ /**
+ * Process Events - Give each node in the pick path, starting at the
bottom
+ * most one, a chance to handle the event.
+ *
+ * @param event event to be processed
+ * @param eventType the type of event being processed
+ */
+ public void processEvent(final PInputEvent event, final int eventType)
{
+ event.setPath(this);
for (int i = nodeStack.size() - 1; i >= 0; i--) {
final PNode each = (PNode) nodeStack.get(i);
@@ -273,8 +326,8 @@
for (int j = 0; j < listeners.length; j++) {
final PInputEventListener listener =
(PInputEventListener) listeners[j];
- listener.processEvent(aEvent, type);
- if (aEvent.isHandled()) {
+ listener.processEvent(event, eventType);
+ if (event.isHandled()) {
return;
}
}
@@ -299,6 +352,9 @@
* Convert the given point from the canvas coordinates, down through
the
* pick path (and through any camera view transforms applied to the
path) to
* the local coordinates of the given node.
+ *
+ * @param canvasPoint point to be transformed
+ * @param nodeOnPath node into which the point is to be transformed
iteratively through the pickpath
*/
public Point2D canvasToLocal(final Point2D canvasPoint, final PNode
nodeOnPath) {
return
getPathTransformTo(nodeOnPath).inverseTransform(canvasPoint, canvasPoint);
@@ -308,6 +364,9 @@
* Convert the given dimension from the canvas coordinates, down
through the
* pick path (and through any camera view transforms applied to the
path) to
* the local coordinates of the given node.
+ *
+ * @param canvasDimension dimension to be transformed
+ * @param nodeOnPath node into which the dimension is to be
transformed iteratively through the stack
*/
public Dimension2D canvasToLocal(final Dimension2D canvasDimension,
final PNode nodeOnPath) {
return
getPathTransformTo(nodeOnPath).inverseTransform(canvasDimension,
canvasDimension);
@@ -317,6 +376,9 @@
* Convert the given rectangle from the canvas coordinates, down
through the
* pick path (and through any camera view transforms applied to the
path) to
* the local coordinates of the given node.
+ *
+ * @param canvasRectangle rectangle to be transformed
+ * @param nodeOnPath node into which the rectangle is to be
transformed iteratively through the stack
*/
public Rectangle2D canvasToLocal(final Rectangle2D canvasRectangle,
final PNode nodeOnPath) {
return
getPathTransformTo(nodeOnPath).inverseTransform(canvasRectangle,
canvasRectangle);
=======================================
---
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PUtil.java
Mon Aug 3 19:46:04 2009
+++
/piccolo2d.java/trunk/core/src/main/java/edu/umd/cs/piccolo/util/PUtil.java
Thu Oct 8 21:24:11 2009
@@ -57,11 +57,11 @@
* PActivities are broken into steps, this is how many milliseconds
should
* pass between steps.
*/
- public static long DEFAULT_ACTIVITY_STEP_RATE = 20;
+ public static long DEFAULT_ACTIVITY_STEP_RATE = 20;
public static int ACTIVITY_SCHEDULER_FRAME_DELAY = 10;
public static Iterator NULL_ITERATOR =
Collections.EMPTY_LIST.iterator();
-
- private static final int PATH_TERMINATOR = -1;
+
+ private static final int PATH_TERMINATOR = -1;
public static Enumeration NULL_ENUMERATION = new Enumeration() {
public boolean hasMoreElements() {
return false;
@@ -73,7 +73,8 @@
};
/**
- * @deprecated This has been moved into a private static class of
PObjectOutputStream
+ * @deprecated This has been moved into a private static class of
+ * PObjectOutputStream
*/
public static OutputStream NULL_OUTPUT_STREAM = new OutputStream() {
public void close() {
@@ -93,9 +94,9 @@
};
/**
- * Creates the simplest possible scene graph. 1 Camera, 1 Layer, 1
Root
+ * Creates the simplest possible scene graph. 1 Camera, 1 Layer, 1 Root
*
- * @return a basic scene with 1 camera, layer and root
+ * @return a basic scene with 1 camera, layer and root
*/
public static PCamera createBasicScenegraph() {
final PRoot root = new PRoot();
@@ -109,6 +110,14 @@
return camera;
}
+ /**
+ * Serializes the given stroke object to the object output stream
provided.
+ * By default strokes are not serializable. This method solves that
problem.
+ *
+ * @param stroke stroke to be serialized
+ * @param out stream to which the stroke is to be serialized.
+ * @throws IOException
+ */
public static void writeStroke(final Stroke stroke, final
ObjectOutputStream out) throws IOException {
if (stroke instanceof Serializable) {
out.writeBoolean(true);
@@ -146,6 +155,16 @@
out.writeFloat(basicStroke.getDashPhase());
}
+ /**
+ * Reconstitutes a stroke from the provided Object Input Stream.
According
+ * to the scheme found in writeStroke. By default strokes are not
+ * serializable.
+ *
+ * @param in stream from which Stroke is to be read
+ * @return a stroke object
+ * @throws IOException
+ * @throws ClassNotFoundException
+ */
public static Stroke readStroke(final ObjectInputStream in) throws
IOException, ClassNotFoundException {
final boolean wroteStroke = in.readBoolean();
if (!wroteStroke) {
@@ -180,6 +199,15 @@
return new BasicStroke(lineWidth, endCap, lineJoin, miterLimit,
dash, dashPhase);
}
+ /**
+ * Reads a path from the provided inputStream in accordance with the
+ * serialization policy defined in writePath.
+ *
+ * @param in stream from which to read the path.
+ * @return reconstituted path
+ * @throws IOException
+ * @throws ClassNotFoundException
+ */
public static GeneralPath readPath(final ObjectInputStream in) throws
IOException, ClassNotFoundException {
final GeneralPath path = new GeneralPath();
@@ -217,6 +245,13 @@
}
}
+ /**
+ * Serializes the given path to the provided Object Output Stream.
+ *
+ * @param path path to be serialized
+ * @param out stream to which the path should be serialized
+ * @throws IOException
+ */
public static void writePath(final GeneralPath path, final
ObjectOutputStream out) throws IOException {
final PathIterator i = path.getPathIterator(null);
final float[] data = new float[6];
--~--~---------~--~----~------------~-------~--~----~
Piccolo2D Developers Group: http://groups.google.com/group/piccolo2d-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
