Merge pull request #90 from rubensousa/docs

Update documentation for new version
rubensousa · Feb 13, 2023 · 98166c1 · 98166c1
2 parents 12124db + 35d20ec
commit 98166c1
Show file tree

Hide file tree

Showing 20 changed files with 465 additions and 70 deletions.
diff --git a/.github/workflows/pr_skipped.yml b/.github/workflows/pr_skipped.yml
@@ -22,5 +22,12 @@ jobs:
       - run: 'echo "No build required"'
   ui_test:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [ x86 ]
+        target: [ android-tv ]
+        api-level: [ 27 ]
+        profile: [ tv_1080p ]
     steps:
       - run: 'echo "No build required"'
diff --git a/README.MD b/README.MD
@@ -22,6 +22,28 @@ androidTestImplementation "com.rubensousa.dpadrecyclerview:dpadrecyclerview-test
 
 Check the official website for more information and recipes: https://rubensousa.github.io/DpadRecyclerView
 
+## New Features compared to Leanback's `BaseGridView`
+
+### Layout
+
+- Supports grids with different span sizes
+- Supports reverse layout
+- XML attributes for easier configuration
+
+### Scrolling and focus
+
+- Supports changing the alignment configuration smoothly
+- Supports limiting the number of pending alignments
+- Supports non smooth scroll changes
+- Supports continuous and circular grid focus
+
+## Features missing from Leanback's `BaseGridView`
+
+- Scrolling in secondary direction
+- Disabling recycling of children
+- Saving and restoring children states: clients can save and restore children on the appropriate RecyclerView.Adapter callbacks
+- Touch event scrolling: on purpose, since `DpadRecyclerView` is only meant to react to focus changes
+- `setChildrenVisibility`: clients can do this by iterating over the children
 
 ## Sample app
 

diff --git a/docs/alignment.md b/docs/alignment.md
@@ -28,7 +28,7 @@ You can also create a top anchor:
 In this case, the configuration would be:
 
 ```kotlin
-ParentAlignment(offset = resources.dpToPx(16), offsetRatio = 0.0f)
+ParentAlignment(offset = 16.dp.toPx(), offsetRatio = 0f)
 ```
 
 Both `offset` and `offsetRatio` start counting from the minimum edge of the `DpadRecyclerView`. For horizontal orientations, this would be the start and for vertical orientation this would be the top.
@@ -52,15 +52,16 @@ The `ChildAlignment` class will take care of calculating the anchor position for
 
 Consider the following example for a **horizontal** `DpadRecyclerView`:
 
-<img width="600" alt="image" src="https://user-images.githubusercontent.com/10662096/200148250-72ddb35f-c9e9-46a8-b7ba-0d28286eaeee.png">
+![Start alignment](../img/start_alignment.png)
 
-The red circle shows the keyline position defined by `ParentAlignment` and the green circles shows the anchor position of each child.
+The blue circle shows the keyline position defined by `ParentAlignment` and the green circles shows the anchor position of each child
+defined by `ChildAlignment`.
 
 In this case, the combined configuration would be:
 
 ```kotlin
-ParentAlignment(offset = resources.dpToPx(16), offsetRatio = 0.0f)
-ChildAlignment(offsetRatio = 0.0f)
+ParentAlignment(offset = 24.dp.toPx(), offsetRatio = 0f)
+ChildAlignment(offsetRatio = 0f)
 ```
 
 ## Examples

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,28 +1,65 @@
 # Changelog
 
-## 1.0.0-alpha04 (2023-02-??)
+## Version 1.0.0
 
-### Improvements
+### 1.0.0-alpha04
 
