From: Jouni Koivuviita Date: Mon, 1 Oct 2007 07:49:27 +0000 (+0000) Subject: Code cleanup and documentation. Ready for first code-review. X-Git-Tag: 6.7.0.beta1~5941 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=9b5782c160059b210a2241a10f3ba7da2f4ef3b2;p=vaadin-framework.git Code cleanup and documentation. Ready for first code-review. svn changeset:2398/svn branch:trunk --- diff --git a/src/com/itmill/toolkit/ui/Slider.java b/src/com/itmill/toolkit/ui/Slider.java index 5210093104..495eac6dc8 100644 --- a/src/com/itmill/toolkit/ui/Slider.java +++ b/src/com/itmill/toolkit/ui/Slider.java @@ -6,71 +6,93 @@ import com.itmill.toolkit.terminal.PaintException; import com.itmill.toolkit.terminal.PaintTarget; public class Slider extends AbstractField { - + public static final int ORIENTATION_HORIZONTAL = 0; + public static final int ORIENTATION_VERTICAL = 1; - + /** Minimum value of slider */ private double min = 0; + /** Maximum value of slider */ private double max = 100; - + /** * Resolution, how many digits are considered relevant after desimal point. - * Must be a non-negative value + * Must be a non-negative value */ private int resolution = 0; - + /** - * Slider orientation (horizontal==default/vertical). + * Slider orientation (horizontal/vertical), defaults . */ private int orientation = ORIENTATION_HORIZONTAL; - + /** - * Slider size in pixels. - * In horizontal mode if set to -1, allow 100% with container. - * In vertical mode if set to -1, default height 120 pixels. + * Slider size in pixels. In horizontal mode, if set to -1, allow 100% width + * of container. In vertical mode, if set to -1, default height is + * determined by the client-side implementation. */ private int size = -1; - + /** - * Handle size in percents related to base size. - * Must be a value between 1-99. Other values are converted to nearest bound. - * A negative value sets the width to auto (client calculates). + * Handle (draggable control element) size in percents relative to base + * size. Must be a value between 1-99. Other values are converted to nearest + * bound. A negative value sets the width to auto (client-side + * implementation calculates). */ private int handleSize = -1; - + /** - * Show arrows that can be pressed to slide the - * handle in some increments (client-side - * implementation decides the increment). + * Show arrows that can be pressed to slide the handle in some increments + * (client-side implementation decides the increment, usually somewhere + * between 5-10% of slide range). */ private boolean arrows = true; - + + /** + * Default Slider constructor. Sets all values to defaults and the slide + * handle at minimum value. + * + */ public Slider() { super(); super.setValue(new Double(min)); } - + + /** + * Create a new slider with the caption given as parameter. All slider + * values set to defaults. + * + * @param caption + * The caption for this Slider (e.g. "Volume"). + */ public Slider(String caption) { this(); setCaption(caption); } - + + /** + * Create a new slider with given range and resolution + * + * @param min + * @param max + * @param resolution + */ public Slider(double min, double max, int resolution) { this(); setMin(min); setMax(max); setResolution(resolution); } - + public Slider(int min, int max) { this(); setMin(min); setMax(max); setResolution(0); } - + public Slider(String caption, int min, int max) { this(min, max); setCaption(caption); @@ -81,15 +103,18 @@ public class Slider extends AbstractField { } /** - * Set the maximum value of the Slider. As a side-effect nullifies the "values" Set. + * Set the maximum value of the Slider. If the current value of the Slider + * is out of new bounds, the value is set to new minimum. + * * @param max + * New maximum value of the Slider. */ public void setMax(double max) { this.max = max; try { - if((new Double(getValue().toString())).doubleValue() > max) - super.setValue(new Double(min)); - } catch(ClassCastException e) { + if ((new Double(getValue().toString())).doubleValue() > max) + super.setValue(new Double(max)); + } catch (ClassCastException e) { super.setValue(new Double(max)); } requestRepaint(); @@ -98,129 +123,218 @@ public class Slider extends AbstractField { public double getMin() { return min; } - + /** - * Set the minimum value of the Slider. As a side-effect nullifies the "values" Set. - * @param max + * Set the minimum value of the Slider. If the current value of the Slider + * is out of new bounds, the value is set to new minimum. + * + * @param min + * New minimum value of the Slider. */ public void setMin(double min) { this.min = min; try { - if((new Double(getValue().toString())).doubleValue() < min) + if ((new Double(getValue().toString())).doubleValue() < min) super.setValue(new Double(min)); - } catch(ClassCastException e) { + } catch (ClassCastException e) { super.setValue(new Double(min)); } requestRepaint(); } + /** + * Get the current orientation of the Slider (horizontal or vertical). + * + * @return orientation + */ public int getOrientation() { return orientation; } + /** + * Set the orientation of the Slider. + * + * @param int + * new orientation + */ public void setOrientation(int orientation) { this.orientation = orientation; requestRepaint(); } + /** + * Get the current resolution of the Slider. + * + * @return resolution + */ public int getResolution() { return resolution; } + /** + * Set a new resolution for the Slider. + * + * @param resolution + */ public void setResolution(int resolution) { - if(resolution < 0) + if (resolution < 0) return; this.resolution = resolution; requestRepaint(); } - public void setValue(Double value, boolean repaintIsNotNeeded) throws ValueOutOfBoundsException { - double v = new Double(value.toString()).doubleValue(); + /** + * Set the value of this Slider. + * + * @param value + * New value of Slider. Must be within Sliders range (min - max), + * otherwise throws an exception. + * @param repaintIsNotNeeded + * If true, client-side is not requested to repaint itself. + * @throws ValueOutOfBoundsException + */ + public void setValue(Double value, boolean repaintIsNotNeeded) + throws ValueOutOfBoundsException { + double v = value.doubleValue(); double newValue; - if(resolution>0) { + if (resolution > 0) { // Round up to resolution newValue = (int) (v * (double) Math.pow(10, resolution)); newValue = newValue / (double) Math.pow(10, resolution); - if(min > newValue || max < newValue) + if (min > newValue || max < newValue) throw new ValueOutOfBoundsException(value); } else { newValue = (int) v; - if(min > newValue || max < newValue) + if (min > newValue || max < newValue) throw new ValueOutOfBoundsException(value); } super.setValue(new Double(newValue), repaintIsNotNeeded); } - + + /** + * Set the value of this Slider. + * + * @param value + * New value of Slider. Must be within Sliders range (min - max), + * otherwise throws an exception. + * @throws ValueOutOfBoundsException + */ public void setValue(Double value) throws ValueOutOfBoundsException { setValue(value, false); } + /** + * Set the value of this Slider. + * + * @param value + * New value of Slider. Must be within Sliders range (min - max), + * otherwise throws an exception. + * @throws ValueOutOfBoundsException + */ + public void setValue(double value) throws ValueOutOfBoundsException { + setValue(new Double(value), false); + } + + /** + * Get the current Slider size. + * + * @return size in pixels or -1. + */ public int getSize() { return size; } + /** + * Set the size for this Slider. + * + * @param size + * in pixels, or -1 auto sizing. + */ public void setSize(int size) { this.size = size; requestRepaint(); } + /** + * Get the handle size of this Slider. + * + * @return handle size in percentages. + */ public int getHandleSize() { return handleSize; } + /** + * Set the handle size of this Slider. + * + * @param handleSize + * in percentages relative to slider base size. + */ public void setHandleSize(int handleSize) { - if(handleSize < 0) + if (handleSize < 0) this.handleSize = -1; - else if(handleSize > 99) + else if (handleSize > 99) this.handleSize = 99; - else if(handleSize < 1) + else if (handleSize < 1) this.handleSize = 1; - else this.handleSize = handleSize; + else + this.handleSize = handleSize; requestRepaint(); } - + + /** + * Show or hide slider arrows. + * + * @param visible + */ public void setArrows(boolean visible) { arrows = visible; requestRepaint(); } - - public boolean arrowsVisible() { + + /** + * Does the slider have arrows? + * + * @return arrows visible + */ + public boolean isArrowsVisible() { return arrows; } public String getTag() { return "slider"; } - + public void paintContent(PaintTarget target) throws PaintException { super.paintContent(target); - + target.addAttribute("min", min); - if(max > min) + if (max > min) target.addAttribute("max", max); else target.addAttribute("max", min); target.addAttribute("resolution", resolution); - - if(resolution > 0) - target.addVariable(this, "value", ((Double)getValue()).doubleValue()); + + if (resolution > 0) + target.addVariable(this, "value", ((Double) getValue()) + .doubleValue()); else - target.addVariable(this, "value", ((Double)getValue()).intValue()); - - if(orientation == ORIENTATION_VERTICAL) + target.addVariable(this, "value", ((Double) getValue()).intValue()); + + if (orientation == ORIENTATION_VERTICAL) target.addAttribute("vertical", true); - - if(arrows) + + if (arrows) target.addAttribute("arrows", true); - - if(size > -1) + + if (size > -1) target.addAttribute("size", size); - - if(min != max && min < max) + + if (min != max && min < max) target.addAttribute("hsize", handleSize); else target.addAttribute("hsize", 100); - + } /** @@ -234,45 +348,52 @@ public class Slider extends AbstractField { if (variables.containsKey("value")) { Object value = variables.get("value"); Double newValue = new Double(value.toString()); - if(newValue != null && newValue != getValue() && !newValue.equals(getValue())) { + if (newValue != null && newValue != getValue() + && !newValue.equals(getValue())) { try { setValue(newValue, true); - } catch(ValueOutOfBoundsException e) { + } catch (ValueOutOfBoundsException e) { // Convert to nearest bound double out = e.getValue().doubleValue(); - if(out < min) + if (out < min) out = min; - if(out > max) + if (out > max) out = max; super.setValue(new Double(out), false); } } } } - + + /** + * ValueOutOfBoundsException + * + * @author IT Mill Ltd. + * + */ public class ValueOutOfBoundsException extends Exception { /** * Serial generated by Eclipse. */ private static final long serialVersionUID = -6451298598644446340L; - + private Double value; - + /** - * Constructs an ValueOutOfBoundsException with the specified - * detail message. + * Constructs an ValueOutOfBoundsException with the + * specified detail message. * * @param valueOutOfBounds */ public ValueOutOfBoundsException(Double valueOutOfBounds) { this.value = valueOutOfBounds; } - + public Double getValue() { return this.value; } - + } public Class getType() {