Author: rwhitcomb
Date: Sat Feb 24 01:46:52 2018
New Revision: 1825187
URL: http://svn.apache.org/viewvc?rev=1825187&view=rev
Log:
PIVOT-1031: Add/update the Javadoc in the Gauge class and its skin class.
Also, fix a couple of pieces of logic if the min/max or current values were
not set in the gauge to use defaults in the paint code (0, 100).
Set more of the colors by default in the skin, and then take out the (now)
default colors that were set in the "gauge_text.bxml" sample.
Modified:
pivot/trunk/tests/src/org/apache/pivot/tests/gauge_test.bxml
pivot/trunk/wtk-terra/src/org/apache/pivot/wtk/skin/terra/TerraGaugeSkin.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Gauge.java
Modified: pivot/trunk/tests/src/org/apache/pivot/tests/gauge_test.bxml
URL:
http://svn.apache.org/viewvc/pivot/trunk/tests/src/org/apache/pivot/tests/gauge_test.bxml?rev=1825187&r1=1825186&r2=1825187&view=diff
==============================================================================
--- pivot/trunk/tests/src/org/apache/pivot/tests/gauge_test.bxml (original)
+++ pivot/trunk/tests/src/org/apache/pivot/tests/gauge_test.bxml Sat Feb 24
01:46:52 2018
@@ -27,7 +27,7 @@ limitations under the License.
<TablePane.Row height="-1">
<Border title="Speed" styles="{backgroundColor:10}">
<Gauge bxml:id="speedGauge" origin="SOUTH" type="Integer"
minValue="0" maxValue="200" value="0" warningLevel="120" criticalLevel="180"
- styles="{gaugeColor:8, backgroundColor:10,
color:'green', warningColor:20, criticalColor:23, font:{size:20}},
thickness:10.0"/>
+ styles="{backgroundColor:10, criticalColor:23,
font:{size:20}}, thickness:10.0"/>
</Border>
</TablePane.Row>
<TablePane.Row height="-1">
Modified:
pivot/trunk/wtk-terra/src/org/apache/pivot/wtk/skin/terra/TerraGaugeSkin.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk-terra/src/org/apache/pivot/wtk/skin/terra/TerraGaugeSkin.java?rev=1825187&r1=1825186&r2=1825187&view=diff
==============================================================================
---
pivot/trunk/wtk-terra/src/org/apache/pivot/wtk/skin/terra/TerraGaugeSkin.java
(original)
+++
pivot/trunk/wtk-terra/src/org/apache/pivot/wtk/skin/terra/TerraGaugeSkin.java
Sat Feb 24 01:46:52 2018
@@ -43,6 +43,11 @@ import org.apache.pivot.wtk.Theme;
import org.apache.pivot.wtk.skin.ComponentSkin;
+/**
+ * Skin class for the {@link Gauge} component, which draws a circular gauge
with possible text
+ * in the center.
+ * <p> The gauge colors, as well as colors for the warning and/or critical
colors can be set.
+ */
public class TerraGaugeSkin<T extends Number> extends ComponentSkin implements
GaugeListener<T> {
private static final float STROKE_WIDTH = 6.0f;
@@ -71,8 +76,13 @@ public class TerraGaugeSkin<T extends Nu
public TerraGaugeSkin() {
// TODO: set the rest of the default stuff (colors, etc.)
font = currentTheme().getFont().deriveFont(Font.BOLD, 24.0f);
- backgroundColor = defaultBackgroundColor();
- padding = Insets.NONE;
+ setBackgroundColor(defaultBackgroundColor());
+ setGaugeColor(8);
+ setColor(Color.green);
+ setWarningColor(20);
+ setCriticalColor(23);
+ setTextColor(8);
+ setPadding(Insets.NONE);
}
@Override
@@ -84,6 +94,9 @@ public class TerraGaugeSkin<T extends Nu
gauge.getGaugeListeners().add(this);
}
+ /**
+ * This is a "display-only" component, so as such will not accept focus.
+ */
@Override
public boolean isFocusable() {
return false;
@@ -140,11 +153,11 @@ public class TerraGaugeSkin<T extends Nu
Rectangle2D rect = new Rectangle2D.Float(x, y, diameter, diameter);
- float minValue = minLevel.floatValue();
- float maxValue = maxLevel.floatValue();
+ float minValue = minLevel == null ? 0.0f : minLevel.floatValue();
+ float maxValue = maxLevel == null ? 100.0f : maxLevel.floatValue();
float fullRange = maxValue - minValue;
float toAngle = 360.0f / fullRange;
- float activeValue = value.floatValue() - minValue;
+ float activeValue = (value == null ? 0.0f : value.floatValue()) -
minValue;
float activeAngle = activeValue * toAngle;
if (backgroundColor != null) {
@@ -317,6 +330,15 @@ public class TerraGaugeSkin<T extends Nu
return this.warningColor;
}
+ /**
+ * Set the warning color to use for the portion of the value display when
the
+ * value exceeds the gauge's warning level.
+ * <p> Note: one, two, or three colors may be displayed depending on the
warning
+ * and critical levels (and whether they are set), and the warning and
critical
+ * colors (and whether they are set) (and of course what the value is).
+ * @param warningColor A color for the warning levels, or {@code null} to
disable
+ * the warning level checks.
+ */
public final void setWarningColor(Color warningColor) {
// Note: null is okay here to effectively disable using the warning
color logic
this.warningColor = warningColor;
@@ -336,6 +358,15 @@ public class TerraGaugeSkin<T extends Nu
return this.criticalColor;
}
+ /**
+ * Set the critical color to use for the portion of the value display when
the
+ * value exceeds the gauge's critical level.
+ * <p> Note: one, two, or three colors may be displayed depending on the
warning
+ * and critical levels (and whether they are set), and the warning and
critical
+ * colors (and whether they are set) (and of course what the value is).
+ * @param criticalColor A color for the critical levels, or {@code null}
to disable
+ * the critical level checks.
+ */
public final void setCriticalColor(Color criticalColor) {
// Note: null is okay here to disable using the critical color logic
this.criticalColor = criticalColor;
@@ -361,26 +392,66 @@ public class TerraGaugeSkin<T extends Nu
invalidateComponent();
}
+ /**
+ * Sets the amount of space to leave between the edge of the gauge area and
+ * the actual drawing.
+ *
+ * @param padding A dictionary containing the keys {top ,left, bottom,
and/or right}.
+ */
public final void setPadding(Dictionary<String, ?> padding) {
setPadding(new Insets(padding));
}
+ /**
+ * Sets the amount of space to leave between the edge of the gauge area and
+ * the actual drawing.
+ *
+ * @param padding A sequence containing the values [top left, bottom,
right].
+ */
public final void setPadding(Sequence<?> padding) {
setPadding(new Insets(padding));
}
+ /**
+ * Sets the amount of space to leave between the edge of the gauge area and
+ * the actual drawing.
+ *
+ * @param padding A single value to use for the padding on all sides.
+ */
public final void setPadding(int padding) {
setPadding(new Insets(padding));
}
+ /**
+ * Sets the amount of space to leave between the edge of the gauge area and
+ * the actual drawing.
+ *
+ * @param padding A single value to use for the padding on all sides.
+ */
public void setPadding(Number padding) {
setPadding(new Insets(padding));
}
+ /**
+ * Sets the amount of space to leave between the edge of the gauge area and
+ * the actual drawing.
+ *
+ * @param padding A string containing an integer or a JSON map or list with
+ * keys/values top, left, bottom, and/or right.
+ */
+ public final void setPadding(String padding) {
+ setPadding(Insets.decode(padding));
+ }
+
public float getThickness() {
return thickness;
}
+ /**
+ * Set the thickness of the value display.
+ * @param thickness The new value (default is {@link #STROKE_WIDTH}).
+ * @throws IllegalArgumentException if the value is 0.0 or less.
+ */
public final void setThickness(float thickness) {
Utils.checkPositive(thickness, "thickness");
@@ -398,17 +469,6 @@ public class TerraGaugeSkin<T extends Nu
setThickness(StringUtils.toNumber(thickness, Float.class));
}
- /**
- * Sets the amount of space to leave between the edge of the Border and its
- * content.
- *
- * @param padding A string containing an integer or a JSON dictionary with
- * keys left, top, bottom, and/or right.
- */
- public final void setPadding(String padding) {
- setPadding(Insets.decode(padding));
- }
-
@Override
public void originChanged(Gauge<T> gauge, Origin previousOrigin) {
invalidateComponent();
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Gauge.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Gauge.java?rev=1825187&r1=1825186&r2=1825187&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Gauge.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Gauge.java Sat Feb 24 01:46:52 2018
@@ -36,12 +36,20 @@ public class Gauge<T extends Number> ext
/** Runtime class (used to check values at runtime). */
private Class<? extends Number> clazz;
+ /**
+ * Default constructor for this component, with the default {@link Origin}
+ * value (which is <tt>NORTH</tt>).
+ */
public Gauge() {
this(Origin.NORTH);
}
+ /**
+ * Constructor for a new gauge object, using the given {@link Origin}
value.
+ * @param origin The "origin" or zero point of the gauge (a compass
direction).
+ */
public Gauge(Origin origin) {
- this.origin = origin;
+ setOrigin(origin);
installSkin(Gauge.class);
}
@@ -49,6 +57,13 @@ public class Gauge<T extends Number> ext
return this.origin;
}
+ /**
+ * Set the "origin" value for this gauge, that is, the point in the circle
where
+ * drawing of the value starts (one of the main compass directions). The
gauge
+ * value will always be drawn clockwise starting from the origin location.
+ * @param origin The new origin value.
+ * @throws IllegalArgumentException if the origin value is {@code null}.
+ */
public void setOrigin(Origin origin) {
Utils.checkNull(origin, "origin");
@@ -60,19 +75,35 @@ public class Gauge<T extends Number> ext
}
}
+ /**
+ * Since this is a generic component that can take any numeric type, for
BXML we need
+ * to specify the specific type of the value (which is also needed for the
min/max and
+ * warning/critical values).
+ * @param typeName The type name for the value of this component. For
convenience you can
+ * specify just "Integer", "Short", "BigDecimal", or any other subclass of
{@link Number}
+ * here, or you can give the fully-qualified name.
+ */
@SuppressWarnings("unchecked")
- public void setType(String type) {
+ public void setType(String typeName) {
try {
- this.clazz = (Class<? extends Number>)((type.indexOf('.') < 0) ?
Class.forName("java.lang." + type) :
- Class.forName(type));
+ this.clazz = (Class<? extends Number>)((typeName.indexOf('.') < 0)
?
+ Class.forName("java.lang." + typeName) :
+ Class.forName(typeName));
} catch (ClassNotFoundException cnfe) {
- throw new RuntimeException(cnfe);
+ if (typeName.indexOf('.') < 0) {
+ // Try "java.math" (for BigDecimal, etc.) types
+ try {
+ this.clazz = (Class<? extends
Number>)Class.forName("java.math." + typeName);
+ } catch (ClassNotFoundException cnfe2) {
+ throw new RuntimeException(cnfe);
+ }
+ }
}
}
/**
- * If the {@link #clazz} was set by a prior call to {@link #setType} then
- * check the runtime class of the value against it, otherwise call {@link
#setType}
+ * If the {@link #clazz} was set by a prior call to {@link #setType
setType()} then
+ * check the runtime class of the value against it, otherwise call {@link
#setType setType()}
* to establish it for the future.
*
* @param value A value presumably compatible with the declared type of
this gauge.
@@ -89,10 +120,20 @@ public class Gauge<T extends Number> ext
}
}
+ /**
+ * @return The current (single) value assigned to this component.
+ */
public T getValue() {
return value;
}
+ /**
+ * Sets the current value displayed by the gauge.
+ * @param value The new value, of the same type as declared for the gauge.
+ * @throws ClassCastException if the type of this value is not what was
given
+ * by the {@link #setType setType()} call or any previous call to the
<tt>"setXXXValue"</tt>
+ * methods (which all call {@link #setOrCheckClass}).
+ */
public void setValue(T value) {
Utils.checkNull(value, "value");
setOrCheckClass(value);
@@ -105,6 +146,13 @@ public class Gauge<T extends Number> ext
}
}
+ /**
+ * Used by BXML to set the value. Converts String to a Number using the
+ * {@link StringUtils#toNumber StringUtils.toNumber()} method, giving the
class value set by
+ * {@link #setType setType()}.
+ * @param value The string value to convert to a number.
+ * @see #setValue
+ */
@SuppressWarnings("unchecked")
public void setValue(String value) {
setValue((T)StringUtils.toNumber(value, clazz));
@@ -114,6 +162,14 @@ public class Gauge<T extends Number> ext
return minValue;
}
+ /**
+ * Set the minimum value for this gauge, which will correspond to the
"origin"
+ * value of the display. Values given by {@link #setValue} will be offset
by
+ * this minimum value before display.
+ * @param minValue The new minimum value for the gauge.
+ * @throws ClassCastException if this value is not null and not of the same
+ * type as previous values set on this gauge.
+ */
public void setMinValue(T minValue) {
if (minValue != null) {
setOrCheckClass(minValue);
@@ -127,6 +183,12 @@ public class Gauge<T extends Number> ext
}
}
+ /**
+ * Used by BXML to set the minimum value. Converts string to number using
the
+ * {@link StringUtils#toNumber StringUtils.toNumber()} method.
+ * @param minValue The string value to convert to a minimum value.
+ * @throws IllegalArgumentException if the input is null or empty.
+ */
@SuppressWarnings("unchecked")
public void setMinValue(String minValue) {
setMinValue((T)StringUtils.toNumber(minValue, clazz));
@@ -136,6 +198,14 @@ public class Gauge<T extends Number> ext
return maxValue;
}
+ /**
+ * Set the maximum value for this gauge, which will correspond to 360
degrees
+ * after the origin of the display. Values given by {@link #setValue} will
be
+ * limited to this maximum value for display.
+ * @param maxValue The new maximum value for the gauge.
+ * @throws ClassCastException if this value is not null and not of the same
+ * type as previous values set on this gauge.
+ */
public void setMaxValue(T maxValue) {
if (maxValue != null) {
setOrCheckClass(maxValue);
@@ -149,6 +219,12 @@ public class Gauge<T extends Number> ext
}
}
+ /**
+ * Used by BXML to set the maximum value. Converts string to number using
the
+ * {@link StringUtils#toNumber StringUtils.toNumber()} method.
+ * @param maxValue The string value to convert to a maximum value.
+ * @throws IllegalArgumentException if the input is null or empty.
+ */
@SuppressWarnings("unchecked")
public void setMaxValue(String maxValue) {
setMaxValue((T)StringUtils.toNumber(maxValue, clazz));
@@ -158,6 +234,18 @@ public class Gauge<T extends Number> ext
return this.warningLevel;
}
+ /**
+ * Set a level at which the gauge will start showing "warning" indication
+ * (basically the warning color set in the skin).
+ * <p> If the warning (or critical) value is set to <tt>null</tt>, and/or
+ * the warning (or critical) color is set to <tt>null</tt> then the display
+ * will always be the same color, no matter the value.
+ * <p> The assumption is that the warning level will be less than the
critical
+ * level, and both will be in the range of the min - max values (this is
not
+ * currently checked anywhere).
+ * @param warningLevel A value of the same type as the other values for
+ * this gauge at which to set the warning threshold (can be {@code null}).
+ */
public final void setWarningLevel(T warningLevel) {
if (warningLevel != null) {
setOrCheckClass(warningLevel);
@@ -166,6 +254,11 @@ public class Gauge<T extends Number> ext
this.warningLevel = warningLevel;
}
+ /**
+ * Set the warning level from a string representation of a number.
+ * @param warningLevel New value.
+ * @see #setValue(String)
+ */
@SuppressWarnings("unchecked")
public void setWarningLevel(String warningLevel) {
setWarningLevel((T)StringUtils.toNumber(warningLevel, clazz));
@@ -175,6 +268,18 @@ public class Gauge<T extends Number> ext
return this.criticalLevel;
}
+ /**
+ * Set a level at which the gauge will start showing "critical" indication
+ * (basically the critical color set in the skin).
+ * <p> If the critical (or warning) value is set to <tt>null</tt>, and/or
+ * the critical (or warning) color is set to <tt>null</tt> then the display
+ * will always be the same color, no matter the value.
+ * <p> The assumption is that the warning level will be less than the
critical
+ * level, and both will be in the range of the min - max values (this is
not
+ * currently checked anywhere).
+ * @param criticalLevel A value of the same type as the other values for
+ * this gauge at which to set the critical threshold (can be {@code null}).
+ */
public final void setCriticalLevel(T criticalLevel) {
if (criticalLevel != null) {
setOrCheckClass(criticalLevel);
@@ -183,6 +288,11 @@ public class Gauge<T extends Number> ext
this.criticalLevel = criticalLevel;
}
+ /**
+ * Set the critical level from a string representation of a number.
+ * @param criticalLevel New value.
+ * @see #setValue(String)
+ */
@SuppressWarnings("unchecked")
public void setCriticalLevel(String criticalLevel) {
setCriticalLevel((T)StringUtils.toNumber(criticalLevel, clazz));
@@ -192,6 +302,10 @@ public class Gauge<T extends Number> ext
return this.text;
}
+ /**
+ * Set the text string to be displayed in the middle of the gauge.
+ * @param text The new text to be shown (can be <tt>null</tt> or empty).
+ */
public void setText(String text) {
// Null text is allowed
String previousText = this.text;
