Adds tests and JavaDoc regarding Escalator's spacers (#16644)

Change-Id: I9b35a48df8b4e9801c26a25eb1ccce5351c61ddd

2 files changed, 34 insertions, 1 deletions

diff --git a/client/src/com/vaadin/client/widget/escalator/RowContainer.java b/client/src/com/vaadin/client/widget/escalator/RowContainer.java
index ea56c25062..e2baf9a03b 100644
--- a/client/src/com/vaadin/client/widget/escalator/RowContainer.java
+++ b/client/src/com/vaadin/client/widget/escalator/RowContainer.java
@@ -50,6 +50,10 @@ public interface RowContainer {
          * <p>
          * If a spacer is already registered with the given row index, that
          * spacer will be updated with the given height.
+         * <p>
+         * <em>Note:</em> The row index for a spacer will change if rows are
+         * inserted or removed above the current position. Spacers will also be
+         * removed alongside their associated rows
          * 
          * @param rowIndex
          *            the row index for the spacer to modify. The affected
@@ -59,6 +63,8 @@ public interface RowContainer {
          *            negative, the affected spacer (if exists) will be removed
          * @throws IllegalArgumentException
          *             if {@code rowIndex} is not a valid row index
+         * @see #insertRows(int, int)
+         * @see #removeRows(int, int)
          */
         void setSpacer(int rowIndex, double height)
                 throws IllegalArgumentException;
@@ -88,6 +94,26 @@ public interface RowContainer {
          */
         SpacerUpdater getSpacerUpdater();
 
+        /**
+         * {@inheritDoc}
+         * <p>
+         * Any spacers underneath {@code index} will be offset and "pushed"
+         * down. This also modifies the row index they are associated with.
+         */
+        @Override
+        public void insertRows(int index, int numberOfRows)
+                throws IndexOutOfBoundsException, IllegalArgumentException;
+
+        /**
+         * {@inheritDoc}
+         * <p>
+         * Any spacers underneath {@code index} will be offset and "pulled" up.
+         * This also modifies the row index they are associated with. Any
+         * spacers in the removed range will also be closed and removed.
+         */
+        @Override
+        public void removeRows(int index, int numberOfRows)
+                throws IndexOutOfBoundsException, IllegalArgumentException;
     }
 
     /**
diff --git a/client/src/com/vaadin/client/widgets/Escalator.java b/client/src/com/vaadin/client/widgets/Escalator.java
index b36b94c8f3..9d5526b14a 100644
--- a/client/src/com/vaadin/client/widgets/Escalator.java
+++ b/client/src/com/vaadin/client/widgets/Escalator.java
@@ -2925,6 +2925,12 @@ public class Escalator extends Widget implements RequiresResize,
             /*
              * Removing spacers as the very first step will correct the
              * scrollbars and row offsets right away.
+             * 
+             * TODO: actually, it kinda sounds like a Grid feature that a spacer
+             * would be associated with a particular row. Maybe it would be
+             * better to have a spacer separate from rows, and simply collapse
+             * them if they happen to end up on top of each other. This would
+             * probably make supporting the -1 row pretty easy, too.
              */
             spacerContainer.paintRemoveSpacers(removedRowsRange);
 
@@ -3576,7 +3582,7 @@ public class Escalator extends Widget implements RequiresResize,
 
                 // TODO
                 getLogger().warning(
-                        "[[spacers]] removing rows while shrinking the body "
+                        "[[spacers]] removing spacers while shrinking the body "
                                 + "section");
 
                 final ListIterator<TableRowElement> iter = visualRowOrder
@@ -4511,6 +4517,7 @@ public class Escalator extends Widget implements RequiresResize,
                 SpacerImpl spacer = rowIndexToSpacer.remove(this.rowIndex);
                 assert this == spacer : "trying to move an unexpected spacer.";
                 this.rowIndex = rowIndex;
+                root.setPropertyInt(SPACER_LOGICAL_ROW_PROPERTY, rowIndex);
                 rowIndexToSpacer.put(this.rowIndex, this);
             }
         }