From: John Alhroos Date: Wed, 19 May 2010 13:45:14 +0000 (+0000) Subject: Added JavaDoc for AbsoluteLayout (#4927). X-Git-Tag: 6.7.0.beta1~1656^2~5 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=73d3f5be936badec2cdc2b0e3793c0c93a33807b;p=vaadin-framework.git Added JavaDoc for AbsoluteLayout (#4927). svn changeset:13259/svn branch:6.3 --- diff --git a/src/com/vaadin/ui/AbsoluteLayout.java b/src/com/vaadin/ui/AbsoluteLayout.java index c3d6168426..f2964c58eb 100644 --- a/src/com/vaadin/ui/AbsoluteLayout.java +++ b/src/com/vaadin/ui/AbsoluteLayout.java @@ -28,17 +28,31 @@ public class AbsoluteLayout extends AbstractLayout { private static final String CLICK_EVENT = VAbsoluteLayout.CLICK_EVENT_IDENTIFIER; + // The components in the layout private Collection components = new LinkedHashSet(); + + // Maps each component to a position private Map componentToCoordinates = new HashMap(); + /** + * Creates an AbsoluteLayout with full size. + */ public AbsoluteLayout() { setSizeFull(); } + /** + * Gets an iterator for going through all components enclosed in the + * absolute layout. + */ public Iterator getComponentIterator() { return components.iterator(); } + /** + * Replaces one component with another one. The new component inherits the + * old components position. + */ public void replaceComponent(Component oldComponent, Component newComponent) { ComponentPosition position = getPosition(oldComponent); removeComponent(oldComponent); @@ -46,6 +60,13 @@ public class AbsoluteLayout extends AbstractLayout { componentToCoordinates.put(newComponent, position); } + /* + * (non-Javadoc) + * + * @see + * com.vaadin.ui.AbstractComponentContainer#addComponent(com.vaadin.ui.Component + * ) + */ @Override public void addComponent(Component c) { components.add(c); @@ -53,6 +74,13 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /* + * (non-Javadoc) + * + * @see + * com.vaadin.ui.AbstractComponentContainer#removeComponent(com.vaadin.ui + * .Component) + */ @Override public void removeComponent(Component c) { components.remove(c); @@ -60,11 +88,35 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /** + * Adds a component to the layout. The component can be positioned by + * providing a string formatted in CSS-format. + *

+ * For example the string "top:10px;left:10px" will position the component + * 10 pixels from the left and 10 pixels from the top. The identifiers: + * "top","left","right" and "bottom" can be used to specify the position. + *

+ * + * @param c + * The component to add to the layout + * @param cssPosition + * The css position string + */ public void addComponent(Component c, String cssPosition) { addComponent(c); getPosition(c).setCSSString(cssPosition); } + /** + * Gets the position of a component in the layout. Returns null if component + * is not attached to the layout. + * + * @param component + * The component which position is needed + * @return An instance of ComponentPosition containing the position of the + * component, or null if the component is not enclosed in the + * layout. + */ public ComponentPosition getPosition(Component component) { if (componentToCoordinates.containsKey(component)) { return componentToCoordinates.get(component); @@ -76,6 +128,10 @@ public class AbsoluteLayout extends AbstractLayout { } /** + * The CompontPosition class represents a components position within the + * absolute layout. It contains the CSS attributes for left, right, top and + * bottom and the units used to specify them. * + * * TODO symmetric getters and setters for fields to make this simpler to use * in generic java tools * @@ -143,6 +199,14 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /** + * Parses a string and checks if a unit is found. If a unit is not found + * from the string the unit pixels is used. + * + * @param string + * The string to parse the unit from + * @return The found unit + */ private int parseCssUnit(String string) { for (int i = 0; i < UNIT_SYMBOLS.length; i++) { if (UNIT_SYMBOLS[i].equals(string)) { @@ -152,6 +216,11 @@ public class AbsoluteLayout extends AbstractLayout { return 0; // defaults to px (eg. top:0;) } + /** + * Converts the internal values into a valid CSS string. + * + * @return A valid CSS string + */ public String getCSSString() { String s = ""; if (topValue != null) { @@ -172,6 +241,15 @@ public class AbsoluteLayout extends AbstractLayout { return s; } + /** + * Sets the 'top' CSS-attribute + * + * @param topValue + * The value of the 'top' attribute + * @param topUnits + * The unit of the 'top' attribute. See UNIT_SYMBOLS for a + * description of the available units. + */ public void setTop(float topValue, int topUnits) { validateLength(topValue, topUnits); this.topValue = topValue; @@ -179,6 +257,15 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /** + * Sets the 'right' CSS-attribute + * + * @param rightValue + * The value of the 'right' attribute + * @param rightUnits + * The unit of the 'right' attribute. See UNIT_SYMBOLS for a + * description of the available units. + */ public void setRight(float rightValue, int rightUnits) { validateLength(rightValue, rightUnits); this.rightValue = rightValue; @@ -186,6 +273,15 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /** + * Sets the 'bottom' CSS-attribute + * + * @param bottomValue + * The value of the 'bottom' attribute + * @param units + * The unit of the 'bottom' attribute. See UNIT_SYMBOLS for a + * description of the available units. + */ public void setBottom(float bottomValue, int units) { validateLength(bottomValue, units); this.bottomValue = bottomValue; @@ -193,6 +289,15 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /** + * Sets the 'left' CSS-attribute + * + * @param leftValue + * The value of the 'left' attribute + * @param units + * The unit of the 'left' attribute. See UNIT_SYMBOLS for a + * description of the available units. + */ public void setLeft(float leftValue, int units) { validateLength(leftValue, units); this.leftValue = leftValue; @@ -200,31 +305,52 @@ public class AbsoluteLayout extends AbstractLayout { requestRepaint(); } + /** + * Sets the 'z-index' CSS-attribute + * + * @param zIndex + * The z-index for the component. + */ public void setZIndex(int zIndex) { this.zIndex = zIndex; requestRepaint(); } + /** + * Sets the value of the 'top' CSS-attribute + * + * @param topValue + * The value of the 'left' attribute + */ public void setTopValue(float topValue) { validateLength(topValue, topUnits); this.topValue = topValue; requestRepaint(); } + /** + * Gets the 'top' CSS-attributes value in specified units. + * + * @return The value of the 'top' CSS-attribute + */ public float getTopValue() { return topValue == null ? 0 : rightValue.floatValue(); } /** - * @return the rightValue + * Gets the 'right' CSS-attributes value in specified units. + * + * @return The value of the 'right' CSS-attribute */ public float getRightValue() { return rightValue == null ? 0 : rightValue.floatValue(); } /** + * Sets the 'right' CSS-attributes value in specified units. + * * @param rightValue - * the rightValue to set + * The value of the 'right' CSS-attribute */ public void setRightValue(float rightValue) { validateLength(rightValue, rightUnits); @@ -233,15 +359,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the bottomValue + * Gets the 'bottom' CSS-attributes value in specified units. + * + * @return The value of the 'bottom' CSS-attribute */ public float getBottomValue() { return bottomValue == null ? 0 : bottomValue.floatValue(); } /** + * Sets the 'bottom' CSS-attributes value in specified units. + * * @param bottomValue - * the bottomValue to set + * The value of the 'bottom' CSS-attribute */ public void setBottomValue(float bottomValue) { validateLength(bottomValue, bottomUnits); @@ -250,15 +380,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the leftValue + * Gets the 'left' CSS-attributes value in specified units. + * + * @return The value of the 'left' CSS-attribute */ public float getLeftValue() { return leftValue == null ? 0 : leftValue.floatValue(); } /** + * Sets the 'left' CSS-attributes value in specified units. + * * @param leftValue - * the leftValue to set + * The value of the 'left' CSS-attribute */ public void setLeftValue(float leftValue) { validateLength(leftValue, leftUnits); @@ -267,15 +401,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the topUnits + * Gets the unit for the 'top' CSS-attribute + * + * @return See UNIT_SYMBOLS for a description of the available units. */ public int getTopUnits() { return topUnits; } /** + * Sets the unit for the 'top' CSS-attribute + * * @param topUnits - * the topUnits to set + * See UNIT_SYMBOLS for a description of the available units. */ public void setTopUnits(int topUnits) { validateLength(topValue, topUnits); @@ -284,15 +422,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the rightUnits + * Gets the unit for the 'right' CSS-attribute + * + * @return See UNIT_SYMBOLS for a description of the available units. */ public int getRightUnits() { return rightUnits; } /** + * Sets the unit for the 'right' CSS-attribute + * * @param rightUnits - * the rightUnits to set + * See UNIT_SYMBOLS for a description of the available units. */ public void setRightUnits(int rightUnits) { validateLength(rightValue, rightUnits); @@ -301,15 +443,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the bottomUnits + * Gets the unit for the 'bottom' CSS-attribute + * + * @return See UNIT_SYMBOLS for a description of the available units. */ public int getBottomUnits() { return bottomUnits; } /** + * Sets the unit for the 'bottom' CSS-attribute + * * @param bottomUnits - * the bottomUnits to set + * See UNIT_SYMBOLS for a description of the available units. */ public void setBottomUnits(int bottomUnits) { validateLength(bottomValue, bottomUnits); @@ -318,15 +464,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the leftUnits + * Gets the unit for the 'left' CSS-attribute + * + * @return See UNIT_SYMBOLS for a description of the available units. */ public int getLeftUnits() { return leftUnits; } /** + * Sets the unit for the 'left' CSS-attribute + * * @param leftUnits - * the leftUnits to set + * See UNIT_SYMBOLS for a description of the available units. */ public void setLeftUnits(int leftUnits) { validateLength(leftValue, leftUnits); @@ -335,12 +485,19 @@ public class AbsoluteLayout extends AbstractLayout { } /** - * @return the zIndex + * Gets the 'z-index' CSS-attribute. + * + * @return the zIndex The z-index attribute */ public int getZIndex() { return zIndex; } + /* + * (non-Javadoc) + * + * @see java.lang.Object#toString() + */ @Override public String toString() { return getCSSString(); @@ -348,6 +505,13 @@ public class AbsoluteLayout extends AbstractLayout { } + /* + * (non-Javadoc) + * + * @see + * com.vaadin.ui.AbstractLayout#paintContent(com.vaadin.terminal.PaintTarget + * ) + */ @Override public void paintContent(PaintTarget target) throws PaintException { super.paintContent(target); @@ -359,11 +523,25 @@ public class AbsoluteLayout extends AbstractLayout { } } + /** + * Validates a value with the unit + * + * @param topValue + * The value to validate + * @param topUnits2 + * The unit to validate + */ private static void validateLength(float topValue, int topUnits2) { // TODO throw on invalid value } + /* + * (non-Javadoc) + * + * @see com.vaadin.ui.AbstractComponent#changeVariables(java.lang.Object, + * java.util.Map) + */ @Override public void changeVariables(Object source, Map variables) { super.changeVariables(source, variables); @@ -373,6 +551,12 @@ public class AbsoluteLayout extends AbstractLayout { } + /** + * Fires a click event when the layout is clicked + * + * @param parameters + * The parameters recieved from the client side implementation + */ private void fireClick(Map parameters) { MouseEventDetails mouseDetails = MouseEventDetails .deSerialize((String) parameters.get("mouseDetails"));