From d5cba6be7088846d771f48ac93f06c2c87779b87 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Marko=20Gr=C3=B6nroos?= Date: Wed, 2 Nov 2011 10:56:16 +0000 Subject: [PATCH] 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; /** *

- * 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. *

* * @author IT Mill Ltd. @@ -39,6 +40,13 @@ public interface Scrollable extends Serializable { * scrolled right. *

* + *

+ * 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. + *

+ * * @param pixelsScrolled * the xOffset. */ @@ -64,30 +72,54 @@ public interface Scrollable extends Serializable { * scrolled down. *

* + *

+ * 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. + *

+ * + *

+ * 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. + *

+ * * @param pixelsScrolled * the yOffset. */ public void setScrollTop(int pixelsScrolled); /** - * Is the scrolling enabled. + * Is programmatic scrolling enabled. * *

- * Enabling scrolling allows the user to scroll the scrollable view - * interactively + * Whether programmatic scrolling with {@link #setScrollLeft(int)} and + * {@link #setScrollTop(int)} is enabled. *

* - * @return true if the scrolling is allowed, otherwise + * @return true if the scrolling is enabled, otherwise * false. */ public boolean isScrollable(); /** - * Enables or disables scrolling.. + * Enables or disables programmatic scrolling. + * + *

+ * 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. + *

* *

- * Enabling scrolling allows the user to scroll the scrollable view - * interactively + * Notice that this does not 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. *

* * @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. + * + *

+ * 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. + *

* * @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. + * + *

+ * 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. + *

* * @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. + * + *

+ * 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. + *

+ * + * @see com.vaadin.terminal.Scrollable#setScrollTop(int) + * @see #setScrollable(boolean) + */ public void setScrollTop(int pixelsScrolledDown) { if (pixelsScrolledDown < 0) { throw new IllegalArgumentException( -- 2.39.5