From d5cba6be7088846d771f48ac93f06c2c87779b87 Mon Sep 17 00:00:00 2001
From: Marko Grönroos <magi@iki.fi>
Date: Wed, 2 Nov 2011 10:56:16 +0000
Subject: Corrected the Scrollable JavaDoc to correspond with the code.

svn changeset:21864/svn branch:6.7
---
 src/com/vaadin/terminal/Scrollable.java | 50 +++++++++++++++++++++++++++------
 src/com/vaadin/ui/Panel.java            | 40 ++++++++++++++++++++++----
 2 files changed, 76 insertions(+), 14 deletions(-)

diff --git a/src/com/vaadin/terminal/Scrollable.java b/src/com/vaadin/terminal/Scrollable.java
index 5f57a77e76..7f3a0cbd33 100644
--- a/src/com/vaadin/terminal/Scrollable.java
+++ b/src/com/vaadin/terminal/Scrollable.java
@@ -8,8 +8,9 @@ import java.io.Serializable;
 
 /**
  * <p>
- * This interface is implemented by all visual objects that can be scrolled. The
- * unit of scrolling is pixel.
+ * This interface is implemented by all visual objects that can be scrolled
+ * programmatically from the server-side, or for which it is possible to know
+ * the scroll position on the server-side. The unit of scrolling is pixel.
  * </p>
  * 
  * @author IT Mill Ltd.
@@ -39,6 +40,13 @@ public interface Scrollable extends Serializable {
      * scrolled right.
      * </p>
      * 
+     * <p>
+     * The method only has effect if programmatic scrolling is enabled for the
+     * scrollable. Some implementations may require enabling programmatic before
+     * this method can be used. See {@link #setScrollable(boolean)} for more
+     * information.
+     * </p>
+     * 
      * @param pixelsScrolled
      *            the xOffset.
      */
@@ -64,30 +72,54 @@ public interface Scrollable extends Serializable {
      * scrolled down.
      * </p>
      * 
+     * <p>
+     * The method only has effect if programmatic scrolling is enabled for the
+     * scrollable. Some implementations may require enabling programmatic before
+     * this method can be used. See {@link #setScrollable(boolean)} for more
+     * information.
+     * </p>
+     * 
+     * <p>
+     * The scrolling position is limited by the current height of the content
+     * area. If the position is below the height, it is scrolled to the bottom.
+     * However, if the same response also adds height to the content area,
+     * scrolling to bottom only scrolls to the bottom of the previous content
+     * area.
+     * </p>
+     * 
      * @param pixelsScrolled
      *            the yOffset.
      */
     public void setScrollTop(int pixelsScrolled);
 
     /**
-     * Is the scrolling enabled.
+     * Is programmatic scrolling enabled.
      * 
      * <p>
-     * Enabling scrolling allows the user to scroll the scrollable view
-     * interactively
+     * Whether programmatic scrolling with {@link #setScrollLeft(int)} and
+     * {@link #setScrollTop(int)} is enabled.
      * </p>
      * 
-     * @return <code>true</code> if the scrolling is allowed, otherwise
+     * @return <code>true</code> if the scrolling is enabled, otherwise
      *         <code>false</code>.
      */
     public boolean isScrollable();
 
     /**
-     * Enables or disables scrolling..
+     * Enables or disables programmatic scrolling.
+     * 
+     * <p>
+     * Enables setting the scroll position with {@link #setScrollLeft(int)} and
+     * {@link #setScrollTop(int)}. Implementations of the interface may have
+     * programmatic scrolling disabled by default, in which case you need to
+     * enable it to use the mentioned methods.
+     * </p>
      * 
      * <p>
-     * Enabling scrolling allows the user to scroll the scrollable view
-     * interactively
+     * Notice that this does <i>not</i> control whether scroll bars are shown
+     * for a scrollable component. That normally happens automatically when the
+     * content grows too big for the component, relying on the "overflow: auto"
+     * property in CSS.
      * </p>
      * 
      * @param isScrollingEnabled
diff --git a/src/com/vaadin/ui/Panel.java b/src/com/vaadin/ui/Panel.java
index 877171232e..999b45cfa3 100644
--- a/src/com/vaadin/ui/Panel.java
+++ b/src/com/vaadin/ui/Panel.java
@@ -405,8 +405,16 @@ public class Panel extends AbstractComponentContainer implements Scrollable,
         return scrollable;
     }
 
-    /*
-     * (non-Javadoc)
+    /**
+     * Sets the panel as programmatically scrollable.
+     * 
+     * <p>
+     * Panel is by default not scrollable programmatically with
+     * {@link #setScrollLeft(int)} and {@link #setScrollTop(int)}, so if you use
+     * those methods, you need to enable scrolling with this method. Components
+     * that extend Panel may have a different default for the programmatic
+     * scrollability.
+     * </p>
      * 
      * @see com.vaadin.terminal.Scrollable#setScrollable(boolean)
      */
@@ -417,10 +425,19 @@ public class Panel extends AbstractComponentContainer implements Scrollable,
         }
     }
 
-    /*
-     * (non-Javadoc)
+    /**
+     * Sets the horizontal scroll position.
+     * 
+     * <p>
+     * Setting the horizontal scroll position with this method requires that
+     * programmatic scrolling of the component has been enabled. For Panel it is
+     * disabled by default, so you have to call {@link #setScrollable(boolean)}.
+     * Components extending Panel may have a different default for programmatic
+     * scrollability.
+     * </p>
      * 
      * @see com.vaadin.terminal.Scrollable#setScrollLeft(int)
+     * @see #setScrollable(boolean)
      */
     public void setScrollLeft(int pixelsScrolled) {
         if (pixelsScrolled < 0) {
@@ -441,7 +458,20 @@ public class Panel extends AbstractComponentContainer implements Scrollable,
         setScrollLeft(pixels);
     }
 
-    /* Documented in interface */
+    /**
+     * Sets the vertical scroll position.
+     * 
+     * <p>
+     * Setting the vertical scroll position with this method requires that
+     * programmatic scrolling of the component has been enabled. For Panel it is
+     * disabled by default, so you have to call {@link #setScrollable(boolean)}.
+     * Components extending Panel may have a different default for programmatic
+     * scrollability.
+     * </p>
+     * 
+     * @see com.vaadin.terminal.Scrollable#setScrollTop(int)
+     * @see #setScrollable(boolean)
+     */
     public void setScrollTop(int pixelsScrolledDown) {
         if (pixelsScrolledDown < 0) {
             throw new IllegalArgumentException(
-- 
cgit v1.2.3