svn commit: r1458921 - in /pivot/trunk: ./ wtk/src/org/apache/pivot/wtk/ScrollPane.java wtk/src/org/apache/pivot/wtk/Viewport.java

[rw...@apache.org]

Author: rwhitcomb
Date: Wed Mar 20 16:23:18 2013
New Revision: 1458921

URL: http://svn.apache.org/r1458921
Log:
Added some explanations to ScrollPane and Viewport to more clearly
document the usage of the "view" property to add the children.

This a merge of revision 1458918 from branches/2.0.x to trunk.

Modified:
    pivot/trunk/   (props changed)
    pivot/trunk/wtk/src/org/apache/pivot/wtk/ScrollPane.java
    pivot/trunk/wtk/src/org/apache/pivot/wtk/Viewport.java

Propchange: pivot/trunk/
------------------------------------------------------------------------------
  Merged /pivot/branches/2.0.x:r1458918

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ScrollPane.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ScrollPane.java?rev=1458921&r1=1458920&r2=1458921&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ScrollPane.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ScrollPane.java Wed Mar 20 16:23:18 2013
@@ -22,6 +22,10 @@ import org.apache.pivot.util.ListenerLis
 /**
  * Container that provides a scrollable view of a component, with optional
  * fixed row and column headers.
+ * <p> The single component to be scrolled will typically be a {@link Container}
+ * and should be specified by the {@link #setView setView()} method (the "view" property).
+ * So, even then though this class is a {@link Container}, you should not add
+ * components to it via the {@link #add add()} method.
  */
 public class ScrollPane extends Viewport {
     /**

Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Viewport.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Viewport.java?rev=1458921&r1=1458920&r2=1458921&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Viewport.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Viewport.java Wed Mar 20 16:23:18 2013
@@ -24,6 +24,10 @@ import org.apache.pivot.util.ListenerLis
  * Abstract base class for viewport components. Viewports provide a windowed
  * view on a component (called the "view") that is too large to fit within a
  * given area. They are generally scrollable.
+ * <p> Even though this class is a {@link Container}, no components should be
+ * added to it via the {@link #add add()} method.  The component that gets the
+ * windowed (or scrollable) view should be added via the {@link #setView setView()}
+ * method (or the "view" property).
  */
 @DefaultProperty("view")
 public abstract class Viewport extends Container {
@@ -107,10 +111,18 @@ public abstract class Viewport extends C
         }
     }
 
+    /**
+     * Returns the (single) component (typically a {@link Container})
+     * that we are providing a windowed (or scrollable) view of.
+     */
     public Component getView() {
         return view;
     }
 
+    /**
+     * Set the single component (typically a {@link Container}) that
+     * we will provide a windowed (or scrollable) view of.
+     */
     public void setView(Component view) {
        Component previousView = this.view;
 
@@ -176,6 +188,13 @@ public abstract class Viewport extends C
         }
     }
 
+    /**
+     * This method should not be called to remove child components
+     * from the Viewport because the viewable child(ren) are set
+     * by the {@link #setView} method instead.  Any attempt to
+     * remove the "view" component with this method will result
+     * in an exception.
+     */
     @Override
     public Sequence<Component> remove(int index, int count) {
         for (int i = index, n = index + count; i < n; i++) {