From 0fd630341f78d17225d2f1a1e774981da3115721 Mon Sep 17 00:00:00 2001
From: Matti Tahvonen <matti.tahvonen@itmill.com>
Date: Wed, 12 Nov 2008 07:53:27 +0000
Subject: [PATCH] javadocs for expand ratio methods

svn changeset:5867/svn branch:trunk
---
 src/com/itmill/toolkit/ui/GridLayout.java    | 36 ++++++++++++++++----
 src/com/itmill/toolkit/ui/OrderedLayout.java | 31 +++++++++++++++--
 2 files changed, 58 insertions(+), 9 deletions(-)

diff --git a/src/com/itmill/toolkit/ui/GridLayout.java b/src/com/itmill/toolkit/ui/GridLayout.java
index 49aea44ce9..9f68f841a6 100644
--- a/src/com/itmill/toolkit/ui/GridLayout.java
+++ b/src/com/itmill/toolkit/ui/GridLayout.java
@@ -1163,7 +1163,17 @@ public class GridLayout extends AbstractLayout implements
     }
 
     /**
-     * TODO
+     * Sets the expand ratio of given column. Expand ratio defines how excess
+     * space is distributed among columns. Excess space means the space not
+     * consumed by non relatively sized components.
+     * 
+     * <p>
+     * By default excess space is distributed evenly.
+     * 
+     * <p>
+     * Note, that width needs to be defined for this method to have any effect.
+     * 
+     * @see #setWidth(float, int)
      * 
      * @param columnIndex
      * @param ratio
@@ -1173,10 +1183,12 @@ public class GridLayout extends AbstractLayout implements
     }
 
     /**
-     * TODO
+     * Returns the expand ratio of given column
+     * 
+     * @see #setColumnExpandRatio(int, float)
      * 
      * @param columnIndex
-     * @return
+     * @return the expand ratio, 0.0f by default
      */
     public float getColumnExpandRatio(int columnIndex) {
         Float r = columnExpandRatio.get(columnIndex);
@@ -1184,7 +1196,17 @@ public class GridLayout extends AbstractLayout implements
     }
 
     /**
-     * TODO
+     * Sets the expand ratio of given row. Expand ratio defines how excess space
+     * is distributed among rows. Excess space means the space not consumed by
+     * non relatively sized components.
+     * 
+     * <p>
+     * By default excess space is distributed evenly.
+     * 
+     * <p>
+     * Note, that height needs to be defined for this method to have any effect.
+     * 
+     * @see #setHeight(float, int)
      * 
      * @param rowIndex
      * @param ratio
@@ -1194,10 +1216,12 @@ public class GridLayout extends AbstractLayout implements
     }
 
     /**
-     * TODO
+     * Returns the expand ratio of given row.
+     * 
+     * @see #setRowExpandRatio(int, float)
      * 
      * @param rowIndex
-     * @return
+     * @return the expand ratio, 0.0f by default
      */
     public float getRowExpandRatio(int rowIndex) {
         Float r = rowExpandRatio.get(rowIndex);
diff --git a/src/com/itmill/toolkit/ui/OrderedLayout.java b/src/com/itmill/toolkit/ui/OrderedLayout.java
index 7ae96fc623..285f1a5df1 100644
--- a/src/com/itmill/toolkit/ui/OrderedLayout.java
+++ b/src/com/itmill/toolkit/ui/OrderedLayout.java
@@ -12,6 +12,7 @@ import java.util.Map.Entry;
 
 import com.itmill.toolkit.terminal.PaintException;
 import com.itmill.toolkit.terminal.PaintTarget;
+import com.itmill.toolkit.terminal.Sizeable;
 
 /**
  * Ordered layout.
@@ -360,9 +361,32 @@ public class OrderedLayout extends AbstractLayout implements
     }
 
     /**
-     * TODO
+     * <p>
+     * This method is used to control how excess space in layout is distributed
+     * among components. Excess space may exist if layout is sized and contained
+     * non relatively sized components don't consume all available space.
+     * 
+     * <p>
+     * Example how to distribute 1:3 (33%) for component1 and 2:3 (67%) for
+     * component2 :
+     * 
+     * <code>
+     * layout.setExpandRatio(component1, 1);<br>
+     * layout.setExpandRatio(component2, 2);
+     * </code>
+     * 
+     * <p>
+     * If no ratios have been set, the excess space is distributed evenly among
+     * all components.
+     * 
+     * <p>
+     * Note, that width or height (depending on orientation) needs to be defined
+     * for this method to have any effect.
+     * 
+     * @see Sizeable
      * 
      * @param component
+     *            the component which expand ratio is to be set
      * @param ratio
      */
     public void setExpandRatio(Component component, float ratio) {
@@ -370,10 +394,11 @@ public class OrderedLayout extends AbstractLayout implements
     };
 
     /**
-     * TODO
+     * Returns the expand ratio of given component.
      * 
      * @param component
-     * @return
+     *            which expand ratios is requested
+     * @return expand ratio of given component, 0.0f by default
      */
     public float getExpandRatio(Component component) {
         Float ratio = componentToExpandRatio.get(component);
-- 
2.39.5