-### Bug fixes
+2023-02-13
+
+#### New Features
+
+- Added `DpadLinearSpacingItemDecoration` and `DpadGridSpacingItemDecoration` to easily set spacing between items
+- Added `setScrollEnabled` to enable or disable scroll events
+- Added `setLayoutEnabled` to enable or disable the layout of children
+- Added support for reverse layout via `setReverseLayout`
+- Restored support for basic touch event scrolling without triggering selection or alignment changes
+- Added support for item prefetching for nested RecyclerViews
+- `setSmoothScrollMaxPendingAlignments` allows limiting the number of scroll changes still not applied
+- `setSmoothScrollMaxPendingMoves` allows remembering DPAD events not yet applied
+- Improved fast smooth scrolling in grids with different span sizes
+- Added `setOnChildLaidOutListener` to observe when each view is laid out
+- `setFocusSearchEnabledDuringAnimations` allows enabling or disabling focus changes during item animations.
+
+#### API Changes
+
+- `ViewHolderAlignment` was renamed  to `SubPositionAlignment`. Now `DpadViewHolder` returns these alignments in `getSubPositionAlignments`.
+
+#### Bug fixes
 
 - Fixed `DpadRecyclerView` not searching for focus if it's currently retaining focus due to a pivot removal. This prevented accumulating pending moves during smooth scrolling.
