Added JavaDoc for AbsoluteLayout (#4927).

svn changeset:13259/svn branch:6.3

1 files changed, 199 insertions, 15 deletions

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<Component> components = new LinkedHashSet<Component>();
+
+    // Maps each component to a position
     private Map<Component, ComponentPosition> componentToCoordinates = new HashMap<Component, ComponentPosition>();
 
+    /**
+     * Creates an AbsoluteLayout with full size.
+     */
     public AbsoluteLayout() {
         setSizeFull();
     }
 
+    /**
+     * Gets an iterator for going through all components enclosed in the
+     * absolute layout.
+     */
     public Iterator<Component> 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.
+     * <p>
+     * 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.
+     * </p>
+     * 
+     * @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<String, Object> parameters) {
         MouseEventDetails mouseDetails = MouseEventDetails
                 .deSerialize((String) parameters.get("mouseDetails"));