Author: rwhitcomb
Date: Tue Aug 25 11:48:07 2020
New Revision: 1881182
URL: http://svn.apache.org/viewvc?rev=1881182&view=rev
Log:
PIVOT-1032: Fix almost all the style errors in Dimensions, Insets, and Bounds
(add Javadoc, rename some parameters to fix visibility issues, make
parameters final, etc.)
Add a new "intersect(Dimensions)" method to Bounds along the way.
Modified:
pivot/trunk/wtk/src/org/apache/pivot/wtk/Bounds.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Dimensions.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Insets.java
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Bounds.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Bounds.java?rev=1881182&r1=1881181&r2=1881182&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Bounds.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Bounds.java Tue Aug 25 11:48:07
2020
@@ -32,30 +32,39 @@ import org.apache.pivot.util.Utils;
public final class Bounds implements Serializable {
private static final long serialVersionUID = -2473226417628417475L;
+ /** The X-position of the bounding area. */
public final int x;
+ /** The Y-position of the bounding area. */
public final int y;
+ /** The width of the area. */
public final int width;
+ /** The height of the area. */
public final int height;
+ /** The map key to retrieve the X position. */
public static final String X_KEY = "x";
+ /** The map key to retrieve the Y position. */
public static final String Y_KEY = "y";
+ /** The map key to retrieve the width. */
public static final String WIDTH_KEY = "width";
+ /** The map key to retrieve the height. */
public static final String HEIGHT_KEY = "height";
+ /** An empty (zero position and size) area. */
public static final Bounds EMPTY = new Bounds(0, 0, 0, 0);
/**
* Construct a bounds object given all four values for it.
- * @param x The starting X-position of the area.
- * @param y The starting Y-position.
- * @param width The width of the bounded area.
- * @param height The height of the area.
- */
- public Bounds(final int x, final int y, final int width, final int height)
{
- this.x = x;
- this.y = y;
- this.width = width;
- this.height = height;
+ * @param xPos The starting X-position of the area.
+ * @param yPos The starting Y-position.
+ * @param widthValue The width of the bounded area.
+ * @param heightValue The height of the area.
+ */
+ public Bounds(final int xPos, final int yPos, final int widthValue, final
int heightValue) {
+ this.x = xPos;
+ this.y = yPos;
+ this.width = widthValue;
+ this.height = heightValue;
}
/**
@@ -183,10 +192,10 @@ public final class Bounds implements Ser
* the given arguments.
*/
public Bounds union(final int xValue, final int yValue, final int
widthValue, final int heightValue) {
- int x1 = Math.min(this.x, xValue);
- int y1 = Math.min(this.y, yValue);
- int x2 = Math.max(this.x + this.width, xValue + widthValue);
- int y2 = Math.max(this.y + this.height, yValue + heightValue);
+ int x1 = Math.min(x, xValue);
+ int y1 = Math.min(y, yValue);
+ int x2 = Math.max(x + width, xValue + widthValue);
+ int y2 = Math.max(y + height, yValue + heightValue);
return new Bounds(x1, y1, x2 - x1, y2 - y1);
@@ -217,10 +226,10 @@ public final class Bounds implements Ser
* @return The new bounds that is the intersection of this one and the
given area.
*/
public Bounds intersect(final int xValue, final int yValue, final int
widthValue, final int heightValue) {
- int x1 = Math.max(this.x, xValue);
- int y1 = Math.max(this.y, yValue);
- int x2 = Math.min(this.x + this.width, xValue + widthValue);
- int y2 = Math.min(this.y + this.height, yValue + heightValue);
+ int x1 = Math.max(x, xValue);
+ int y1 = Math.max(y, yValue);
+ int x2 = Math.min(x + width, xValue + widthValue);
+ int y2 = Math.min(y + height, yValue + heightValue);
return new Bounds(x1, y1, x2 - x1, y2 - y1);
}
@@ -251,6 +260,19 @@ public final class Bounds implements Ser
}
/**
+ * @return A new bounds object that is the intersection of this one with
the given
+ * area defined by (0,0) to (width, height) of the size value.
+ * @param size The dimensions to intersect with (must not be {@code null}).
+ * @throws IllegalArgumentException if the dimension is {@code null}.
+ * @see #intersect(int, int, int, int)
+ */
+ public Bounds intersect(final Dimensions size) {
+ Utils.checkNull(size, "size");
+
+ return intersect(0, 0, size.width, size.height);
+ }
+
+ /**
* Create a new bounds object that represents this bounds offset by the
given
* values.
* <p> The new bounds has the same width and height, but the X- and
Y-positions
@@ -307,10 +329,8 @@ public final class Bounds implements Ser
* @return Whether this bounds contains the given point.
*/
public boolean contains(final int xValue, final int yValue) {
- return (xValue >= this.x
- && yValue >= this.y
- && xValue < this.x + width
- && yValue < this.y + height);
+ return (xValue >= x && yValue >= y
+ && xValue < x + width && yValue < y + height);
}
/**
@@ -336,13 +356,28 @@ public final class Bounds implements Ser
*/
public boolean contains(final int xValue, final int yValue, final int
widthValue, final int heightValue) {
return (!isEmpty()
- && xValue >= this.x
- && yValue >= this.y
- && xValue + widthValue <= this.x + this.width
- && yValue + heightValue <= this.y + this.height);
+ && xValue >= x && yValue >= y
+ && xValue + widthValue <= x + width && yValue + heightValue <= y
+ height);
}
/**
+ * Does this bounded area contain the X point defined by the given value?
+ * @param xValue The X-position to test.
+ * @return Whether this bounds contains the given X point.
+ */
+ public boolean containsX(final int xValue) {
+ return (xValue >= x && xValue < x + width);
+ }
+
+ /**
+ * Does this bounded area contain the Y point defined by the given value?
+ * @param yValue The Y-position to test.
+ * @return Whether this bounds contains the given Y point.
+ */
+ public boolean containsY(final int yValue) {
+ return (yValue >= y && yValue < y + height);
+ }
+ /**
* @return Does this bounded area intersect with the bounded area given by
the argument?
* @param bounds The other area to test (must not be {@code null}).
* @throws IllegalArgumentException if the given bounds is {@code null}.
@@ -363,10 +398,8 @@ public final class Bounds implements Ser
*/
public boolean intersects(final int xValue, final int yValue, final int
widthValue, final int heightValue) {
return (!isEmpty()
- && xValue + widthValue > this.x
- && yValue + heightValue > this.y
- && xValue < this.x + this.width
- && yValue < this.y + this.height);
+ && xValue + widthValue > x && yValue + heightValue > y
+ && xValue < x + width && yValue < y + height);
}
/**
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Dimensions.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Dimensions.java?rev=1881182&r1=1881181&r2=1881182&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Dimensions.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Dimensions.java Tue Aug 25
11:48:07 2020
@@ -30,29 +30,47 @@ import org.apache.pivot.util.Utils;
public final class Dimensions implements Serializable {
private static final long serialVersionUID = -3644511824857807902L;
+ /** The width value of the dimension. */
public final int width;
+ /** The height value of the dimension. */
public final int height;
+ /** The map key to retrieve the width value. */
public static final String WIDTH_KEY = "width";
+ /** The map key to retrieve the height value. */
public static final String HEIGHT_KEY = "height";
+ /** An empty (zero size) dimension value. */
public static final Dimensions ZERO = new Dimensions(0);
/**
* Construct a "square" dimensions that has the same width
* as height.
*
- * @param side The width and height of this dimensions.
+ * @param size The width and height of this dimension.
*/
- public Dimensions(final int side) {
- this.width = this.height = side;
+ public Dimensions(final int size) {
+ this.width = size;
+ this.height = size;
}
- public Dimensions(final int width, final int height) {
- this.width = width;
- this.height = height;
+ /**
+ * Construct a dimension with the given values.
+ *
+ * @param widthValue The width of the new dimension.
+ * @param heightValue The height of the new dimension.
+ */
+ public Dimensions(final int widthValue, final int heightValue) {
+ this.width = widthValue;
+ this.height = heightValue;
}
+ /**
+ * Construct new dimensions from the given dimensions.
+ *
+ * @param dimensions The existing dimensions to copy.
+ * @throws IllegalArgumentException if the given dimensions is {@code
null}.
+ */
public Dimensions(final Dimensions dimensions) {
Utils.checkNull(dimensions, "dimensions");
@@ -60,6 +78,14 @@ public final class Dimensions implements
this.height = dimensions.height;
}
+ /**
+ * Construct new dimensions from the given dictionary.
+ *
+ * @param dimensions The dictionary to lookup the new values from.
+ * @throws IllegalArgumentException if the dictionary value is {@code
null}.
+ * @see #WIDTH_KEY
+ * @see #HEIGHT_KEY
+ */
public Dimensions(final Dictionary<String, ?> dimensions) {
Utils.checkNull(dimensions, "dimensions");
@@ -67,6 +93,12 @@ public final class Dimensions implements
height = dimensions.getInt(HEIGHT_KEY, 0);
}
+ /**
+ * Construct new dimensions from the given sequence of {@link Number}
values.
+ *
+ * @param dimensions The sequence of dimension values in [width, height]
order.
+ * @throws IllegalArgumentException if the sequence value is {@code null}.
+ */
public Dimensions(final Sequence<?> dimensions) {
Utils.checkNull(dimensions, "dimensions");
@@ -78,11 +110,11 @@ public final class Dimensions implements
* Expand this dimensions by the given amount (positive or
* negative) in both width and height directions.
*
- * @param factor The amount to add to/subtract from both the width and
height.
+ * @param delta The amount to add to/subtract from both the width and
height.
* @return The new dimensions with the changed values.
*/
- public Dimensions expand(final int factor) {
- return new Dimensions(width + factor, height + factor);
+ public Dimensions expand(final int delta) {
+ return new Dimensions(width + delta, height + delta);
}
/**
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Insets.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Insets.java?rev=1881182&r1=1881181&r2=1881182&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Insets.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Insets.java Tue Aug 25 11:48:07
2020
@@ -31,14 +31,22 @@ import org.apache.pivot.util.Utils;
public final class Insets implements Serializable {
private static final long serialVersionUID = -8528862892185591370L;
+ /** Value for the top inset (or above the object). */
public final int top;
+ /** Value for the left inset (or to the left of the object). */
public final int left;
+ /** Value for the bottom inset (or below the object). */
public final int bottom;
+ /** Value for the right inset (or to the right of the object). */
public final int right;
+ /** Map key name for the "top" value. */
public static final String TOP_KEY = "top";
+ /** Map key name for the "left" value. */
public static final String LEFT_KEY = "left";
+ /** Map key name for the "bottom" value. */
public static final String BOTTOM_KEY = "bottom";
+ /** Map key name for the "right" value. */
public static final String RIGHT_KEY = "right";
/**
@@ -46,14 +54,24 @@ public final class Insets implements Ser
*/
public static final Insets NONE = new Insets(0);
- public Insets(int inset) {
+ /**
+ * Construct insets with all the same value.
+ *
+ * @param inset The pixel inset to use on all four sides.
+ */
+ public Insets(final int inset) {
this.top = inset;
this.left = inset;
this.bottom = inset;
this.right = inset;
}
- public Insets(Number inset) {
+ /**
+ * Construct insets with all the same integer value.
+ *
+ * @param inset The pixel value for all the insets (truncated to an
integer).
+ */
+ public Insets(final Number inset) {
Utils.checkNull(inset, "padding/margin");
int value = inset.intValue();
@@ -63,11 +81,19 @@ public final class Insets implements Ser
this.right = value;
}
- public Insets(int top, int left, int bottom, int right) {
- this.top = top;
- this.left = left;
- this.bottom = bottom;
- this.right = right;
+ /**
+ * Construct with different values for each side.
+ *
+ * @param topV The top inset value.
+ * @param leftV The left inset value.
+ * @param bottomV The bottom inset value.
+ * @param rightV The right inset value.
+ */
+ public Insets(final int topV, final int leftV, final int bottomV, final
int rightV) {
+ this.top = topV;
+ this.left = leftV;
+ this.bottom = bottomV;
+ this.right = rightV;
}
/**
@@ -83,7 +109,7 @@ public final class Insets implements Ser
* @see #getHeight
* @see #getWidth
*/
- public Insets(int height, int width) {
+ public Insets(final int height, final int width) {
this.top = height / 2;
// For odd height, assign the excess to the bottom
this.bottom = height - this.top;
@@ -103,11 +129,17 @@ public final class Insets implements Ser
* @param size The total size (height and width) to assign.
* @see #getSize
*/
- public Insets(Dimensions size) {
+ public Insets(final Dimensions size) {
this(size.height, size.width);
}
- public Insets(Insets insets) {
+ /**
+ * Copy an insets structure to a new one with the same values.
+ *
+ * @param insets The existing insets to copy (must not be null).
+ * @throws IllegalArgumentException if the input is null.
+ */
+ public Insets(final Insets insets) {
Utils.checkNull(insets, "padding/margin");
this.top = insets.top;
@@ -116,7 +148,13 @@ public final class Insets implements Ser
this.right = insets.right;
}
- public Insets(Dictionary<String, ?> insets) {
+ /**
+ * Construct a new set of insets given a dictionary with the values to use.
+ *
+ * @param insets The dictionary of values to use.
+ * @throws IllegalArgumentException if the input is null.
+ */
+ public Insets(final Dictionary<String, ?> insets) {
Utils.checkNull(insets, "padding/margin");
this.top = insets.getInt(TOP_KEY);
@@ -125,7 +163,14 @@ public final class Insets implements Ser
this.right = insets.getInt(RIGHT_KEY);
}
- public Insets(Sequence<?> insets) {
+ /**
+ * Construct a new set of insets given a sequence of values to use.
+ *
+ * @param insets The sequence of values to use in the order of [top, left,
+ * bottom, right].
+ * @throws IllegalArgumentException if the input is null.
+ */
+ public Insets(final Sequence<?> insets) {
Utils.checkNull(insets, "padding/margin");
this.top = ((Number) insets.get(0)).intValue();
@@ -164,7 +209,7 @@ public final class Insets implements Ser
}
@Override
- public boolean equals(Object object) {
+ public boolean equals(final Object object) {
boolean equals = false;
if (object instanceof Insets) {
@@ -211,7 +256,7 @@ public final class Insets implements Ser
* @see #Insets(int, int, int, int)
* @see #Insets(int)
*/
- public static Insets decode(String value) {
+ public static Insets decode(final String value) {
Utils.checkNullOrEmpty(value, "padding/margin");
Insets insets;
