You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

RowContainer.java 12KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339
  1. /*
  2. * Copyright 2000-2021 Vaadin Ltd.
  3. *
  4. * Licensed under the Apache License, Version 2.0 (the "License"); you may not
  5. * use this file except in compliance with the License. You may obtain a copy of
  6. * the License at
  7. *
  8. * http://www.apache.org/licenses/LICENSE-2.0
  9. *
  10. * Unless required by applicable law or agreed to in writing, software
  11. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  12. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  13. * License for the specific language governing permissions and limitations under
  14. * the License.
  15. */
  16. package com.vaadin.client.widget.escalator;
  17. import java.util.List;
  18. import java.util.function.Consumer;
  19. import com.google.gwt.dom.client.Element;
  20. import com.google.gwt.dom.client.TableRowElement;
  21. import com.google.gwt.dom.client.TableSectionElement;
  22. import com.vaadin.client.widgets.Escalator;
  23. /**
  24. * A representation of the rows in each of the sections (header, body and
  25. * footer) in an {@link com.vaadin.client.widgets.Escalator}.
  26. *
  27. * @since 7.4
  28. * @author Vaadin Ltd
  29. * @see com.vaadin.client.widgets.Escalator#getHeader()
  30. * @see com.vaadin.client.widgets.Escalator#getBody()
  31. * @see com.vaadin.client.widgets.Escalator#getFooter()
  32. * @see SpacerContainer
  33. */
  34. public interface RowContainer {
  35. /**
  36. * The row container for the body section in an
  37. * {@link com.vaadin.client.widgets.Escalator}.
  38. * <p>
  39. * The body section can contain both rows and spacers.
  40. *
  41. * @since 7.5.0
  42. * @author Vaadin Ltd
  43. * @see com.vaadin.client.widgets.Escalator#getBody()
  44. */
  45. public interface BodyRowContainer extends RowContainer {
  46. /**
  47. * Marks a spacer and its height.
  48. * <p>
  49. * If a spacer is already registered with the given row index, that
  50. * spacer will be updated with the given height.
  51. * <p>
  52. * <em>Note:</em> The row index for a spacer will change if rows are
  53. * inserted or removed above the current position. Spacers will also be
  54. * removed alongside their associated rows
  55. *
  56. * @param rowIndex
  57. * the row index for the spacer to modify. The affected
  58. * spacer is underneath the given index. Use -1 to insert a
  59. * spacer before the first row
  60. * @param height
  61. * the pixel height of the spacer. If {@code height} is
  62. * negative, the affected spacer (if exists) will be removed
  63. * @throws IllegalArgumentException
  64. * if {@code rowIndex} is not a valid row index
  65. * @see #insertRows(int, int)
  66. * @see #removeRows(int, int)
  67. */
  68. void setSpacer(int rowIndex, double height)
  69. throws IllegalArgumentException;
  70. /**
  71. * Checks whether the given rowIndex contains a spacer.
  72. *
  73. * @param rowIndex
  74. * the row index for the queried spacer.
  75. * @return {@code true} if spacer for given row index exists,
  76. * {@code false} otherwise
  77. * @since 8.9
  78. */
  79. boolean spacerExists(int rowIndex);
  80. /**
  81. * Updates the spacer corresponding with the given rowIndex to currently
  82. * provided contents.
  83. *
  84. * @since 8.13
  85. * @param rowIndex
  86. * the row index for the spacer in need of updating
  87. */
  88. void resetSpacer(int rowIndex);
  89. /**
  90. * Sets a new spacer updater.
  91. * <p>
  92. * Spacers that are currently visible will be updated, i.e.
  93. * {@link SpacerUpdater#destroy(Spacer) destroyed} with the previous
  94. * one, and {@link SpacerUpdater#init(Spacer) initialized} with the new
  95. * one.
  96. *
  97. * @param spacerUpdater
  98. * the new spacer updater
  99. * @throws IllegalArgumentException
  100. * if {@code spacerUpdater} is {@code null}
  101. */
  102. void setSpacerUpdater(SpacerUpdater spacerUpdater)
  103. throws IllegalArgumentException;
  104. /**
  105. * Gets the spacer updater currently in use.
  106. * <p>
  107. * {@link SpacerUpdater#NULL} is the default.
  108. *
  109. * @return the spacer updater currently in use. Never <code>null</code>
  110. */
  111. SpacerUpdater getSpacerUpdater();
  112. /**
  113. * {@inheritDoc}
  114. * <p>
  115. * Any spacers underneath {@code index} will be offset and "pushed"
  116. * down. This also modifies the row index they are associated with.
  117. */
  118. @Override
  119. public void insertRows(int index, int numberOfRows)
  120. throws IndexOutOfBoundsException, IllegalArgumentException;
  121. /**
  122. * {@inheritDoc}
  123. * <p>
  124. * Any spacers underneath {@code index} will be offset and "pulled" up.
  125. * This also modifies the row index they are associated with. Any
  126. * spacers in the removed range will also be closed and removed.
  127. */
  128. @Override
  129. public void removeRows(int index, int numberOfRows)
  130. throws IndexOutOfBoundsException, IllegalArgumentException;
  131. /**
  132. * Recalculates and updates the positions of rows and spacers within the
  133. * given range and ensures there is no gap below the rows if there are
  134. * enough rows to fill the space. Recalculates the scrollbars for
  135. * virtual viewport.
  136. *
  137. * @param index
  138. * logical index of the first row to reposition
  139. * @param numberOfRows
  140. * the number of rows to reposition
  141. * @since 8.9
  142. */
  143. public void updateRowPositions(int index, int numberOfRows);
  144. /**
  145. * Sets a callback function that is executed when new rows are added to
  146. * the escalator.
  147. *
  148. * @param consumer
  149. * A Consumer function that receives the newly added table
  150. * row elements.
  151. * @since 8.1
  152. */
  153. public void setNewRowCallback(Consumer<List<TableRowElement>> consumer);
  154. }
  155. /**
  156. * An arbitrary pixel height of a row, before any autodetection for the row
  157. * height has been made.
  158. */
  159. public static final double INITIAL_DEFAULT_ROW_HEIGHT = 20;
  160. /**
  161. * Returns the current {@link EscalatorUpdater} used to render cells.
  162. *
  163. * @return the current escalator updater
  164. */
  165. public EscalatorUpdater getEscalatorUpdater();
  166. /**
  167. * Sets the {@link EscalatorUpdater} to use when displaying data in the
  168. * escalator.
  169. *
  170. * @param escalatorUpdater
  171. * the escalator updater to use to render cells. May not be
  172. * <code>null</code>
  173. * @throws IllegalArgumentException
  174. * if {@code cellRenderer} is <code>null</code>
  175. * @see EscalatorUpdater#NULL
  176. */
  177. public void setEscalatorUpdater(EscalatorUpdater escalatorUpdater)
  178. throws IllegalArgumentException;
  179. /**
  180. * Removes rows at a certain index in the current row container.
  181. *
  182. * @param index
  183. * the index of the first row to be removed
  184. * @param numberOfRows
  185. * the number of rows to remove, starting from the index
  186. * @throws IndexOutOfBoundsException
  187. * if any integer number in the range
  188. * <code>[index..(index+numberOfRows)]</code> is not an existing
  189. * row index
  190. * @throws IllegalArgumentException
  191. * if {@code numberOfRows} is less than 1.
  192. */
  193. public void removeRows(int index, int numberOfRows)
  194. throws IndexOutOfBoundsException, IllegalArgumentException;
  195. /**
  196. * Adds rows at a certain index in this row container.
  197. * <p>
  198. * The new rows will be inserted between the row at the index, and the row
  199. * before (an index of 0 means that the rows are inserted at the beginning).
  200. * Therefore, the rows currently at the index and afterwards will be moved
  201. * downwards.
  202. * <p>
  203. * The contents of the inserted rows will subsequently be queried from the
  204. * escalator updater.
  205. * <p>
  206. * <em>Note:</em> Only the contents of the inserted rows will be rendered.
  207. * If inserting new rows affects the contents of existing rows,
  208. * {@link #refreshRows(int, int)} needs to be called for those rows
  209. * separately.
  210. *
  211. * @param index
  212. * the index of the row before which new rows are inserted, or
  213. * {@link #getRowCount()} to add rows at the end
  214. * @param numberOfRows
  215. * the number of rows to insert after the <code>index</code>
  216. * @see #setEscalatorUpdater(EscalatorUpdater)
  217. * @throws IndexOutOfBoundsException
  218. * if <code>index</code> is not an integer in the range
  219. * <code>[0..{@link #getRowCount()}]</code>
  220. * @throws IllegalArgumentException
  221. * if {@code numberOfRows} is less than 1.
  222. */
  223. public void insertRows(int index, int numberOfRows)
  224. throws IndexOutOfBoundsException, IllegalArgumentException;
  225. /**
  226. * Refreshes a range of rows in the current row container.
  227. * <p>
  228. * The data for the refreshed rows is queried from the current cell
  229. * renderer.
  230. *
  231. * @param index
  232. * the index of the first row that will be updated
  233. * @param numberOfRows
  234. * the number of rows to update, starting from the index
  235. * @see #setEscalatorUpdater(EscalatorUpdater)
  236. * @throws IndexOutOfBoundsException
  237. * if any integer number in the range
  238. * <code>[index..(index+numberOfColumns)]</code> is not an
  239. * existing column index.
  240. * @throws IllegalArgumentException
  241. * if {@code numberOfRows} is less than 1.
  242. */
  243. public void refreshRows(int index, int numberOfRows)
  244. throws IndexOutOfBoundsException, IllegalArgumentException;
  245. /**
  246. * Gets the number of rows in the current row container.
  247. *
  248. * @return the number of rows in the current row container
  249. */
  250. public int getRowCount();
  251. /**
  252. * For internal use only. May be removed or replaced in the future.
  253. *
  254. * @since 8.7
  255. * @return {@code true} if row height calculations have been scheduled
  256. */
  257. public boolean isAutodetectingRowHeightLater();
  258. /**
  259. * The default height of the rows in this RowContainer.
  260. *
  261. * @param px
  262. * the default height in pixels of the rows in this RowContainer
  263. * @throws IllegalArgumentException
  264. * if <code>px &lt; 1</code>
  265. * @see #getDefaultRowHeight()
  266. */
  267. public void setDefaultRowHeight(double px) throws IllegalArgumentException;
  268. /**
  269. * Returns the default height of the rows in this RowContainer.
  270. * <p>
  271. * This value will be equal to {@link #INITIAL_DEFAULT_ROW_HEIGHT} if the
  272. * {@link Escalator} has not yet had a chance to autodetect the row height,
  273. * or no explicit value has yet given via {@link #setDefaultRowHeight(int)}
  274. *
  275. * @return the default height of the rows in this RowContainer, in pixels
  276. * @see #setDefaultRowHeight(int)
  277. */
  278. public double getDefaultRowHeight();
  279. /**
  280. * Returns the cell object which contains information about the cell the
  281. * element is in.
  282. *
  283. * @param element
  284. * The element to get the cell for. If element is not present in
  285. * row container then <code>null</code> is returned.
  286. *
  287. * @return the cell of the element, or <code>null</code> if element is not
  288. * present in the {@link RowContainer}.
  289. */
  290. public Cell getCell(Element element);
  291. /**
  292. * Gets the row element with given logical index. For lazy loaded containers
  293. * such as Escalators BodyRowContainer visibility should be checked before
  294. * calling this function. See {@link Escalator#getVisibleRowRange()}.
  295. *
  296. * @param index
  297. * the logical index of the element to retrieve
  298. * @return the element at position {@code index}
  299. * @throws IndexOutOfBoundsException
  300. * if {@code index} is not valid within container
  301. * @throws IllegalStateException
  302. * if {@code index} is currently not available in the DOM
  303. */
  304. public TableRowElement getRowElement(int index)
  305. throws IndexOutOfBoundsException, IllegalStateException;
  306. /**
  307. * Returns the root element of RowContainer.
  308. *
  309. * @return RowContainer root element
  310. */
  311. public TableSectionElement getElement();
  312. }