+- A nested `DpadRecyclerView` now won't search for focus if its parent `RecyclerView` is still smooth scrolling ([#50](https://github.com/rubensousa/DpadRecyclerView/issues/50))
+- Alignment not being restored correctly for small lists ([#71](https://github.com/rubensousa/DpadRecyclerView/issues/71))
+- Unnecessary `ItemAnimator` animations were running when scrolling during item changes ([#47](https://github.com/rubensousa/DpadRecyclerView/issues/47))
+- a11y scroll actions were not triggering scroll events ([#66](https://github.com/rubensousa/DpadRecyclerView/issues/66))
+- Circular focus not working correctly for the first row ([#37](https://github.com/rubensousa/DpadRecyclerView/issues/37))
 
-### Testing
+#### Testing
 
 - `DisableIdleTimeoutRule` will now wait for idle input after the test is over to avoid dispatching key events to other tests
 
-## 1.0.0-alpha03 (2023-01-26)
+### 1.0.0-alpha03
+
+2023-01-26
+
+#### New Features
 
-- Replaced `DpadLayoutManager` with new `PivotLayoutManager` for proper customization of layout logic ([#10](https://github.com/rubensousa/DpadRecyclerView/issues/10)), ([#16](https://github.com/rubensousa/DpadRecyclerView/issues/16))
 - Added support for findFirstVisibleItemPosition and findLastVisibleItemPosition ([#23](https://github.com/rubensousa/DpadRecyclerView/issues/23))
 - Added support for recycling children on detach ([#17](https://github.com/rubensousa/DpadRecyclerView/issues/17))
 
-## 1.0.0-alpha02 (2022-12-10)
+#### API Changes
+- Replaced `DpadLayoutManager` with new `PivotLayoutManager` for proper customization of layout logic ([#10](https://github.com/rubensousa/DpadRecyclerView/issues/10)), ([#16](https://github.com/rubensousa/DpadRecyclerView/issues/16))
+
 
+### 1.0.0-alpha02
+
+2022-12-10
+
+#### API Changes
 - Allow extending from `DpadRecyclerView`
 - Removed `RecyclerView.canScrollHorizontally` and `RecyclerView.canScrollVertically` since they're not used and clients can create them themselves
 
-## 1.0.0-alpha01 (2022-11-06)
+### 1.0.0-alpha01 
+
+2022-11-06
 
 - Initial alpha release
diff --git a/docs/img/center_alignment.png b/docs/img/center_alignment.png
diff --git a/docs/img/circular_focus.png b/docs/img/circular_focus.png
diff --git a/docs/img/continuous_focus.png b/docs/img/continuous_focus.png
diff --git a/docs/img/max_pending_alignments.png b/docs/img/max_pending_alignments.png
diff --git a/docs/img/start_alignment.png b/docs/img/start_alignment.png
diff --git a/docs/img/start_alignment_padding.png b/docs/img/start_alignment_padding.png
diff --git a/docs/img/subposition_alignment.png b/docs/img/subposition_alignment.png
diff --git a/docs/index.md b/docs/index.md
@@ -12,26 +12,27 @@ Motivation for this library is available in my [blog](https://rubensousa.com/202
 - minSDK: 21
 - Java 8
 
-## Features supported
-
-
-| Feature                          | BaseGridView | DpadRecyclerView |
-|----------------------------------|--------------|------------------|
-| Smooth view alignment changes    | ❌            | ✅                |
-| Throttle focus changes           | ❌            | ✅                |
-| Multiple span sizes              | ❌            | ✅                |
-| Change orientation at runtime    | ❌            | ✅                |
-| Disabling smooth scrolling       | ❌            | ✅                |
-| Circular grid focus              | ❌            | ✅                |
-| Continuous grid focus            | ❌            | ✅                |
-| XML attributes for configuration | ❌            | ✅                |
-| Touch event scrolling            | ✅            | ❌                |
-| Save children state*             | ✅            | ❌                |
-| setLayoutEnabled*                | ✅            | ❌                |
-| setScrollEnabled*                | ✅            | ❌                |
-| Scroll in secondary direction    | ✅            | ❌                |
-
-`*` features still planned
+## New Features compared to Leanback's `BaseGridView`
+
+### Layout
+
+- Supports grids with different span sizes
+- Supports reverse layout
+- XML attributes for easier configuration
+
+### Scrolling and focus
+
+- Supports changing the alignment configuration smoothly
+- Supports limiting the number of pending alignments
+- Supports non smooth scroll changes
+- Supports continuous and circular grid focus
+
+## Features missing from Leanback's `BaseGridView`
+
+- Scrolling in secondary direction
+- Disabling recycling of children
+- Saving and restoring children states: clients can save and restore children on the appropriate RecyclerView.Adapter callbacks
+- `setChildrenVisibility`: clients can do this by iterating over the children
 
 
 ## License

diff --git a/docs/migrating_leanback.md b/docs/migrating_leanback.md
@@ -20,9 +20,8 @@ You can combine `DpadRecyclerView` with `BaseGridView` as follows:
 Instead of using `VerticalGridView` or `HorizontalGridView`, use `DpadRecyclerView` and set the orientation either programmatically
 with `setOrientation` or with plain XML:
 
-```xml linenums="1" hl_lines="6"
-<com.rubensousa.dpadrecyclerview.DpadRecyclerView xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:app="http://schemas.android.com/apk/res-auto"
+```xml linenums="1" hl_lines="5"
+<com.rubensousa.dpadrecyclerview.DpadRecyclerView 
     android:id="@+id/recyclerView"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
@@ -39,6 +38,8 @@ The window alignment APIs from `BaseGridView` can now be found in the `ParentAli
     recyclerView.windowAlignment = BaseGridView.WINDOW_ALIGN_NO_EDGE
     recyclerView.windowAlignmentOffset = 0
     recyclerView.windowAlignmentOffsetPercent = 100f
+    recyclerView.windowAlignmentPreferKeyLineOverLowEdge = false
+    recyclerView.windowAlignmentPreferKeyLineOverHighEdge = false
     ```
 
 === "DpadRecyclerView"
@@ -48,7 +49,8 @@ The window alignment APIs from `BaseGridView` can now be found in the `ParentAli
         ParentAlignment(
             edge = ParentAlignment.Edge.NONE,
             offset = 0,
-            offsetRatio = 1f
+            offsetRatio = 1f,
+            preferKeylineOverEdge = false
         )
     )
     ```
@@ -148,4 +150,5 @@ Please check the examples in the recipes at [Spacing](recipes/spacing.md).
 
 ## Presenters
 
-These will still work out of the box with `DpadRecyclerView`, but feel free to use any other RecyclerView framework in case you want to get rid completely of the Leanback library.
+These will still work out of the box with `DpadRecyclerView` since they're just a wrapper over `RecyclerView.Adapter`,
+ but feel free to use any other RecyclerView framework in case you want to get rid completely of the Leanback library.